popeye-cli 1.7.0 → 1.9.0

package/src/workflow/db-setup-runner.ts

@@ -0,0 +1,391 @@
+/**
+ * Database setup pipeline runner
+ * Executes sequential steps to configure, migrate, and verify a database
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { DbStatus, DbSetupStep } from '../types/database.js';
+import type { SetupStepResult, SetupResult } from '../types/database-runtime.js';
+import { transitionDbStatus } from './db-state-machine.js';
+
+const execAsync = promisify(exec);
+
+/**
+ * Options for the setup pipeline
+ */
+export interface SetupPipelineOptions {
+  /** Skip seed step */
+  skipSeed?: boolean;
+  /** Callback for step progress */
+  onStep?: (step: DbSetupStep, status: 'start' | 'success' | 'fail', message: string) => void;
+}
+
+/**
+ * Read and parse a .env file for key=value pairs
+ *
+ * @param envPath - Path to .env file
+ * @returns Map of environment variable key-value pairs
+ */
+export async function readEnvFile(envPath: string): Promise<Record<string, string>> {
+  const result: Record<string, string> = {};
+  try {
+    const content = await fs.readFile(envPath, 'utf-8');
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eqIndex = trimmed.indexOf('=');
+      if (eqIndex === -1) continue;
+      const key = trimmed.slice(0, eqIndex).trim();
+      let value = trimmed.slice(eqIndex + 1).trim();
+      // Strip surrounding quotes
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      result[key] = value;
+    }
+  } catch {
+    // File doesn't exist or isn't readable
+  }
+  return result;
+}
+
+/**
+ * Scan migration files for prerequisite extension comments
+ * Looks for lines like: # popeye:requires_extension=vector
+ *
+ * @param migrationsDir - Path to migrations/versions/ directory
+ * @returns Array of required extension names
+ */
+export async function parseMigrationPrereqs(migrationsDir: string): Promise<string[]> {
+  const extensions: string[] = [];
+  const versionsDir = path.join(migrationsDir, 'versions');
+
+  try {
+    const files = await fs.readdir(versionsDir);
+    for (const file of files) {
+      if (!file.endsWith('.py')) continue;
+      const content = await fs.readFile(path.join(versionsDir, file), 'utf-8');
+      const matches = content.matchAll(/# popeye:requires_extension=(\w+)/g);
+      for (const match of matches) {
+        if (!extensions.includes(match[1])) {
+          extensions.push(match[1]);
+        }
+      }
+    }
+  } catch {
+    // Directory doesn't exist or isn't readable
+  }
+
+  return extensions;
+}
+
+/**
+ * Derive the snake_case package name from the project state
+ *
+ * @param projectDir - Project root directory
+ * @returns Python package name
+ */
+export async function getPackageName(projectDir: string): Promise<string> {
+  try {
+    const statePath = path.join(projectDir, '.popeye', 'state.json');
+    const content = await fs.readFile(statePath, 'utf-8');
+    const state = JSON.parse(content);
+    const name: string = state.name || 'project';
+    return name.toLowerCase().replace(/-/g, '_').replace(/[^a-z0-9_]/g, '');
+  } catch {
+    return 'backend';
+  }
+}
+
+/**
+ * Resolve the backend directory path
+ *
+ * @param projectDir - Project root directory
+ * @returns Absolute path to apps/backend
+ */
+export function resolveBackendDir(projectDir: string): string {
+  return path.join(projectDir, 'apps', 'backend');
+}
+
+/**
+ * Execute a single pipeline step and track timing
+ */
+async function executeStep(
+  step: DbSetupStep,
+  fn: () => Promise<string>,
+  options?: SetupPipelineOptions
+): Promise<SetupStepResult> {
+  options?.onStep?.(step, 'start', `Starting ${step}...`);
+  const start = Date.now();
+
+  try {
+    const message = await fn();
+    const durationMs = Date.now() - start;
+    options?.onStep?.(step, 'success', message);
+    return { step, success: true, message, durationMs };
+  } catch (err) {
+    const durationMs = Date.now() - start;
+    const error = err instanceof Error ? err.message : String(err);
+    options?.onStep?.(step, 'fail', error);
+    return { step, success: false, message: `Step failed: ${step}`, durationMs, error };
+  }
+}
+
+/**
+ * Step 1: Check database connection
+ */
+async function checkConnection(backendDir: string): Promise<string> {
+  const env = await readEnvFile(path.join(backendDir, '.env'));
+  const dbUrl = env['DATABASE_URL'] || '';
+
+  if (!dbUrl) {
+    throw new Error(
+      'DATABASE_URL not found in apps/backend/.env. ' +
+      'Run "popeye db configure" to set it up.'
+    );
+  }
+
+  // Test connectivity using Python asyncpg
+  const cmd = `cd "${backendDir}" && python3 -c "
+import asyncio, asyncpg, os
+async def check():
+    conn = await asyncpg.connect('${dbUrl.replace(/'/g, "\\'")}')
+    await conn.execute('SELECT 1')
+    await conn.close()
+asyncio.run(check())
+"`;
+
+  try {
+    await execAsync(cmd, { timeout: 15000 });
+    return 'Database connection verified successfully';
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Database connection failed: ${msg}`);
+  }
+}
+
+/**
+ * Step 2: Ensure required extensions
+ */
+async function ensureExtensions(backendDir: string): Promise<string> {
+  const migrationsDir = path.join(backendDir, 'migrations');
+  const extensions = await parseMigrationPrereqs(migrationsDir);
+
+  if (extensions.length === 0) {
+    return 'No prerequisite extensions required';
+  }
+
+  const env = await readEnvFile(path.join(backendDir, '.env'));
+  const dbUrl = env['DATABASE_URL'] || '';
+
+  for (const ext of extensions) {
+    const cmd = `cd "${backendDir}" && python3 -c "
+import asyncio, asyncpg
+async def ensure():
+    conn = await asyncpg.connect('${dbUrl.replace(/'/g, "\\'")}')
+    await conn.execute('CREATE EXTENSION IF NOT EXISTS ${ext}')
+    await conn.close()
+asyncio.run(ensure())
+"`;
+
+    try {
+      await execAsync(cmd, { timeout: 15000 });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`Failed to create extension '${ext}': ${msg}`);
+    }
+  }
+
+  return `Extensions verified: ${extensions.join(', ')}`;
+}
+
+/**
+ * Step 3: Apply Alembic migrations
+ */
+async function applyMigrations(backendDir: string): Promise<string> {
+  const cmd = `cd "${backendDir}" && alembic upgrade head 2>&1`;
+
+  try {
+    const { stdout } = await execAsync(cmd, { timeout: 60000 });
+    // Count applied migrations from output
+    const appliedMatches = stdout.match(/Running upgrade/g);
+    const count = appliedMatches ? appliedMatches.length : 0;
+    return count > 0
+      ? `Applied ${count} migration(s) successfully`
+      : 'All migrations already up to date';
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Migration failed: ${msg}`);
+  }
+}
+
+/**
+ * Step 4: Run seed script (if exists)
+ */
+async function seedMinimal(backendDir: string): Promise<string> {
+  const seedPaths = [
+    path.join(backendDir, 'scripts', 'seed.py'),
+    path.join(backendDir, 'seed.py'),
+  ];
+
+  let seedPath: string | null = null;
+  for (const p of seedPaths) {
+    try {
+      await fs.access(p);
+      seedPath = p;
+      break;
+    } catch {
+      // Try next
+    }
+  }
+
+  if (!seedPath) {
+    return 'No seed script found (skipped)';
+  }
+
+  const cmd = `cd "${backendDir}" && python3 "${seedPath}" 2>&1`;
+
+  try {
+    await execAsync(cmd, { timeout: 30000 });
+    return 'Seed script executed successfully';
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Seed script failed: ${msg}`);
+  }
+}
+
+/**
+ * Step 5: Run readiness tests
+ */
+async function runReadinessTests(backendDir: string): Promise<string> {
+  const env = await readEnvFile(path.join(backendDir, '.env'));
+  const dbUrl = env['DATABASE_URL'] || '';
+
+  const cmd = `cd "${backendDir}" && python3 -c "
+import asyncio, asyncpg
+async def check():
+    conn = await asyncpg.connect('${dbUrl.replace(/'/g, "\\'")}')
+    # Verify connectivity
+    await conn.execute('SELECT 1')
+    # Verify alembic_version table exists and has a version
+    row = await conn.fetchrow('SELECT version_num FROM alembic_version LIMIT 1')
+    if row is None:
+        raise Exception('No migration version found in alembic_version table')
+    await conn.close()
+    return row['version_num']
+asyncio.run(check())
+"`;
+
+  try {
+    await execAsync(cmd, { timeout: 15000 });
+    return 'Readiness tests passed: connectivity and migration version verified';
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Readiness tests failed: ${msg}`);
+  }
+}
+
+/**
+ * Run the complete database setup pipeline
+ *
+ * Steps execute sequentially. Pipeline stops on first failure.
+ *
+ * @param projectDir - Project root directory
+ * @param options - Pipeline options
+ * @returns Full pipeline result
+ */
+export async function runDbSetupPipeline(
+  projectDir: string,
+  options: SetupPipelineOptions = {}
+): Promise<SetupResult> {
+  const backendDir = resolveBackendDir(projectDir);
+  const steps: SetupStepResult[] = [];
+  const pipelineStart = Date.now();
+
+  // Step 1: Check connection
+  const connResult = await executeStep('check_connection', () => checkConnection(backendDir), options);
+  steps.push(connResult);
+  if (!connResult.success) {
+    return buildResult(steps, pipelineStart, 'error');
+  }
+
+  // Step 2: Ensure extensions
+  const extResult = await executeStep('ensure_extensions', () => ensureExtensions(backendDir), options);
+  steps.push(extResult);
+  if (!extResult.success) {
+    return buildResult(steps, pipelineStart, 'error');
+  }
+
+  // Step 3: Apply migrations
+  const migResult = await executeStep('apply_migrations', () => applyMigrations(backendDir), options);
+  steps.push(migResult);
+  if (!migResult.success) {
+    return buildResult(steps, pipelineStart, 'error');
+  }
+
+  // Step 4: Seed (optional)
+  if (!options.skipSeed) {
+    const seedResult = await executeStep('seed_minimal', () => seedMinimal(backendDir), options);
+    steps.push(seedResult);
+    if (!seedResult.success) {
+      return buildResult(steps, pipelineStart, 'error');
+    }
+  }
+
+  // Step 5: Readiness tests
+  const readyResult = await executeStep('readiness_tests', () => runReadinessTests(backendDir), options);
+  steps.push(readyResult);
+  if (!readyResult.success) {
+    return buildResult(steps, pipelineStart, 'error');
+  }
+
+  // Step 6: Mark ready (always succeeds if we got here)
+  const markResult = await executeStep('mark_ready', async () => {
+    return 'Database marked as ready';
+  }, options);
+  steps.push(markResult);
+
+  return buildResult(steps, pipelineStart, 'ready');
+}
+
+/**
+ * Build a SetupResult from accumulated steps
+ */
+function buildResult(
+  steps: SetupStepResult[],
+  pipelineStart: number,
+  finalStatus: DbStatus
+): SetupResult {
+  const totalDurationMs = Date.now() - pipelineStart;
+  const success = finalStatus === 'ready';
+  const failedStep = steps.find((s) => !s.success);
+
+  return {
+    success,
+    steps,
+    totalDurationMs,
+    finalStatus,
+    error: failedStep?.error,
+  };
+}
+
+/**
+ * Compute the new DB status after a pipeline run and validate the transition
+ *
+ * @param currentStatus - Current DB status from state
+ * @param pipelineResult - Result of the pipeline run
+ * @returns New DB status after validated transition
+ */
+export function computePostPipelineStatus(
+  currentStatus: DbStatus,
+  pipelineResult: SetupResult
+): DbStatus {
+  // Transition to 'applying' first
+  const applying = transitionDbStatus(currentStatus, 'applying');
+  // Then transition to final status
+  return transitionDbStatus(applying, pipelineResult.finalStatus);
+}

package/src/workflow/db-state-machine.ts

@@ -0,0 +1,58 @@
+/**
+ * Database lifecycle state machine
+ * Enforces valid transitions between DB status states
+ */
+
+import type { DbStatus } from '../types/database.js';
+
+/**
+ * Valid state transitions map
+ * Each key maps to an array of valid target states
+ */
+const VALID_TRANSITIONS: Record<DbStatus, DbStatus[]> = {
+  unconfigured: ['configured'],
+  configured: ['applying', 'unconfigured'],
+  applying: ['ready', 'error'],
+  ready: ['configured', 'unconfigured'],
+  error: ['configured', 'unconfigured'],
+};
+
+/**
+ * Check if a transition from current to target is valid
+ *
+ * @param current - Current DB status
+ * @param target - Target DB status
+ * @returns True if the transition is allowed
+ */
+export function canTransition(current: DbStatus, target: DbStatus): boolean {
+  const allowed = VALID_TRANSITIONS[current];
+  return allowed !== undefined && allowed.includes(target);
+}
+
+/**
+ * Validate and execute a state transition
+ *
+ * @param current - Current DB status
+ * @param target - Desired target status
+ * @returns The new status
+ * @throws Error if the transition is invalid
+ */
+export function transitionDbStatus(current: DbStatus, target: DbStatus): DbStatus {
+  if (!canTransition(current, target)) {
+    throw new Error(
+      `Invalid DB status transition: '${current}' -> '${target}'. ` +
+      `Allowed transitions from '${current}': [${getAvailableTransitions(current).join(', ')}]`
+    );
+  }
+  return target;
+}
+
+/**
+ * Get the list of valid next states from the current status
+ *
+ * @param current - Current DB status
+ * @returns Array of valid target states
+ */
+export function getAvailableTransitions(current: DbStatus): DbStatus[] {
+  return VALID_TRANSITIONS[current] || [];
+}

package/src/workflow/index.ts

@@ -55,6 +55,13 @@ export * from './workspace-manager.js';
 export * from './website-updater.js';
 export * from './website-strategy.js';
 export * from './overview.js';
+export * from './db-state-machine.js';
+export * from './db-setup-runner.js';
+export * from './audit-scanner.js';
+export * from './audit-analyzer.js';
+export * from './audit-reporter.js';
+export * from './audit-recovery.js';
+export * from './audit-mode.js';
 
 /**
  * Workflow options

package/tests/cli/commands/review.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Tests for the review CLI command.
+ */
+import { describe, it, expect } from 'vitest';
+import { createReviewCommand } from '../../../src/cli/commands/review.js';
+
+describe('createReviewCommand', () => {
+  it('should create a command named review', () => {
+    const cmd = createReviewCommand();
+    expect(cmd.name()).toBe('review');
+  });
+
+  it('should have audit as an alias', () => {
+    const cmd = createReviewCommand();
+    expect(cmd.aliases()).toContain('audit');
+  });
+
+  it('should accept the depth option', () => {
+    const cmd = createReviewCommand();
+    const depthOpt = cmd.options.find((o) => o.long === '--depth');
+    expect(depthOpt).toBeDefined();
+  });
+
+  it('should accept the strict option', () => {
+    const cmd = createReviewCommand();
+    const strictOpt = cmd.options.find((o) => o.long === '--strict');
+    expect(strictOpt).toBeDefined();
+  });
+
+  it('should accept the format option', () => {
+    const cmd = createReviewCommand();
+    const formatOpt = cmd.options.find((o) => o.long === '--format');
+    expect(formatOpt).toBeDefined();
+  });
+
+  it('should accept the no-recover option', () => {
+    const cmd = createReviewCommand();
+    const recoverOpt = cmd.options.find((o) => o.long === '--no-recover');
+    expect(recoverOpt).toBeDefined();
+  });
+
+  it('should accept the target option', () => {
+    const cmd = createReviewCommand();
+    const targetOpt = cmd.options.find((o) => o.long === '--target');
+    expect(targetOpt).toBeDefined();
+  });
+
+  it('should have a description', () => {
+    const cmd = createReviewCommand();
+    expect(cmd.description()).toBeTruthy();
+  });
+});

package/tests/generators/admin-wizard-orchestrator.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Tests for admin wizard orchestrator (file list and dependencies)
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import {
+  getAdminWizardFiles,
+  ADMIN_WIZARD_PYTHON_DEPS,
+} from '../../src/generators/admin-wizard.js';
+
+const TEST_PACKAGE = 'my_project';
+
+describe('getAdminWizardFiles', () => {
+  const files = getAdminWizardFiles(TEST_PACKAGE);
+
+  it('should return backend middleware files', () => {
+    expect(files).toContain(`apps/backend/src/${TEST_PACKAGE}/middleware/__init__.py`);
+    expect(files).toContain(`apps/backend/src/${TEST_PACKAGE}/middleware/admin_auth.py`);
+  });
+
+  it('should return backend admin route file', () => {
+    expect(files).toContain(`apps/backend/src/${TEST_PACKAGE}/routes/admin_db.py`);
+  });
+
+  it('should return frontend admin component files', () => {
+    expect(files).toContain('apps/frontend/src/admin/useAdminApi.ts');
+    expect(files).toContain('apps/frontend/src/admin/DbStatusBanner.tsx');
+    expect(files).toContain('apps/frontend/src/admin/ConnectionForm.tsx');
+    expect(files).toContain('apps/frontend/src/admin/MigrationProgress.tsx');
+    expect(files).toContain('apps/frontend/src/admin/DbSetupStepper.tsx');
+    expect(files).toContain('apps/frontend/src/admin/index.ts');
+  });
+
+  it('should have correct number of files', () => {
+    expect(files).toHaveLength(9);
+  });
+
+  it('should use correct package name prefix for backend files', () => {
+    const customFiles = getAdminWizardFiles('acme_app');
+    const backendFiles = customFiles.filter((f) => f.startsWith('apps/backend/'));
+    for (const f of backendFiles) {
+      expect(f).toContain('acme_app');
+    }
+  });
+
+  it('should use apps/frontend prefix for frontend files', () => {
+    const frontendFiles = files.filter((f) => f.startsWith('apps/frontend/'));
+    expect(frontendFiles).toHaveLength(6);
+    for (const f of frontendFiles) {
+      expect(f).toContain('src/admin/');
+    }
+  });
+});
+
+describe('ADMIN_WIZARD_PYTHON_DEPS', () => {
+  it('should include python-multipart', () => {
+    expect(ADMIN_WIZARD_PYTHON_DEPS).toContain('python-multipart>=0.0.7');
+  });
+
+  it('should be a non-empty array', () => {
+    expect(ADMIN_WIZARD_PYTHON_DEPS.length).toBeGreaterThan(0);
+  });
+});