sofia-cli 0.1.1

package/dist/src/develop/pocScaffolder.js

@@ -0,0 +1,542 @@
+/**
+ * PoC Scaffolder.
+ *
+ * Generates the initial proof-of-concept project structure from a
+ * `node-ts-vitest` template. Creates all required files for a working
+ * TypeScript + Vitest project.
+ *
+ * Contract: specs/002-poc-generation/contracts/poc-output.md
+ */
+import { writeFile, mkdir, access } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { execSync } from 'node:child_process';
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Convert an idea title to a kebab-case project name.
+ */
+export function toKebabCase(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .substring(0, 64);
+}
+/**
+ * Check if a file exists.
+ */
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Template definitions ─────────────────────────────────────────────────────
+const NODE_TS_VITEST_TEMPLATE = [
+    {
+        path: '.gitignore',
+        skipIfExists: false,
+        content: `node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+.env
+`,
+    },
+    {
+        path: 'package.json',
+        skipIfExists: true,
+        content: (ctx) => JSON.stringify({
+            name: ctx.projectName,
+            version: '0.1.0',
+            private: true,
+            type: 'module',
+            scripts: {
+                build: 'tsc',
+                start: 'node dist/index.js',
+                test: 'vitest run',
+            },
+            dependencies: {},
+            devDependencies: {
+                typescript: '^5.0.0',
+                vitest: '^3.0.0',
+                '@types/node': '^20.0.0',
+            },
+        }, null, 2) + '\n',
+    },
+    {
+        path: 'tsconfig.json',
+        skipIfExists: true,
+        content: JSON.stringify({
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'Node16',
+                moduleResolution: 'Node16',
+                strict: true,
+                outDir: 'dist',
+                rootDir: 'src',
+                declaration: true,
+                esModuleInterop: true,
+                skipLibCheck: true,
+            },
+            include: ['src'],
+        }, null, 2) + '\n',
+    },
+    {
+        path: 'README.md',
+        skipIfExists: true,
+        content: (ctx) => `# ${ctx.ideaTitle}
+
+${ctx.ideaDescription}
+
+## Generated by
+
+sofIA — AI Discovery Workshop CLI  
+Session: \`${ctx.sessionId}\`  
+Generated: ${new Date().toISOString()}
+
+## Prerequisites
+
+- Node.js 20+
+- npm 9+
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm test
+npm start
+\`\`\`
+
+## How It Works
+
+${ctx.planSummary}
+
+## Technology Stack
+
+- **Language**: ${ctx.techStack.language}
+- **Runtime**: ${ctx.techStack.runtime}
+- **Test Runner**: ${ctx.techStack.testRunner}
+${ctx.techStack.framework ? `- **Framework**: ${ctx.techStack.framework}\n` : ''}
+## Workshop Context
+
+This project was selected and designed through a structured AI Discovery Workshop.
+See [WORKSHOP.md](WORKSHOP.md) for the full decision history, including business
+context, ideation, evaluation, selection rationale, and implementation plan.
+
+Detailed per-phase documentation is in [\`docs/workshop/\`](docs/workshop/).
+`,
+    },
+    {
+        path: 'src/index.ts',
+        skipIfExists: true,
+        content: (ctx) => `/**
+ * ${ctx.ideaTitle}
+ *
+ * ${ctx.ideaDescription}
+ *
+ * Generated by sofIA (session: ${ctx.sessionId})
+ */
+
+/**
+ * Main entry point for the ${ctx.projectName} PoC.
+ *
+ * TODO: Implement the core functionality described in the plan:
+ * ${ctx.planSummary.substring(0, 300)}
+ * 
+ * The test file (tests/index.test.ts) describes the expected behavior.
+ * Implement the required functions to make the tests pass.
+ */
+
+export async function main(input?: unknown): Promise<{ status: string; processed?: boolean }> {
+  // TODO: Implement based on the plan and test requirements
+  throw new Error('Not implemented yet. Ralph loop will implement this based on tests.');
+}
+
+// Run if called directly
+const isMain = process.argv[1]?.endsWith('index.js') || process.argv[1]?.endsWith('index.ts');
+if (isMain) {
+  main()
+    .then((result) => console.log('PoC result:', result))
+    .catch((err) => console.error('PoC error:', err));
+}
+`,
+    },
+    {
+        path: 'tests/index.test.ts',
+        skipIfExists: true,
+        content: (ctx) => `/**
+ * Tests for ${ctx.ideaTitle} PoC.
+ *
+ * These tests describe the expected behavior of the implementation.
+ * They are intentionally failing initially — the Ralph loop will
+ * iteratively fix the implementation until they pass.
+ *
+ * Generated by sofIA (session: ${ctx.sessionId})
+ * Plan Summary: ${ctx.planSummary.substring(0, 200)}
+ */
+import { describe, it, expect } from 'vitest';
+
+describe('${ctx.projectName} PoC', () => {
+  describe('Core Module Exports', () => {
+    it('should export the main entry point', async () => {
+      // This test will fail until src/index.ts exports the required functions
+      const module = await import('../src/index.js');
+      expect(module).toBeDefined();
+      expect(typeof module.main).toBe('function');
+    });
+
+    it('should export core functionality modules', async () => {
+      // Uncomment and modify based on your architecture:
+      // const module = await import('../src/index.js');
+      // expect(module.processData).toBeDefined();
+      // expect(module.analyzeResults).toBeDefined();
+      // expect(module.generateOutput).toBeDefined();
+      
+      // Placeholder: Replace with actual module exports from your plan
+      const module = await import('../src/index.js');
+      expect(module.main).toBeDefined();
+    });
+  });
+
+  describe('Main Functionality', () => {
+    it('should execute the main workflow', async () => {
+      // This test describes the core PoC workflow from the plan
+      const { main } = await import('../src/index.js');
+      
+      // TODO: Ralph loop will implement this based on the plan summary
+      const result = await main();
+      
+      expect(result).toBeDefined();
+      expect(result).toHaveProperty('status');
+      expect(result.status).toBe('success');
+    });
+
+    it('should handle input data correctly', async () => {
+      // Test data processing as described in the plan
+      const { main } = await import('../src/index.js');
+      
+      const testInput = { data: 'test' };
+      const result = await main(testInput);
+      
+      expect(result).toBeDefined();
+      expect(result).toHaveProperty('processed');
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should handle invalid input gracefully', async () => {
+      const { main } = await import('../src/index.js');
+      
+      // Test error cases
+      await expect(async () => {
+        await main(null);
+      }).rejects.toThrow();
+    });
+  });
+});
+`,
+    },
+    {
+        path: '.sofia-metadata.json',
+        skipIfExists: false,
+        content: (ctx) => JSON.stringify({
+            sessionId: ctx.sessionId,
+            featureSpec: '002-poc-generation',
+            generatedAt: new Date().toISOString(),
+            ideaTitle: ctx.ideaTitle,
+            totalIterations: 0,
+            finalStatus: null,
+            terminationReason: null,
+            techStack: {
+                language: ctx.techStack.language.toLowerCase(),
+                runtime: ctx.techStack.runtime.toLowerCase(),
+                testRunner: ctx.techStack.testRunner,
+            },
+        }, null, 2) + '\n',
+    },
+];
+// ── PocScaffolder ────────────────────────────────────────────────────────────
+/**
+ * Generates a PoC project scaffold from the `node-ts-vitest` template.
+ *
+ * Accepts a ScaffoldContext derived from a workshop session and creates
+ * all required files. Files that already exist and have `skipIfExists: true`
+ * are skipped to allow resuming a partial scaffold.
+ */
+export class PocScaffolder {
+    template;
+    templateId;
+    constructor(templateOrFiles) {
+        if (templateOrFiles && 'files' in templateOrFiles && 'id' in templateOrFiles) {
+            // TemplateEntry
+            const entry = templateOrFiles;
+            this.template = entry.files;
+            this.templateId = entry.id;
+        }
+        else {
+            this.template = templateOrFiles ?? NODE_TS_VITEST_TEMPLATE;
+            this.templateId = undefined;
+        }
+    }
+    /**
+     * Build a ScaffoldContext from a workshop session.
+     */
+    static buildContext(session, outputDir, templateEntry) {
+        const idea = session.ideas?.find((i) => i.id === session.selection?.ideaId);
+        const ideaTitle = idea?.title ?? 'AI PoC';
+        const ideaDescription = idea?.description ?? 'A proof-of-concept AI application.';
+        const planSummary = session.plan?.architectureNotes
+            ? session.plan.architectureNotes
+            : (session.plan?.milestones?.map((m) => m.title).join(', ') ?? 'See plan for details');
+        const techStack = templateEntry?.techStack
+            ? { ...templateEntry.techStack }
+            : {
+                language: 'TypeScript',
+                runtime: 'Node.js 20',
+                testRunner: 'npm test',
+                buildCommand: 'npm run build',
+                framework: undefined,
+            };
+        // Infer framework from plan if present
+        if (session.plan?.architectureNotes) {
+            const notes = session.plan.architectureNotes.toLowerCase();
+            if (notes.includes('express'))
+                techStack.framework = 'Express';
+            else if (notes.includes('fastapi'))
+                techStack.framework = 'FastAPI';
+            else if (notes.includes('next'))
+                techStack.framework = 'Next.js';
+        }
+        return {
+            projectName: toKebabCase(ideaTitle),
+            ideaTitle,
+            ideaDescription,
+            techStack,
+            planSummary,
+            sessionId: session.sessionId,
+            outputDir,
+        };
+    }
+    /**
+     * Scaffold the PoC project into the output directory.
+     *
+     * Creates all template files, respecting skipIfExists.
+     * Returns lists of created and skipped files.
+     */
+    async scaffold(context) {
+        await mkdir(context.outputDir, { recursive: true });
+        const createdFiles = [];
+        const skippedFiles = [];
+        for (const templateFile of this.template) {
+            const fullPath = join(context.outputDir, templateFile.path);
+            const shouldSkip = templateFile.skipIfExists !== false;
+            if (shouldSkip && (await fileExists(fullPath))) {
+                skippedFiles.push(templateFile.path);
+                continue;
+            }
+            // Ensure parent directory exists
+            const parentDir = dirname(fullPath);
+            await mkdir(parentDir, { recursive: true });
+            // Generate content
+            const content = typeof templateFile.content === 'function'
+                ? templateFile.content(context)
+                : templateFile.content;
+            await writeFile(fullPath, content, 'utf-8');
+            createdFiles.push(templateFile.path);
+        }
+        // FR-022: Add templateId to metadata if available
+        const metadataPath = join(context.outputDir, '.sofia-metadata.json');
+        if (await fileExists(metadataPath)) {
+            try {
+                const { readFile: rf } = await import('node:fs/promises');
+                const raw = await rf(metadataPath, 'utf-8');
+                const metadata = JSON.parse(raw);
+                if (this.templateId) {
+                    metadata.templateId = this.templateId;
+                }
+                await writeFile(metadataPath, JSON.stringify(metadata, null, 2) + '\n', 'utf-8');
+            }
+            catch {
+                // Ignore metadata update errors
+            }
+        }
+        return { createdFiles, skippedFiles, context };
+    }
+    /**
+     * Scan scaffold files for TODO markers and update .sofia-metadata.json.
+     * Called after scaffolding to track initial TODO count (FR-022).
+     */
+    static async scanAndRecordTodos(outputDir) {
+        const { readFile: rf, readdir, stat } = await import('node:fs/promises');
+        const markers = [];
+        async function scanDir(dir, base) {
+            let entries;
+            try {
+                entries = await readdir(dir);
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                if (entry === 'node_modules' || entry === '.git' || entry === 'dist')
+                    continue;
+                const full = join(dir, entry);
+                const rel = base ? `${base}/${entry}` : entry;
+                let s;
+                try {
+                    s = await stat(full);
+                }
+                catch {
+                    continue;
+                }
+                if (s.isDirectory()) {
+                    await scanDir(full, rel);
+                }
+                else if (s.isFile()) {
+                    try {
+                        const content = await rf(full, 'utf-8');
+                        const lines = content.split('\n');
+                        for (let i = 0; i < lines.length; i++) {
+                            if (lines[i].includes('TODO:')) {
+                                markers.push(`${rel}:${i + 1}: ${lines[i].trim()}`);
+                            }
+                        }
+                    }
+                    catch {
+                        // skip binary or unreadable files
+                    }
+                }
+            }
+        }
+        await scanDir(outputDir, '');
+        const todos = {
+            totalInitial: markers.length,
+            remaining: markers.length,
+            markers,
+        };
+        // Update .sofia-metadata.json with TODO info
+        const metadataPath = join(outputDir, '.sofia-metadata.json');
+        try {
+            const raw = await rf(metadataPath, 'utf-8');
+            const metadata = JSON.parse(raw);
+            metadata.todos = todos;
+            await writeFile(metadataPath, JSON.stringify(metadata, null, 2) + '\n', 'utf-8');
+        }
+        catch {
+            // Metadata file may not exist yet
+        }
+        return todos;
+    }
+    /**
+     * Get the list of file paths in the template.
+     */
+    getTemplateFiles() {
+        return this.template.map((f) => f.path);
+    }
+    /**
+     * Initialize a local git repository in the output directory.
+     * Creates an initial commit with all scaffold files.
+     *
+     * @param outputDir The directory to initialize git in
+     * @returns true if successful, false otherwise
+     */
+    static async initializeGitRepo(outputDir) {
+        try {
+            // Check if git is already initialized
+            const gitDir = join(outputDir, '.git');
+            const exists = await fileExists(gitDir);
+            if (exists) {
+                return true; // Already initialized
+            }
+            // Initialize git repository
+            execSync('git init', { cwd: outputDir, stdio: 'ignore' });
+            // Stage all files
+            execSync('git add .', { cwd: outputDir, stdio: 'ignore' });
+            // Create initial commit
+            execSync('git commit -m "chore: initial scaffold from sofIA"', {
+                cwd: outputDir,
+                stdio: 'ignore',
+                env: {
+                    ...process.env,
+                    GIT_AUTHOR_NAME: 'sofIA',
+                    GIT_AUTHOR_EMAIL: 'sofia@workshop.local',
+                    GIT_COMMITTER_NAME: 'sofIA',
+                    GIT_COMMITTER_EMAIL: 'sofia@workshop.local',
+                },
+            });
+            return true;
+        }
+        catch (_err) {
+            // Git initialization failed - not critical, just return false
+            return false;
+        }
+    }
+}
+/**
+ * Validate that a scaffold directory meets the poc-output contract requirements.
+ */
+export async function validatePocOutput(outputDir) {
+    const requiredFiles = [
+        'package.json',
+        'README.md',
+        'tsconfig.json',
+        '.gitignore',
+        '.sofia-metadata.json',
+    ];
+    const missingFiles = [];
+    const errors = [];
+    // Check required files
+    for (const file of requiredFiles) {
+        const exists = await fileExists(join(outputDir, file));
+        if (!exists) {
+            missingFiles.push(file);
+        }
+    }
+    // Check package.json has test script
+    if (!missingFiles.includes('package.json')) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            const pkgContent = await readFile(join(outputDir, 'package.json'), 'utf-8');
+            const pkg = JSON.parse(pkgContent);
+            if (!pkg.scripts?.test) {
+                errors.push('package.json is missing "test" script');
+            }
+        }
+        catch {
+            errors.push('package.json is not valid JSON');
+        }
+    }
+    // Check for at least one .ts file in src/
+    const { readdir } = await import('node:fs/promises');
+    let hasSrcTs = false;
+    try {
+        const srcFiles = await readdir(join(outputDir, 'src'));
+        hasSrcTs = srcFiles.some((f) => f.endsWith('.ts'));
+    }
+    catch {
+        // src/ doesn't exist
+    }
+    if (!hasSrcTs) {
+        errors.push('No TypeScript files found in src/');
+    }
+    // Check for at least one .test.ts file in tests/
+    let hasTestFile = false;
+    try {
+        const testFiles = await readdir(join(outputDir, 'tests'));
+        hasTestFile = testFiles.some((f) => f.endsWith('.test.ts'));
+    }
+    catch {
+        // tests/ doesn't exist
+    }
+    if (!hasTestFile) {
+        errors.push('No test files found in tests/');
+    }
+    return {
+        valid: missingFiles.length === 0 && errors.length === 0,
+        missingFiles,
+        errors,
+    };
+}