create-propelkit 1.0.0

package/src/messages.js

@@ -0,0 +1,119 @@
+const chalk = require('chalk');
+
+const messages = {
+  welcome: () => {
+    console.log('');
+    console.log(chalk.cyan.bold('PropelKit'));
+    console.log(chalk.dim('AI-powered SaaS boilerplate for India'));
+    console.log('');
+  },
+
+  detectingCLIs: () => {
+    console.log(chalk.dim('Detecting installed tools...'));
+  },
+
+  claudeRequired: (installUrl) => {
+    console.log('');
+    console.log(chalk.red.bold('Claude Code is required to use PropelKit'));
+    console.log('');
+    console.log('PropelKit uses Claude Code as the AI PM to build your project.');
+    console.log('');
+    console.log(chalk.cyan('Install Claude Code:'));
+    console.log(chalk.dim(`  ${installUrl}`));
+    console.log('');
+    console.log('After installing, run this command again.');
+    console.log('');
+  },
+
+  supabaseBenefits: () => {
+    console.log(chalk.cyan('Supabase CLI Benefits:'));
+    console.log(chalk.dim('  - Automatic database migrations after each phase'));
+    console.log(chalk.dim('  - No need to manually copy SQL to Supabase dashboard'));
+    console.log(chalk.dim('  - Local development with supabase start'));
+    console.log('');
+    console.log(chalk.dim('Without Supabase CLI:'));
+    console.log(chalk.dim('  - SQL will be shown inline for you to paste manually'));
+    console.log(chalk.dim('  - Migration files saved to supabase/migrations/'));
+    console.log('');
+  },
+
+  githubBenefits: () => {
+    console.log(chalk.cyan('GitHub CLI Benefits:'));
+    console.log(chalk.dim('  - Automatic repo creation'));
+    console.log(chalk.dim('  - Automatic push after each phase'));
+    console.log(chalk.dim('  - Branch management'));
+    console.log('');
+    console.log(chalk.dim('Without GitHub CLI:'));
+    console.log(chalk.dim('  - Local git commits still happen'));
+    console.log(chalk.dim('  - You push to remote manually'));
+    console.log('');
+  },
+
+  launchingClaude: (projectDir) => {
+    console.log('');
+    console.log(chalk.cyan.bold('Launching Claude Code...'));
+    console.log(chalk.dim(`Directory: ${projectDir}`));
+    console.log('');
+    console.log(chalk.yellow('When Claude Code opens, type:'));
+    console.log(chalk.white.bold('  /propelkit:new-project'));
+    console.log('');
+    console.log(chalk.dim('This starts the AI PM conversation to build your project.'));
+    console.log('');
+  },
+
+  cloneInstructions: (repoUrl, targetDir) => {
+    console.log('');
+    console.log(chalk.cyan('Cloning PropelKit...'));
+    console.log(chalk.dim(`  From: ${repoUrl}`));
+    console.log(chalk.dim(`  To: ${targetDir}`));
+    console.log('');
+  },
+
+  resumeInstructions: (command) => {
+    console.log('');
+    console.log(chalk.yellow('To resume, run:'));
+    console.log(chalk.white.bold(`  ${command}`));
+    console.log('');
+  },
+
+  starterLicenseValid: () => {
+    console.log(chalk.green('License validated: STARTER'));
+    console.log('');
+  },
+
+  proLicenseValid: () => {
+    console.log(chalk.green('License validated: PRO'));
+    console.log('');
+  },
+
+  licenseInvalid: (message) => {
+    console.log('');
+    console.log(chalk.red('License validation failed'));
+    console.log(chalk.dim(message || 'Invalid license key'));
+    console.log('');
+    console.log(`Purchase a license at: ${chalk.cyan('https://propelkit.dev')}`);
+    console.log('');
+  },
+
+  starterWizardComplete: () => {
+    console.log('');
+    console.log(chalk.green.bold('PropelKit Starter is ready!'));
+    console.log('');
+    console.log(chalk.dim('Run these commands to start:'));
+    console.log(chalk.cyan('  npm install'));
+    console.log(chalk.cyan('  npm run dev'));
+    console.log('');
+  },
+
+  proLaunchingAIPM: (projectDir) => {
+    console.log('');
+    console.log(chalk.cyan.bold('Launching AI PM in Claude Code...'));
+    console.log(chalk.dim(`Project: ${projectDir}`));
+    console.log('');
+    console.log(chalk.dim('When Claude Code opens, type:'));
+    console.log(chalk.white.bold('  /propelkit:new-project'));
+    console.log('');
+  }
+};
+
+module.exports = messages;

package/src/orchestrators/existing-designs.ts

@@ -0,0 +1,176 @@
+/**
+ * Existing Designs Orchestrator
+ *
+ * TypeScript orchestrator that chains import → translation → integration
+ * for the "I have existing designs" CLI path.
+ *
+ * Spawned by design-flow.js via npx tsx.
+ */
+
+import { importProject } from '@/lib/import';
+import { translateProject } from '@/lib/translation';
+import { analyzeIntegration, generateIntegrationReport } from '@/lib/integration';
+import * as path from 'path';
+
+interface CliArgs {
+  projectDir: string;
+  sourceBase64: string;
+}
+
+interface ImportSource {
+  type: 'github' | 'local';
+  url?: string;
+  path?: string;
+}
+
+/**
+ * Parse command-line arguments.
+ *
+ * Expected format: --project-dir <path> --source-base64 <json>
+ */
+function parseArgs(argv: string[]): CliArgs {
+  const args: Record<string, string> = {};
+
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const value = argv[i + 1];
+
+      if (value && !value.startsWith('--')) {
+        args[key] = value;
+        i++; // Skip next item since we consumed it
+      }
+    }
+  }
+
+  if (!args.projectDir || !args.sourceBase64) {
+    console.error('');
+    console.error('Usage: tsx existing-designs.ts --project-dir <path> --source-base64 <json>');
+    console.error('');
+    process.exit(1);
+  }
+
+  return {
+    projectDir: args.projectDir,
+    sourceBase64: args.sourceBase64,
+  };
+}
+
+/**
+ * Main orchestration function.
+ *
+ * Chains import → translation → integration pipeline.
+ */
+async function main() {
+  const args = parseArgs(process.argv);
+
+  // Decode source from base64
+  const sourceJson = Buffer.from(args.sourceBase64, 'base64').toString('utf-8');
+  const source: ImportSource = JSON.parse(sourceJson);
+
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  PropelKit: Existing Designs Import');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+
+  // Step 1: Import
+  console.log('[1/3] Importing project...');
+  console.log('');
+
+  const importResult = await importProject({
+    source,
+    destinationBase: path.join(args.projectDir, 'src', 'imported'),
+  });
+
+  if (!importResult.success) {
+    console.error('');
+    console.error('❌ Import failed:');
+    importResult.errors.forEach((err) => console.error(`   - ${err}`));
+    console.error('');
+    process.exit(1);
+  }
+
+  console.log(`✓ Imported to: ${importResult.projectPath}`);
+  if (importResult.warnings.length > 0) {
+    console.log(`⚠ ${importResult.warnings.length} warnings (see below)`);
+    importResult.warnings.forEach((w) => console.log(`   - ${w}`));
+  }
+  console.log('');
+
+  // Step 2: Translation
+  console.log('[2/3] Translating to Next.js App Router...');
+  console.log('');
+
+  const translationResult = await translateProject({
+    sourceDir: importResult.projectPath,
+    targetDir: path.join(args.projectDir, 'src', 'app'),
+    preserveComments: true,
+    incremental: false,
+  });
+
+  if (!translationResult.success) {
+    console.error('');
+    console.error('❌ Translation failed:');
+    translationResult.errors.forEach((err) => console.error(`   - ${err}`));
+    console.error('');
+    process.exit(1);
+  }
+
+  console.log(`✓ Translated ${translationResult.components.length} components`);
+  console.log(`✓ Migrated ${translationResult.routes.length} routes`);
+  if (translationResult.warnings.length > 0) {
+    console.log(`⚠ ${translationResult.warnings.length} warnings (see report)`);
+  }
+  console.log('');
+
+  // Step 3: Integration Analysis
+  console.log('[3/3] Analyzing backend integration needs...');
+  console.log('');
+
+  const integrationResult = await analyzeIntegration(importResult.projectPath);
+
+  if (integrationResult.errors.length > 0) {
+    console.error('');
+    console.error('⚠ Integration analysis had errors:');
+    integrationResult.errors.forEach((err) => console.error(`   - ${err}`));
+    console.error('');
+  }
+
+  const reportPath = await generateIntegrationReport(
+    integrationResult,
+    path.join(args.projectDir, 'INTEGRATION.md')
+  );
+
+  console.log(`✓ Integration report generated`);
+  console.log('');
+
+  // Summary
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  Summary');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log(`  Components analyzed: ${integrationResult.components.length}`);
+  console.log(`  Auth migrations needed: ${integrationResult.summary.authMigrations}`);
+  console.log(`  Data components: ${integrationResult.summary.dataComponents}`);
+  console.log(`  Total TODOs: ${integrationResult.summary.totalTodos}`);
+  console.log('');
+  console.log(`📄 Next steps: Review ${path.basename(reportPath)}`);
+  console.log('');
+
+  process.exit(0);
+}
+
+// Execute with error handling
+main().catch((err) => {
+  console.error('');
+  console.error('💥 Fatal error:');
+  console.error(err instanceof Error ? err.message : String(err));
+  console.error('');
+  if (err instanceof Error && err.stack) {
+    console.error('Stack trace:');
+    console.error(err.stack);
+  }
+  process.exit(1);
+});

package/src/page-mapper.js

@@ -0,0 +1,247 @@
+/**
+ * Feature-to-page template mapping
+ * Derives page suggestions from PropelKit feature flags
+ */
+
+/**
+ * Page templates organized by feature category
+ * Each category contains pages that are relevant when that feature is enabled
+ */
+const PAGE_TEMPLATES = {
+  // Core pages (always included)
+  core: ['Home', 'Dashboard', 'Settings', '404'],
+
+  // Auth pages (always included)
+  auth: ['Login', 'Signup', 'Forgot Password', 'Reset Password'],
+
+  // Payment pages (always included)
+  payments: ['Pricing', 'Checkout', 'Billing History'],
+
+  // Multi-tenancy pages (optional - based on features.multiTenancy)
+  multiTenancy: ['Team Settings', 'Invite Members', 'Role Management'],
+
+  // Credits pages (optional - based on features.credits)
+  credits: ['Usage Dashboard', 'Purchase Credits'],
+
+  // GST pages (always included for India)
+  gst: ['Invoice Settings'],
+
+  // Admin pages (always included)
+  admin: ['Admin Panel']
+};
+
+/**
+ * Page detail templates for Lovable prompt generation
+ * Contains purpose, elements, components, and user flow for each known page
+ */
+const PAGE_DETAILS = {
+  // Core pages
+  'Home': {
+    purpose: 'Landing page introducing the product and converting visitors',
+    elements: ['Hero section with value proposition', 'Feature highlights grid', 'Social proof/testimonials', 'Pricing preview', 'Call-to-action buttons', 'Footer with links'],
+    components: ['Hero', 'FeatureGrid', 'TestimonialCarousel', 'PricingPreview', 'Button', 'Footer'],
+    userFlow: 'Visitor lands on page -> Reads value proposition -> Explores features -> Clicks CTA to sign up'
+  },
+  'Dashboard': {
+    purpose: 'Main user interface showing key metrics and quick actions after login',
+    elements: ['Welcome message', 'Metrics cards with key stats', 'Recent activity feed', 'Quick action buttons', 'Navigation sidebar'],
+    components: ['Card', 'Chart', 'Table', 'Button', 'Sidebar'],
+    userFlow: 'User logs in -> Views overview metrics -> Takes quick actions or navigates to detailed sections'
+  },
+  'Settings': {
+    purpose: 'User profile and account preferences management',
+    elements: ['Profile information form', 'Account preferences', 'Notification settings', 'Security settings', 'Danger zone (delete account)'],
+    components: ['Form', 'Input', 'Toggle', 'Select', 'Button', 'Alert'],
+    userFlow: 'User navigates to settings -> Modifies preferences -> Saves changes'
+  },
+  '404': {
+    purpose: 'Error page for routes that do not exist',
+    elements: ['Friendly error message', 'Illustration', 'Home navigation link', 'Search option'],
+    components: ['ErrorMessage', 'Illustration', 'Link', 'SearchInput'],
+    userFlow: 'User hits invalid URL -> Sees error page -> Navigates back to home or searches'
+  },
+
+  // Auth pages
+  'Login': {
+    purpose: 'Authenticate existing users to access their account',
+    elements: ['Email input field', 'Password input field', 'Remember me checkbox', 'Login button', 'Forgot password link', 'Sign up redirect link'],
+    components: ['Form', 'Input', 'Checkbox', 'Button', 'Link'],
+    userFlow: 'User enters credentials -> Submits form -> Redirects to dashboard on success'
+  },
+  'Signup': {
+    purpose: 'Register new users and create their account',
+    elements: ['Name input field', 'Email input field', 'Password input field', 'Confirm password field', 'Terms acceptance checkbox', 'Sign up button', 'Login redirect link'],
+    components: ['Form', 'Input', 'Checkbox', 'Button', 'Link'],
+    userFlow: 'User fills registration form -> Submits -> Email verification sent -> Redirects to onboarding'
+  },
+  'Forgot Password': {
+    purpose: 'Allow users to request password reset via email',
+    elements: ['Email input field', 'Submit button', 'Back to login link', 'Success message'],
+    components: ['Form', 'Input', 'Button', 'Link', 'Alert'],
+    userFlow: 'User enters email -> Submits request -> Receives reset link via email'
+  },
+  'Reset Password': {
+    purpose: 'Set a new password after clicking reset link',
+    elements: ['New password input', 'Confirm password input', 'Submit button', 'Password requirements hint'],
+    components: ['Form', 'Input', 'Button', 'Alert'],
+    userFlow: 'User clicks email link -> Enters new password -> Submits -> Redirects to login'
+  },
+
+  // Payment pages
+  'Pricing': {
+    purpose: 'Display subscription plans and pricing options for comparison',
+    elements: ['Plan cards with pricing', 'Feature comparison table', 'Toggle for monthly/annual', 'CTA buttons per plan', 'FAQ section'],
+    components: ['PricingCard', 'Badge', 'Toggle', 'Button', 'Accordion'],
+    userFlow: 'User views plans -> Compares features -> Selects plan -> Proceeds to checkout'
+  },
+  'Checkout': {
+    purpose: 'Complete purchase with payment details',
+    elements: ['Order summary', 'Payment form', 'Billing address form', 'GST number input', 'Coupon code input', 'Pay button'],
+    components: ['Form', 'Input', 'Card', 'Button', 'Alert'],
+    userFlow: 'User reviews order -> Enters payment details -> Submits -> Payment processed -> Confirmation'
+  },
+  'Billing History': {
+    purpose: 'View past invoices and payment history',
+    elements: ['Invoice list table', 'Download invoice buttons', 'Filter by date', 'Payment status badges'],
+    components: ['Table', 'Button', 'Badge', 'DatePicker', 'Pagination'],
+    userFlow: 'User views invoice list -> Filters by date if needed -> Downloads specific invoice'
+  },
+
+  // Multi-tenancy pages
+  'Team Settings': {
+    purpose: 'Manage organization settings and details',
+    elements: ['Organization name and logo', 'Organization details form', 'Team member list', 'Billing settings', 'Delete organization option'],
+    components: ['Form', 'Input', 'Avatar', 'Table', 'Button', 'Alert'],
+    userFlow: 'Admin navigates to settings -> Updates org details -> Saves changes'
+  },
+  'Invite Members': {
+    purpose: 'Invite new team members to the organization',
+    elements: ['Email input field', 'Role selector', 'Send invite button', 'Pending invitations list', 'Resend/cancel invite options'],
+    components: ['Form', 'Input', 'Select', 'Button', 'Table', 'Badge'],
+    userFlow: 'Admin enters email -> Selects role -> Sends invite -> Manages pending invites'
+  },
+  'Role Management': {
+    purpose: 'Manage team member roles and permissions',
+    elements: ['Team members table', 'Role dropdown per member', 'Remove member option', 'Role descriptions'],
+    components: ['Table', 'Select', 'Button', 'Badge', 'Dialog'],
+    userFlow: 'Admin views members -> Changes roles as needed -> Removes members if necessary'
+  },
+
+  // Credits pages
+  'Usage Dashboard': {
+    purpose: 'Monitor credit usage and consumption patterns',
+    elements: ['Current balance display', 'Usage chart over time', 'Usage breakdown by feature', 'Low balance warning', 'Purchase credits CTA'],
+    components: ['Card', 'Chart', 'Table', 'Alert', 'Button', 'Progress'],
+    userFlow: 'User views balance -> Checks usage history -> Clicks to purchase if low'
+  },
+  'Purchase Credits': {
+    purpose: 'Buy additional credits for the account',
+    elements: ['Credit package options', 'Custom amount input', 'Payment summary', 'Purchase button', 'Volume discounts display'],
+    components: ['Card', 'Input', 'Button', 'Badge', 'Alert'],
+    userFlow: 'User selects package -> Reviews total -> Completes payment -> Credits added'
+  },
+
+  // GST pages
+  'Invoice Settings': {
+    purpose: 'Configure GST and invoice details for Indian billing',
+    elements: ['GST number input', 'Business name', 'Business address', 'State selector', 'Invoice preferences'],
+    components: ['Form', 'Input', 'Select', 'Button', 'Alert'],
+    userFlow: 'User enters GST details -> Saves settings -> Future invoices use these details'
+  },
+
+  // Admin pages
+  'Admin Panel': {
+    purpose: 'Superadmin dashboard for managing the entire platform',
+    elements: ['Platform metrics', 'User management table', 'Revenue overview', 'System health status', 'Recent activity log'],
+    components: ['Card', 'Chart', 'Table', 'Badge', 'Button', 'Tabs'],
+    userFlow: 'Admin views platform stats -> Manages users -> Monitors system health'
+  }
+};
+
+/**
+ * Derive list of pages based on feature flags
+ * @param {object} featuresConfig - Object with feature flags (multiTenancy, credits, etc.)
+ * @returns {string[]} - Sorted array of unique page names
+ */
+function derivePages(featuresConfig) {
+  const pages = new Set();
+
+  // Core pages (always included)
+  PAGE_TEMPLATES.core.forEach(page => pages.add(page));
+
+  // Auth pages (always included)
+  PAGE_TEMPLATES.auth.forEach(page => pages.add(page));
+
+  // Payment pages (always included)
+  PAGE_TEMPLATES.payments.forEach(page => pages.add(page));
+
+  // GST pages (always included for India-first SaaS)
+  PAGE_TEMPLATES.gst.forEach(page => pages.add(page));
+
+  // Admin pages (always included)
+  PAGE_TEMPLATES.admin.forEach(page => pages.add(page));
+
+  // Multi-tenancy pages (optional)
+  if (featuresConfig && featuresConfig.multiTenancy) {
+    PAGE_TEMPLATES.multiTenancy.forEach(page => pages.add(page));
+  }
+
+  // Credits pages (optional)
+  if (featuresConfig && featuresConfig.credits) {
+    PAGE_TEMPLATES.credits.forEach(page => pages.add(page));
+  }
+
+  // Convert to array and sort alphabetically
+  return Array.from(pages).sort();
+}
+
+/**
+ * Get detailed page information for Lovable prompt generation
+ * @param {string} pageName - Name of the page
+ * @returns {{ purpose: string, elements: string[], components: string[], userFlow: string }}
+ */
+function getPageDetails(pageName) {
+  // Return specific details if available
+  if (PAGE_DETAILS[pageName]) {
+    return PAGE_DETAILS[pageName];
+  }
+
+  // Return generic fallback for custom/unknown pages
+  return {
+    purpose: `${pageName} page functionality`,
+    elements: ['Main content area', 'Navigation elements', 'Action buttons'],
+    components: ['Card', 'Button', 'Form'],
+    userFlow: 'User navigates to page -> Interacts with content -> Completes action'
+  };
+}
+
+/**
+ * Get all page names from a specific category
+ * @param {string} category - Category name (core, auth, payments, etc.)
+ * @returns {string[]} - Array of page names in that category
+ */
+function getPagesInCategory(category) {
+  return PAGE_TEMPLATES[category] || [];
+}
+
+/**
+ * Check if a page is optional (depends on feature flags)
+ * @param {string} pageName - Name of the page
+ * @returns {boolean} - True if page is optional
+ */
+function isOptionalPage(pageName) {
+  const optionalPages = [
+    ...PAGE_TEMPLATES.multiTenancy,
+    ...PAGE_TEMPLATES.credits
+  ];
+  return optionalPages.includes(pageName);
+}
+
+module.exports = {
+  PAGE_TEMPLATES,
+  PAGE_DETAILS,
+  derivePages,
+  getPageDetails,
+  getPagesInCategory,
+  isOptionalPage
+};