popeye-cli 1.7.0 → 1.9.0

package/src/cli/commands/review.ts

@@ -0,0 +1,187 @@
+/**
+ * CLI command: popeye review
+ *
+ * Runs a post-build audit/review of the project, producing a structured
+ * report with findings and optional recovery tasks.
+ *
+ * Pattern follows doctor.ts command factory.
+ */
+
+import { Command } from 'commander';
+import path from 'node:path';
+import {
+  printHeader,
+  printSuccess,
+  printError,
+  printWarning,
+  printInfo,
+  printKeyValue,
+  printSection,
+} from '../output.js';
+import { runAuditMode, type AuditModeRunOptions } from '../../workflow/audit-mode.js';
+import type { AuditModeResult, ComponentKind } from '../../types/audit.js';
+
+// ---------------------------------------------------------------------------
+// Run audit (exported for testability + slash command reuse)
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute the audit and print results to the console.
+ *
+ * @param projectDir - Absolute path to the project directory.
+ * @param options - CLI options.
+ * @returns The audit result.
+ */
+export async function runReview(
+  projectDir: string,
+  options: {
+    depth?: number;
+    strict?: boolean;
+    format?: 'json' | 'md' | 'both';
+    recover?: boolean;
+    target?: string;
+  } = {}
+): Promise<AuditModeResult> {
+  printHeader('Project Audit / Review');
+
+  const auditOptions: AuditModeRunOptions = {
+    projectDir,
+    depth: options.depth ?? 2,
+    runTests: true,
+    strict: options.strict ?? false,
+    format: options.format ?? 'both',
+    autoRecover: options.recover ?? true,
+    target: (options.target ?? 'all') as 'all' | ComponentKind,
+    onProgress: (stage, message) => {
+      printInfo(`[${stage}] ${message}`);
+    },
+  };
+
+  const result = await runAuditMode(auditOptions);
+
+  if (!result.success) {
+    printError(`Audit failed: ${result.error}`);
+    return result;
+  }
+
+  // Print summary
+  console.log();
+  printSection('Summary');
+  printKeyValue('Project', result.summary.projectName);
+  printKeyValue('Language', result.summary.language);
+  printKeyValue('Source files', result.summary.totalSourceFiles);
+  printKeyValue('Test files', result.summary.totalTestFiles);
+  printKeyValue('Lines of code', result.summary.totalLinesOfCode);
+  printKeyValue('Components', result.summary.componentCount);
+
+  // Print score
+  console.log();
+  printSection('Audit Score');
+  const score = result.audit.overallScore;
+  if (score >= 80) {
+    printSuccess(`Overall: ${score}/100`);
+  } else if (score >= 60) {
+    printWarning(`Overall: ${score}/100`);
+  } else {
+    printError(`Overall: ${score}/100`);
+  }
+
+  // Print finding counts
+  if (result.audit.criticalCount > 0) {
+    printError(`Critical: ${result.audit.criticalCount}`);
+  }
+  if (result.audit.majorCount > 0) {
+    printWarning(`Major: ${result.audit.majorCount}`);
+  }
+  if (result.audit.minorCount > 0) {
+    printInfo(`Minor: ${result.audit.minorCount}`);
+  }
+  if (result.audit.infoCount > 0) {
+    printInfo(`Info: ${result.audit.infoCount}`);
+  }
+
+  // Recommendation
+  console.log();
+  const rec = result.audit.recommendation;
+  if (rec === 'pass') {
+    printSuccess(`Recommendation: ${rec}`);
+  } else if (rec === 'fix-and-recheck') {
+    printWarning(`Recommendation: ${rec}`);
+  } else {
+    printError(`Recommendation: ${rec}`);
+  }
+
+  // Report paths
+  if (Object.keys(result.reportPaths).length > 0) {
+    console.log();
+    printSection('Reports');
+    if (result.reportPaths.auditMd) {
+      printInfo(`Markdown: ${result.reportPaths.auditMd}`);
+    }
+    if (result.reportPaths.auditJson) {
+      printInfo(`JSON: ${result.reportPaths.auditJson}`);
+    }
+    if (result.reportPaths.recoveryMd) {
+      printWarning(`Recovery plan: ${result.reportPaths.recoveryMd}`);
+    }
+  }
+
+  // Recovery info
+  if (result.recovery) {
+    console.log();
+    printSection('Recovery Plan');
+    printWarning(
+      `${result.recovery.milestones.length} recovery milestone(s), estimated ${result.recovery.estimatedEffort}`
+    );
+    if (auditOptions.autoRecover) {
+      printSuccess('Recovery milestones injected — run /resume to execute.');
+    } else {
+      printInfo('Run without --no-recover to auto-inject recovery milestones.');
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Commander command factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the `popeye review` CLI command.
+ *
+ * @returns Commander command instance.
+ */
+export function createReviewCommand(): Command {
+  const cmd = new Command('review')
+    .alias('audit')
+    .description('Run a post-build audit/review of the project')
+    .argument('[directory]', 'Project directory', '.')
+    .option('-d, --depth <level>', 'Audit depth: 1=shallow, 2=standard, 3=deep', '2')
+    .option('-s, --strict', 'Enable strict mode (higher standards)', false)
+    .option('-f, --format <type>', 'Output format: json, md, both', 'both')
+    .option('--no-recover', 'Skip auto-injection of recovery milestones')
+    .option('-t, --target <kind>', 'Audit target: all, frontend, backend, website', 'all')
+    .action(async (directory: string, opts: Record<string, string | boolean>) => {
+      const projectDir = path.resolve(directory);
+
+      try {
+        const result = await runReview(projectDir, {
+          depth: parseInt(opts.depth as string, 10),
+          strict: opts.strict as boolean,
+          format: opts.format as 'json' | 'md' | 'both',
+          recover: opts.recover as boolean,
+          target: opts.target as string,
+        });
+
+        if (!result.success) {
+          process.exit(1);
+        }
+      } catch (err) {
+        printError(err instanceof Error ? err.message : 'Audit failed');
+        process.exit(1);
+      }
+    });
+
+  return cmd;
+}

package/src/cli/index.ts

@@ -15,6 +15,9 @@ import {
   createResetCommand,
   createCancelCommand,
   createConfigCommand,
+  createDbCommand,
+  createDoctorCommand,
+  createReviewCommand,
 } from './commands/index.js';
 import { startInteractiveMode } from './interactive.js';
 import { printError } from './output.js';
@@ -54,6 +57,9 @@ export function createProgram(): Command {
   program.addCommand(createResetCommand());
   program.addCommand(createCancelCommand());
   program.addCommand(createConfigCommand());
+  program.addCommand(createDbCommand());
+  program.addCommand(createDoctorCommand());
+  program.addCommand(createReviewCommand());
 
   // Interactive mode command
   program

package/src/cli/interactive.ts

@@ -844,6 +844,9 @@ function showHelp(): void {
     ['/new <idea>', 'Force start a new project (skips existing check)'],
     ['/resume', 'Resume interrupted project'],
     ['/overview [fix]', 'Project review with analysis; fix to auto-discover docs'],
+    ['/db [action]', 'Database management (status/configure/apply)'],
+    ['/doctor', 'Run database and project readiness checks'],
+    ['/review', 'Run post-build audit/review with findings and recovery'],
     ['/clear', 'Clear screen'],
     ['/exit', 'Exit Popeye'],
   ];
@@ -1012,6 +1015,19 @@ async function handleInput(input: string, state: SessionState): Promise<boolean>
         }
         break;
 
+      case '/db':
+        await handleDbSlashCommand(state, args);
+        break;
+
+      case '/doctor':
+        await handleDoctorSlashCommand(state);
+        break;
+
+      case '/review':
+      case '/audit':
+        await handleReviewSlashCommand(state, args);
+        break;
+
       default:
         printError(`Unknown command: ${cmd}`);
         printInfo('Type /help for available commands');
@@ -1055,6 +1071,143 @@ async function handleStatus(state: SessionState): Promise<void> {
   console.log(summary);
 }
 
+/**
+ * Handle /db slash command - database management
+ */
+async function handleDbSlashCommand(state: SessionState, args: string[]): Promise<void> {
+  if (!state.projectDir) {
+    printError('No active project. Create or resume a project first.');
+    return;
+  }
+
+  const action = args[0] || 'status';
+
+  switch (action) {
+    case 'status': {
+      try {
+        const { loadProject } = await import('../state/index.js');
+        const { DEFAULT_DB_CONFIG } = await import('../types/database.js');
+        const projectState = await loadProject(state.projectDir);
+        const dbConfig = projectState.dbConfig || { ...DEFAULT_DB_CONFIG, designed: false };
+
+        console.log();
+        printInfo('Database Status:');
+        console.log(`  Designed:     ${dbConfig.designed ? 'Yes' : 'No'}`);
+        console.log(`  Status:       ${dbConfig.status}`);
+        console.log(`  Mode:         ${dbConfig.mode || 'not set'}`);
+        console.log(`  Vector:       ${dbConfig.vectorRequired ? 'Yes' : 'No'}`);
+        console.log(`  Migrations:   ${dbConfig.migrationsApplied}`);
+        if (dbConfig.lastError) {
+          printError(`  Last Error:   ${dbConfig.lastError}`);
+        }
+        console.log();
+      } catch (err) {
+        printError(err instanceof Error ? err.message : 'Failed to load project state');
+      }
+      break;
+    }
+    case 'configure': {
+      printInfo('Use "popeye db configure" from the CLI for interactive configuration.');
+      printInfo('Or set DATABASE_URL in apps/backend/.env manually.');
+      break;
+    }
+    case 'apply': {
+      printInfo('Use "popeye db apply" from the CLI to run the setup pipeline.');
+      break;
+    }
+    default:
+      printError(`Unknown db action: ${action}`);
+      printInfo('Usage: /db [status|configure|apply]');
+  }
+}
+
+/**
+ * Handle /doctor slash command - readiness checks
+ */
+async function handleDoctorSlashCommand(state: SessionState): Promise<void> {
+  if (!state.projectDir) {
+    printError('No active project. Create or resume a project first.');
+    return;
+  }
+
+  try {
+    const { runDoctorChecks } = await import('./commands/doctor.js');
+
+    console.log();
+    printInfo('Running readiness checks...');
+    console.log();
+
+    const result = await runDoctorChecks(state.projectDir);
+
+    for (const check of result.checks) {
+      const label = check.passed ? '[PASS]' : check.severity === 'info' ? '[SKIP]' : '[FAIL]';
+      if (check.passed) {
+        printSuccess(`  ${label} ${check.name}: ${check.message}`);
+      } else if (check.severity === 'info') {
+        printInfo(`  ${label} ${check.name}: ${check.message}`);
+      } else if (check.severity === 'warning') {
+        printWarning(`  ${label} ${check.name}: ${check.message}`);
+      } else {
+        printError(`  ${label} ${check.name}: ${check.message}`);
+      }
+    }
+
+    console.log();
+    if (result.healthy) {
+      printSuccess('All critical checks passed.');
+    } else {
+      printWarning('Some critical checks failed. See above for details.');
+    }
+  } catch (err) {
+    printError(err instanceof Error ? err.message : 'Doctor checks failed');
+  }
+}
+
+/**
+ * Handle /review or /audit slash command - post-build project audit
+ */
+async function handleReviewSlashCommand(state: SessionState, args: string[] = []): Promise<void> {
+  if (!state.projectDir) {
+    printError('No active project. Create or resume a project first.');
+    return;
+  }
+
+  // Parse CLI-style flags from args
+  const options: {
+    depth?: number;
+    strict?: boolean;
+    format?: 'json' | 'md' | 'both';
+    recover?: boolean;
+    target?: string;
+  } = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if ((arg === '--depth' || arg === '-d') && args[i + 1]) {
+      options.depth = parseInt(args[++i], 10);
+    } else if (arg === '--strict' || arg === '-s') {
+      options.strict = true;
+    } else if ((arg === '--format' || arg === '-f') && args[i + 1]) {
+      options.format = args[++i] as 'json' | 'md' | 'both';
+    } else if (arg === '--no-recover') {
+      options.recover = false;
+    } else if (arg === '--recover') {
+      options.recover = true;
+    } else if ((arg === '--target' || arg === '-t') && args[i + 1]) {
+      options.target = args[++i];
+    }
+  }
+
+  try {
+    const { runReview } = await import('./commands/review.js');
+
+    console.log();
+    await runReview(state.projectDir, options);
+  } catch (err) {
+    printError(err instanceof Error ? err.message : 'Audit failed');
+  }
+}
+
 /**
  * Handle /overview command - full project plan and milestone review
  */
@@ -1734,11 +1887,27 @@ async function handleResume(state: SessionState, args: string[]): Promise<void>
     return;
   }
 
-  // Discover all projects (registered + scanned in current directory)
-  console.log();
-  printInfo('Scanning for projects...');
+  // Reason: If there's already an active project with pending work (e.g., from /review recovery),
+  // skip project discovery and go straight to resuming.
+  if (state.projectDir) {
+    const activeStatus = await getWorkflowStatus(state.projectDir);
+    if (activeStatus.exists && activeStatus.state) {
+      const { phase, status: pStatus } = activeStatus.state;
+      const hasPendingWork = phase !== 'complete' || pStatus !== 'complete';
+      if (hasPendingWork) {
+        printInfo(`Resuming active project: ${activeStatus.state.name}`);
+        // Fall through to the resume logic below (skip discovery)
+      }
+    }
+  }
+
+  // Only discover projects if no active project with pending work
+  if (!state.projectDir || (await getWorkflowStatus(state.projectDir)).state?.phase === 'complete') {
+    // Discover all projects (registered + scanned in current directory)
+    console.log();
+    printInfo('Scanning for projects...');
 
-  const { all: allProjects } = await discoverProjects(state.projectDir || process.cwd());
+    const { all: allProjects } = await discoverProjects(state.projectDir || process.cwd());
 
   // If projects found, let user select one
   if (allProjects.length > 0) {
@@ -1815,6 +1984,7 @@ async function handleResume(state: SessionState, args: string[]): Promise<void>
     console.log();
     printInfo(`Selected: ${selectedProject.name}`);
   }
+  } // end: project discovery block
 
   // Now check for formal project state at the selected/current directory
   if (!state.projectDir) {

package/src/generators/admin-wizard.ts

@@ -0,0 +1,146 @@
+/**
+ * Admin Wizard generator orchestration module
+ * Creates the admin wizard backend + frontend layers for fullstack projects
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import {
+  generateAdminAuthMiddleware,
+  generateMiddlewareInit,
+  generateAdminDbRoutes,
+} from './templates/admin-wizard-python.js';
+import {
+  generateUseAdminApiHook,
+  generateDbStatusBanner,
+  generateConnectionForm,
+  generateMigrationProgress,
+  generateDbSetupStepper,
+  generateAdminIndex,
+} from './templates/admin-wizard-react.js';
+
+/** Python dependencies required by the admin wizard */
+export const ADMIN_WIZARD_PYTHON_DEPS = ['python-multipart>=0.0.7'];
+
+/**
+ * Create a directory if it doesn't exist
+ */
+async function ensureDir(dirPath: string): Promise<void> {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+/**
+ * Write a file with content
+ */
+async function writeFile(filePath: string, content: string): Promise<void> {
+  await fs.writeFile(filePath, content, 'utf-8');
+}
+
+/**
+ * Generate the complete admin wizard layer (backend middleware/routes + frontend components)
+ *
+ * Creates middleware/, routes/admin_db.py in the backend, and admin/ components
+ * in the frontend. Also augments requirements.txt with admin dependencies.
+ *
+ * @param projectDir - Root project directory (contains apps/)
+ * @param packageName - Python package name (snake_case)
+ * @returns List of absolute file paths created
+ */
+export async function generateAdminWizardLayer(
+  projectDir: string,
+  packageName: string
+): Promise<string[]> {
+  const backendDir = path.join(projectDir, 'apps', 'backend');
+  const srcPkgDir = path.join(backendDir, 'src', packageName);
+  const frontendDir = path.join(projectDir, 'apps', 'frontend');
+  const filesCreated: string[] = [];
+
+  // Ensure directories
+  await ensureDir(path.join(srcPkgDir, 'middleware'));
+  await ensureDir(path.join(frontendDir, 'src', 'admin'));
+
+  // Define all files to generate
+  const files: Array<{ path: string; content: string }> = [
+    // Backend: middleware
+    {
+      path: path.join(srcPkgDir, 'middleware', '__init__.py'),
+      content: generateMiddlewareInit(),
+    },
+    {
+      path: path.join(srcPkgDir, 'middleware', 'admin_auth.py'),
+      content: generateAdminAuthMiddleware(),
+    },
+    // Backend: admin routes
+    {
+      path: path.join(srcPkgDir, 'routes', 'admin_db.py'),
+      content: generateAdminDbRoutes(packageName),
+    },
+    // Frontend: admin components
+    {
+      path: path.join(frontendDir, 'src', 'admin', 'useAdminApi.ts'),
+      content: generateUseAdminApiHook(),
+    },
+    {
+      path: path.join(frontendDir, 'src', 'admin', 'DbStatusBanner.tsx'),
+      content: generateDbStatusBanner(),
+    },
+    {
+      path: path.join(frontendDir, 'src', 'admin', 'ConnectionForm.tsx'),
+      content: generateConnectionForm(),
+    },
+    {
+      path: path.join(frontendDir, 'src', 'admin', 'MigrationProgress.tsx'),
+      content: generateMigrationProgress(),
+    },
+    {
+      path: path.join(frontendDir, 'src', 'admin', 'DbSetupStepper.tsx'),
+      content: generateDbSetupStepper(),
+    },
+    {
+      path: path.join(frontendDir, 'src', 'admin', 'index.ts'),
+      content: generateAdminIndex(),
+    },
+  ];
+
+  // Write all files
+  for (const file of files) {
+    await writeFile(file.path, file.content);
+    filesCreated.push(file.path);
+  }
+
+  // Augment requirements.txt with admin deps
+  const reqPath = path.join(backendDir, 'requirements.txt');
+  try {
+    const existingReqs = await fs.readFile(reqPath, 'utf-8');
+    if (!existingReqs.includes('# Admin')) {
+      const adminSection = `\n# Admin\n${ADMIN_WIZARD_PYTHON_DEPS.join('\n')}\n`;
+      await writeFile(reqPath, existingReqs.trimEnd() + adminSection);
+    }
+  } catch {
+    // requirements.txt doesn't exist yet - will be created by the main generator
+  }
+
+  return filesCreated;
+}
+
+/**
+ * Get the list of relative file paths generated by the admin wizard layer
+ *
+ * @param packageName - Python package name (snake_case)
+ * @returns List of relative file paths
+ */
+export function getAdminWizardFiles(packageName: string): string[] {
+  return [
+    // Backend
+    `apps/backend/src/${packageName}/middleware/__init__.py`,
+    `apps/backend/src/${packageName}/middleware/admin_auth.py`,
+    `apps/backend/src/${packageName}/routes/admin_db.py`,
+    // Frontend
+    'apps/frontend/src/admin/useAdminApi.ts',
+    'apps/frontend/src/admin/DbStatusBanner.tsx',
+    'apps/frontend/src/admin/ConnectionForm.tsx',
+    'apps/frontend/src/admin/MigrationProgress.tsx',
+    'apps/frontend/src/admin/DbSetupStepper.tsx',
+    'apps/frontend/src/admin/index.ts',
+  ];
+}

package/src/generators/all.ts

@@ -16,6 +16,9 @@ import {
   generateUiPackage as generateUiPackageImpl,
 } from './shared-packages.js';
 import type { BrandColorOptions } from './shared-packages.js';
+import { generateAllDockerComposeWithDb } from './templates/database-docker.js';
+import { getAdminWizardFiles } from './admin-wizard.js';
+import { getDatabaseFiles } from './database.js';
 
 /**
  * Options for all project generation
@@ -479,14 +482,14 @@ export async function generateAllProject(
         path: path.join(projectDir, '.popeye', 'workspace.json'),
         content: generateAllWorkspaceJson(projectName),
       },
-      // Docker compose (override to include website)
+      // Docker compose (override to include website + postgres)
       {
         path: path.join(projectDir, 'docker-compose.yml'),
-        content: generateAllDockerCompose(projectName),
+        content: generateAllDockerComposeWithDb(projectName),
       },
       {
         path: path.join(projectDir, 'infra', 'docker', 'docker-compose.yml'),
-        content: generateAllDockerCompose(projectName),
+        content: generateAllDockerComposeWithDb(projectName),
       },
       // README
       {
@@ -562,6 +565,10 @@ export function getAllProjectFiles(projectName: string): string[] {
     'packages/ui/src/button.tsx',
     'packages/ui/src/card.tsx',
     'packages/contracts/.gitkeep',
+    // Database layer
+    ...getDatabaseFiles(packageName, 'sqlalchemy'),
+    // Admin wizard layer
+    ...getAdminWizardFiles(packageName),
   ];
 }