popeye-cli 1.4.3 → 1.4.5

package/dist/workflow/execution-mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution-mode.d.ts","sourceRoot":"","sources":["../../src/workflow/execution-mode.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"execution-mode.d.ts","sourceRoot":"","sources":["../../src/workflow/execution-mode.ts"],"names":[],"mappings":"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"}

package/dist/workflow/execution-mode.js

@@ -94,6 +94,7 @@ const DEFAULT_MAX_RETRIES = 3;
 async function generateProjectReadme(projectDir, state) {
     try {
         const readmePath = path.join(projectDir, 'README.md');
+        const workspace = isWorkspace(state.language);
         // Extract features from completed milestones
         const features = state.milestones
             .filter(m => m.status === 'complete')
@@ -102,119 +103,495 @@ async function generateProjectReadme(projectDir, state) {
             description: m.description,
             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';
-        // Build README content
-        const readmeContent = `# ${state.name}
+        // Load workspace.json for workspace projects
+        let wsConfig = 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
+            }
+        }
+        const description = state.specification
+            ? extractDescriptionFromSpec(state.specification)
+            : 'A project generated by Popeye CLI.';
+        const sections = [];
+        // Title and description
+        sections.push(`# ${state.name}\n\n${description}`);
+        // Features
+        const featuresContent = features.map(f => `### ${f.name}
+${f.description || ''}
+${f.tasks.length > 0 ? f.tasks.map(t => `- ${t}`).join('\n') : ''}`).join('\n\n');
+        sections.push(`## Features\n\n${featuresContent}`);
+        // Prerequisites
+        sections.push(`## Prerequisites\n\n${generatePrerequisites(state.language)}`);
+        // Installation
+        sections.push(`## Installation\n\n${generateInstallation(state.name, state.language)}`);
+        // Environment Setup
+        sections.push(`## Environment Setup
 
-${state.specification ? extractDescriptionFromSpec(state.specification) : 'A project generated by Popeye CLI.'}
+1. Copy the example environment file:
+   \`\`\`bash
+   cp .env.example .env
+   \`\`\`
 
-## Features
+2. Edit \`.env\` and fill in the required values.`);
+        // Running the Application
+        sections.push(`## Running the Application\n\n${generateRunSection(state.language, wsConfig)}`);
+        // 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
 
-${features.map(f => `### ${f.name}
-${f.description || ''}
-${f.tasks.length > 0 ? f.tasks.map(t => `- ${t}`).join('\n') : ''}`).join('\n\n')}
+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) {
+    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, language) {
+    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, wsConfig) {
+    if (language === 'python') {
+        return `### Development Mode
 
-## Prerequisites
+\`\`\`bash
+python src/main.py
+\`\`\`
+
+### Running Tests
 
-${isTypeScript ? `- Node.js 18.0 or higher
-- npm 8.0 or higher` : `- Python 3.9 or higher
-- pip (Python package manager)`}
+\`\`\`bash
+pytest tests/ -v
+\`\`\`
 
-## Installation
+### Build for Production
 
 \`\`\`bash
-# Clone the repository (if applicable)
-cd ${state.name}
+python -m py_compile src/**/*.py
+\`\`\``;
+    }
+    if (language === 'typescript') {
+        return `### Development Mode
 
-# Install dependencies
-${installCmd}
+\`\`\`bash
+npm run dev
 \`\`\`
 
-## Environment Setup
+### Running Tests
 
-1. Copy the example environment file:
-   \`\`\`bash
-   cp .env.example .env
-   \`\`\`
+\`\`\`bash
+npm test
+\`\`\`
+
+### Build for Production
 
-2. Edit \`.env\` and fill in the required values.
+\`\`\`bash
+npm run build
+\`\`\`
 
-## Running the Application
+### Start Production Server
 
-### Development Mode
+\`\`\`bash
+npm start
+\`\`\``;
+    }
+    if (language === 'website') {
+        return `### Development Mode
 
 \`\`\`bash
-${devCmd}
+npm run dev
 \`\`\`
 
 ### Running Tests
 
 \`\`\`bash
-${testCmd}
+npm test
 \`\`\`
 
 ### Build for Production
 
 \`\`\`bash
-${buildCmd}
+npm run build
 \`\`\`
 
-${isTypeScript ? `### Start Production Server
+### Preview Production Build
 
 \`\`\`bash
-npm start
+npm run start
+\`\`\``;
+    }
+    // Workspace projects (fullstack, all)
+    const apps = wsConfig?.apps;
+    const lines = [];
+    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, language) {
+    if (language === 'python') {
+        return `\`\`\`
+${name}/
 ├── src/                    # Source code
-${isTypeScript ? `│   └── index.ts           # Main entry point` : `│   ├── __init__.py
-│   └── main.py            # Main entry point`}
+│   ├── __init__.py
+│   └── main.py            # 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`}
+├── requirements.txt       # Python dependencies
+├── pyproject.toml         # Project configuration
 ├── .env.example           # Environment template
 ├── .gitignore
 ├── Dockerfile
 └── README.md
-\`\`\`
+\`\`\``;
+    }
+    if (language === 'typescript') {
+        return `\`\`\`
+${name}/
+├── src/                    # Source code
+│   └── index.ts           # Main entry point
+├── tests/                  # Test files
+├── docs/                   # Documentation
+│   ├── PLAN.md            # Development plan
+│   └── WORKFLOW_LOG.md    # Execution log
+├── 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, language, wsConfig) {
+    const apps = wsConfig?.apps;
+    const feImage = apps?.frontend?.docker?.imageName || `${name}-frontend`;
+    const beImage = apps?.backend?.docker?.imageName || `${name}-backend`;
+    const lines = [];
+    lines.push(`Each app can be built and deployed independently as a Docker container.
 
-## Development
+### Build Docker Images
 
-This project was generated using [Popeye CLI](https://github.com/your-org/popeye-cli), an autonomous code generation tool.
+\`\`\`bash
+# Frontend
+docker build -t ${feImage} -f apps/frontend/Dockerfile apps/frontend
 
-### Development Plan
+# 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
 
-See [docs/PLAN.md](docs/PLAN.md) for the complete development plan used to build this project.
+\`\`\`bash
+# Start all services
+docker-compose up -d
 
-### Workflow Log
+# View logs
+docker-compose logs -f
 
-See [docs/WORKFLOW_LOG.md](docs/WORKFLOW_LOG.md) for detailed execution logs.
+# Stop all services
+docker-compose down
+\`\`\``);
+    lines.push(`
+### Individual App Deployment
 
-## License
+#### 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.)
+\`\`\`
 
-MIT
-`;
-        await fs.writeFile(readmePath, readmeContent, 'utf-8');
-        return { success: true, path: readmePath };
+#### 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
+\`\`\``);
     }
-    catch (error) {
-        return {
-            success: false,
-            error: error instanceof Error ? error.message : 'Failed to generate README',
-        };
+    return lines.join('\n');
+}
+/**
+ * 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, language) {
+    const missingCritical = [];
+    const missingRecommended = [];
+    let content;
+    try {
+        content = await fs.readFile(path.join(projectDir, 'README.md'), 'utf-8');
     }
+    catch {
+        return { valid: false, missingCritical: ['README.md file not found'], missingRecommended: [] };
+    }
+    const contentLower = content.toLowerCase();
+    // Sections required for ALL project types
+    const universalRequired = [
+        { label: 'Installation', patterns: ['## installation'] },
+        { label: 'Running the Application', patterns: ['## running', 'development mode'] },
+        { label: 'Project Structure', patterns: ['## project structure'] },
+        { label: 'Environment Setup', patterns: ['## environment', '.env'] },
+    ];
+    for (const section of universalRequired) {
+        if (!section.patterns.some(p => contentLower.includes(p))) {
+            missingCritical.push(section.label);
+        }
+    }
+    // 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');
+    }
+    // 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,
+    };
 }
 /**
  * Extract a brief description from the specification
@@ -979,6 +1356,36 @@ ${buildResult.structuralIssue ? buildErrors.slice(0, 1500) : buildErrors.slice(0
                 error: readmeResult.error,
             });
         }
+        // ============================================
+        // 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);
         onProgress?.('execution-complete', `Project complete! ${completedMilestones} milestones, ${completedTasks} tasks executed successfully.`);