popeye-cli 1.7.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,
@@ -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/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

@@ -101,6 +101,35 @@ export {
   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/workflow.ts

@@ -9,6 +9,8 @@ import type { OutputLanguage, OpenAIModel } from './project.js';
 import type { ConsensusIteration } from './consensus.js';
 import type { TestPlanOutput } from './tester.js';
 import { TestPlanOutputSchema, TestVerdictSchema } from './tester.js';
+import type { DbConfig } from './database.js';
+import { DbConfigSchema } from './database.js';
 
 /**
  * Workflow phases
@@ -230,6 +232,8 @@ export interface ProjectState {
   sourceDocPaths?: string[];
   /** Whether QA Tester skill is active (default: true for new projects, undefined/false for existing) */
   qaEnabled?: boolean;
+  /** Database configuration tracking (workspace projects only) */
+  dbConfig?: DbConfig;
 }
 
 /**
@@ -276,6 +280,7 @@ export const ProjectStateSchema = z.object({
   strategyError: z.string().optional(),
   sourceDocPaths: z.array(z.string()).optional(),
   qaEnabled: z.boolean().optional(),
+  dbConfig: DbConfigSchema.optional(),
 });
 
 /**