forgedev 1.0.0

package/src/guided.js

@@ -0,0 +1,315 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import { log, writeFile } from './utils.js';
+import { askDescription, askAdjustment, askGuidedConfirm } from './prompts.js';
+import { recommend } from './recommender.js';
+
+const FEATURE_MAP = {
+  auth: ['login', 'sign up', 'signup', 'account', 'user', 'password', 'register', 'authentication'],
+  realtime: ['real-time', 'realtime', 'live', 'instant', 'track', 'notify', 'chat', 'websocket', 'stream'],
+  ai: ['ai', 'smart', 'auto-generate', 'recommend', 'suggest', 'intelligent', 'gpt', 'llm', 'chatbot', 'openai', 'anthropic', 'claude', 'embedding', 'vector', 'rag', 'ml', 'machine learning'],
+  payments: ['pay', 'order', 'purchase', 'subscribe', 'billing', 'stripe', 'price', 'cart', 'checkout', 'invoice'],
+  uploads: ['upload', 'image', 'photo', 'file', 'document', 'pdf', 'attachment', 'media', 's3', 'storage'],
+  dashboard: ['dashboard', 'analytics', 'report', 'chart', 'stats', 'metrics', 'admin panel'],
+  roles: ['admin', 'role', 'permission', 'owner', 'manager', 'staff', 'customer', 'moderator'],
+  email: ['email', 'notification', 'send', 'newsletter', 'invite', 'alert'],
+  search: ['search', 'filter', 'browse', 'find', 'catalog', 'list', 'sort'],
+  scheduling: ['schedule', 'book', 'appointment', 'calendar', 'reserve', 'time slot', 'booking'],
+};
+
+const FRONTEND_SIGNALS = ['dashboard', 'landing', 'ui', 'page', 'form', 'website', 'portal', 'interface', 'responsive', 'frontend', 'display', 'view', 'browse', 'menu'];
+const BACKEND_ONLY_SIGNALS = ['api', 'endpoint', 'webhook', 'microservice', 'worker', 'cron', 'queue', 'batch', 'pipeline'];
+const PYTHON_SIGNALS = ['python', 'fastapi', 'flask', 'django', 'ml', 'data science', 'scraping', 'pandas', 'numpy', 'tensorflow'];
+
+const ENTITY_PATTERNS = [
+  /manage (?:their |the )?(\w+)/gi,
+  /(?:create|add|edit|update|delete|view|list|track|monitor) (?:their |the |a |an )?(\w+)/gi,
+  /(\w+) can /gi,
+  /store (\w+)/gi,
+];
+
+const STOP_WORDS = new Set([
+  'i', 'a', 'an', 'the', 'and', 'or', 'but', 'is', 'are', 'was', 'were',
+  'be', 'been', 'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will',
+  'would', 'could', 'should', 'may', 'might', 'can', 'shall', 'to', 'of',
+  'in', 'for', 'on', 'with', 'at', 'by', 'from', 'it', 'its', 'this',
+  'that', 'these', 'those', 'my', 'your', 'their', 'our', 'them', 'they',
+  'we', 'you', 'me', 'him', 'her', 'us', 'what', 'which', 'who', 'whom',
+  'want', 'need', 'like', 'app', 'application', 'system', 'platform',
+  'where', 'when', 'how', 'not', 'no', 'so', 'if', 'then', 'also',
+]);
+
+export function analyzeDescription(text) {
+  if (!text || !text.trim()) {
+    return { features: [], entities: [], suggestedServiceType: 'full_stack', suggestedLanguage: 'typescript' };
+  }
+
+  const lower = text.toLowerCase();
+  const features = [];
+
+  for (const [feature, keywords] of Object.entries(FEATURE_MAP)) {
+    if (keywords.some(k => lower.includes(k))) {
+      features.push(feature);
+    }
+  }
+
+  // Extract entities
+  const entitySet = new Set();
+  for (const pattern of ENTITY_PATTERNS) {
+    let match;
+    const regex = new RegExp(pattern.source, pattern.flags);
+    while ((match = regex.exec(lower)) !== null) {
+      const entity = match[1];
+      if (entity && entity.length > 2 && !STOP_WORDS.has(entity)) {
+        entitySet.add(entity);
+      }
+    }
+  }
+  const entities = [...entitySet];
+
+  // Determine if frontend/backend needed
+  const needsFrontend = FRONTEND_SIGNALS.some(s => lower.includes(s)) ||
+    features.some(f => ['dashboard', 'search', 'uploads'].includes(f)) ||
+    !BACKEND_ONLY_SIGNALS.some(s => lower.includes(s));
+  const needsBackend = BACKEND_ONLY_SIGNALS.some(s => lower.includes(s)) ||
+    features.some(f => ['auth', 'payments', 'email', 'ai'].includes(f)) ||
+    needsFrontend; // full-stack apps always need a backend
+
+  // Determine language
+  const suggestPython = PYTHON_SIGNALS.some(s => lower.includes(s));
+  const suggestedLanguage = suggestPython ? 'python' : 'typescript';
+
+  // Determine service type
+  let suggestedServiceType;
+  if (needsFrontend && needsBackend && suggestPython) {
+    suggestedServiceType = 'full_stack'; // will become polyglot
+  } else if (needsFrontend && needsBackend) {
+    suggestedServiceType = 'full_stack';
+  } else if (!needsFrontend && needsBackend) {
+    suggestedServiceType = 'api_service';
+  } else {
+    suggestedServiceType = 'web_app';
+  }
+
+  // AI service override — if AI is the primary focus
+  if (features.includes('ai') && !features.includes('dashboard') && !features.includes('payments')) {
+    suggestedServiceType = 'ai_service';
+  }
+
+  return { features, entities, suggestedServiceType, suggestedLanguage };
+}
+
+export function mapFeaturesToStack(analysis) {
+  const refinements = {
+    language: analysis.suggestedLanguage,
+    auth: analysis.features.includes('auth') || analysis.features.includes('roles'),
+    ai: analysis.features.includes('ai'),
+    fileUploads: analysis.features.includes('uploads'),
+    realtime: analysis.features.includes('realtime'),
+    deployment: 'docker',
+    claudeCode: true,
+  };
+
+  const stackConfig = recommend(analysis.suggestedServiceType, refinements);
+  return stackConfig;
+}
+
+export function buildGuidedPreview(analysis, stackConfig) {
+  const lines = [];
+
+  lines.push(chalk.bold('  What you\'ll get:'));
+
+  // Group by detected entities/roles
+  const hasRoles = analysis.features.includes('roles');
+  const entities = analysis.entities;
+
+  if (entities.length > 0) {
+    lines.push('  ├── A website where you can:');
+    for (const entity of entities.slice(0, 5)) {
+      lines.push(`  │   • Manage ${entity}`);
+    }
+    lines.push('  │');
+  } else {
+    lines.push('  ├── A website for your application');
+    lines.push('  │');
+  }
+
+  // Feature descriptions in plain English
+  if (analysis.features.includes('auth') || analysis.features.includes('roles')) {
+    const roleDesc = hasRoles ? ' (with different roles like admin and user)' : '';
+    lines.push(`  ├── User accounts${roleDesc}`);
+  }
+  if (analysis.features.includes('dashboard')) {
+    lines.push('  ├── A dashboard to see your data at a glance');
+  }
+  if (analysis.features.includes('realtime')) {
+    lines.push('  ├── Real-time updates (changes appear instantly)');
+  }
+  if (analysis.features.includes('payments')) {
+    lines.push('  ├── Payment processing for orders or subscriptions');
+  }
+  if (analysis.features.includes('uploads')) {
+    lines.push('  ├── File uploads (images, documents, etc.)');
+  }
+  if (analysis.features.includes('search')) {
+    lines.push('  ├── Search and filtering');
+  }
+  if (analysis.features.includes('scheduling')) {
+    lines.push('  ├── Scheduling and bookings');
+  }
+  if (analysis.features.includes('email')) {
+    lines.push('  ├── Email notifications');
+  }
+  if (analysis.features.includes('ai')) {
+    lines.push('  ├── AI-powered features');
+  }
+
+  // Always included
+  lines.push('  ├── A database to store all your data');
+  lines.push('  │');
+  lines.push('  └── Developer tools:');
+  lines.push('      • Code quality checks (catches errors automatically)');
+  lines.push('      • Guided workflows (type /project:help anytime you\'re stuck)');
+  lines.push('      • Testing templates');
+
+  return lines.join('\n');
+}
+
+export function generateGettingStarted(projectName, stackConfig) {
+  const isPolyglot = stackConfig.stackId === 'polyglot-fullstack';
+  const isFastapi = stackConfig.stackId === 'fastapi-backend';
+
+  let setupCommands;
+  if (isFastapi) {
+    setupCommands = `cd backend
+python -m venv venv
+source venv/bin/activate  # or venv\\\\Scripts\\\\activate on Windows
+pip install -r requirements.txt
+uvicorn app.main:app --reload`;
+  } else if (isPolyglot) {
+    setupCommands = `# Start the database:
+docker compose up -d postgres
+
+# Start the frontend:
+cd frontend && npm install && npm run dev
+
+# In another terminal, start the backend:
+cd backend && pip install -r requirements.txt && uvicorn app.main:app --reload`;
+  } else {
+    setupCommands = `npm install
+npm run dev`;
+  }
+
+  const devUrl = isFastapi ? 'http://localhost:8000/docs' : 'http://localhost:3000';
+
+  return `# Getting Started with ${projectName}
+
+## What Just Happened?
+
+DevForge created a starter version of your app with all the basic
+building blocks in place. Think of it like getting a house with the
+foundation, walls, and plumbing already done — you just need to
+furnish and decorate it.
+
+## Your Project Structure (Plain English)
+
+\`\`\`
+📁 ${projectName}/
+├── src/          ← This is where your app's code lives
+│   ├── app/      ← The pages people see in their browser
+│   └── lib/      ← Helper code (like a toolbox)
+├── docs/         ← Guides and documentation (you're reading one now!)
+├── .claude/      ← AI assistant configuration (helps catch mistakes)
+└── README.md     ← Overview of your project
+\`\`\`
+
+## First Steps
+
+### 1. Start your app
+Open a terminal in this folder and run:
+\`\`\`bash
+${setupCommands}
+\`\`\`
+
+Then open ${devUrl} in your browser. You should see your app!
+
+### 2. Make your first change
+Open a file in your code editor. Change some text. Save.
+Your browser should update automatically.
+
+### 3. Get AI help (if you have Claude Code)
+Type \`/project:help\` in Claude Code. It will ask what you're trying
+to do and give you step-by-step guidance.
+
+## Common Tasks
+
+| I want to...                | Do this                                        |
+|-----------------------------|------------------------------------------------|
+| Add a new page              | Create a new folder in src/app/ with a page file |
+| Change how something looks  | Edit the styles in the component                |
+| Add a new feature           | Type /project:help → "Start a new feature"      |
+| Fix a bug                   | Type /project:help → "Fix a bug"                |
+| Check if everything works   | Type /project:status                            |
+`;
+}
+
+export async function runGuidedFlow(projectName, outputDir, scaffoldFn) {
+  let description = await askDescription();
+
+  if (!description || !description.trim()) {
+    log.error('Please provide a description of what you want to build.');
+    process.exit(1);
+  }
+
+  let analysis = analyzeDescription(description);
+  let stackConfig = mapFeaturesToStack(analysis);
+
+  if (stackConfig.supported === false) {
+    log.warn('Could not determine a supported stack from your description.');
+    log.info('Try describing a web app, API, or full-stack application.');
+    process.exit(1);
+  }
+
+  stackConfig.projectName = projectName;
+
+  // Show preview loop
+  let confirmed = false;
+  while (!confirmed) {
+    console.log('');
+    console.log(chalk.bold('  Got it! Here\'s what I\'ll set up for you:'));
+    console.log('');
+    console.log(buildGuidedPreview(analysis, stackConfig));
+    console.log('');
+
+    const choice = await askGuidedConfirm();
+
+    if (choice === 'yes') {
+      confirmed = true;
+    } else {
+      const adjustment = await askAdjustment();
+      if (adjustment && adjustment.trim()) {
+        // Re-analyze with the combined description
+        description = description + '. ' + adjustment;
+        analysis = analyzeDescription(description);
+        stackConfig = mapFeaturesToStack(analysis);
+        if (stackConfig.supported === false) {
+          log.warn('Could not determine a supported stack. Using previous configuration.');
+          stackConfig = mapFeaturesToStack(analyzeDescription(description.split('. ').slice(0, -1).join('. ')));
+        }
+        stackConfig.projectName = projectName;
+        console.log('');
+        log.info('Updated!');
+      }
+    }
+  }
+
+  // Scaffold
+  await scaffoldFn(outputDir, stackConfig);
+
+  // Generate getting-started.md for guided mode
+  const gettingStartedContent = generateGettingStarted(projectName, stackConfig);
+  writeFile(
+    path.join(outputDir, 'docs', 'getting-started.md'),
+    gettingStartedContent
+  );
+}

package/src/index.js

@@ -0,0 +1,148 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { execSync } from 'node:child_process';
+import chalk from 'chalk';
+import { log, toKebabCase } from './utils.js';
+import { askServiceType, askRefinements, askNewMode, confirmStack } from './prompts.js';
+import { recommend } from './recommender.js';
+import { compose } from './composer.js';
+import { generateClaudeConfig } from './claude-configurator.js';
+import { generateUAT } from './uat-generator.js';
+
+export async function runNew(projectName) {
+  const safeName = toKebabCase(projectName);
+  const outputDir = path.resolve(process.cwd(), safeName);
+
+  if (fs.existsSync(outputDir)) {
+    log.error(`Directory "${safeName}" already exists. Choose a different name or delete it first.`);
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log(chalk.bold.cyan('  🔨 DevForge') + chalk.dim(' — Let\'s build something.'));
+  console.log('');
+
+  const mode = await askNewMode();
+
+  if (mode === 'guided') {
+    const { runGuidedFlow } = await import('./guided.js');
+    await runGuidedFlow(safeName, outputDir, scaffold);
+  } else {
+    await runDeveloperFlow(safeName, outputDir);
+  }
+}
+
+async function runDeveloperFlow(safeName, outputDir) {
+  const serviceType = await askServiceType();
+  const refinements = await askRefinements(serviceType);
+  const stackConfig = recommend(serviceType, refinements);
+
+  if (stackConfig.supported === false) {
+    log.warn(stackConfig.message);
+    process.exit(0);
+  }
+
+  stackConfig.projectName = safeName;
+
+  const confirmed = await confirmStack(stackConfig);
+  if (!confirmed) {
+    log.info('Cancelled.');
+    process.exit(0);
+  }
+
+  await scaffold(outputDir, stackConfig);
+}
+
+export async function scaffold(outputDir, stackConfig) {
+  console.log('');
+  const totalSteps = stackConfig.claudeCode ? 4 : 3;
+  let step = 0;
+
+  step++;
+  log.step(step, totalSteps, 'Scaffolding project structure...');
+  await compose(outputDir, stackConfig);
+
+  if (stackConfig.claudeCode) {
+    step++;
+    log.step(step, totalSteps, 'Generating Claude Code infrastructure...');
+    await generateClaudeConfig(outputDir, stackConfig);
+  }
+
+  step++;
+  log.step(step, totalSteps, 'Generating UAT templates...');
+  await generateUAT(outputDir, stackConfig);
+
+  step++;
+  log.step(step, totalSteps, 'Initializing git repository...');
+  initGit(outputDir);
+
+  console.log('');
+  log.success('Done! Your project is ready.');
+  console.log('');
+  printNextSteps(stackConfig.projectName, stackConfig);
+}
+
+function initGit(outputDir) {
+  try {
+    execSync('git init', { cwd: outputDir, stdio: 'ignore' });
+  } catch {
+    // git not available — skip silently
+  }
+}
+
+export function printNextSteps(projectName, config, isGuided = false) {
+  if (isGuided) {
+    console.log(chalk.bold('  To start building:'));
+    console.log(`    cd ${projectName}`);
+    console.log('    npm install');
+    console.log('    npm run dev');
+    console.log('');
+    console.log(`  Then open your browser to ${chalk.cyan('http://localhost:3000')}`);
+    console.log('');
+    console.log(chalk.bold('  📖 New to coding? Here\'s what to do next:'));
+    console.log('    1. Open this folder in VS Code (or any code editor)');
+    console.log('    2. If you have Claude Code installed, type /project:help');
+    console.log('       — it will guide you step by step');
+    console.log('    3. Or read docs/getting-started.md for a beginner-friendly walkthrough');
+    console.log('');
+    return;
+  }
+
+  console.log(chalk.bold('  Next steps:'));
+  console.log(`    cd ${projectName}`);
+
+  if (config.stackId === 'nextjs-fullstack') {
+    console.log('    npm install');
+    console.log('    cp .env.example .env');
+    console.log('    npx prisma db push');
+    console.log('    npm run dev');
+  } else if (config.stackId === 'fastapi-backend') {
+    console.log('    cd backend');
+    console.log('    python -m venv venv');
+    console.log('    source venv/bin/activate  # or venv\\Scripts\\activate on Windows');
+    console.log('    pip install -r requirements.txt');
+    console.log('    cp .env.example .env');
+    console.log('    uvicorn app.main:app --reload');
+  } else if (config.stackId === 'polyglot-fullstack') {
+    console.log('    docker compose up -d postgres');
+    console.log('    # Frontend:');
+    console.log('    cd frontend && npm install && npm run dev');
+    console.log('    # Backend:');
+    console.log('    cd backend && pip install -r requirements.txt && uvicorn app.main:app --reload');
+  }
+
+  if (config.claudeCode) {
+    console.log('');
+    console.log(chalk.bold('  Claude Code:'));
+    console.log('    Your project includes pre-configured Claude Code infrastructure:');
+    console.log(chalk.dim('    - CLAUDE.md          (project context + rules)'));
+    console.log(chalk.dim('    - .claude/hooks/     (auto-lint, quality gates)'));
+    console.log(chalk.dim('    - .claude/skills/    (framework knowledge)'));
+    console.log(chalk.dim('    - .claude/agents/    (verification chain)'));
+    console.log(chalk.dim('    - .claude/commands/  (audit, verify, pre-pr)'));
+    console.log(chalk.dim('    - docs/prompt-library.md'));
+    console.log(chalk.dim('    - docs/uat/          (acceptance testing)'));
+  }
+
+  console.log('');
+}

package/src/init-mode.js

@@ -0,0 +1,134 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import { log } from './utils.js';
+import { scanProject } from './scanner.js';
+import { generateClaudeConfig } from './claude-configurator.js';
+import { generateUAT } from './uat-generator.js';
+
+export async function runInit(projectDir) {
+  console.log('');
+  console.log(chalk.bold.cyan('  🔨 DevForge') + chalk.dim(' — Adding dev guardrails'));
+  console.log('');
+  console.log('  Scanning...');
+  console.log('');
+
+  const scan = scanProject(projectDir);
+
+  if (scan.stackId === 'unknown') {
+    log.warn('Could not detect a supported stack in this directory.');
+    log.dim('  Supported: Next.js, FastAPI, or polyglot (Next.js + FastAPI)');
+    log.dim('  Make sure you\'re in the project root directory.');
+    process.exit(1);
+  }
+
+  // Print what was detected
+  const detected = [];
+  if (scan.frontend.detected) {
+    detected.push(`${scan.frontend.framework} (${scan.frontend.language})`);
+  }
+  if (scan.backend.detected) {
+    detected.push(`${scan.backend.framework} (${scan.backend.language})`);
+  }
+  if (scan.database.detected) {
+    detected.push(`${scan.database.type} (${scan.database.orm})`);
+  }
+  if (scan.testing.unit) detected.push(scan.testing.unit);
+  if (scan.testing.e2e) detected.push(scan.testing.e2e);
+  if (scan.testing.backend) detected.push(scan.testing.backend);
+
+  console.log(chalk.bold('  Detected: ') + detected.join(' + '));
+  if (scan.infrastructure.hasClaudeMd) {
+    console.log(chalk.dim(`  CLAUDE.md exists (${scan.infrastructure.claudeMdLines} lines)`));
+  }
+  console.log('');
+
+  // Build a synthetic stackConfig from scan results
+  const stackConfig = buildConfigFromScan(scan);
+
+  // Install infrastructure
+  console.log(chalk.bold('  Installing:'));
+
+  // Generate Claude Code infrastructure (skips CLAUDE.md if it exists, merges settings.json if it exists)
+  const skipClaudeMd = scan.infrastructure.hasClaudeMd;
+  const mergeSettings = scan.infrastructure.hasHooks;
+  await generateClaudeConfig(projectDir, stackConfig, { skipClaudeMd, mergeSettings });
+
+  if (!skipClaudeMd) {
+    console.log(chalk.green('  ✓ ') + 'CLAUDE.md — project context + rules');
+  } else {
+    console.log(chalk.yellow('  ⊘ ') + `CLAUDE.md — exists (tip: run ${chalk.cyan('/project:optimize-claude-md')} to slim it)`);
+  }
+
+  if (!scan.infrastructure.hasHooks) {
+    console.log(chalk.green('  ✓ ') + '.claude/hooks/ — auto-lint, quality gate, file protection');
+  } else {
+    console.log(chalk.yellow('  ⊘ ') + '.claude/hooks/ — already configured');
+  }
+
+  if (!scan.infrastructure.hasAgents) {
+    console.log(chalk.green('  ✓ ') + '.claude/agents/ — code quality, security, spec validator');
+  }
+  if (!scan.infrastructure.hasCommands) {
+    console.log(chalk.green('  ✓ ') + '.claude/commands/ — help, status, next, done, audit, pre-pr');
+  }
+  if (!scan.infrastructure.hasSkills) {
+    console.log(chalk.green('  ✓ ') + '.claude/skills/ — framework-specific knowledge');
+  }
+
+  // Generate UAT templates
+  if (!scan.infrastructure.hasUAT) {
+    await generateUAT(projectDir, stackConfig);
+    console.log(chalk.green('  ✓ ') + 'docs/uat/ — acceptance test templates');
+  } else {
+    console.log(chalk.yellow('  ⊘ ') + 'docs/uat/ — already exists');
+  }
+
+  console.log('');
+  log.success('  Done. Type /project:help to get started.');
+  console.log('');
+}
+
+export function buildConfigFromScan(scan) {
+  const config = {
+    projectName: scan.projectName,
+    stackId: scan.stackId,
+    serviceType: scan.stackId === 'fastapi-backend' ? 'api_service' : 'full_stack',
+    frontend: null,
+    backend: null,
+    database: null,
+    auth: scan.auth.detected ? scan.auth.type : null,
+    testing: scan.testing,
+    ai: scan.ai,
+    realtime: false,
+    fileUploads: false,
+    deployment: scan.deployment || 'docker',
+    claudeCode: true,
+    templateModules: [],
+  };
+
+  if (scan.frontend.detected) {
+    config.frontend = {
+      framework: scan.frontend.framework,
+      language: scan.frontend.language,
+      styling: 'tailwind',
+      ui: 'shadcn',
+    };
+  }
+
+  if (scan.backend.detected) {
+    config.backend = {
+      framework: scan.backend.framework,
+      language: scan.backend.language,
+      orm: scan.database.detected ? scan.database.orm : (scan.backend.language === 'python' ? 'sqlalchemy' : 'prisma'),
+    };
+  }
+
+  if (scan.database.detected) {
+    config.database = {
+      type: scan.database.type,
+      orm: scan.database.orm,
+    };
+  }
+
+  return config;
+}