sofia-cli 0.1.1

package/src/develop/templateRegistry.ts

@@ -0,0 +1,427 @@
+/**
+ * Template Registry.
+ *
+ * Defines scaffold templates for different tech stacks and provides
+ * selection logic based on plan architecture notes.
+ *
+ * Contract: specs/004-dev-resume-hardening/contracts/cli.md
+ */
+import type { TemplateFile, ScaffoldContext } from './pocScaffolder.js';
+import type { TechStack } from '../shared/schemas/session.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface TemplateEntry {
+  /** Unique template identifier */
+  id: string;
+  /** Human-readable name for logging */
+  displayName: string;
+  /** Scaffold file definitions */
+  files: TemplateFile[];
+  /** Technology stack for session state */
+  techStack: TechStack;
+  /** Command to install dependencies (e.g., 'npm install') */
+  installCommand: string;
+  /** Command to run tests with JSON output */
+  testCommand: string;
+  /** Keywords to match from plan's architectureNotes/dependencies */
+  matchPatterns: string[];
+}
+
+export type TemplateRegistry = Map<string, TemplateEntry>;
+
+// ── Template Definitions ─────────────────────────────────────────────────────
+
+export const NODE_TS_VITEST_TEMPLATE: TemplateEntry = {
+  id: 'node-ts-vitest',
+  displayName: 'TypeScript + Node.js + Vitest',
+  techStack: {
+    language: 'TypeScript',
+    runtime: 'Node.js 20',
+    testRunner: 'npm test',
+    buildCommand: 'npm run build',
+  },
+  installCommand: 'npm install',
+  testCommand: 'npm test -- --reporter=json',
+  matchPatterns: ['typescript', 'node', 'vitest', 'ts'],
+  files: [
+    {
+      path: '.gitignore',
+      skipIfExists: false,
+      content: `node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+.env
+`,
+    },
+    {
+      path: 'package.json',
+      skipIfExists: true,
+      content: (ctx: ScaffoldContext) =>
+        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: ScaffoldContext) => `# ${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` : ''}
+`,
+    },
+    {
+      path: 'src/index.ts',
+      skipIfExists: true,
+      content: (ctx: ScaffoldContext) => `/**
+ * ${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.
+ * The test file (tests/index.test.ts) describes the expected behavior.
+ */
+export function main(): string {
+  return 'Hello from ${ctx.projectName}!';
+}
+
+// Run if called directly
+const isMain = process.argv[1]?.endsWith('index.js') || process.argv[1]?.endsWith('index.ts');
+if (isMain) {
+  console.log(main());
+}
+`,
+    },
+    {
+      path: 'tests/index.test.ts',
+      skipIfExists: true,
+      content: (ctx: ScaffoldContext) => `/**
+ * 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})
+ */
+import { describe, it, expect } from 'vitest';
+import { main } from '../src/index.js';
+
+describe('${ctx.projectName}', () => {
+  it('should initialize successfully', () => {
+    const result = main();
+    expect(result).toBeDefined();
+    expect(typeof result).toBe('string');
+  });
+
+  it('should implement core functionality', () => {
+    // TODO: sofIA Ralph loop will refine this test to match the actual implementation
+    // Plan: ${ctx.planSummary.substring(0, 200)}
+    const result = main();
+    expect(result).toContain('${ctx.projectName}');
+  });
+});
+`,
+    },
+    {
+      path: '.sofia-metadata.json',
+      skipIfExists: false,
+      content: (ctx: ScaffoldContext) =>
+        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',
+    },
+  ],
+};
+
+export const PYTHON_PYTEST_TEMPLATE: TemplateEntry = {
+  id: 'python-pytest',
+  displayName: 'Python + pytest',
+  techStack: {
+    language: 'Python',
+    runtime: 'Python 3.11',
+    testRunner: 'pytest',
+  },
+  installCommand: 'pip install -r requirements.txt',
+  testCommand: 'pytest --tb=short -q --json-report --json-report-file=-',
+  matchPatterns: ['python', 'fastapi', 'flask', 'django', 'pytest'],
+  files: [
+    {
+      path: '.gitignore',
+      skipIfExists: false,
+      content: `__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+*.egg-info/
+.env
+.pytest_cache/
+`,
+    },
+    {
+      path: 'requirements.txt',
+      skipIfExists: true,
+      content: (ctx: ScaffoldContext) => `# ${ctx.projectName} dependencies
+pytest>=7.0.0
+pytest-json-report>=1.5.0
+`,
+    },
+    {
+      path: 'pytest.ini',
+      skipIfExists: true,
+      content: `[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+`,
+    },
+    {
+      path: 'README.md',
+      skipIfExists: true,
+      content: (ctx: ScaffoldContext) => `# ${ctx.ideaTitle}
+
+${ctx.ideaDescription}
+
+## Generated by
+
+sofIA — AI Discovery Workshop CLI  
+Session: \`${ctx.sessionId}\`  
+Generated: ${new Date().toISOString()}
+
+## Prerequisites
+
+- Python 3.11+
+- pip
+
+## Quick Start
+
+\`\`\`bash
+pip install -r requirements.txt
+pytest
+python src/main.py
+\`\`\`
+
+## 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` : ''}
+`,
+    },
+    {
+      path: 'src/__init__.py',
+      skipIfExists: true,
+      content: '',
+    },
+    {
+      path: 'src/main.py',
+      skipIfExists: true,
+      content: (ctx: ScaffoldContext) => `"""
+${ctx.ideaTitle}
+
+${ctx.ideaDescription}
+
+Generated by sofIA (session: ${ctx.sessionId})
+"""
+
+
+def main() -> str:
+    """Main entry point for the ${ctx.projectName} PoC.
+
+    TODO: Implement the core functionality described in the plan.
+    The test file (tests/test_main.py) describes the expected behavior.
+    """
+    return "Hello from ${ctx.projectName}!"
+
+
+if __name__ == "__main__":
+    print(main())
+`,
+    },
+    {
+      path: 'tests/test_main.py',
+      skipIfExists: true,
+      content: (ctx: ScaffoldContext) => `"""
+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})
+"""
+from src.main import main
+
+
+def test_main_returns_string():
+    result = main()
+    assert isinstance(result, str)
+
+
+def test_main_contains_project_name():
+    result = main()
+    assert "${ctx.projectName}" in result
+`,
+    },
+    {
+      path: '.sofia-metadata.json',
+      skipIfExists: false,
+      content: (ctx: ScaffoldContext) =>
+        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',
+    },
+  ],
+};
+
+// ── Default Registry ─────────────────────────────────────────────────────────
+
+/**
+ * Create the default template registry with built-in templates.
+ */
+export function createDefaultRegistry(): TemplateRegistry {
+  const registry: TemplateRegistry = new Map();
+  registry.set(NODE_TS_VITEST_TEMPLATE.id, NODE_TS_VITEST_TEMPLATE);
+  registry.set(PYTHON_PYTEST_TEMPLATE.id, PYTHON_PYTEST_TEMPLATE);
+  return registry;
+}
+
+// ── Selection ────────────────────────────────────────────────────────────────
+
+/**
+ * Select a template from the registry based on plan architecture notes and dependencies.
+ *
+ * Uses first-match-wins logic: concatenates architectureNotes + dependencies into a
+ * search string, then checks each template's matchPatterns (case-insensitive).
+ * Falls back to `node-ts-vitest` if no match is found.
+ */
+export function selectTemplate(
+  registry: TemplateRegistry,
+  architectureNotes?: string,
+  dependencies?: string[],
+): TemplateEntry {
+  const searchText = [architectureNotes ?? '', ...(dependencies ?? [])].join(' ').toLowerCase();
+
+  for (const entry of registry.values()) {
+    if (entry.matchPatterns.some((p) => searchText.includes(p.toLowerCase()))) {
+      return entry;
+    }
+  }
+
+  // Default fallback
+  return registry.get('node-ts-vitest')!;
+}

package/src/develop/testRunner.ts

@@ -0,0 +1,276 @@
+/**
+ * Test Runner.
+ *
+ * Spawns the PoC's test suite via `npm test -- --reporter=json` in the
+ * output directory, parses Vitest JSON reporter output into a structured
+ * TestResults object, and enforces a 60-second timeout.
+ *
+ * Contract: specs/002-poc-generation/contracts/ralph-loop.md
+ */
+import { spawn } from 'node:child_process';
+
+import type { TestFailure, TestResults } from '../shared/schemas/session.js';
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_RAW_OUTPUT_CHARS = 2_000;
+
+// ── Vitest JSON output types ─────────────────────────────────────────────────
+
+interface VitestAssertionResult {
+  title: string;
+  fullName: string;
+  status: 'passed' | 'failed' | 'skipped' | 'todo' | 'pending';
+  duration?: number;
+  failureMessages?: string[];
+  ancestorTitles?: string[];
+}
+
+interface VitestTestResult {
+  testFilePath: string;
+  status: 'passed' | 'failed';
+  assertionResults: VitestAssertionResult[];
+  startTime?: number;
+  endTime?: number;
+  message?: string;
+}
+
+interface VitestJsonReport {
+  numPassedTests?: number;
+  numFailedTests?: number;
+  numPendingTests?: number;
+  numTotalTests?: number;
+  success?: boolean;
+  testResults?: VitestTestResult[];
+  startTime?: number;
+  endTime?: number;
+}
+
+// ── TestRunner ────────────────────────────────────────────────────────────────
+
+export interface TestRunnerOptions {
+  /** Timeout in milliseconds (default: 60000) */
+  timeoutMs?: number;
+  /** Custom test command (default: 'npm test -- --reporter=json') */
+  testCommand?: string;
+}
+
+export class TestRunner {
+  private readonly timeoutMs: number;
+  private readonly testCommand: string;
+
+  constructor(options: TestRunnerOptions = {}) {
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.testCommand = options.testCommand ?? 'npm test -- --reporter=json';
+  }
+
+  /**
+   * Run the test suite in the given output directory.
+   *
+   * Spawns `npm test -- --reporter=json` and parses the JSON output.
+   * On timeout, returns an error result.
+   */
+  async run(outputDir: string): Promise<TestResults> {
+    const startTime = Date.now();
+
+    let rawOutput = '';
+    let timedOut = false;
+
+    try {
+      rawOutput = await this.spawnTests(outputDir, (timed) => {
+        timedOut = timed;
+      });
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return this.buildErrorResult(startTime, `Test runner error: ${msg}`);
+    }
+
+    if (timedOut) {
+      return this.buildErrorResult(startTime, `Test runner timed out after ${this.timeoutMs}ms`);
+    }
+
+    // Truncate rawOutput to max chars from the end
+    const truncatedOutput =
+      rawOutput.length > MAX_RAW_OUTPUT_CHARS
+        ? rawOutput.slice(-MAX_RAW_OUTPUT_CHARS)
+        : rawOutput;
+
+    return this.parseOutput(truncatedOutput, startTime, rawOutput);
+  }
+
+  /**
+   * Spawn test process and collect output.
+   */
+  private spawnTests(
+    outputDir: string,
+    onTimeout: (timed: boolean) => void,
+  ): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const stdoutChunks: Buffer[] = [];
+      const stderrChunks: Buffer[] = [];
+
+      const parts = this.testCommand.split(/\s+/);
+      const cmd = parts[0];
+      const args = parts.slice(1);
+
+      const child = spawn(cmd, args, {
+        cwd: outputDir,
+        shell: false,
+        env: {
+          ...process.env,
+          // Disable color output for reliable JSON parsing
+          NO_COLOR: '1',
+          FORCE_COLOR: '0',
+        },
+      });
+
+      child.stdout.on('data', (chunk: Buffer) => {
+        stdoutChunks.push(chunk);
+      });
+
+      child.stderr.on('data', (chunk: Buffer) => {
+        stderrChunks.push(chunk);
+      });
+
+      const timer = setTimeout(() => {
+        onTimeout(true);
+        child.kill('SIGTERM');
+        // Force kill after 5 more seconds
+        setTimeout(() => {
+          if (!child.killed) child.kill('SIGKILL');
+        }, 5_000);
+      }, this.timeoutMs);
+
+      child.on('close', () => {
+        clearTimeout(timer);
+        // Combine stdout and stderr for parsing (Vitest may output to stderr)
+        const combined = [
+          Buffer.concat(stdoutChunks).toString('utf-8'),
+          Buffer.concat(stderrChunks).toString('utf-8'),
+        ]
+          .filter(Boolean)
+          .join('\n');
+        resolve(combined);
+      });
+
+      child.on('error', (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Parse Vitest JSON reporter output into TestResults.
+   * Exposed as protected for unit testing purposes.
+   */
+  protected parseOutput(output: string, startTime: number, rawOutput: string): TestResults {
+    const durationMs = Date.now() - startTime;
+
+    // Try to extract JSON from the output (Vitest may mix JSON with other output)
+    const json = this.extractJson(output);
+
+    if (!json) {
+      // Could not parse JSON — return raw output as error info
+      return {
+        passed: 0,
+        failed: 0,
+        skipped: 0,
+        total: 0,
+        durationMs,
+        failures: [],
+        rawOutput: rawOutput.slice(-MAX_RAW_OUTPUT_CHARS),
+      };
+    }
+
+    const passed = json.numPassedTests ?? 0;
+    const failed = json.numFailedTests ?? 0;
+    const skipped = json.numPendingTests ?? 0;
+    const total = json.numTotalTests ?? passed + failed + skipped;
+
+    const failures: TestFailure[] = this.extractFailures(json);
+
+    return {
+      passed,
+      failed,
+      skipped,
+      total,
+      durationMs,
+      failures: failures.slice(0, 10), // max 10 failures
+      rawOutput: rawOutput.slice(-MAX_RAW_OUTPUT_CHARS),
+    };
+  }
+
+  /**
+   * Extract JSON object from potentially mixed output.
+   * Protected for subclass testing.
+   */
+  protected extractJson(output: string): VitestJsonReport | null {
+    // Try to find a JSON object/array in the output
+    const lines = output.split('\n');
+
+    // Try each line (Vitest may output JSON on a single line)
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        try {
+          return JSON.parse(trimmed) as VitestJsonReport;
+        } catch {
+          // Not valid JSON on this line
+        }
+      }
+    }
+
+    // Try the entire output
+    const start = output.indexOf('{');
+    const end = output.lastIndexOf('}');
+    if (start !== -1 && end !== -1 && end > start) {
+      try {
+        return JSON.parse(output.slice(start, end + 1)) as VitestJsonReport;
+      } catch {
+        // Not valid JSON
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Extract TestFailure objects from Vitest JSON output.
+   */
+  private extractFailures(json: VitestJsonReport): TestFailure[] {
+    const failures: TestFailure[] = [];
+
+    for (const testResult of json.testResults ?? []) {
+      for (const assertion of testResult.assertionResults ?? []) {
+        if (assertion.status === 'failed') {
+          const message = assertion.failureMessages?.join('\n') ?? 'Test failed';
+          failures.push({
+            testName: assertion.fullName || assertion.title,
+            message: message.substring(0, 500), // Truncate individual messages
+            file: testResult.testFilePath,
+          });
+        }
+      }
+    }
+
+    return failures;
+  }
+
+  /**
+   * Build an error result (timeout or spawn failure).
+   * Protected for subclass testing.
+   */
+  protected buildErrorResult(startTime: number, errorMessage: string): TestResults {
+    return {
+      passed: 0,
+      failed: 0,
+      skipped: 0,
+      total: 0,
+      durationMs: Date.now() - startTime,
+      failures: [],
+      rawOutput: errorMessage,
+    };
+  }
+}