create-propelkit 1.0.0

package/src/prompt-generator.js

@@ -0,0 +1,429 @@
+/**
+ * Lovable Prompt Generator
+ *
+ * Generates comprehensive Lovable prompts from design system and page list.
+ * Uses array-based markdown generation pattern (PropelKit convention).
+ */
+
+/**
+ * Typography configurations for each style reference.
+ * @param {string} styleReference - One of: linear, notion, stripe, vercel, airbnb
+ * @returns {{ headings: string, body: string, characteristics: string }}
+ */
+function getTypography(styleReference) {
+  const typographyMap = {
+    linear: {
+      headings: 'Inter, system-ui, sans-serif',
+      body: 'Inter, system-ui, sans-serif',
+      characteristics: 'Clean, technical, precise'
+    },
+    notion: {
+      headings: 'Inter, ui-sans-serif, sans-serif',
+      body: 'Inter, ui-sans-serif, sans-serif',
+      characteristics: 'Friendly, approachable, readable'
+    },
+    stripe: {
+      headings: 'Sohne, system-ui, sans-serif',
+      body: 'Sohne, system-ui, sans-serif',
+      characteristics: 'Professional, elegant, refined'
+    },
+    vercel: {
+      headings: 'Geist Sans, system-ui, sans-serif',
+      body: 'Geist Sans, system-ui, sans-serif',
+      characteristics: 'Modern, geometric, minimal'
+    },
+    airbnb: {
+      headings: 'Cereal, system-ui, sans-serif',
+      body: 'Cereal, system-ui, sans-serif',
+      characteristics: 'Warm, inviting, human'
+    }
+  };
+
+  const key = styleReference.toLowerCase();
+  return typographyMap[key] || typographyMap.linear;
+}
+
+/**
+ * Get human-readable style description.
+ * @param {string} styleReference - One of: linear, notion, stripe, vercel, airbnb
+ * @returns {string}
+ */
+function getStyleDescription(styleReference) {
+  const descriptions = {
+    linear: 'Linear (minimal, dark mode friendly, clean typography)',
+    notion: 'Notion (friendly, content-focused, approachable)',
+    stripe: 'Stripe (professional, elegant, trustworthy)',
+    vercel: 'Vercel (modern, geometric, developer-focused)',
+    airbnb: 'Airbnb (warm, inviting, human-centered)'
+  };
+
+  const key = styleReference.toLowerCase();
+  return descriptions[key] || descriptions.linear;
+}
+
+/**
+ * Page detail templates for each known page type.
+ * @param {string} pageName - Name of the page
+ * @returns {{ purpose: string, elements: string[], components: string, userFlow: string }}
+ */
+function getPageDetails(pageName) {
+  const pageTemplates = {
+    // Core pages
+    'Home': {
+      purpose: 'Landing page that introduces the product and drives conversions',
+      elements: [
+        'Hero section with value proposition',
+        'Feature highlights (3-4 key benefits)',
+        'Social proof (testimonials or logos)',
+        'Pricing preview or CTA section',
+        'Footer with navigation links'
+      ],
+      components: 'Hero, FeatureCard, Testimonial, PricingPreview, Footer',
+      userFlow: 'User lands, scans value prop, reviews features, clicks CTA to sign up'
+    },
+    'Dashboard': {
+      purpose: 'Central hub showing key metrics and quick actions',
+      elements: [
+        'Welcome message with user name',
+        'Metrics cards (4-6 key numbers)',
+        'Recent activity feed',
+        'Quick action buttons',
+        'Status indicators or alerts'
+      ],
+      components: 'MetricCard, ActivityFeed, Button, Card, Badge',
+      userFlow: 'User logs in, sees overview, takes quick action or dives deeper'
+    },
+    'Settings': {
+      purpose: 'User preferences and account management',
+      elements: [
+        'Profile section (name, email, avatar)',
+        'Notification preferences',
+        'Security settings (password, 2FA)',
+        'Connected accounts',
+        'Danger zone (delete account)'
+      ],
+      components: 'Form, Input, Switch, Avatar, Tabs, AlertDialog',
+      userFlow: 'User navigates to settings, updates preferences, saves changes'
+    },
+    '404': {
+      purpose: 'Friendly error page for missing routes',
+      elements: [
+        'Clear error message',
+        'Illustration or icon',
+        'Link to home page',
+        'Search suggestion',
+        'Help contact option'
+      ],
+      components: 'Card, Button, Input',
+      userFlow: 'User hits broken link, sees error, clicks to return home'
+    },
+
+    // Auth pages
+    'Login': {
+      purpose: 'Authenticate returning users',
+      elements: [
+        'Email input field',
+        'Password input with visibility toggle',
+        'Remember me checkbox',
+        'Login button',
+        'Forgot password link',
+        'Sign up redirect link'
+      ],
+      components: 'Form, Input, Button, Checkbox, Card',
+      userFlow: 'User enters credentials, clicks login, redirected to dashboard'
+    },
+    'Signup': {
+      purpose: 'Register new users',
+      elements: [
+        'Name input field',
+        'Email input field',
+        'Password input with strength indicator',
+        'Terms and conditions checkbox',
+        'Sign up button',
+        'Login redirect link'
+      ],
+      components: 'Form, Input, Button, Checkbox, Card, PasswordStrength',
+      userFlow: 'User fills form, accepts terms, clicks signup, receives welcome email'
+    },
+    'Forgot Password': {
+      purpose: 'Initiate password reset flow',
+      elements: [
+        'Email input field',
+        'Submit button',
+        'Success message area',
+        'Back to login link'
+      ],
+      components: 'Form, Input, Button, Card, Alert',
+      userFlow: 'User enters email, clicks submit, checks inbox for reset link'
+    },
+    'Reset Password': {
+      purpose: 'Set new password after reset request',
+      elements: [
+        'New password input',
+        'Confirm password input',
+        'Password requirements list',
+        'Submit button',
+        'Success redirect'
+      ],
+      components: 'Form, Input, Button, Card, Alert',
+      userFlow: 'User sets new password, confirms it, clicks submit, redirected to login'
+    },
+
+    // Payment pages
+    'Pricing': {
+      purpose: 'Display plans and drive subscription decisions',
+      elements: [
+        'Plan cards (3 tiers recommended)',
+        'Feature comparison table',
+        'Toggle for monthly/annual pricing',
+        'CTA buttons per plan',
+        'FAQ section',
+        'Money-back guarantee badge'
+      ],
+      components: 'PricingCard, Table, Toggle, Button, Accordion, Badge',
+      userFlow: 'User compares plans, toggles billing cycle, selects plan, proceeds to checkout'
+    },
+    'Checkout': {
+      purpose: 'Complete payment transaction',
+      elements: [
+        'Order summary card',
+        'Payment method selection',
+        'Payment form (card details)',
+        'Billing address form',
+        'Apply coupon input',
+        'Secure payment badge',
+        'Pay button with amount'
+      ],
+      components: 'Card, Form, Input, Button, RadioGroup, Badge',
+      userFlow: 'User reviews order, enters payment details, clicks pay, sees confirmation'
+    },
+    'Billing History': {
+      purpose: 'View past invoices and payment methods',
+      elements: [
+        'Invoice table with download links',
+        'Current subscription status',
+        'Payment methods list',
+        'Add payment method button',
+        'Cancel subscription option'
+      ],
+      components: 'Table, Card, Button, Badge, Dialog',
+      userFlow: 'User views invoices, downloads receipts, manages payment methods'
+    },
+
+    // Multi-tenancy pages
+    'Team Settings': {
+      purpose: 'Manage team configuration and branding',
+      elements: [
+        'Team name input',
+        'Team logo upload',
+        'Team URL/slug setting',
+        'Member list with roles',
+        'Remove member actions',
+        'Team deletion option'
+      ],
+      components: 'Form, Input, Avatar, Table, Button, AlertDialog',
+      userFlow: 'Admin updates team info, manages members, saves changes'
+    },
+    'Invite Members': {
+      purpose: 'Add new team members via email invitation',
+      elements: [
+        'Email input field',
+        'Role selector dropdown',
+        'Send invite button',
+        'Pending invitations list',
+        'Resend/cancel invite actions'
+      ],
+      components: 'Form, Input, Select, Button, Table, Badge',
+      userFlow: 'Admin enters email, selects role, sends invite, tracks pending invites'
+    },
+    'Role Management': {
+      purpose: 'Configure team roles and permissions',
+      elements: [
+        'Roles table',
+        'Permission matrix (role x permission)',
+        'Create role button',
+        'Edit role dialog',
+        'Default role indicator'
+      ],
+      components: 'Table, Checkbox, Button, Dialog, Badge',
+      userFlow: 'Admin views roles, edits permissions, creates custom roles'
+    },
+
+    // Credits pages
+    'Usage Dashboard': {
+      purpose: 'Monitor credit consumption and balance',
+      elements: [
+        'Credit balance card',
+        'Usage chart (time series)',
+        'Usage breakdown by feature',
+        'Low credit warning',
+        'Top up CTA button'
+      ],
+      components: 'Card, Chart, Progress, Alert, Button',
+      userFlow: 'User checks balance, reviews usage patterns, tops up if needed'
+    },
+    'Purchase Credits': {
+      purpose: 'Buy additional credits',
+      elements: [
+        'Credit package options',
+        'Quantity selector',
+        'Bulk discount indicator',
+        'Price summary',
+        'Checkout button'
+      ],
+      components: 'Card, RadioGroup, Input, Button, Badge',
+      userFlow: 'User selects package, adjusts quantity, proceeds to payment'
+    },
+
+    // Admin pages
+    'Admin Panel': {
+      purpose: 'System administration and monitoring',
+      elements: [
+        'User statistics card',
+        'Revenue metrics',
+        'System health indicators',
+        'Recent signups list',
+        'Quick admin actions'
+      ],
+      components: 'Card, Chart, Table, Badge, Button',
+      userFlow: 'Admin reviews metrics, monitors health, takes administrative actions'
+    },
+
+    // Profile page
+    'Profile': {
+      purpose: 'View and edit user profile information',
+      elements: [
+        'Avatar with upload option',
+        'Display name field',
+        'Email field (read-only)',
+        'Bio/about text area',
+        'Save button'
+      ],
+      components: 'Form, Input, Textarea, Avatar, Button, Card',
+      userFlow: 'User views profile, updates information, saves changes'
+    },
+
+    // Reports page
+    'Reports': {
+      purpose: 'View detailed analytics and generate reports',
+      elements: [
+        'Date range selector',
+        'Report type selector',
+        'Data visualization charts',
+        'Export options (CSV, PDF)',
+        'Saved reports list'
+      ],
+      components: 'DatePicker, Select, Chart, Button, Table',
+      userFlow: 'User selects date range, chooses report type, views data, exports'
+    }
+  };
+
+  // Return template or fallback for unknown pages
+  return pageTemplates[pageName] || {
+    purpose: `${pageName} functionality`,
+    elements: [
+      'Main content area',
+      'Navigation elements',
+      'Action buttons',
+      'Status indicators'
+    ],
+    components: 'Card, Button, Form',
+    userFlow: 'User interacts with page content and takes relevant actions'
+  };
+}
+
+/**
+ * Generate comprehensive Lovable prompt from design system and pages.
+ * @param {{ primaryColor: string, accentColor: string, styleReference: string, brandVoice: string }} designSystem
+ * @param {string[]} pages - Array of page names
+ * @param {string} projectName - Name of the project
+ * @returns {string} - Complete markdown prompt for Lovable
+ */
+function generateLovablePrompt(designSystem, pages, projectName) {
+  const lines = [];
+  const { primaryColor, accentColor, styleReference, brandVoice } = designSystem;
+  const typography = getTypography(styleReference);
+  const styleDescription = getStyleDescription(styleReference);
+
+  // Header
+  lines.push(`# ${projectName} - Complete UI Design`);
+  lines.push('');
+
+  // Design System section
+  lines.push('## Design System');
+  lines.push('');
+  lines.push(`**Style Reference:** ${styleDescription}`);
+  lines.push(`**Primary Color:** ${primaryColor}`);
+  lines.push(`**Accent Color:** ${accentColor}`);
+  lines.push(`**Brand Voice:** ${brandVoice}`);
+  lines.push('');
+  lines.push('**Typography:**');
+  lines.push(`- Headings: ${typography.headings}`);
+  lines.push(`- Body: ${typography.body}`);
+  lines.push(`- Characteristics: ${typography.characteristics}`);
+  lines.push('');
+
+  // Anti-Patterns section (CRITICAL for 2026)
+  lines.push('## Anti-Patterns to Avoid');
+  lines.push('');
+  lines.push('Create distinctive, human-centered design. DO NOT use:');
+  lines.push('');
+  lines.push('- Generic purple-to-blue gradients (the "AI aesthetic")');
+  lines.push('- Stock photo placeholder images with perfect diversity casting');
+  lines.push('- Overly rounded everything (8px border-radius on all elements)');
+  lines.push('- Generic "Get Started" hero sections with floating mockups');
+  lines.push('- Emoji-fueled faux-minimalism that feels hollow');
+  lines.push('- Same-y corporate filler aesthetics with meaningless taglines');
+  lines.push('');
+  lines.push('**Instead:** Add texture, intentional friction, human imperfection, and genuine brand personality. Make it feel crafted, not generated.');
+  lines.push('');
+
+  // Pages section
+  lines.push('## Pages');
+  lines.push('');
+
+  for (let i = 0; i < pages.length; i++) {
+    const pageName = pages[i];
+    const details = getPageDetails(pageName);
+
+    lines.push(`### ${i + 1}. ${pageName}`);
+    lines.push('');
+    lines.push(`**Purpose:** ${details.purpose}`);
+    lines.push('');
+    lines.push('**Key Elements:**');
+    for (const element of details.elements) {
+      lines.push(`- ${element}`);
+    }
+    lines.push('');
+    lines.push(`**Components:** ${details.components}`);
+    lines.push('');
+    lines.push(`**User Flow:** ${details.userFlow}`);
+    lines.push('');
+  }
+
+  // Global Notes section
+  lines.push('## Global Notes');
+  lines.push('');
+  lines.push('- Use Tailwind CSS with shadcn/ui components');
+  lines.push('- Follow responsive design principles (mobile-first)');
+  lines.push('- Ensure accessibility compliance (WCAG 2.1 AA)');
+  lines.push('- Include loading states for async operations');
+  lines.push('- Include empty states for lists and tables');
+  lines.push('- Add subtle hover effects and micro-interactions');
+  lines.push('- Use consistent spacing based on 4px/8px grid');
+  lines.push('- Implement smooth transitions (150-300ms duration)');
+  lines.push('');
+
+  // Footer
+  lines.push('---');
+  lines.push('*Generated by PropelKit AI PM*');
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  generateLovablePrompt,
+  getTypography,
+  getStyleDescription,
+  getPageDetails
+};

package/src/scenarios.js

@@ -0,0 +1,217 @@
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const inquirer = require('inquirer');
+const chalk = require('chalk');
+const _messages = require('./messages'); // Reserved for future use
+const { REPOS } = require('./config');
+
+/**
+ * Ask user which scenario applies
+ * @returns {Promise<'fresh'|'existing'>}
+ */
+async function askScenario() {
+  const { scenario } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'scenario',
+      message: 'What would you like to do?',
+      choices: [
+        {
+          name: 'Start fresh - Clone PropelKit and create new project',
+          value: 'fresh'
+        },
+        {
+          name: 'Configure existing - I already cloned PropelKit',
+          value: 'existing'
+        }
+      ]
+    }
+  ]);
+  return scenario;
+}
+
+/**
+ * Handle fresh start scenario - clone repo
+ * @param {string} tier - License tier ('starter' or 'pro')
+ * @param {object} clis - CLI detection results
+ * @param {boolean} useGitHub - Whether user wants GitHub integration (from CLI-03 prompt)
+ * @returns {Promise<string>} - Path to project directory
+ */
+async function handleFreshStart(tier, clis, useGitHub) {
+  // Ask for project name/directory
+  const { projectName } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'projectName',
+      message: 'Project name (will create directory):',
+      default: 'my-saas',
+      validate: (input) => {
+        if (!input.trim()) return 'Project name is required';
+        if (fs.existsSync(input)) return `Directory "${input}" already exists`;
+        if (!/^[a-z0-9-_]+$/i.test(input)) return 'Use letters, numbers, dashes, underscores only';
+        return true;
+      }
+    }
+  ]);
+
+  const targetDir = path.resolve(process.cwd(), projectName);
+  const repoUrl = REPOS[tier]; // 'starter' or 'pro'
+  const tierLabel = tier.charAt(0).toUpperCase() + tier.slice(1);
+
+  console.log('');
+  console.log(chalk.cyan(`Cloning PropelKit ${tierLabel}...`));
+  console.log(chalk.dim(`  From: ${repoUrl}`));
+  console.log(chalk.dim(`  To: ${targetDir}`));
+  console.log('');
+
+  try {
+    // Clone the repo
+    execSync(`git clone ${repoUrl} "${targetDir}"`, {
+      stdio: 'inherit'
+    });
+
+    // Remove .git to start fresh
+    const gitDir = path.join(targetDir, '.git');
+    if (fs.existsSync(gitDir)) {
+      fs.rmSync(gitDir, { recursive: true, force: true });
+    }
+
+    // Initialize fresh git repo
+    execSync('git init', { cwd: targetDir, stdio: 'pipe' });
+
+    console.log('');
+    console.log(chalk.green(`PropelKit ${tierLabel} cloned successfully!`));
+    console.log('');
+
+    // Write initial config with CLI availability, useGitHub preference, and tier
+    await writeInitialConfig(targetDir, clis, useGitHub, tier);
+
+    return targetDir;
+  } catch (error) {
+    throw new Error(`Failed to clone PropelKit: ${error.message}`);
+  }
+}
+
+/**
+ * Handle existing clone scenario
+ * @param {string} tier - License tier ('starter' or 'pro')
+ * @param {object} clis - CLI detection results
+ * @param {boolean} useGitHub - Whether user wants GitHub integration (from CLI-03 prompt)
+ * @returns {Promise<string>} - Path to project directory
+ */
+async function handleExistingClone(tier, clis, useGitHub) {
+  const currentDir = process.cwd();
+
+  // Check if this looks like a PropelKit project
+  const hasPackageJson = fs.existsSync(path.join(currentDir, 'package.json'));
+  const hasPropelkitCommands = fs.existsSync(path.join(currentDir, '.claude', 'commands', 'propelkit'));
+
+  if (!hasPackageJson) {
+    console.log('');
+    console.log(chalk.yellow('Warning: No package.json found in current directory.'));
+    console.log(chalk.dim('Make sure you\'re in the PropelKit project root.'));
+    console.log('');
+
+    const { proceed } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'proceed',
+        message: 'Continue anyway?',
+        default: false
+      }
+    ]);
+
+    if (!proceed) {
+      throw new Error('Aborted by user');
+    }
+  }
+
+  if (!hasPropelkitCommands) {
+    console.log('');
+    console.log(chalk.yellow('Warning: PropelKit commands not found at .claude/commands/propelkit/'));
+    console.log(chalk.dim('This may not be a PropelKit project or it may be outdated.'));
+    console.log('');
+  }
+
+  // Write config with CLI availability, useGitHub preference, and tier
+  await writeInitialConfig(currentDir, clis, useGitHub, tier);
+
+  return currentDir;
+}
+
+/**
+ * Write initial .planning/config.json with CLI availability, GitHub preference, and tier
+ * @param {string} projectDir - Project directory
+ * @param {object[]} clis - CLI detection results
+ * @param {boolean} useGitHub - Whether user wants GitHub integration (CLI-03)
+ * @param {string} tier - License tier ('starter' or 'pro')
+ */
+async function writeInitialConfig(projectDir, clis, useGitHub, tier) {
+  const planningDir = path.join(projectDir, '.planning');
+
+  // Create .planning directory if needed
+  if (!fs.existsSync(planningDir)) {
+    fs.mkdirSync(planningDir, { recursive: true });
+  }
+
+  // Build cliAvailable object from detection results
+  const cliAvailable = {};
+  for (const cli of clis) {
+    cliAvailable[cli.name] = cli.installed;
+  }
+
+  // Check if config already exists
+  const configPath = path.join(planningDir, 'config.json');
+  let config = {};
+
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } catch (_e) {
+      // Invalid JSON, start fresh
+    }
+  }
+
+  // Merge CLI availability into config
+  config.cliAvailable = cliAvailable;
+
+  // Store GitHub integration preference (CLI-03 requirement)
+  config.useGitHub = useGitHub;
+
+  // Store tier for later use
+  config.tier = tier;
+
+  // Write config
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  console.log(chalk.dim(`CLI availability saved to .planning/config.json`));
+  console.log(chalk.dim(`Tier: ${tier}`));
+  if (useGitHub) {
+    console.log(chalk.dim(`GitHub integration: enabled`));
+  }
+}
+
+/**
+ * Main scenario handler
+ * @param {string} tier - License tier ('starter' or 'pro')
+ * @param {object[]} clis - CLI detection results
+ * @param {boolean} useGitHub - Whether user wants GitHub integration (from CLI-03 prompt)
+ * @returns {Promise<string>} - Path to project directory
+ */
+async function handleScenario(tier, clis, useGitHub) {
+  const scenario = await askScenario();
+
+  if (scenario === 'fresh') {
+    return handleFreshStart(tier, clis, useGitHub);
+  } else {
+    return handleExistingClone(tier, clis, useGitHub);
+  }
+}
+
+module.exports = {
+  askScenario,
+  handleFreshStart,
+  handleExistingClone,
+  handleScenario
+};