popeye-cli 1.6.0 → 1.8.0

package/src/generators/templates/database-typescript.ts

@@ -0,0 +1,238 @@
+/**
+ * TypeScript backend database template functions
+ * Generates Prisma + pgvector files for future TS backend projects
+ * NOT wired into any generator in Phase 1 - templates exist for future use
+ */
+
+/**
+ * Generate Prisma schema with PostgreSQL datasource and pgvector
+ */
+export function generatePrismaSchema(projectName: string): string {
+  return `// Prisma schema for ${projectName}
+// Learn more: https://pris.ly/d/prisma-schema
+
+generator client {
+  provider        = "prisma-client-js"
+  previewFeatures = ["postgresqlExtensions"]
+}
+
+datasource db {
+  provider   = "postgresql"
+  url        = env("DATABASE_URL")
+  extensions = [pgvector(map: "vector", schema: "public")]
+}
+
+model AppSettings {
+  id        Int      @id @default(autoincrement())
+  key       String   @unique
+  value     String
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@map("app_settings")
+}
+`;
+}
+
+/**
+ * Generate PrismaClient singleton with connection handling
+ */
+export function generatePrismaClient(projectName: string): string {
+  return `/**
+ * Prisma client singleton for ${projectName}.
+ *
+ * Ensures a single PrismaClient instance is reused across the application.
+ */
+
+import { PrismaClient } from "@prisma/client";
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined;
+};
+
+export const prisma =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    log:
+      process.env.NODE_ENV === "development"
+        ? ["query", "error", "warn"]
+        : ["error"],
+  });
+
+if (process.env.NODE_ENV !== "production") {
+  globalForPrisma.prisma = prisma;
+}
+
+export default prisma;
+`;
+}
+
+/**
+ * Generate .env.example additions for Prisma
+ */
+export function generatePrismaEnv(): string {
+  return `# Database
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/mydb?schema=public"
+`;
+}
+
+/**
+ * Generate Prisma seed script
+ */
+export function generatePrismaSeed(): string {
+  return `/**
+ * Prisma seed script.
+ *
+ * Seeds the database with initial data using upsert pattern.
+ * Run with: npx prisma db seed
+ */
+
+import { PrismaClient } from "@prisma/client";
+
+const prisma = new PrismaClient();
+
+async function main() {
+  console.log("Seeding database...");
+
+  // Upsert default app settings
+  await prisma.appSettings.upsert({
+    where: { key: "app_version" },
+    update: { value: "1.0.0" },
+    create: { key: "app_version", value: "1.0.0" },
+  });
+
+  console.log("Seeding complete.");
+}
+
+main()
+  .then(async () => {
+    await prisma.$disconnect();
+  })
+  .catch(async (e) => {
+    console.error(e);
+    await prisma.$disconnect();
+    process.exit(1);
+  });
+`;
+}
+
+/**
+ * Generate database health check for Prisma
+ */
+export function generatePrismaDbHealth(): string {
+  return `/**
+ * Database health check utilities.
+ *
+ * Tests connection and checks migration status.
+ */
+
+import prisma from "./client";
+
+export interface DbHealthResult {
+  connected: boolean;
+  migrations?: { current: string | null };
+  error?: string;
+}
+
+/**
+ * Check database connectivity and migration status.
+ */
+export async function checkDbHealth(): Promise<DbHealthResult> {
+  try {
+    // Test basic connectivity
+    await prisma.$queryRaw\`SELECT 1\`;
+
+    // Check migration status
+    let currentMigration: string | null = null;
+    try {
+      const result = await prisma.$queryRaw<
+        Array<{ migration_name: string }>
+      >\`SELECT migration_name FROM _prisma_migrations ORDER BY finished_at DESC LIMIT 1\`;
+      currentMigration = result[0]?.migration_name ?? null;
+    } catch {
+      // _prisma_migrations table may not exist yet
+    }
+
+    return {
+      connected: true,
+      migrations: { current: currentMigration },
+    };
+  } catch (error) {
+    return {
+      connected: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+`;
+}
+
+/**
+ * Generate pgvector raw query helpers for Prisma
+ */
+export function generatePrismaVectorHelpers(): string {
+  return `/**
+ * pgvector helpers using Prisma raw queries.
+ *
+ * Provides cosine similarity search and vector extension checks.
+ */
+
+import prisma from "./client";
+
+/**
+ * Perform cosine similarity search against a vector column.
+ */
+export async function cosineSimilaritySearch(
+  tableName: string,
+  columnName: string,
+  queryVector: number[],
+  limit: number = 10
+): Promise<Array<{ id: number; similarity: number }>> {
+  const vectorStr = \`[\${queryVector.join(",")}]\`;
+
+  const results = await prisma.$queryRawUnsafe<
+    Array<{ id: number; similarity: number }>
+  >(
+    \`SELECT id, 1 - (\${columnName} <=> $1::vector) AS similarity \` +
+      \`FROM \${tableName} \` +
+      \`ORDER BY \${columnName} <=> $1::vector \` +
+      \`LIMIT $2\`,
+    vectorStr,
+    limit
+  );
+
+  return results;
+}
+
+/**
+ * Check if the pgvector extension is installed.
+ */
+export async function checkVectorExtension(): Promise<boolean> {
+  try {
+    const result = await prisma.$queryRaw<Array<{ extname: string }>>\`
+      SELECT extname FROM pg_extension WHERE extname = 'vector'
+    \`;
+    return result.length > 0;
+  } catch {
+    return false;
+  }
+}
+`;
+}
+
+/**
+ * Generate Prisma DB index.ts with re-exports
+ */
+export function generatePrismaDbInit(): string {
+  return `/**
+ * Database package re-exports.
+ */
+
+export { prisma, default as PrismaClient } from "./client";
+export { checkDbHealth, type DbHealthResult } from "./health";
+export {
+  cosineSimilaritySearch,
+  checkVectorExtension,
+} from "./vector";
+`;
+}

package/src/generators/templates/fullstack.ts

@@ -212,6 +212,35 @@ cd apps/frontend && npm run lint
 cd apps/backend && ruff check .
 \`\`\`
 
+## Database
+
+Database is **UNCONFIGURED** by default. The app runs without a database in limited mode.
+
+### Local Docker (recommended for development)
+
+\`\`\`bash
+# docker-compose starts PostgreSQL automatically
+docker-compose up
+\`\`\`
+
+### Managed Database
+
+Set \`DATABASE_URL\` in \`apps/backend/.env\` to connect to a managed PostgreSQL instance (Neon, Supabase, etc.).
+
+### Health Check
+
+\`\`\`bash
+# Check database connectivity and migration status
+curl http://localhost:8000/health/db
+\`\`\`
+
+### Migrations
+
+\`\`\`bash
+cd apps/backend
+alembic upgrade head
+\`\`\`
+
 ## Apps
 
 ### Frontend (apps/frontend)

package/src/generators/templates/index.ts

@@ -14,3 +14,8 @@ export * as websiteLandingTemplates from './website-landing.js';
 export * as websitePricingTemplates from './website-pricing.js';
 export * as websiteLayoutTemplates from './website-layout.js';
 export * as websiteSectionTemplates from './website-sections.js';
+export * as databasePythonTemplates from './database-python.js';
+export * as databaseTypescriptTemplates from './database-typescript.js';
+export * as databaseDockerTemplates from './database-docker.js';
+export * as adminWizardPythonTemplates from './admin-wizard-python.js';
+export * as adminWizardReactTemplates from './admin-wizard-react.js';

package/src/state/index.ts

@@ -15,6 +15,9 @@ import type {
 } from '../types/workflow.js';
 import type { ConsensusIteration } from '../types/consensus.js';
 import type { ProjectSpec } from '../types/project.js';
+import { isWorkspace } from '../types/project.js';
+import { DEFAULT_DB_CONFIG } from '../types/database.js';
+import type { DbConfig } from '../types/database.js';
 import {
   loadState,
   saveState,
@@ -60,8 +63,14 @@ export async function createProject(
     consensusHistory: [],
     createdAt: now,
     updatedAt: now,
+    qaEnabled: true,
   };
 
+  // Set default DB config for workspace projects (fullstack / all)
+  if (isWorkspace(spec.language)) {
+    state.dbConfig = { ...DEFAULT_DB_CONFIG };
+  }
+
   await saveState(projectDir, state);
 
   // Register project in global registry
@@ -394,6 +403,26 @@ export async function storeWebsiteStrategyPath(
   return updateState(projectDir, { websiteStrategy: strategyPath });
 }
 
+/**
+ * Update database configuration with partial updates
+ * Merges partial DbConfig updates into the existing config
+ *
+ * @param projectDir - The project root directory
+ * @param updates - Partial DbConfig updates to merge
+ * @returns The updated project state
+ */
+export async function updateDbConfig(
+  projectDir: string,
+  updates: Partial<DbConfig>
+): Promise<ProjectState> {
+  const current = await loadProject(projectDir);
+  const currentDbConfig = current.dbConfig || { ...DEFAULT_DB_CONFIG };
+
+  return updateState(projectDir, {
+    dbConfig: { ...currentDbConfig, ...updates },
+  });
+}
+
 /**
  * Mark the project as complete
  *

package/src/types/consensus.ts

@@ -91,6 +91,8 @@ export interface ConsensusConfig {
   additionalReviewers?: AIProvider[];
   /** Custom reviewer persona for domain-specific reviews (e.g., marketing strategist for website projects) */
   reviewerPersona?: string;
+  /** Consensus threshold for test plans (default: 90, lower than code plan threshold) */
+  testPlanThreshold?: number;
 }
 
 /**
@@ -153,6 +155,7 @@ export const ConsensusConfigSchema = z.object({
   temperature: z.number().min(0).max(2).default(0.3),
   maxTokens: z.number().min(100).max(32000).default(4096),
   reviewerPersona: z.string().optional(),
+  testPlanThreshold: z.number().min(0).max(100).optional(),
 });
 
 /**

package/src/types/database-runtime.ts

@@ -0,0 +1,69 @@
+/**
+ * Database runtime types and Zod schemas for Phase 2
+ * Defines setup pipeline results, readiness checks, and doctor output
+ */
+
+import { z } from 'zod';
+import { DbStatusSchema, DbSetupStepSchema } from './database.js';
+
+/**
+ * Result of a single setup pipeline step
+ */
+export const SetupStepResultSchema = z.object({
+  /** Which pipeline step */
+  step: DbSetupStepSchema,
+  /** Whether the step succeeded */
+  success: z.boolean(),
+  /** Human-readable status message */
+  message: z.string(),
+  /** Duration in milliseconds */
+  durationMs: z.number(),
+  /** Error details if step failed */
+  error: z.string().optional(),
+});
+export type SetupStepResult = z.infer<typeof SetupStepResultSchema>;
+
+/**
+ * Full setup pipeline result
+ */
+export const SetupResultSchema = z.object({
+  /** Whether the entire pipeline succeeded */
+  success: z.boolean(),
+  /** Individual step results */
+  steps: z.array(SetupStepResultSchema),
+  /** Total pipeline duration in milliseconds */
+  totalDurationMs: z.number(),
+  /** Final DB status after pipeline */
+  finalStatus: DbStatusSchema,
+  /** Error message if pipeline failed */
+  error: z.string().optional(),
+});
+export type SetupResult = z.infer<typeof SetupResultSchema>;
+
+/**
+ * Single readiness check (used by doctor command)
+ */
+export const ReadinessCheckSchema = z.object({
+  /** Check name */
+  name: z.string(),
+  /** Whether the check passed */
+  passed: z.boolean(),
+  /** Human-readable result message */
+  message: z.string(),
+  /** Severity level */
+  severity: z.enum(['critical', 'warning', 'info']),
+});
+export type ReadinessCheck = z.infer<typeof ReadinessCheckSchema>;
+
+/**
+ * Full doctor readiness result
+ */
+export const ReadinessResultSchema = z.object({
+  /** Overall health status */
+  healthy: z.boolean(),
+  /** Individual check results */
+  checks: z.array(ReadinessCheckSchema),
+  /** ISO timestamp of when checks ran */
+  timestamp: z.string(),
+});
+export type ReadinessResult = z.infer<typeof ReadinessResultSchema>;

package/src/types/database.ts

@@ -0,0 +1,84 @@
+/**
+ * Database configuration types and Zod schemas
+ * Defines DB lifecycle states, provisioning modes, and config tracking
+ */
+
+import { z } from 'zod';
+
+/**
+ * Database lifecycle status
+ */
+export const DbStatusSchema = z.enum([
+  'unconfigured',
+  'configured',
+  'applying',
+  'ready',
+  'error',
+]);
+export type DbStatus = z.infer<typeof DbStatusSchema>;
+
+/**
+ * Database provisioning mode
+ * - local_docker: PostgreSQL runs in Docker Compose
+ * - managed: External managed database (Neon, Supabase, etc.)
+ */
+export const DbModeSchema = z.enum(['local_docker', 'managed']);
+export type DbMode = z.infer<typeof DbModeSchema>;
+
+/**
+ * Database provider (informational only)
+ */
+export const DbProviderSchema = z.enum(['neon', 'supabase', 'other']);
+export type DbProvider = z.infer<typeof DbProviderSchema>;
+
+/**
+ * Backend ORM choice
+ */
+export const BackendOrmSchema = z.enum(['sqlalchemy', 'prisma', 'drizzle']);
+export type BackendOrm = z.infer<typeof BackendOrmSchema>;
+
+/**
+ * Setup pipeline steps (forward compat for Phase 2)
+ */
+export const DbSetupStepSchema = z.enum([
+  'check_connection',
+  'ensure_extensions',
+  'apply_migrations',
+  'seed_minimal',
+  'readiness_tests',
+  'mark_ready',
+]);
+export type DbSetupStep = z.infer<typeof DbSetupStepSchema>;
+
+/**
+ * Main database configuration tracking object
+ */
+export const DbConfigSchema = z.object({
+  /** Whether DB layer was generated */
+  designed: z.boolean(),
+  /** Provisioning mode - unset until user configures */
+  mode: DbModeSchema.optional(),
+  /** Whether pgvector is included */
+  vectorRequired: z.boolean(),
+  /** Current lifecycle state */
+  status: DbStatusSchema,
+  /** Last error message */
+  lastError: z.string().optional(),
+  /** Number of migrations applied (updated by runner, not generator) */
+  migrationsApplied: z.number(),
+  /** ISO timestamp of last readiness check */
+  readinessCheckedAt: z.string().optional(),
+});
+export type DbConfig = z.infer<typeof DbConfigSchema>;
+
+/**
+ * Default DB config for new fullstack/all projects
+ * vectorRequired: true because fullstack/all projects get pgvector by default
+ * mode is intentionally absent (unset until user configures provisioning)
+ */
+export const DEFAULT_DB_CONFIG: DbConfig = {
+  designed: true,
+  status: 'unconfigured',
+  vectorRequired: true,
+  migrationsApplied: 0,
+};

package/src/types/index.ts

@@ -80,6 +80,56 @@ export {
   type ConsensusTrackingRecord,
 } from './consensus.js';
 
+// Tester (QA) types
+export {
+  TestVerdictSchema,
+  TestScopeSchema,
+  TestCommandSchema,
+  TestCaseSchema,
+  TestPlanOutputSchema,
+  TestRunReviewSchema,
+  FixStepSchema,
+  TestFixPlanSchema,
+  type TestVerdict,
+  type TestScope,
+  type TestCommand,
+  type TestCase,
+  type TestPlanOutput,
+  type TestRunReview,
+  type FixStep,
+  type TestFixPlan,
+  type DiscoveredTestCommands,
+} from './tester.js';
+
+// Database types
+export {
+  DbStatusSchema,
+  DbModeSchema,
+  DbProviderSchema,
+  BackendOrmSchema,
+  DbSetupStepSchema,
+  DbConfigSchema,
+  DEFAULT_DB_CONFIG,
+  type DbStatus,
+  type DbMode,
+  type DbProvider,
+  type BackendOrm,
+  type DbSetupStep,
+  type DbConfig,
+} from './database.js';
+
+// Database runtime types
+export {
+  SetupStepResultSchema,
+  SetupResultSchema,
+  ReadinessCheckSchema,
+  ReadinessResultSchema,
+  type SetupStepResult,
+  type SetupResult,
+  type ReadinessCheck,
+  type ReadinessResult,
+} from './database-runtime.js';
+
 // CLI types
 export {
   EXIT_CODES,

package/src/types/tester.ts

@@ -0,0 +1,136 @@
+/**
+ * Tester (QA) skill type definitions
+ * Defines test planning, review, and fix plan structures
+ */
+
+import { z } from 'zod';
+
+/**
+ * Test verdict from the Tester's review
+ */
+export const TestVerdictSchema = z.enum(['PASS', 'PASS_WITH_NOTES', 'FAIL']);
+export type TestVerdict = z.infer<typeof TestVerdictSchema>;
+
+/**
+ * Scope components that a test plan can cover
+ */
+export const TestScopeSchema = z.enum(['frontend', 'backend', 'db', 'infra']);
+export type TestScope = z.infer<typeof TestScopeSchema>;
+
+/**
+ * A structured test command to execute
+ */
+export const TestCommandSchema = z.object({
+  /** The shell command to run */
+  command: z.string().min(1),
+  /** Working directory (relative to project root) */
+  cwd: z.string().optional(),
+  /** Human-readable purpose of this command */
+  purpose: z.string().min(1),
+  /** Whether this command must pass for the test run to succeed */
+  required: z.boolean(),
+});
+export type TestCommand = z.infer<typeof TestCommandSchema>;
+
+/**
+ * Individual test case in the test matrix
+ */
+export const TestCaseSchema = z.object({
+  /** Unique identifier within the test plan */
+  id: z.string().min(1),
+  /** Category: unit, integration, e2e, smoke, lint, build */
+  category: z.string().min(1),
+  /** Human-readable description of what is being tested */
+  description: z.string().min(1),
+  /** What must be true for this test to pass */
+  acceptanceCriteria: z.string().min(1),
+  /** What evidence (log output, report) is needed to verify */
+  evidenceRequired: z.string().min(1),
+  /** Priority: critical, high, medium, low */
+  priority: z.enum(['critical', 'high', 'medium', 'low']),
+});
+export type TestCase = z.infer<typeof TestCaseSchema>;
+
+/**
+ * Structured test plan output from the Tester
+ */
+export const TestPlanOutputSchema = z.object({
+  /** What risks this test plan targets */
+  summary: z.string().min(1),
+  /** Components covered by this plan */
+  scope: z.array(TestScopeSchema).min(1),
+  /** Matrix of test cases with acceptance criteria */
+  testMatrix: z.array(TestCaseSchema).min(1),
+  /** Exact commands to execute (with cwd, purpose, required flag) */
+  commands: z.array(TestCommandSchema).min(1),
+  /** Top risks this test plan focuses on (3-7 items) */
+  riskFocus: z.array(z.string().min(1)).min(1),
+  /** What evidence (logs, reports) to capture */
+  evidenceRequired: z.array(z.string().min(1)).min(1),
+  /** Minimum verification always present: build, lint, smoke */
+  minimumVerification: z.array(z.string().min(1)).min(1),
+  /** Rationale if tester decides no custom tests are needed (min verification still applies) */
+  noTestsRationale: z.string().optional(),
+});
+export type TestPlanOutput = z.infer<typeof TestPlanOutputSchema>;
+
+/**
+ * Post-run review from the Tester
+ */
+export const TestRunReviewSchema = z.object({
+  /** Overall verdict */
+  verdict: TestVerdictSchema,
+  /** Summary of the review */
+  summary: z.string().min(1),
+  /** List of evidence that was checked */
+  evidenceReviewed: z.array(z.string().min(1)).min(1),
+  /** Specific failures found (empty array if PASS) */
+  failures: z.array(z.string()),
+  /** Missing evidence or coverage gaps */
+  gaps: z.array(z.string()),
+  /** Recommendations for improvement */
+  recommendations: z.array(z.string()),
+  /** Whether this verdict requires consensus (true if FAIL) */
+  requiresConsensus: z.boolean(),
+});
+export type TestRunReview = z.infer<typeof TestRunReviewSchema>;
+
+/**
+ * Individual fix step in a TestFixPlan
+ */
+export const FixStepSchema = z.object({
+  /** File to modify */
+  file: z.string().min(1),
+  /** Description of the change */
+  change: z.string().min(1),
+  /** Why this change is needed */
+  reason: z.string().min(1),
+});
+export type FixStep = z.infer<typeof FixStepSchema>;
+
+/**
+ * Fix plan proposed by the Tester when tests fail
+ */
+export const TestFixPlanSchema = z.object({
+  /** Which acceptance criteria failed */
+  failedCriteria: z.array(z.string().min(1)).min(1),
+  /** Root cause analysis from the Tester */
+  rootCauseAnalysis: z.string().min(1),
+  /** Ordered steps to fix the failures */
+  fixSteps: z.array(FixStepSchema).min(1),
+  /** Risks of introducing regressions */
+  regressionRisks: z.array(z.string()),
+  /** Strategy for re-testing after fix */
+  retestStrategy: z.string().min(1),
+});
+export type TestFixPlan = z.infer<typeof TestFixPlanSchema>;
+
+/**
+ * Discovered test infrastructure for a project
+ */
+export interface DiscoveredTestCommands {
+  testCmd: string | null;
+  lintCmd: string | null;
+  buildCmd: string | null;
+  typecheckCmd: string | null;
+}