popeye-cli 1.7.0 → 1.8.0

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),
   ];
 }
 

package/src/generators/database.ts

@@ -0,0 +1,286 @@
+/**
+ * Database generator orchestration module
+ * Creates complete database layers for fullstack and TS backend projects
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import type { BackendOrm } from '../types/database.js';
+import {
+  generateDbConnection,
+  generateDbModels,
+  generateDbInit,
+  generateDbSettings,
+  generateAlembicIni,
+  generateAlembicEnvPy,
+  generateAlembicScriptMako,
+  generateInitialMigration,
+  generateDbVectorHelpers,
+  generateDbStartupHook,
+  generateDbHealthRoute,
+  generateDbConftest,
+} from './templates/database-python.js';
+import {
+  generatePrismaSchema,
+  generatePrismaClient,
+  generatePrismaSeed,
+  generatePrismaDbHealth,
+  generatePrismaVectorHelpers,
+  generatePrismaDbInit,
+} from './templates/database-typescript.js';
+
+/** Python database dependencies */
+export const DB_PYTHON_DEPS = [
+  'sqlalchemy[asyncio]>=2.0.0',
+  'asyncpg>=0.29.0',
+  'alembic>=1.13.0',
+  'pgvector>=0.2.5',
+];
+
+/**
+ * Options for database layer generation
+ */
+interface DatabaseLayerOptions {
+  includeVector?: boolean;
+}
+
+/**
+ * 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 Python database layer for a backend project
+ *
+ * Creates database/, migrations/, and supporting files under apps/backend/
+ *
+ * @param projectDir - Root project directory (contains apps/)
+ * @param projectName - Project name (used for naming)
+ * @param packageName - Python package name (snake_case)
+ * @param options - Generation options
+ * @returns List of absolute file paths created
+ */
+export async function generatePythonDatabaseLayer(
+  projectDir: string,
+  _projectName: string,
+  packageName: string,
+  options: DatabaseLayerOptions = {}
+): Promise<string[]> {
+  const includeVector = options.includeVector !== false;
+  const backendDir = path.join(projectDir, 'apps', 'backend');
+  const srcPkgDir = path.join(backendDir, 'src', packageName);
+  const filesCreated: string[] = [];
+
+  // Ensure directories exist
+  await ensureDir(path.join(srcPkgDir, 'database'));
+  await ensureDir(path.join(srcPkgDir, 'routes'));
+  await ensureDir(path.join(backendDir, 'migrations', 'versions'));
+  await ensureDir(path.join(backendDir, 'tests'));
+
+  // Define all files to generate
+  const files: Array<{ path: string; content: string }> = [
+    // Database package
+    {
+      path: path.join(srcPkgDir, 'database', '__init__.py'),
+      content: generateDbInit(packageName),
+    },
+    {
+      path: path.join(srcPkgDir, 'database', 'connection.py'),
+      content: generateDbConnection(packageName),
+    },
+    {
+      path: path.join(srcPkgDir, 'database', 'models.py'),
+      content: generateDbModels(packageName),
+    },
+    {
+      path: path.join(srcPkgDir, 'database', 'settings.py'),
+      content: generateDbSettings(packageName),
+    },
+    // Alembic migrations
+    {
+      path: path.join(backendDir, 'alembic.ini'),
+      content: generateAlembicIni(packageName),
+    },
+    {
+      path: path.join(backendDir, 'migrations', 'env.py'),
+      content: generateAlembicEnvPy(packageName),
+    },
+    {
+      path: path.join(backendDir, 'migrations', 'script.py.mako'),
+      content: generateAlembicScriptMako(),
+    },
+    {
+      path: path.join(backendDir, 'migrations', 'versions', '001_initial.py'),
+      content: generateInitialMigration(packageName),
+    },
+    // Startup hook
+    {
+      path: path.join(srcPkgDir, 'startup.py'),
+      content: generateDbStartupHook(packageName),
+    },
+    // Health route
+    {
+      path: path.join(srcPkgDir, 'routes', 'health_db.py'),
+      content: generateDbHealthRoute(packageName),
+    },
+    // Test fixtures
+    {
+      path: path.join(backendDir, 'tests', 'conftest_db.py'),
+      content: generateDbConftest(packageName),
+    },
+  ];
+
+  // Add vector helpers if requested
+  if (includeVector) {
+    files.push({
+      path: path.join(srcPkgDir, 'database', 'vector.py'),
+      content: generateDbVectorHelpers(packageName),
+    });
+  }
+
+  // Write all files
+  for (const file of files) {
+    await writeFile(file.path, file.content);
+    filesCreated.push(file.path);
+  }
+
+  // Augment requirements.txt with DB deps
+  const reqPath = path.join(backendDir, 'requirements.txt');
+  try {
+    const existingReqs = await fs.readFile(reqPath, 'utf-8');
+    const augmented = augmentRequirements(existingReqs, DB_PYTHON_DEPS);
+    await writeFile(reqPath, augmented);
+  } catch {
+    // requirements.txt doesn't exist yet - will be created by the main generator
+  }
+
+  return filesCreated;
+}
+
+/**
+ * Generate the complete TypeScript database layer for a project
+ *
+ * Creates prisma/ and src/db/ directories with Prisma-based DB files
+ * NOTE: Not wired into any generator in Phase 1
+ *
+ * @param projectDir - Project directory (where prisma/ and src/ live)
+ * @param projectName - Project name
+ * @param options - Generation options
+ * @returns List of absolute file paths created
+ */
+export async function generateTypeScriptDatabaseLayer(
+  projectDir: string,
+  projectName: string,
+  _options: DatabaseLayerOptions = {}
+): Promise<string[]> {
+  const filesCreated: string[] = [];
+
+  // Ensure directories
+  await ensureDir(path.join(projectDir, 'prisma'));
+  await ensureDir(path.join(projectDir, 'src', 'db'));
+
+  const files: Array<{ path: string; content: string }> = [
+    {
+      path: path.join(projectDir, 'prisma', 'schema.prisma'),
+      content: generatePrismaSchema(projectName),
+    },
+    {
+      path: path.join(projectDir, 'prisma', 'seed.ts'),
+      content: generatePrismaSeed(),
+    },
+    {
+      path: path.join(projectDir, 'src', 'db', 'client.ts'),
+      content: generatePrismaClient(projectName),
+    },
+    {
+      path: path.join(projectDir, 'src', 'db', 'health.ts'),
+      content: generatePrismaDbHealth(),
+    },
+    {
+      path: path.join(projectDir, 'src', 'db', 'vector.ts'),
+      content: generatePrismaVectorHelpers(),
+    },
+    {
+      path: path.join(projectDir, 'src', 'db', 'index.ts'),
+      content: generatePrismaDbInit(),
+    },
+  ];
+
+  for (const file of files) {
+    await writeFile(file.path, file.content);
+    filesCreated.push(file.path);
+  }
+
+  return filesCreated;
+}
+
+/**
+ * Append database dependencies to an existing requirements.txt
+ *
+ * Idempotent: checks for existing "# Database" section to avoid duplicates.
+ * Handles empty input gracefully.
+ *
+ * @param baseContent - Existing requirements.txt content
+ * @param dbDeps - Database dependency strings to add
+ * @returns Augmented requirements.txt content
+ */
+export function augmentRequirements(baseContent: string, dbDeps: string[]): string {
+  // Check for existing Database section
+  if (baseContent.includes('# Database')) {
+    return baseContent;
+  }
+
+  // Ensure trailing newline before adding section
+  const base = baseContent.trimEnd();
+  const depsBlock = dbDeps.join('\n');
+
+  return `${base}\n\n# Database\n${depsBlock}\n`;
+}
+
+/**
+ * Get the list of relative file paths generated for a database layer
+ *
+ * @param packageName - Python package name (for sqlalchemy) or project name (for prisma)
+ * @param orm - ORM type
+ * @returns List of relative file paths
+ */
+export function getDatabaseFiles(packageName: string, orm: BackendOrm): string[] {
+  if (orm === 'sqlalchemy') {
+    return [
+      `apps/backend/src/${packageName}/database/__init__.py`,
+      `apps/backend/src/${packageName}/database/connection.py`,
+      `apps/backend/src/${packageName}/database/models.py`,
+      `apps/backend/src/${packageName}/database/settings.py`,
+      `apps/backend/src/${packageName}/database/vector.py`,
+      `apps/backend/src/${packageName}/routes/health_db.py`,
+      `apps/backend/src/${packageName}/startup.py`,
+      'apps/backend/alembic.ini',
+      'apps/backend/migrations/env.py',
+      'apps/backend/migrations/script.py.mako',
+      'apps/backend/migrations/versions/001_initial.py',
+      'apps/backend/tests/conftest_db.py',
+    ];
+  }
+
+  if (orm === 'prisma') {
+    return [
+      'prisma/schema.prisma',
+      'prisma/seed.ts',
+      'src/db/client.ts',
+      'src/db/health.ts',
+      'src/db/vector.ts',
+      'src/db/index.ts',
+    ];
+  }
+
+  return [];
+}

package/src/generators/fullstack.ts

@@ -9,7 +9,6 @@ import type { ProjectSpec } from '../types/project.js';
 import type { GenerationResult } from './python.js';
 import {
   generateWorkspaceJson,
-  generateRootDockerCompose,
   generateRootReadme,
   generateRootGitignore,
   generateFrontendReadme,
@@ -19,7 +18,6 @@ import {
   generateTailwindConfig,
   generatePostcssConfig,
   generateMainCss,
-  generateAppTsx,
   generateMainTsx,
   generateIndexHtml,
   generateFrontendPackageJson,
@@ -30,10 +28,15 @@ import {
   generateFrontendTest,
   generateVitestSetup,
   generateFrontendVitestConfig,
-  generateFastAPIMain,
   generateBackendDockerfile,
   generateFastAPIRequirements,
 } from './templates/fullstack.js';
+import { generateAppTsxWithAdmin } from './templates/admin-wizard-react.js';
+import { generateFastAPIMainWithAdmin } from './templates/admin-wizard-python.js';
+import { generateDockerComposeWithDb, generateDbEnvExample } from './templates/database-docker.js';
+import { generatePythonDatabaseLayer } from './database.js';
+import { getDatabaseFiles } from './database.js';
+import { generateAdminWizardLayer, getAdminWizardFiles } from './admin-wizard.js';
 
 /**
  * Options for fullstack project generation
@@ -112,11 +115,11 @@ export async function generateFullstackProject(
       // Docker
       {
         path: path.join(projectDir, 'infra', 'docker', 'docker-compose.yml'),
-        content: generateRootDockerCompose(projectName),
+        content: generateDockerComposeWithDb(projectName),
       },
       {
         path: path.join(projectDir, 'docker-compose.yml'),
-        content: generateRootDockerCompose(projectName),
+        content: generateDockerComposeWithDb(projectName),
       },
       // Documentation
       {
@@ -192,7 +195,7 @@ export async function generateFullstackProject(
       },
       {
         path: path.join(frontendDir, 'src', 'App.tsx'),
-        content: generateAppTsx(projectName),
+        content: generateAppTsxWithAdmin(projectName),
       },
       {
         path: path.join(frontendDir, 'src', 'index.css'),
@@ -228,7 +231,7 @@ export async function generateFullstackProject(
       // Environment
       {
         path: path.join(frontendDir, '.env.example'),
-        content: 'VITE_API_URL=http://localhost:8000\n',
+        content: 'VITE_API_URL=http://localhost:8000\nVITE_ADMIN_TOKEN=change-me-to-a-random-string\n',
       },
       {
         path: path.join(frontendDir, '.gitignore'),
@@ -265,7 +268,7 @@ export async function generateFullstackProject(
       },
       {
         path: path.join(backendDir, 'src', packageName, 'main.py'),
-        content: generateFastAPIMain(projectName),
+        content: generateFastAPIMainWithAdmin(projectName, packageName),
       },
       // Test files
       {
@@ -293,7 +296,7 @@ export async function generateFullstackProject(
       // Environment
       {
         path: path.join(backendDir, '.env.example'),
-        content: 'DEBUG=true\nDATABASE_URL=sqlite:///./data/app.db\n',
+        content: generateDbEnvExample(projectName),
       },
       {
         path: path.join(backendDir, '.gitignore'),
@@ -312,6 +315,16 @@ export async function generateFullstackProject(
       filesCreated.push(file.path);
     }
 
+    // Generate database layer (SQLAlchemy + Alembic + pgvector)
+    const dbFiles = await generatePythonDatabaseLayer(
+      projectDir, projectName, packageName, { includeVector: true }
+    );
+    filesCreated.push(...dbFiles);
+
+    // Generate admin wizard layer (middleware + routes + React components)
+    const adminFiles = await generateAdminWizardLayer(projectDir, packageName);
+    filesCreated.push(...adminFiles);
+
     return {
       success: true,
       projectDir,
@@ -520,6 +533,10 @@ export function getFullstackProjectFiles(projectName: string): string[] {
     'apps/backend/.env.example',
     'apps/backend/.gitignore',
     'apps/backend/Makefile',
+    // Database layer
+    ...getDatabaseFiles(packageName, 'sqlalchemy'),
+    // Admin wizard layer
+    ...getAdminWizardFiles(packageName),
   ];
 }
 

package/src/generators/index.ts

@@ -69,6 +69,18 @@ export {
   getAllProjectFiles,
   type AllGeneratorOptions,
 } from './all.js';
+export {
+  generatePythonDatabaseLayer,
+  generateTypeScriptDatabaseLayer,
+  augmentRequirements,
+  getDatabaseFiles,
+  DB_PYTHON_DEPS,
+} from './database.js';
+export {
+  generateAdminWizardLayer,
+  getAdminWizardFiles,
+  ADMIN_WIZARD_PYTHON_DEPS,
+} from './admin-wizard.js';
 export * from './templates/index.js';
 
 /**