popeye-cli 1.4.3 → 1.4.5

package/src/workflow/execution-mode.ts

@@ -29,7 +29,7 @@ import { runComprehensiveVerification, autoFixIssues, resolveProjectPaths } from
 import { setupUI } from './ui-setup.js';
 import { designUI, saveUISpecification, loadUISpecification } from './ui-designer.js';
 import { iterateUntilConsensus, runOptimizedConsensusProcess, type ConsensusProcessResult } from './consensus.js';
-import { isWorkspace } from '../types/project.js';
+import { isWorkspace, type OutputLanguage } from '../types/project.js';
 import { getProjectStructureSummary } from './project-structure.js';
 
 /**
@@ -167,6 +167,7 @@ async function generateProjectReadme(
 ): Promise<{ success: boolean; path?: string; error?: string }> {
   try {
     const readmePath = path.join(projectDir, 'README.md');
+    const workspace = isWorkspace(state.language);
 
     // Extract features from completed milestones
     const features = state.milestones
@@ -177,121 +178,562 @@ async function generateProjectReadme(
         tasks: m.tasks.filter(t => t.status === 'complete').map(t => t.name),
       }));
 
-    // Determine run commands based on language
-    const isTypeScript = state.language === 'typescript';
-    const installCmd = isTypeScript ? 'npm install' : 'pip install -r requirements.txt';
-    const devCmd = isTypeScript ? 'npm run dev' : 'python src/main.py';
-    const testCmd = isTypeScript ? 'npm test' : 'pytest tests/ -v';
-    const buildCmd = isTypeScript ? 'npm run build' : 'python -m py_compile src/**/*.py';
+    // Load workspace.json for workspace projects
+    let wsConfig: Record<string, unknown> | null = null;
+    if (workspace) {
+      try {
+        const wsContent = await fs.readFile(path.join(projectDir, '.popeye', 'workspace.json'), 'utf-8');
+        wsConfig = JSON.parse(wsContent);
+      } catch {
+        // workspace.json not available, use defaults
+      }
+    }
 
-    // Build README content
-    const readmeContent = `# ${state.name}
+    const description = state.specification
+      ? extractDescriptionFromSpec(state.specification)
+      : 'A project generated by Popeye CLI.';
 
-${state.specification ? extractDescriptionFromSpec(state.specification) : 'A project generated by Popeye CLI.'}
+    const sections: string[] = [];
 
-## Features
+    // Title and description
+    sections.push(`# ${state.name}\n\n${description}`);
 
-${features.map(f => `### ${f.name}
+    // Features
+    const featuresContent = features.map(f => `### ${f.name}
 ${f.description || ''}
-${f.tasks.length > 0 ? f.tasks.map(t => `- ${t}`).join('\n') : ''}`).join('\n\n')}
-
-## Prerequisites
+${f.tasks.length > 0 ? f.tasks.map(t => `- ${t}`).join('\n') : ''}`).join('\n\n');
+    sections.push(`## Features\n\n${featuresContent}`);
 
-${isTypeScript ? `- Node.js 18.0 or higher
-- npm 8.0 or higher` : `- Python 3.9 or higher
-- pip (Python package manager)`}
+    // Prerequisites
+    sections.push(`## Prerequisites\n\n${generatePrerequisites(state.language)}`);
 
-## Installation
-
-\`\`\`bash
-# Clone the repository (if applicable)
-cd ${state.name}
-
-# Install dependencies
-${installCmd}
-\`\`\`
+    // Installation
+    sections.push(`## Installation\n\n${generateInstallation(state.name, state.language)}`);
 
-## Environment Setup
+    // Environment Setup
+    sections.push(`## Environment Setup
 
 1. Copy the example environment file:
    \`\`\`bash
    cp .env.example .env
    \`\`\`
 
-2. Edit \`.env\` and fill in the required values.
+2. Edit \`.env\` and fill in the required values.`);
 
-## Running the Application
+    // Running the Application
+    sections.push(`## Running the Application\n\n${generateRunSection(state.language, wsConfig)}`);
 
-### Development Mode
+    // Project Structure
+    sections.push(`## Project Structure\n\n${generateStructureSection(state.name, state.language)}`);
+
+    // Deployment - per-app for workspace projects
+    if (workspace) {
+      sections.push(`## Deployment\n\n${generateDeploymentSection(state.name, state.language, wsConfig)}`);
+    }
+
+    // Development footer
+    sections.push(`## Development
+
+This project was generated using [Popeye CLI](https://github.com/your-org/popeye-cli), an autonomous code generation tool.
+
+### Development Plan
+
+See [docs/PLAN.md](docs/PLAN.md) for the complete development plan used to build this project.
+
+### Workflow Log
+
+See [docs/WORKFLOW_LOG.md](docs/WORKFLOW_LOG.md) for detailed execution logs.
+
+## License
+
+MIT`);
+
+    const readmeContent = sections.join('\n\n') + '\n';
+    await fs.writeFile(readmePath, readmeContent, 'utf-8');
+
+    return { success: true, path: readmePath };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to generate README',
+    };
+  }
+}
+
+/**
+ * Generate prerequisites section based on language
+ */
+function generatePrerequisites(language: OutputLanguage): string {
+  if (language === 'python') {
+    return `- Python 3.9 or higher
+- pip (Python package manager)`;
+  }
+  if (language === 'typescript' || language === 'website') {
+    return `- Node.js 18.0 or higher
+- npm 8.0 or higher`;
+  }
+  // Workspace projects (fullstack, all) need both
+  return `- Node.js 18.0 or higher
+- npm 8.0 or higher
+- Python 3.9 or higher
+- pip (Python package manager)
+- Docker and Docker Compose (recommended for local development)`;
+}
+
+/**
+ * Generate installation section based on language
+ */
+function generateInstallation(name: string, language: OutputLanguage): string {
+  const lines = [`\`\`\`bash`, `cd ${name}`, ''];
+
+  if (isWorkspace(language)) {
+    lines.push('# Install all workspace dependencies');
+    lines.push('npm install');
+    lines.push('');
+    lines.push('# Install backend Python dependencies');
+    lines.push('cd apps/backend && pip install -r requirements.txt && cd ../..');
+    if (language === 'all') {
+      lines.push('');
+      lines.push('# Install website dependencies (if not covered by workspace)');
+      lines.push('cd apps/website && npm install && cd ../..');
+    }
+  } else if (language === 'python') {
+    lines.push('pip install -r requirements.txt');
+  } else {
+    lines.push('npm install');
+  }
+
+  lines.push('```');
+  return lines.join('\n');
+}
+
+/**
+ * Generate run commands section based on language
+ */
+function generateRunSection(language: OutputLanguage, wsConfig: Record<string, unknown> | null): string {
+  if (language === 'python') {
+    return `### Development Mode
 
 \`\`\`bash
-${devCmd}
+python src/main.py
 \`\`\`
 
 ### Running Tests
 
 \`\`\`bash
-${testCmd}
+pytest tests/ -v
 \`\`\`
 
 ### Build for Production
 
 \`\`\`bash
-${buildCmd}
+python -m py_compile src/**/*.py
+\`\`\``;
+  }
+
+  if (language === 'typescript') {
+    return `### Development Mode
+
+\`\`\`bash
+npm run dev
+\`\`\`
+
+### Running Tests
+
+\`\`\`bash
+npm test
+\`\`\`
+
+### Build for Production
+
+\`\`\`bash
+npm run build
 \`\`\`
 
-${isTypeScript ? `### Start Production Server
+### Start Production Server
 
 \`\`\`bash
 npm start
+\`\`\``;
+  }
+
+  if (language === 'website') {
+    return `### Development Mode
+
+\`\`\`bash
+npm run dev
+\`\`\`
+
+### Running Tests
+
+\`\`\`bash
+npm test
+\`\`\`
+
+### Build for Production
+
+\`\`\`bash
+npm run build
+\`\`\`
+
+### Preview Production Build
+
+\`\`\`bash
+npm run start
+\`\`\``;
+  }
+
+  // Workspace projects (fullstack, all)
+  const apps = (wsConfig as { apps?: Record<string, { path?: string; commands?: Record<string, string> }> })?.apps;
+
+  const lines: string[] = [];
+
+  lines.push(`### Run Everything (Docker Compose)
+
+\`\`\`bash
+docker-compose up
 \`\`\`
-` : ''}
-## Project Structure
 
+### Run Individual Apps`);
+
+  // Frontend
+  const fePath = apps?.frontend?.path || 'apps/frontend';
+  lines.push(`
+#### Frontend (React/Vite)
+
+\`\`\`bash
+cd ${fePath}
+npm run dev      # Development server
+npm run build    # Production build
+npm test         # Run tests
+\`\`\``);
+
+  // Backend
+  const bePath = apps?.backend?.path || 'apps/backend';
+  lines.push(`
+#### Backend (Python/FastAPI)
+
+\`\`\`bash
+cd ${bePath}
+uvicorn src.backend.main:app --reload --port 8000   # Development server
+pip install -e .                                      # Build/install
+pytest tests/ -v                                      # Run tests
+\`\`\``);
+
+  // Website (for 'all' projects)
+  if (language === 'all') {
+    const webPath = apps?.website?.path || 'apps/website';
+    lines.push(`
+#### Website (Next.js)
+
+\`\`\`bash
+cd ${webPath}
+npm run dev      # Development server (port 3001)
+npm run build    # Production build
+npm test         # Run tests
+\`\`\``);
+  }
+
+  // All-at-once commands
+  lines.push(`
+### Run All Tests
+
+\`\`\`bash
+npm run test:all
 \`\`\`
-${state.name}/
+
+### Build All
+
+\`\`\`bash
+npm run build:all
+\`\`\``);
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate project structure section based on language
+ */
+function generateStructureSection(name: string, language: OutputLanguage): string {
+  if (language === 'python') {
+    return `\`\`\`
+${name}/
+├── src/                    # Source code
+│   ├── __init__.py
+│   └── main.py            # Main entry point
+├── tests/                  # Test files
+├── docs/                   # Documentation
+│   ├── PLAN.md            # Development plan
+│   └── WORKFLOW_LOG.md    # Execution log
+├── requirements.txt       # Python dependencies
+├── pyproject.toml         # Project configuration
+├── .env.example           # Environment template
+├── .gitignore
+├── Dockerfile
+└── README.md
+\`\`\``;
+  }
+
+  if (language === 'typescript') {
+    return `\`\`\`
+${name}/
 ├── src/                    # Source code
-${isTypeScript ? `│   └── index.ts           # Main entry point` : `│   ├── __init__.py
-│   └── main.py            # Main entry point`}
+│   └── index.ts           # Main entry point
 ├── tests/                  # Test files
 ├── docs/                   # Documentation
 │   ├── PLAN.md            # Development plan
 │   └── WORKFLOW_LOG.md    # Execution log
-${isTypeScript ? `├── package.json           # Dependencies and scripts
-├── tsconfig.json          # TypeScript configuration` : `├── requirements.txt       # Python dependencies
-├── pyproject.toml         # Project configuration`}
+├── package.json           # Dependencies and scripts
+├── tsconfig.json          # TypeScript configuration
 ├── .env.example           # Environment template
 ├── .gitignore
 ├── Dockerfile
 └── README.md
+\`\`\``;
+  }
+
+  if (language === 'website') {
+    return `\`\`\`
+${name}/
+├── app/                    # Next.js app directory
+│   ├── layout.tsx         # Root layout
+│   └── page.tsx           # Home page
+├── components/            # React components
+├── public/                # Static assets
+├── docs/                  # Documentation
+│   ├── PLAN.md           # Development plan
+│   └── WORKFLOW_LOG.md   # Execution log
+├── package.json          # Dependencies and scripts
+├── next.config.js        # Next.js configuration
+├── tsconfig.json         # TypeScript configuration
+├── .env.example          # Environment template
+├── .gitignore
+├── Dockerfile
+└── README.md
+\`\`\``;
+  }
+
+  // Workspace (fullstack / all)
+  const websiteTree = language === 'all' ? `│   ├── website/           # Next.js marketing/landing site
+│   │   ├── app/
+│   │   ├── components/
+│   │   ├── package.json
+│   │   └── Dockerfile
+` : '';
+
+  const packagesTree = language === 'all' ? `├── packages/              # Shared packages
+│   ├── design-tokens/     # Shared design tokens
+│   ├── ui/                # Shared UI components
+│   └── contracts/         # API contracts (OpenAPI)
+` : '';
+
+  return `\`\`\`
+${name}/
+├── apps/
+│   ├── frontend/          # React/Vite frontend
+│   │   ├── src/
+│   │   ├── package.json
+│   │   └── Dockerfile
+│   ├── backend/           # Python/FastAPI backend
+│   │   ├── src/
+│   │   ├── tests/
+│   │   ├── requirements.txt
+│   │   └── Dockerfile
+${websiteTree}${packagesTree}├── docs/                  # Documentation
+│   ├── PLAN.md            # Development plan
+│   └── WORKFLOW_LOG.md    # Execution log
+├── .popeye/               # Popeye configuration
+│   └── workspace.json     # Workspace configuration
+├── docker-compose.yml     # Local development stack
+├── package.json           # Root workspace config
+├── .env.example           # Environment template
+├── .gitignore
+└── README.md
+\`\`\``;
+}
+
+/**
+ * Generate deployment section for workspace projects
+ */
+function generateDeploymentSection(
+  name: string,
+  language: OutputLanguage,
+  wsConfig: Record<string, unknown> | null
+): string {
+  const apps = (wsConfig as { apps?: Record<string, { docker?: { imageName?: string; context?: string; dockerfile?: string } }> })?.apps;
+  const feImage = apps?.frontend?.docker?.imageName || `${name}-frontend`;
+  const beImage = apps?.backend?.docker?.imageName || `${name}-backend`;
+
+  const lines: string[] = [];
+
+  lines.push(`Each app can be built and deployed independently as a Docker container.
+
+### Build Docker Images
+
+\`\`\`bash
+# Frontend
+docker build -t ${feImage} -f apps/frontend/Dockerfile apps/frontend
+
+# Backend
+docker build -t ${beImage} -f apps/backend/Dockerfile apps/backend`);
+
+  if (language === 'all') {
+    const webImage = apps?.website?.docker?.imageName || `${name}-website`;
+    lines.push(`
+# Website
+docker build -t ${webImage} -f apps/website/Dockerfile apps/website`);
+  }
+
+  lines.push('```');
+
+  lines.push(`
+### Deploy with Docker Compose
+
+\`\`\`bash
+# Start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop all services
+docker-compose down
+\`\`\``);
+
+  lines.push(`
+### Individual App Deployment
+
+#### Frontend (Static Site)
+The frontend builds to static files that can be served by any CDN or static hosting:
+\`\`\`bash
+cd apps/frontend
+npm run build
+# Deploy the dist/ folder to your hosting provider (Vercel, Netlify, S3, etc.)
 \`\`\`
 
-## Development
+#### Backend (API Server)
+The backend runs as a Python ASGI server:
+\`\`\`bash
+cd apps/backend
+pip install -r requirements.txt
+uvicorn src.backend.main:app --host 0.0.0.0 --port 8000
+\`\`\``);
+
+  if (language === 'all') {
+    lines.push(`
+#### Website (Next.js SSR/SSG)
+The website can be deployed as a Node.js server or exported as static files:
+\`\`\`bash
+cd apps/website
+npm run build
+npm start                # Run as Node.js server
+# Or deploy to Vercel/Netlify for automatic SSR support
+\`\`\``);
+  }
 
-This project was generated using [Popeye CLI](https://github.com/your-org/popeye-cli), an autonomous code generation tool.
+  return lines.join('\n');
+}
 
-### Development Plan
+/**
+ * Result of README validation
+ */
+interface ReadmeValidationResult {
+  valid: boolean;
+  missingCritical: string[];
+  missingRecommended: string[];
+}
 
-See [docs/PLAN.md](docs/PLAN.md) for the complete development plan used to build this project.
+/**
+ * Validate that the generated README contains required sections for the project type.
+ *
+ * Critical sections block completion; recommended sections produce warnings.
+ *
+ * @param projectDir - Project root directory
+ * @param language - Project language type
+ * @returns Validation result with lists of missing sections
+ */
+async function validateReadme(
+  projectDir: string,
+  language: OutputLanguage
+): Promise<ReadmeValidationResult> {
+  const missingCritical: string[] = [];
+  const missingRecommended: string[] = [];
 
-### Workflow Log
+  let content: string;
+  try {
+    content = await fs.readFile(path.join(projectDir, 'README.md'), 'utf-8');
+  } catch {
+    return { valid: false, missingCritical: ['README.md file not found'], missingRecommended: [] };
+  }
 
-See [docs/WORKFLOW_LOG.md](docs/WORKFLOW_LOG.md) for detailed execution logs.
+  const contentLower = content.toLowerCase();
 
-## License
+  // Sections required for ALL project types
+  const universalRequired: Array<{ label: string; patterns: string[] }> = [
+    { label: 'Installation', patterns: ['## installation'] },
+    { label: 'Running the Application', patterns: ['## running', 'development mode'] },
+    { label: 'Project Structure', patterns: ['## project structure'] },
+    { label: 'Environment Setup', patterns: ['## environment', '.env'] },
+  ];
 
-MIT
-`;
+  for (const section of universalRequired) {
+    if (!section.patterns.some(p => contentLower.includes(p))) {
+      missingCritical.push(section.label);
+    }
+  }
 
-    await fs.writeFile(readmePath, readmeContent, 'utf-8');
+  // Check for build/test commands
+  if (!contentLower.includes('npm run build') && !contentLower.includes('pip install') && !contentLower.includes('py_compile')) {
+    missingCritical.push('Build command');
+  }
+  if (!contentLower.includes('npm test') && !contentLower.includes('pytest')) {
+    missingRecommended.push('Test command');
+  }
 
-    return { success: true, path: readmePath };
-  } catch (error) {
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : 'Failed to generate README',
-    };
+  // Workspace-specific checks (fullstack, all)
+  if (isWorkspace(language)) {
+    // Must have per-app sections
+    if (!contentLower.includes('frontend') || !contentLower.includes('backend')) {
+      missingCritical.push('Per-app instructions (frontend/backend)');
+    }
+
+    // Must have deployment section
+    if (!contentLower.includes('## deployment') && !contentLower.includes('### deploy')) {
+      missingCritical.push('Deployment section');
+    }
+
+    // Must mention docker
+    if (!contentLower.includes('docker')) {
+      missingCritical.push('Docker instructions');
+    }
+
+    // 'all' projects must mention website
+    if (language === 'all') {
+      if (!contentLower.includes('website') && !contentLower.includes('next.js')) {
+        missingCritical.push('Website app instructions');
+      }
+    }
+  }
+
+  // Website-specific
+  if (language === 'website') {
+    if (!contentLower.includes('next.js') && !contentLower.includes('next')) {
+      missingRecommended.push('Next.js reference');
+    }
+  }
+
+  // Python-specific
+  if (language === 'python') {
+    if (!contentLower.includes('pip install') && !contentLower.includes('requirements.txt')) {
+      missingCritical.push('Python dependency installation');
+    }
   }
+
+  return {
+    valid: missingCritical.length === 0,
+    missingCritical,
+    missingRecommended,
+  };
 }
 
 /**
@@ -1283,6 +1725,39 @@ ${buildResult.structuralIssue ? buildErrors.slice(0, 1500) : buildErrors.slice(0
       });
     }
 
+    // ============================================
+    // VALIDATE README COMPLETENESS
+    // ============================================
+    onProgress?.('readme', 'Validating README completeness...');
+    let readmeValidation = await validateReadme(projectDir, state.language);
+
+    if (!readmeValidation.valid) {
+      onProgress?.('readme-warning', `README missing critical sections: ${readmeValidation.missingCritical.join(', ')}`);
+
+      // Re-generate and retry once
+      onProgress?.('readme', 'Re-generating README to include missing sections...');
+      await generateProjectReadme(projectDir, state);
+      readmeValidation = await validateReadme(projectDir, state.language);
+
+      if (!readmeValidation.valid) {
+        onProgress?.('readme-warning', `README still missing after re-generation: ${readmeValidation.missingCritical.join(', ')}`);
+        await logger.warn('completion', 'readme_incomplete', 'README is missing critical sections', {
+          missing: readmeValidation.missingCritical,
+        });
+      } else {
+        onProgress?.('readme', 'README validated successfully after re-generation');
+      }
+    } else {
+      onProgress?.('readme', 'README validated successfully');
+    }
+
+    // Log recommended (non-blocking) warnings
+    if (readmeValidation.missingRecommended.length > 0) {
+      for (const rec of readmeValidation.missingRecommended) {
+        onProgress?.('readme-info', `README recommendation: add ${rec}`);
+      }
+    }
+
     // All milestones complete
     state = await completeProject(projectDir);