forgedev 1.0.0

package/src/doctor-prompts.js

@@ -0,0 +1,295 @@
+const PROMPT_TEMPLATES = {
+  CLAUDE_MD_TOO_LONG: (issue) => {
+    const lines = issue.title.match(/(\d+) lines/)?.[1] || '?';
+    return `Read CLAUDE.md. It's ${lines} lines — too long for Claude Code to follow reliably (target: <150).
+
+Propose a split:
+- What stays in CLAUDE.md (universal rules, commands, pitfalls)
+- What moves to .claude/skills/ (schemas, specs, detailed lists)
+- What moves to backend/CLAUDE.md or src/CLAUDE.md (directory-scoped rules)
+
+Show me the proposal as a table. Do NOT modify until I approve.`;
+  },
+
+  UNAUTH_ENDPOINT: (issue) => {
+    const fileList = (issue.files || []).map(f => `- ${f}`).join('\n');
+    return `These endpoints are missing authentication:
+${fileList}
+
+For each: add the appropriate auth check.
+- FastAPI: add Depends(get_current_user) and appropriate RBAC
+- Next.js: add getServerSession or auth() check
+Follow the pattern used in endpoints that already have auth.
+Write a test for each endpoint confirming 401 without auth.`;
+  },
+
+  FLAKY_TESTS: (issue) => {
+    const fileList = (issue.files || []).map(f => `- ${f}`).join('\n');
+    return `These tests use waitForTimeout() or hardcoded delays — they will fail randomly:
+${fileList}
+
+For each:
+1. Replace waitForTimeout with waitForSelector, waitForResponse, or other event-based waits
+2. Replace cy.wait(N) with cy.intercept + cy.wait('@alias')
+3. Remove arbitrary setTimeout delays in tests
+4. Run each test 3x to verify it's stable`;
+  },
+
+  CROSS_DOMAIN_IMPORT: (issue) => {
+    const fileList = (issue.files || []).map(f => `- ${f}`).join('\n');
+    return `These files import across the frontend/backend boundary:
+${fileList}
+
+Fix by:
+1. Move shared types to a shared/ directory
+2. Use API calls instead of direct imports
+3. Duplicate small utilities rather than cross-importing
+Never import server code into client bundles.`;
+  },
+
+  BARE_EXCEPT: (issue) => {
+    const fileList = (issue.files || []).map(f => `- ${f}`).join('\n');
+    return `These locations use bare except: blocks (catch-all that swallows real errors):
+${fileList}
+
+For each: replace with a specific exception type.
+- If catching expected errors: except ValueError, except KeyError, etc.
+- If catching any exception for logging: except Exception as e: with logging
+- Never use bare except: — it hides bugs`;
+  },
+
+  MISSING_HEALTH: (issue) => {
+    return `Add a health check endpoint to the application.
+
+For FastAPI: Add a /health endpoint that returns {"status": "ok"} and optionally checks database connectivity.
+For Next.js: Add src/app/api/health/route.ts that returns {"status": "ok"}.
+For both: Include database connectivity check if a database is configured.
+
+This endpoint is used by load balancers and monitoring to verify the app is running.`;
+  },
+
+  MISSING_SHUTDOWN: (issue) => {
+    return `Add graceful shutdown handling to the application.
+
+For FastAPI: Use the lifespan context manager to handle startup/shutdown events.
+For Next.js: The framework handles this, but ensure any custom servers handle SIGTERM.
+For Docker: Ensure the process responds to SIGTERM within the stop_grace_period.
+
+On shutdown: close database connections, finish in-flight requests, flush logs.`;
+  },
+
+  MISSING_UAT: () => {
+    return `Generate UAT (User Acceptance Test) scenarios for this project.
+
+Read the codebase to understand all user-facing features, then create:
+1. docs/uat/UAT_TEMPLATE.md with test scenarios for each feature
+2. docs/uat/UAT_CHECKLIST.csv with a checklist format
+
+Each scenario should have:
+- Description (what's being tested)
+- Preconditions
+- Steps (numbered)
+- Expected result
+- Priority (P0 = critical path, P1 = important, P2 = nice to have)`;
+  },
+
+  SCATTERED_API_CALLS: (issue) => {
+    const fileList = (issue.files || []).map(f => `- ${f}`).join('\n');
+    return `These components call fetch() or axios directly instead of through a centralized API client:
+${fileList}
+
+Create a centralized API client (e.g., src/lib/api.ts or src/services/api.ts) with typed methods for each endpoint. Then refactor each component to use the centralized client.
+
+Benefits: single place to add auth headers, error handling, base URL config, and response typing.`;
+  },
+
+  LARGE_FILES: (issue) => {
+    const fileList = (issue.files || []).map(f => `- ${f}`).join('\n');
+    return `These files are very large and should be split:
+${fileList}
+
+For each:
+1. Identify logical sections that could be separate files
+2. Extract into focused modules (one responsibility per file)
+3. Update imports
+4. Run tests after each extraction
+
+Don't refactor all at once — one file per session.`;
+  },
+
+  MISSING_SCOPED_CLAUDE_MD: (issue) => {
+    const dir = issue.title.includes('frontend') ? 'frontend' : 'backend';
+    return `Create ${dir}/CLAUDE.md with ${dir}-specific rules.
+
+Keep it under 30 lines. Include:
+- Framework-specific patterns and conventions
+- Naming conventions for this layer
+- Common pitfalls specific to this part of the codebase
+
+This scopes rules so Claude Code only loads them when working in this directory.`;
+  },
+
+  UNUSED_DEPENDENCIES: (issue) => {
+    const fileList = (issue.files || []).map(f => `- ${f}`).join('\n');
+    return `These dependencies may be unused:
+${fileList}
+
+For each: search the codebase to confirm it's truly unused (some deps are used implicitly by frameworks or plugins). If confirmed unused, remove with npm uninstall.`;
+  },
+
+  HARDCODED_VALUES: (issue) => {
+    const fileList = (issue.files || []).map(f => `- ${f}`).join('\n');
+    return `These locations have hardcoded values that should be environment variables:
+${fileList}
+
+For each: move to .env and reference via process.env.VARIABLE_NAME (or os.environ in Python). Update .env.example with the variable name and a placeholder value.`;
+  },
+
+  UNUSED_EXPORTS: (issue) => {
+    const fileList = (issue.files || []).map(f => `- ${f}`).join('\n');
+    return `These exported symbols may not be imported anywhere:
+${fileList}
+
+For each: verify it's truly unused, then either remove the export keyword or delete the function/constant entirely. Run tests after each change.`;
+  },
+
+  DUPLICATE_CODE: (issue) => {
+    const fileList = (issue.files || []).map(f => `- ${f}`).join('\n');
+    return `These files contain duplicated code blocks:
+${fileList}
+
+For each group of duplicates: extract the shared logic into a utility function in the appropriate lib/ or utils/ directory. Update all call sites. Run tests after each extraction.`;
+  },
+
+  DEAD_FEATURES: (issue) => {
+    const fileList = (issue.files || []).map(f => `- ${f}`).join('\n');
+    return `These files appear to be dead or stub features:
+${fileList}
+
+For each: determine if the feature is planned (keep stub but add TODO with ticket reference) or abandoned (delete the file). Check git blame for context.`;
+  },
+
+  INLINE_AI_PROMPTS: (issue) => {
+    const fileList = (issue.files || []).map(f => `- ${f}`).join('\n');
+    return `These files have inline AI/LLM prompts mixed with application logic:
+${fileList}
+
+Extract all prompts into a dedicated prompts file (e.g., src/lib/prompts.ts or prompts/). This makes prompts easier to version, A/B test, and iterate on without changing application code.`;
+  },
+};
+
+export function generatePrompt(issue) {
+  const template = PROMPT_TEMPLATES[issue.promptId];
+  if (!template) {
+    return `Fix: ${issue.title}\n\nImpact: ${issue.impact}\nFiles: ${(issue.files || []).join(', ')}`;
+  }
+  return template(issue);
+}
+
+export function generateAllPrompts(issues) {
+  const sections = [];
+  let sessionNum = 1;
+
+  // Group by severity
+  const critical = issues.filter(i => i.severity === 'critical');
+  const warnings = issues.filter(i => i.severity === 'warning');
+  const info = issues.filter(i => i.severity === 'info');
+
+  for (const issue of [...critical, ...warnings, ...info]) {
+    const prompt = generatePrompt(issue);
+    const effortLabel = issue.effort === 'quick' ? '~10 min' :
+                        issue.effort === 'medium' ? '~30 min' : '~1 hour';
+
+    sections.push(`## Session ${sessionNum}: ${issue.title}
+**Severity:** ${issue.severity} | **Effort:** ${effortLabel}
+**Impact:** ${issue.impact}
+${issue.files && issue.files.length > 0 ? `**Files:** ${issue.files.join(', ')}` : ''}
+
+\`\`\`
+${prompt}
+\`\`\`
+`);
+    sessionNum++;
+  }
+
+  return `# Fix Prompts — Run These in Claude Code (In Order)
+
+${sections.join('\n')}
+Run each as a separate Claude Code session. /clear between sessions.
+`;
+}
+
+export function generateReport(issues, projectName) {
+  const critical = issues.filter(i => i.severity === 'critical');
+  const warnings = issues.filter(i => i.severity === 'warning');
+  const info = issues.filter(i => i.severity === 'info');
+  const healthy = []; // Could be populated by passing in good checks
+
+  let report = `# DevForge Doctor Report — ${projectName}
+Generated: ${new Date().toISOString().split('T')[0]}
+
+## Summary
+- Critical: ${critical.length} issues
+- Warning: ${warnings.length} issues
+- Info: ${info.length} suggestions
+
+`;
+
+  if (critical.length > 0) {
+    report += `## Critical Issues\n\n`;
+    for (let i = 0; i < critical.length; i++) {
+      const issue = critical[i];
+      const prompt = generatePrompt(issue);
+      report += `### ${i + 1}. ${issue.title}
+**Impact:** ${issue.impact}
+**Effort:** ${issue.effort}
+${issue.files && issue.files.length > 0 ? `**Files:** ${issue.files.join(', ')}` : ''}
+
+**Fix prompt:**
+\`\`\`
+${prompt}
+\`\`\`
+
+`;
+    }
+  }
+
+  if (warnings.length > 0) {
+    report += `## Warnings\n\n`;
+    for (let i = 0; i < warnings.length; i++) {
+      const issue = warnings[i];
+      const prompt = generatePrompt(issue);
+      report += `### ${i + 1}. ${issue.title}
+**Impact:** ${issue.impact}
+**Effort:** ${issue.effort}
+${issue.files && issue.files.length > 0 ? `**Files:** ${issue.files.join(', ')}` : ''}
+
+**Fix prompt:**
+\`\`\`
+${prompt}
+\`\`\`
+
+`;
+    }
+  }
+
+  if (info.length > 0) {
+    report += `## Suggestions\n\n`;
+    for (let i = 0; i < info.length; i++) {
+      const issue = info[i];
+      const prompt = generatePrompt(issue);
+      report += `### ${i + 1}. ${issue.title}
+**Impact:** ${issue.impact}
+**Effort:** ${issue.effort}
+
+**Fix prompt:**
+\`\`\`
+${prompt}
+\`\`\`
+
+`;
+    }
+  }
+
+  return report;
+}

package/src/doctor.js

@@ -0,0 +1,281 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import { log, ensureDir, writeFile } from './utils.js';
+import { scanProject } from './scanner.js';
+import { runAllChecks } from './doctor-checks.js';
+import { generatePrompt, generateAllPrompts, generateReport } from './doctor-prompts.js';
+import { askDoctorAction } from './prompts.js';
+
+export async function runDoctor(projectDir) {
+  console.log('');
+  console.log(chalk.bold.cyan('  🔨 DevForge Doctor') + chalk.dim(' — Project Health Check'));
+  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 vitals
+  printVitals(scan);
+
+  // Run all checks
+  const issues = runAllChecks(projectDir, scan);
+
+  if (issues.length === 0) {
+    console.log(chalk.green('  ✓ Your project looks healthy! No issues found.'));
+    console.log('');
+    return;
+  }
+
+  // Print issues summary
+  printIssues(issues);
+
+  // Ask what to do
+  const action = await askDoctorAction();
+
+  switch (action) {
+    case 'guided':
+      await guidedFix(issues);
+      break;
+    case 'report':
+      await saveReport(issues, scan, projectDir);
+      break;
+    case 'autofix':
+      await autoFixSafe(issues, projectDir);
+      break;
+    case 'prompts':
+      await exportPrompts(issues, projectDir);
+      break;
+  }
+}
+
+function printVitals(scan) {
+  console.log(chalk.bold('  📊 Project Vitals:'));
+  console.log('');
+
+  const parts = [];
+  if (scan.frontend.detected) {
+    parts.push(`  ${chalk.bold('Frontend:')}  ${scan.frontend.framework} (${scan.frontend.language})`);
+  }
+  if (scan.backend.detected) {
+    parts.push(`  ${chalk.bold('Backend:')}   ${scan.backend.framework} (${scan.backend.language})`);
+  }
+  if (scan.database.detected) {
+    parts.push(`  ${chalk.bold('Database:')}  ${scan.database.type} (${scan.database.orm})`);
+  }
+
+  const testParts = [scan.testing.unit, scan.testing.e2e, scan.testing.backend].filter(Boolean);
+  if (testParts.length) {
+    parts.push(`  ${chalk.bold('Testing:')}   ${testParts.join(' + ')}`);
+  }
+
+  if (scan.ai) {
+    parts.push(`  ${chalk.bold('AI:')}        integration detected`);
+  }
+
+  console.log(parts.join('\n'));
+  console.log('');
+}
+
+function printIssues(issues) {
+  const critical = issues.filter(i => i.severity === 'critical');
+  const warnings = issues.filter(i => i.severity === 'warning');
+  const info = issues.filter(i => i.severity === 'info');
+
+  console.log(chalk.bold('  Health Issues Found:'));
+  console.log('');
+
+  if (critical.length > 0) {
+    console.log(chalk.red.bold('  🔴 CRITICAL'));
+    for (let i = 0; i < critical.length; i++) {
+      const issue = critical[i];
+      console.log(chalk.red(`    ${i + 1}. ${issue.title}`));
+      console.log(chalk.dim(`       → ${issue.impact}`));
+      if (issue.files && issue.files.length > 0 && issue.files.length <= 3) {
+        console.log(chalk.dim(`       Files: ${issue.files.join(', ')}`));
+      }
+    }
+    console.log('');
+  }
+
+  if (warnings.length > 0) {
+    console.log(chalk.yellow.bold('  🟡 WARNING'));
+    for (let i = 0; i < warnings.length; i++) {
+      const issue = warnings[i];
+      console.log(chalk.yellow(`    ${critical.length + i + 1}. ${issue.title}`));
+      console.log(chalk.dim(`       → ${issue.impact}`));
+    }
+    console.log('');
+  }
+
+  if (info.length > 0) {
+    console.log(chalk.blue.bold('  ℹ️  SUGGESTIONS'));
+    for (let i = 0; i < info.length; i++) {
+      const issue = info[i];
+      console.log(chalk.blue(`    ${critical.length + warnings.length + i + 1}. ${issue.title}`));
+      console.log(chalk.dim(`       → ${issue.impact}`));
+    }
+    console.log('');
+  }
+
+  // Print good checks
+  const goodChecks = [];
+  if (!critical.some(i => i.promptId === 'UNAUTH_ENDPOINT') && !warnings.some(i => i.promptId === 'UNAUTH_ENDPOINT')) {
+    goodChecks.push('All endpoints have authentication');
+  }
+  if (!critical.some(i => i.promptId === 'FLAKY_TESTS')) {
+    goodChecks.push('No flaky test patterns detected');
+  }
+  if (!warnings.some(i => i.promptId === 'BARE_EXCEPT')) {
+    goodChecks.push('No bare except blocks');
+  }
+
+  if (goodChecks.length > 0) {
+    console.log(chalk.green.bold('  🟢 GOOD'));
+    for (const check of goodChecks) {
+      console.log(chalk.green(`    ✓ ${check}`));
+    }
+    console.log('');
+  }
+}
+
+async function guidedFix(issues) {
+  const { input } = await import('@inquirer/prompts');
+  const critical = issues.filter(i => i.severity === 'critical');
+  const warnings = issues.filter(i => i.severity === 'warning');
+  const allIssues = [...critical, ...warnings];
+
+  if (allIssues.length === 0) {
+    log.info('No critical or warning issues to fix.');
+    return;
+  }
+
+  for (let i = 0; i < allIssues.length; i++) {
+    const issue = allIssues[i];
+    const prompt = generatePrompt(issue);
+
+    console.log('');
+    console.log(chalk.bold(`  Issue ${i + 1} of ${allIssues.length}: ${issue.title}`));
+    console.log('');
+    console.log(chalk.dim(`  ${issue.impact}`));
+    console.log('');
+    console.log('  To fix this, open Claude Code and paste:');
+    console.log(chalk.cyan('  ┌' + '─'.repeat(68) + '┐'));
+    const promptLines = prompt.split('\n');
+    for (const line of promptLines) {
+      const padded = line.padEnd(68);
+      console.log(chalk.cyan('  │ ') + padded + chalk.cyan(' │'));
+    }
+    console.log(chalk.cyan('  └' + '─'.repeat(68) + '┘'));
+
+    if (i < allIssues.length - 1) {
+      await input({ message: 'Press enter for next issue, or type q to quit:' }).then(answer => {
+        if (answer.toLowerCase() === 'q') {
+          process.exit(0);
+        }
+      });
+    }
+  }
+
+  console.log('');
+  log.success('All issues shown. Fix them in Claude Code one at a time.');
+  console.log('');
+}
+
+async function saveReport(issues, scan, projectDir) {
+  const report = generateReport(issues, scan.projectName);
+  const reportPath = path.join(projectDir, 'docs', 'doctor-report.md');
+  writeFile(reportPath, report);
+  console.log('');
+  log.success(`Report saved to ${path.relative(projectDir, reportPath)}`);
+  console.log('');
+}
+
+async function autoFixSafe(issues, projectDir) {
+  console.log('');
+  console.log('  Auto-fixing safe issues...');
+  console.log('');
+
+  let fixed = 0;
+
+  // Create missing directories
+  const dirsToCreate = ['docs/uat', 'docs/plans'];
+  for (const dir of dirsToCreate) {
+    const fullPath = path.join(projectDir, dir);
+    if (!fs.existsSync(fullPath)) {
+      ensureDir(fullPath);
+      console.log(chalk.green(`  ✓ Created ${dir}/ directory`));
+      fixed++;
+    }
+  }
+
+  // Fix hook script permissions (Unix only)
+  if (process.platform !== 'win32') {
+    const hooksDir = path.join(projectDir, '.claude', 'hooks');
+    if (fs.existsSync(hooksDir)) {
+      const hookFiles = fs.readdirSync(hooksDir).filter(f => f.endsWith('.sh'));
+      for (const hookFile of hookFiles) {
+        const hookPath = path.join(hooksDir, hookFile);
+        try {
+          fs.chmodSync(hookPath, '755');
+          console.log(chalk.green(`  ✓ Fixed ${path.join('.claude/hooks', hookFile)} permissions (chmod +x)`));
+          fixed++;
+        } catch {
+          // Skip
+        }
+      }
+    }
+  }
+
+  // Add missing .gitignore entries
+  const gitignorePath = path.join(projectDir, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf-8');
+    const entriesToAdd = [];
+
+    if (!content.includes('.claude/todos')) entriesToAdd.push('.claude/todos');
+    if (!content.includes('.claude/plans')) entriesToAdd.push('.claude/plans');
+
+    if (entriesToAdd.length > 0) {
+      const addition = '\n# Claude Code temp files\n' + entriesToAdd.join('\n') + '\n';
+      fs.appendFileSync(gitignorePath, addition);
+      console.log(chalk.green(`  ✓ Added ${entriesToAdd.length} entries to .gitignore`));
+      fixed++;
+    }
+  }
+
+  const skipped = issues.filter(i => !i.autoFixable).length;
+
+  if (fixed === 0) {
+    console.log(chalk.dim('  Nothing to auto-fix.'));
+  }
+
+  if (skipped > 0) {
+    console.log(chalk.dim(`  ⊘ Skipped ${skipped} issues that need Claude Code to fix`));
+  }
+
+  console.log('');
+  if (skipped > 0) {
+    console.log(`  For the remaining issues, run: ${chalk.cyan('npx devforge doctor')} → option 1 or 2`);
+    console.log('');
+  }
+}
+
+async function exportPrompts(issues, projectDir) {
+  const content = generateAllPrompts(issues);
+  const promptsPath = path.join(projectDir, 'docs', 'doctor-prompts.md');
+  writeFile(promptsPath, content);
+  console.log('');
+  log.success(`Fix prompts saved to ${path.relative(projectDir, promptsPath)}`);
+  console.log(chalk.dim('  Open Claude Code and work through them one at a time.'));
+  console.log(chalk.dim('  /clear between sessions.'));
+  console.log('');
+}