sofia-cli 0.1.1

package/specs/002-poc-generation/contracts/ralph-loop.md

@@ -0,0 +1,113 @@
+# Contract: Ralph Loop Iteration
+
+Defines the interface contract for the Ralph loop — the autonomous code-generation-test-refine cycle that powers the Develop phase.
+
+## RalphLoop interface
+
+```typescript
+interface RalphLoopOptions {
+  /** CopilotClient for LLM interactions. */
+  client: CopilotClient;
+  /** IO for user-visible output (spinner, activity, streaming text). */
+  io: LoopIO;
+  /** The workshop session with selection and plan populated. */
+  session: WorkshopSession;
+  /** Activity spinner for visual feedback. */
+  spinner?: ActivitySpinner;
+  /** Maximum iterations before forced termination (default: 10). */
+  maxIterations?: number;
+  /** Working directory for the PoC (default: ./poc/<sessionId>/). */
+  outputDir?: string;
+  /** Callback for session persistence after each iteration. */
+  onSessionUpdate?: (session: WorkshopSession) => Promise<void>;
+  /** Event listener for telemetry. */
+  onEvent?: (event: SofiaEvent) => void;
+}
+
+interface RalphLoopResult {
+  /** Updated session with poc state filled in. */
+  session: WorkshopSession;
+  /** Final status of the loop. */
+  finalStatus: 'success' | 'failed' | 'partial';
+  /** Why the loop stopped. */
+  terminationReason: 'tests-passing' | 'max-iterations' | 'user-stopped' | 'error';
+  /** Total iterations executed. */
+  iterationsCompleted: number;
+}
+```
+
+## Loop lifecycle
+
+```
+1. Validate session (selection + plan present)
+2. Scaffold PoC (iteration 1 / outcome: "scaffold")
+   └─ Create project structure, README, package.json, initial tests
+3. Install dependencies (npm install in outputDir)
+4. For iteration = 2..maxIterations:
+   a. Run tests
+   b. If all pass → terminate (tests-passing)
+   c. Parse test failures
+   d. Build LLM prompt with: plan context + current code + test failures
+   e. Send to LLM via ConversationLoop (auto-completing, single turn)
+   f. Apply generated code changes to filesystem
+   g. If new dependencies added to package.json → re-run npm install
+   h. Persist iteration to session
+   i. Check user abort (Ctrl+C) → terminate (user-stopped)
+5. If maxIterations reached → terminate (max-iterations)
+```
+
+> **Note**: Scaffold is always iteration 1 (`outcome: "scaffold"`). LLM-driven refinement
+> iterations start at 2. This aligns with the data model where `PocIteration.iteration`
+> is 1-indexed and the first entry always has `outcome: "scaffold"`.
+
+## Iteration prompt contract
+
+Each iteration sends the LLM a message containing:
+
+```
+## Current State
+- Iteration: {N} of {max}
+- Previous outcome: {tests-passing | tests-failing | scaffold}
+
+## Test Results
+- Passed: {N}, Failed: {N}, Skipped: {N}
+- Failures:
+  1. {testName}: {message} (at {file}:{line})
+  ...
+
+## Files in PoC
+{tree listing of current files}
+
+## Task
+Fix the failing tests. Respond with the complete updated file contents
+for each file you need to modify, using fenced code blocks with file paths.
+```
+
+## Code change format
+
+The LLM must respond with fenced code blocks that include the file path:
+
+````
+```typescript file=src/index.ts
+// complete file content
+```
+````
+
+The code generator parses these blocks and writes them to disk.
+
+## Termination conditions
+
+| Condition | `finalStatus` | `terminationReason` |
+|-----------|--------------|---------------------|
+| All tests pass | `success` | `tests-passing` |
+| Max iterations reached, some tests pass | `partial` | `max-iterations` |
+| Max iterations reached, no tests pass | `failed` | `max-iterations` |
+| User presses Ctrl+C | session preserved as-is | `user-stopped` |
+| Unrecoverable error (LLM timeout, disk error) | `failed` | `error` |
+
+## Error handling
+
+- **LLM timeout**: Log the error, record iteration as `outcome: "error"`, continue to next iteration if retries remain.
+- **Test runner timeout (60s)**: Record as `outcome: "error"` with `errorMessage`, feed timeout info to next iteration.
+- **Filesystem error**: Fail fast with clear error, preserve session state.
+- **Missing session data**: Fail fast before scaffolding with guidance to run Plan phase first.

package/specs/002-poc-generation/data-model.md

@@ -0,0 +1,172 @@
+# Data Model: PoC Generation & Ralph Loop
+
+**Feature**: [spec.md](spec.md)
+**Research**: [research.md](research.md)
+**Date**: 2026-02-27
+
+This document defines the entities introduced or extended by Feature 002. It builds on the Feature 001 data model and extends `PocDevelopmentState` and `PocIteration` with the fields needed for the Ralph loop.
+
+## Entities Modified
+
+### PocDevelopmentState (extended from 001)
+
+Extends the entity defined in Feature 001's [data-model.md](../001-cli-workshop-rebuild/data-model.md) §13.
+
+**Fields**
+
+- `repoPath?: string` — local path to generated PoC directory (e.g., `./poc/<sessionId>/`)
+- `repoUrl?: string` — GitHub URL if created via MCP
+- `repoSource: "local" | "github-mcp"` — how the repo was created
+- `techStack?: TechStack` — technology choices for the PoC
+- `iterations: PocIteration[]` — iteration history (extended, see below)
+- `finalStatus?: "success" | "failed" | "partial"` — extended with "partial" for max-iteration with some passing tests
+- `terminationReason?: "tests-passing" | "max-iterations" | "user-stopped" | "error"` — why the loop ended
+- `totalDurationMs?: number` — total wall-clock time for all iterations
+- `finalTestResults?: TestResults` — test state at loop termination
+
+**Validation rules**
+
+- `repoPath` OR `repoUrl` must be set after first successful scaffold.
+- `repoSource` is required once scaffolding completes.
+- `finalStatus` is set only when the Ralph loop terminates.
+- `terminationReason` is set alongside `finalStatus`.
+- `iterations` must be ordered by `iteration` (1-indexed, monotonically increasing).
+
+### PocIteration (extended from 001)
+
+Extends the entity defined in Feature 001's [data-model.md](../001-cli-workshop-rebuild/data-model.md) §13.
+
+**Fields**
+
+- `iteration: number` — 1-indexed iteration counter
+- `startedAt: string` — ISO-8601 timestamp
+- `endedAt?: string` — ISO-8601 timestamp
+- `outcome: "tests-passing" | "tests-failing" | "error" | "scaffold"` — what happened this iteration
+- `changesSummary?: string` — human-readable description of what changed
+- `filesChanged: string[]` — list of file paths created/modified in this iteration
+- `testResults?: TestResults` — structured test execution results
+- `errorMessage?: string` — error message if iteration failed with an error
+- `llmPromptContext?: string` — summary of context sent to LLM (for auditability, not full prompt)
+
+**Validation rules**
+
+- `iteration` starts at 1, increments by 1.
+- First iteration always has `outcome: "scaffold"`.
+- `filesChanged` must be relative paths within the PoC directory.
+- `testResults` is present when `outcome` is `"tests-passing"` or `"tests-failing"`.
+
+## Entities Introduced
+
+### TechStack
+
+Captures the technology choices for the generated PoC. Determined during scaffolding from the session's `plan.architectureNotes` and `plan.dependencies`.
+
+**Fields**
+
+- `language: string` — primary language (e.g., "TypeScript", "Python")
+- `framework?: string` — web framework or runtime (e.g., "Express", "FastAPI")
+- `testRunner: string` — test runner command (e.g., "npm test", "pytest")
+- `buildCommand?: string` — build command if applicable (e.g., "npm run build")
+- `runtime: string` — runtime environment (e.g., "Node.js 20", "Python 3.11")
+
+**Validation rules**
+
+- `language` and `runtime` are required.
+- `testRunner` is required — the Ralph loop cannot proceed without it.
+
+### TestResults
+
+Structured output from running the PoC's test suite.
+
+**Fields**
+
+- `passed: number` — count of passing tests
+- `failed: number` — count of failing tests
+- `skipped: number` — count of skipped tests
+- `total: number` — total test count
+- `durationMs: number` — test execution time
+- `failures: TestFailure[]` — details of each failure (max 10 to avoid prompt bloat)
+- `rawOutput?: string` — truncated raw test runner output (max 2000 chars)
+
+**Validation rules**
+
+- `total === passed + failed + skipped`.
+- `failures.length <= failed` (may be truncated).
+- `rawOutput` is truncated to 2000 characters from the end (tail).
+
+### TestFailure
+
+Individual test failure detail, fed back to the LLM as context for the next iteration.
+
+**Fields**
+
+- `testName: string` — name/path of the failing test
+- `message: string` — assertion error or exception message
+- `expected?: string` — expected value (if assertion failure)
+- `actual?: string` — actual value (if assertion failure)
+- `file?: string` — test file path
+- `line?: number` — line number of failure
+
+### ScaffoldTemplate
+
+Describes a PoC scaffold template. Templates are defined programmatically (no external template files).
+
+**Fields**
+
+- `id: string` — template identifier (e.g., "node-typescript-express", "python-fastapi")
+- `name: string` — human-readable name
+- `language: string` — primary language
+- `files: TemplateFile[]` — list of files to generate
+
+### TemplateFile
+
+A single file in a scaffold template.
+
+**Fields**
+
+- `path: string` — path relative to PoC root
+- `content: string` — file content (may contain `{{placeholder}}` tokens)
+- `skipIfExists: boolean` — whether to skip writing if file already exists (default: true)
+
+## State Machine Extensions
+
+The Develop phase now has internal sub-states managed by the Ralph loop:
+
+```
+Develop (entered) → Scaffolding → Iteration 1 → ... → Iteration N → Complete/Failed
+```
+
+Transitions within Develop:
+
+- `Scaffolding`: Generate initial PoC project structure → outcome: "scaffold"
+- `Iteration N` (N >= 2): Run tests → feed failures to LLM → generate fixes → outcome: "tests-passing" | "tests-failing" | "error"
+- `Complete`: `finalStatus = "success"` when `terminationReason = "tests-passing"`
+- `Failed`: `finalStatus = "failed"` when `terminationReason = "max-iterations" | "error"`
+- `Partial`: `finalStatus = "partial"` when some tests pass but loop hit max iterations
+
+## Relationships
+
+```
+WorkshopSession
+├── selection: SelectedIdea        ← Input (from Feature 001)
+├── plan: ImplementationPlan       ← Input (from Feature 001)
+└── poc: PocDevelopmentState       ← Output (Feature 002)
+    ├── techStack: TechStack
+    ├── iterations[]: PocIteration
+    │   ├── testResults?: TestResults
+    │   │   └── failures[]: TestFailure
+    │   └── filesChanged[]
+    ├── finalTestResults?: TestResults
+    └── terminationReason
+```
+
+## Export Extensions
+
+The Develop section of `exports/<sessionId>/develop.md` should include:
+
+- PoC repository location (path or URL)
+- Technology stack summary
+- Iteration timeline with outcomes
+- Final test results
+- Files generated/modified per iteration
+- Termination reason

package/specs/002-poc-generation/plan.md

@@ -0,0 +1,109 @@
+# Implementation Plan: PoC Generation & Ralph Loop
+
+**Branch**: `002-poc-generation` | **Date**: 2026-02-27 | **Spec**: [specs/002-poc-generation/spec.md](spec.md)
+**Input**: Feature specification from `/specs/002-poc-generation/spec.md`
+
+**Note**: This plan was generated by the `/speckit.plan` command.
+
+## Summary
+
+Implement the **Develop** phase for sofIA: transform a completed workshop session (with `selection` and `plan` data from Feature 001) into a working proof-of-concept repository. The implementation uses a **Ralph loop** — an autonomous, iterative code-generation cycle where the LLM generates code, tests are executed, failures are fed back as context, and the LLM refines until tests pass or a max-iteration limit is reached. Supports both GitHub MCP–based repo creation and local-filesystem fallback.
+
+## Technical Context
+
+**Language/Version**: Node.js (>=20 LTS) with TypeScript (ES2022 target, ESM)
+**Primary Dependencies**: `@github/copilot-sdk` (LLM orchestration), `commander` (CLI), `ora` (spinner feedback), `marked`/`marked-terminal` (markdown rendering), `pino` (logging), `zod` (schema validation)
+**Storage**: Filesystem — sessions in `.sofia/sessions/<id>.json`, PoC output in `./poc/<sessionId>/` (local) or GitHub repo (MCP)
+**Testing**: Vitest with `@vitest/coverage-v8`; unit, integration, e2e, and live test directories
+**Target Platform**: Linux/macOS CLI (Windows supported via WSL)
+**Project Type**: CLI application (extends existing `sofiacli` binary)
+**Performance Goals**: Complete a single Ralph loop iteration in <120s (LLM timeout); full PoC generation in <10 iterations
+**Constraints**: LLM call timeout at 120s per turn; GitHub MCP may be unavailable; no direct filesystem access on remote repos
+**Scale/Scope**: Single-user CLI, one PoC per session, typical PoC is 5–20 source files
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- **Outcome-first discovery**: ✅ PoC generation is the culminating deliverable of the workshop — directly tied to the user's selected AI idea and business goals.
+- **Secure-by-default**: ✅ No secrets in logs/prompts; PoC scaffolds use secure defaults; GitHub MCP requests respect organization policies.
+- **Node.js + TypeScript**: ✅ Extends the existing sofIA CLI codebase with the same stack.
+- **MCP-first**: ✅ GitHub MCP for repo creation when available; Context7 for library documentation; Microsoft Docs/Azure MCP for cloud guidance; web.search for implementation research; local fallback is explicit and auditable.
+- **Test-first (NON-NEGOTIABLE)**: ✅ Ralph loop is inherently test-driven — each iteration starts from a failing test. Implementation follows Red → Green → Review.
+- **CLI transparency**: ✅ Spinner shows iteration progress; streaming output during code generation; clear failure messages with recovery options.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/002-poc-generation/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+├── contracts/           # Phase 1 output
+│   ├── ralph-loop.md    # Ralph loop iteration contract
+│   └── poc-output.md    # PoC repository output contract
+└── tasks.md             # Phase 2 output (created by /speckit.tasks)
+```
+
+### Source Code (repository root)
+
+```text
+src/
+├── cli/
+│   ├── developCommand.ts        # NEW: `sofia dev` command handler
+│   └── index.ts                 # MODIFIED: register dev command
+├── develop/                     # NEW: Develop phase module
+│   ├── ralphLoop.ts             # Autonomous Ralph loop orchestrator
+│   ├── pocScaffolder.ts         # PoC repo scaffold generation
+│   ├── testRunner.ts            # Test execution and result parsing
+│   ├── codeGenerator.ts         # LLM-driven code generation per iteration
+│   ├── mcpContextEnricher.ts    # MCP-driven context enrichment (Context7, Azure MCP, web.search)
+│   └── githubMcpAdapter.ts      # GitHub MCP repo creation adapter
+├── phases/
+│   └── phaseHandlers.ts         # MODIFIED: replace boundary handler with real Develop handler
+├── prompts/
+│   ├── develop.md               # NEW: Develop phase system prompt (code generation)
+│   └── develop-boundary.md      # EXISTING: requirements capture (kept for backward compat)
+├── sessions/
+│   └── exportWriter.ts          # MODIFIED: enrich Develop export with iteration details
+└── shared/
+    └── schemas/
+        └── session.ts           # MODIFIED: extend PocDevelopmentState with richer fields
+
+tests/
+├── unit/
+│   ├── develop/
+│   │   ├── ralphLoop.spec.ts
+│   │   ├── pocScaffolder.spec.ts
+│   │   ├── testRunner.spec.ts
+│   │   ├── codeGenerator.spec.ts
+│   │   ├── mcpContextEnricher.spec.ts
+│   │   └── githubMcpAdapter.spec.ts
+│   └── cli/
+│       └── developCommand.spec.ts
+├── integration/
+│   ├── ralphLoopFlow.spec.ts
+│   └── pocGeneration.spec.ts
+└── e2e/
+    └── developE2e.spec.ts
+```
+
+**Structure Decision**: Single project, extending the existing `src/` layout. New code lives in `src/develop/` as a cohesive module. The `develop/` directory groups Ralph loop components (orchestrator, scaffolder, test runner, code generator, MCP adapter) as peer modules with clean interfaces.
+
+## Post-Design Constitution Re-Check
+
+*All 6 gates re-evaluated after Phase 1 design. No violations.*
+
+- **Outcome-first discovery**: ✅ Contracts explicitly link PoC output back to the workshop session and selected idea via `.sofia-metadata.json`.
+- **Secure-by-default**: ✅ Local-first output; GitHub MCP is opt-in; no PII in metadata; scaffold templates use secure TS defaults.
+- **Node.js + TypeScript**: ✅ All contracts specify TypeScript, ESM, Vitest; scaffold generates strict `tsconfig.json`.
+- **MCP-first**: ✅ GitHub MCP for repo creation when available; graceful local fallback with no error; Context7 for PoC dependency docs; Azure MCP for cloud architecture guidance; web.search for stuck-iteration research; no ad-hoc HTTP calls.
+- **Test-first (NON-NEGOTIABLE)**: ✅ Ralph loop contract is inherently test-driven — every iteration starts from test failures. Generated PoCs always include test files.
+- **CLI transparency**: ✅ Spinner/progress during iterations; clear termination reasons; structured error messages with recovery guidance.
+
+## Complexity Tracking
+
+No constitution violations — all gates pass (both pre-research and post-design checks).

package/specs/002-poc-generation/quickstart.md

@@ -0,0 +1,97 @@
+# Quickstart: sofIA PoC Generation (Develop Phase)
+
+## Prerequisites
+
+- Node.js 20 LTS
+- npm
+- A completed sofIA workshop session (with Selection and Plan phases done)
+
+## Setup
+
+```bash
+npm install
+```
+
+## Run PoC generation
+
+```bash
+# Start PoC generation for the most recent session
+npm run start -- dev
+
+# Start PoC generation for a specific session
+npm run start -- dev --session <id>
+
+# Set max iterations (default: 10)
+npm run start -- dev --session <id> --max-iterations 5
+
+# Specify output directory (default: ./poc/<sessionId>/)
+npm run start -- dev --session <id> --output ./my-poc
+```
+
+## What happens
+
+1. **Validation** — Checks the session has completed the Selection and Plan phases
+2. **Scaffolding** — Creates a project skeleton in the output directory (package.json, tsconfig.json, README.md, initial src/ and tests/)
+3. **Ralph Loop** — Iterates autonomously:
+   - Runs tests (`vitest run --reporter=json`)
+   - If tests pass → done
+   - If tests fail → sends failures + current code to LLM → applies fixes → re-runs tests
+4. **Completion** — Writes `.sofia-metadata.json`, updates session state, reports results
+
+## Output
+
+```
+./poc/<sessionId>/
+├── README.md            # What the PoC does, how to run it
+├── package.json         # Dependencies, scripts
+├── tsconfig.json        # TypeScript config
+├── src/                 # Generated implementation
+├── tests/               # Generated tests
+└── .sofia-metadata.json # Session linkage & metadata
+```
+
+## Run the generated PoC
+
+```bash
+cd ./poc/<sessionId>
+npm install
+npm test        # Run the tests
+npm start       # Run the PoC
+```
+
+## Storage
+
+- PoC output: `./poc/<sessionId>/` (or custom `--output` path)
+- Session state (updated): `.sofia/sessions/<sessionId>.json`
+- Exports (updated): `./exports/<sessionId>/`
+
+## Testing the Develop module
+
+```bash
+# Unit tests for develop module
+npm test -- tests/unit/develop/
+
+# Integration tests (Ralph loop with fakes)
+npm test -- tests/integration/ralphLoop.integration.test.ts
+
+# E2E (full PoC generation with real LLM — slow)
+npm test -- tests/e2e/pocGeneration.e2e.test.ts
+```
+
+## Debug logs
+
+```bash
+npm run start -- dev --session <id> --debug --log-file .sofia/logs/dev.log
+```
+
+## GitHub MCP integration (optional)
+
+When the GitHub MCP server is available, sofIA can create a GitHub repository for the PoC:
+
+```bash
+# PoC generation will auto-detect GitHub MCP availability
+# and prompt before creating a repo
+npm run start -- dev --session <id>
+```
+
+If GitHub MCP is not available, all output stays local — no error, just a different `repoSource` in session state.