popeye-cli 1.7.0 → 1.9.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,
@@ -63,6 +66,11 @@ export async function createProject(
     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
@@ -395,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/audit.ts

@@ -0,0 +1,294 @@
+/**
+ * Audit system type definitions.
+ *
+ * Zod schemas and TypeScript types for the post-build audit/review feature.
+ * Covers scanning, analysis, reporting, and recovery.
+ */
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Enums
+// ---------------------------------------------------------------------------
+
+export const AuditSeveritySchema = z.enum(['critical', 'major', 'minor', 'info']);
+export type AuditSeverity = z.infer<typeof AuditSeveritySchema>;
+
+export const AuditCategorySchema = z.enum([
+  'feature-completeness',
+  'integration-wiring',
+  'test-coverage',
+  'config-deployment',
+  'dependency-sanity',
+  'consistency',
+  'security',
+  'documentation',
+]);
+export type AuditCategory = z.infer<typeof AuditCategorySchema>;
+
+export const ComponentKindSchema = z.enum([
+  'frontend',
+  'backend',
+  'website',
+  'shared',
+  'infra',
+]);
+export type ComponentKind = z.infer<typeof ComponentKindSchema>;
+
+// ---------------------------------------------------------------------------
+// Evidence
+// ---------------------------------------------------------------------------
+
+export const AuditEvidenceSchema = z.object({
+  file: z.string(),
+  line: z.number().optional(),
+  snippet: z.string().optional(),
+  description: z.string().optional(),
+});
+export type AuditEvidence = z.infer<typeof AuditEvidenceSchema>;
+
+// ---------------------------------------------------------------------------
+// Dependency manifest
+// ---------------------------------------------------------------------------
+
+export const DependencyManifestSchema = z.object({
+  file: z.string(),
+  type: z.enum(['package.json', 'requirements.txt', 'pyproject.toml', 'other']),
+  dependencies: z.record(z.string(), z.string()).optional(),
+  devDependencies: z.record(z.string(), z.string()).optional(),
+});
+export type DependencyManifest = z.infer<typeof DependencyManifestSchema>;
+
+// ---------------------------------------------------------------------------
+// File entry
+// ---------------------------------------------------------------------------
+
+export const FileEntrySchema = z.object({
+  path: z.string(),
+  lines: z.number().optional(),
+  extension: z.string().optional(),
+});
+export type FileEntry = z.infer<typeof FileEntrySchema>;
+
+export const FileExcerptSchema = z.object({
+  path: z.string(),
+  content: z.string(),
+});
+export type FileExcerpt = z.infer<typeof FileExcerptSchema>;
+
+// ---------------------------------------------------------------------------
+// Component scan (per-component scanning for upgrade safety)
+// ---------------------------------------------------------------------------
+
+export const ComponentScanSchema = z.object({
+  kind: ComponentKindSchema,
+  rootDir: z.string(),
+  language: z.enum(['typescript', 'python', 'mixed']),
+  framework: z.string().optional(),
+  entryPoints: z.array(z.string()),
+  routeFiles: z.array(z.string()),
+  testFiles: z.array(FileEntrySchema),
+  sourceFiles: z.array(FileEntrySchema),
+  dependencyManifests: z.array(DependencyManifestSchema),
+});
+export type ComponentScan = z.infer<typeof ComponentScanSchema>;
+
+// ---------------------------------------------------------------------------
+// Wiring matrix (deterministic FE<->BE wiring check)
+// ---------------------------------------------------------------------------
+
+export const WiringMismatchSchema = z.object({
+  type: z.string(),
+  details: z.string(),
+  evidence: z.array(AuditEvidenceSchema),
+});
+export type WiringMismatch = z.infer<typeof WiringMismatchSchema>;
+
+export const WiringMatrixSchema = z.object({
+  frontendApiBaseEnvKeys: z.array(z.string()),
+  frontendApiBaseResolved: z.string().optional(),
+  backendCorsOrigins: z.array(z.string()).optional(),
+  backendApiPrefix: z.string().optional(),
+  potentialMismatches: z.array(WiringMismatchSchema),
+});
+export type WiringMatrix = z.infer<typeof WiringMatrixSchema>;
+
+// ---------------------------------------------------------------------------
+// Project scan result
+// ---------------------------------------------------------------------------
+
+export const ProjectScanResultSchema = z.object({
+  tree: z.string(),
+  // Component-based scanning (upgrade-safe)
+  components: z.array(ComponentScanSchema),
+  detectedComposition: z.array(ComponentKindSchema),
+  stateLanguage: z.string(),
+  compositionMismatch: z.boolean(),
+  // Aggregated totals
+  sourceFiles: z.array(FileEntrySchema),
+  testFiles: z.array(FileEntrySchema),
+  configFiles: z.array(z.string()),
+  entryPoints: z.array(z.string()),
+  routeFiles: z.array(z.string()),
+  dependencies: z.array(DependencyManifestSchema),
+  totalSourceFiles: z.number(),
+  totalTestFiles: z.number(),
+  totalLinesOfCode: z.number(),
+  totalLinesOfTests: z.number(),
+  language: z.string(),
+  // Priority doc reads
+  claudeMdContent: z.string().optional(),
+  readmeContent: z.string().optional(),
+  docsIndex: z.array(z.string()),
+  keyFileSnippets: z.array(FileExcerptSchema),
+  // Wiring matrix
+  wiring: WiringMatrixSchema.optional(),
+  // Config
+  envExampleContent: z.string().optional(),
+  dockerComposeContent: z.string().optional(),
+});
+export type ProjectScanResult = z.infer<typeof ProjectScanResultSchema>;
+
+// ---------------------------------------------------------------------------
+// Search metadata (Serena tracking)
+// ---------------------------------------------------------------------------
+
+export const SearchMetadataSchema = z.object({
+  serenaUsed: z.boolean(),
+  serenaRetries: z.number(),
+  serenaErrors: z.array(z.string()),
+  fallbackUsed: z.boolean(),
+  fallbackTool: z.string(),
+  searchQueries: z.array(z.string()),
+});
+export type SearchMetadata = z.infer<typeof SearchMetadataSchema>;
+
+// ---------------------------------------------------------------------------
+// Audit finding
+// ---------------------------------------------------------------------------
+
+export const AuditFindingSchema = z.object({
+  id: z.string(),
+  category: AuditCategorySchema,
+  severity: AuditSeveritySchema,
+  title: z.string(),
+  description: z.string(),
+  evidence: z.array(AuditEvidenceSchema),
+  recommendation: z.string(),
+  autoFixable: z.boolean(),
+});
+export type AuditFinding = z.infer<typeof AuditFindingSchema>;
+
+// ---------------------------------------------------------------------------
+// Summary report
+// ---------------------------------------------------------------------------
+
+export const ProjectSummaryReportSchema = z.object({
+  projectName: z.string(),
+  language: z.string(),
+  totalSourceFiles: z.number(),
+  totalTestFiles: z.number(),
+  totalLinesOfCode: z.number(),
+  totalLinesOfTests: z.number(),
+  componentCount: z.number(),
+  detectedComposition: z.array(ComponentKindSchema),
+  entryPointCount: z.number(),
+  routeCount: z.number(),
+  dependencyCount: z.number(),
+  hasDocker: z.boolean(),
+  hasEnvExample: z.boolean(),
+  hasCiConfig: z.boolean(),
+  aiOverview: z.string().optional(),
+});
+export type ProjectSummaryReport = z.infer<typeof ProjectSummaryReportSchema>;
+
+// ---------------------------------------------------------------------------
+// Audit report
+// ---------------------------------------------------------------------------
+
+export const AuditRecommendationSchema = z.enum([
+  'pass',
+  'fix-and-recheck',
+  'major-rework',
+]);
+export type AuditRecommendation = z.infer<typeof AuditRecommendationSchema>;
+
+export const ProjectAuditReportSchema = z.object({
+  projectName: z.string(),
+  language: z.string(),
+  auditedAt: z.string(),
+  auditRunId: z.string(),
+  summary: ProjectSummaryReportSchema,
+  findings: z.array(AuditFindingSchema),
+  overallScore: z.number(),
+  categoryScores: z.record(AuditCategorySchema, z.number()),
+  criticalCount: z.number(),
+  majorCount: z.number(),
+  minorCount: z.number(),
+  infoCount: z.number(),
+  passedChecks: z.array(z.string()),
+  searchMetadata: SearchMetadataSchema,
+  recommendation: AuditRecommendationSchema,
+});
+export type ProjectAuditReport = z.infer<typeof ProjectAuditReportSchema>;
+
+// ---------------------------------------------------------------------------
+// Recovery
+// ---------------------------------------------------------------------------
+
+export const RecoveryTaskSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  findingIds: z.array(z.string()),
+  acceptanceCriteria: z.array(z.string()),
+  testPlan: z.string().optional(),
+  appTarget: ComponentKindSchema,
+});
+export type RecoveryTask = z.infer<typeof RecoveryTaskSchema>;
+
+export const RecoveryMilestoneSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  tasks: z.array(RecoveryTaskSchema),
+});
+export type RecoveryMilestone = z.infer<typeof RecoveryMilestoneSchema>;
+
+export const RecoveryPlanSchema = z.object({
+  generatedAt: z.string(),
+  auditScore: z.number(),
+  auditRunId: z.string(),
+  totalFindings: z.number(),
+  criticalFindings: z.number(),
+  milestones: z.array(RecoveryMilestoneSchema),
+  estimatedEffort: z.string(),
+});
+export type RecoveryPlan = z.infer<typeof RecoveryPlanSchema>;
+
+// ---------------------------------------------------------------------------
+// Options & result
+// ---------------------------------------------------------------------------
+
+export const AuditModeOptionsSchema = z.object({
+  projectDir: z.string(),
+  depth: z.number().min(1).max(3).default(2),
+  runTests: z.boolean().default(true),
+  strict: z.boolean().default(false),
+  format: z.enum(['json', 'md', 'both']).default('both'),
+  autoRecover: z.boolean().default(true),
+  target: z.union([z.literal('all'), ComponentKindSchema]).default('all'),
+});
+export type AuditModeOptions = z.infer<typeof AuditModeOptionsSchema>;
+
+export const AuditModeResultSchema = z.object({
+  success: z.boolean(),
+  summary: ProjectSummaryReportSchema,
+  audit: ProjectAuditReportSchema,
+  recovery: RecoveryPlanSchema.optional(),
+  reportPaths: z.object({
+    auditMd: z.string().optional(),
+    auditJson: z.string().optional(),
+    recoveryMd: z.string().optional(),
+    recoveryJson: z.string().optional(),
+  }),
+  error: z.string().optional(),
+});
+export type AuditModeResult = z.infer<typeof AuditModeResultSchema>;

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>;