sofia-cli 0.1.1

package/src/develop/pocScaffolder.ts

@@ -0,0 +1,646 @@
+/**
+ * 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';
+
+import type { TechStack } from '../shared/schemas/session.js';
+import type { WorkshopSession } from '../shared/schemas/session.js';
+import type { TemplateEntry } from './templateRegistry.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface ScaffoldContext {
+  /** Kebab-case project name derived from idea title */
+  projectName: string;
+  /** Original idea title */
+  ideaTitle: string;
+  /** Idea description from workshop */
+  ideaDescription: string;
+  /** Tech stack to use */
+  techStack: TechStack;
+  /** Summary of the implementation plan */
+  planSummary: string;
+  /** Workshop session ID */
+  sessionId: string;
+  /** Output directory (absolute path) */
+  outputDir: string;
+}
+
+export interface TemplateFile {
+  /** Path relative to outputDir */
+  path: string;
+  /** File content string or generator function */
+  content: string | ((ctx: ScaffoldContext) => string);
+  /** Skip writing if file already exists (default: true) */
+  skipIfExists?: boolean;
+}
+
+export interface ScaffoldResult {
+  /** Files that were created */
+  createdFiles: string[];
+  /** Files that were skipped because they already existed */
+  skippedFiles: string[];
+  /** The scaffold context used */
+  context: ScaffoldContext;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Convert an idea title to a kebab-case project name.
+ */
+export function toKebabCase(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .substring(0, 64);
+}
+
+/**
+ * Check if a file exists.
+ */
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Template definitions ─────────────────────────────────────────────────────
+
+const NODE_TS_VITEST_TEMPLATE: TemplateFile[] = [
+  {
+    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 {
+  private readonly template: TemplateFile[];
+  private readonly templateId: string | undefined;
+
+  constructor(templateOrFiles?: TemplateEntry | TemplateFile[]) {
+    if (templateOrFiles && 'files' in templateOrFiles && 'id' in templateOrFiles) {
+      // TemplateEntry
+      const entry = templateOrFiles as TemplateEntry;
+      this.template = entry.files;
+      this.templateId = entry.id;
+    } else {
+      this.template = (templateOrFiles as TemplateFile[] | undefined) ?? NODE_TS_VITEST_TEMPLATE;
+      this.templateId = undefined;
+    }
+  }
+
+  /**
+   * Build a ScaffoldContext from a workshop session.
+   */
+  static buildContext(
+    session: WorkshopSession,
+    outputDir: string,
+    templateEntry?: TemplateEntry,
+  ): ScaffoldContext {
+    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: 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: ScaffoldContext): Promise<ScaffoldResult> {
+    await mkdir(context.outputDir, { recursive: true });
+
+    const createdFiles: string[] = [];
+    const skippedFiles: string[] = [];
+
+    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: string): Promise<{
+    totalInitial: number;
+    remaining: number;
+    markers: string[];
+  }> {
+    const { readFile: rf, readdir, stat } = await import('node:fs/promises');
+    const markers: string[] = [];
+
+    async function scanDir(dir: string, base: string): Promise<void> {
+      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(): string[] {
+    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: string): Promise<boolean> {
+    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;
+    }
+  }
+}
+
+// ── Output Validator ─────────────────────────────────────────────────────────
+
+export interface ValidationResult {
+  valid: boolean;
+  missingFiles: string[];
+  errors: string[];
+}
+
+/**
+ * Validate that a scaffold directory meets the poc-output contract requirements.
+ */
+export async function validatePocOutput(outputDir: string): Promise<ValidationResult> {
+  const requiredFiles = [
+    'package.json',
+    'README.md',
+    'tsconfig.json',
+    '.gitignore',
+    '.sofia-metadata.json',
+  ];
+
+  const missingFiles: string[] = [];
+  const errors: string[] = [];
+
+  // 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) as { scripts?: Record<string, string> };
+      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,
+  };
+}