sofia-cli 0.1.1

package/dist/tests/unit/shared/errorClassifier.spec.js

@@ -0,0 +1,131 @@
+/**
+ * Error classifier tests (T055).
+ *
+ * Validates centralized error classification and user-facing messages:
+ * - Maps known error codes to categories
+ * - Provides actionable messages
+ * - Handles unknown errors gracefully
+ * - Supports MCP, network, auth, and session errors
+ */
+import { describe, it, expect } from 'vitest';
+import { classifyError, toUserMessage, } from '../../../src/shared/errorClassifier.js';
+describe('errorClassifier', () => {
+    describe('classifyError', () => {
+        it('classifies ECONNREFUSED as connection error', () => {
+            const err = Object.assign(new Error('connect ECONNREFUSED'), { code: 'ECONNREFUSED' });
+            const result = classifyError(err);
+            expect(result.category).toBe('connection');
+            expect(result.recoverable).toBe(true);
+        });
+        it('classifies ENOTFOUND as dns error', () => {
+            const err = Object.assign(new Error('getaddrinfo ENOTFOUND'), { code: 'ENOTFOUND' });
+            const result = classifyError(err);
+            expect(result.category).toBe('dns');
+            expect(result.recoverable).toBe(true);
+        });
+        it('classifies ETIMEDOUT as timeout error', () => {
+            const err = Object.assign(new Error('connect ETIMEDOUT'), { code: 'ETIMEDOUT' });
+            const result = classifyError(err);
+            expect(result.category).toBe('timeout');
+            expect(result.recoverable).toBe(true);
+        });
+        it('classifies 401 as auth error', () => {
+            const err = Object.assign(new Error('Unauthorized'), { statusCode: 401 });
+            const result = classifyError(err);
+            expect(result.category).toBe('auth');
+            expect(result.recoverable).toBe(false);
+        });
+        it('classifies 403 as auth error', () => {
+            const err = Object.assign(new Error('Forbidden'), { statusCode: 403 });
+            const result = classifyError(err);
+            expect(result.category).toBe('auth');
+        });
+        it('classifies 429 as rate-limit error', () => {
+            const err = Object.assign(new Error('Too Many Requests'), { statusCode: 429 });
+            const result = classifyError(err);
+            expect(result.category).toBe('rate-limit');
+            expect(result.recoverable).toBe(true);
+        });
+        it('classifies ENOENT as not-found error', () => {
+            const err = Object.assign(new Error('ENOENT: no such file'), { code: 'ENOENT' });
+            const result = classifyError(err);
+            expect(result.category).toBe('not-found');
+        });
+        it('classifies session validation errors', () => {
+            const err = new Error('Invalid session: missing required field');
+            err.name = 'ZodError';
+            const result = classifyError(err);
+            expect(result.category).toBe('validation');
+        });
+        it('classifies unknown errors as internal', () => {
+            const err = new Error('Something unexpected happened');
+            const result = classifyError(err);
+            expect(result.category).toBe('internal');
+            expect(result.recoverable).toBe(false);
+        });
+        it('classifies MCP-related errors', () => {
+            const err = new Error('MCP server workiq failed to start');
+            const result = classifyError(err);
+            expect(result.category).toBe('mcp');
+        });
+        it('handles non-Error objects', () => {
+            const result = classifyError('string error');
+            expect(result.category).toBe('internal');
+            expect(result.originalError).toBe('string error');
+        });
+    });
+    describe('toUserMessage', () => {
+        it('returns actionable message for connection errors', () => {
+            const classification = {
+                category: 'connection',
+                recoverable: true,
+                message: 'Connection refused',
+                originalError: new Error('ECONNREFUSED'),
+            };
+            const msg = toUserMessage(classification);
+            expect(msg).toContain('connection');
+        });
+        it('returns actionable message for auth errors', () => {
+            const classification = {
+                category: 'auth',
+                recoverable: false,
+                message: 'Unauthorized',
+                originalError: new Error('401'),
+            };
+            const msg = toUserMessage(classification);
+            expect(msg).toContain('auth');
+        });
+        it('returns actionable message for timeout errors', () => {
+            const classification = {
+                category: 'timeout',
+                recoverable: true,
+                message: 'Request timed out',
+                originalError: new Error('ETIMEDOUT'),
+            };
+            const msg = toUserMessage(classification);
+            expect(msg).toContain('timed out');
+        });
+        it('returns generic message for internal errors', () => {
+            const classification = {
+                category: 'internal',
+                recoverable: false,
+                message: 'Unexpected error',
+                originalError: new Error('kaboom'),
+            };
+            const msg = toUserMessage(classification);
+            expect(msg.length).toBeGreaterThan(0);
+        });
+        it('does not include stack traces', () => {
+            const err = new Error('test');
+            err.stack = 'Error: test\n at something.js:1:2';
+            const classification = {
+                category: 'internal',
+                recoverable: false,
+                message: 'test',
+                originalError: err,
+            };
+            const msg = toUserMessage(classification);
+            expect(msg).not.toContain('at something');
+        });
+    });
+});

package/dist/tests/unit/shared/events.spec.js

@@ -0,0 +1,55 @@
+/**
+ * Unit tests for event model.
+ */
+import { describe, it, expect } from 'vitest';
+import { createTextDeltaEvent, createActivityEvent, createToolCallEvent, createToolResultEvent, createPhaseChangedEvent, createErrorEvent, } from '../../../src/shared/events.js';
+describe('event model', () => {
+    it('createTextDeltaEvent creates a valid event', () => {
+        const event = createTextDeltaEvent('Hello ');
+        expect(event.type).toBe('TextDelta');
+        expect(event.text).toBe('Hello ');
+        expect(event.timestamp).toBeTruthy();
+    });
+    it('createActivityEvent creates a valid event', () => {
+        const event = createActivityEvent('Connecting to MCP...');
+        expect(event.type).toBe('Activity');
+        expect(event.message).toBe('Connecting to MCP...');
+    });
+    it('createToolCallEvent includes tool name and args', () => {
+        const event = createToolCallEvent('web.search', { query: 'AI trends' });
+        expect(event.type).toBe('ToolCall');
+        expect(event.toolName).toBe('web.search');
+        expect(event.args).toEqual({ query: 'AI trends' });
+    });
+    it('createToolResultEvent includes tool name and result', () => {
+        const event = createToolResultEvent('web.search', { results: [] });
+        expect(event.type).toBe('ToolResult');
+        expect(event.toolName).toBe('web.search');
+    });
+    it('createPhaseChangedEvent includes old and new phase', () => {
+        const event = createPhaseChangedEvent('Discover', 'Ideate');
+        expect(event.type).toBe('PhaseChanged');
+        expect(event.fromPhase).toBe('Discover');
+        expect(event.toPhase).toBe('Ideate');
+    });
+    it('createErrorEvent includes code and message', () => {
+        const event = createErrorEvent('MCP_TIMEOUT', 'WorkIQ timed out');
+        expect(event.type).toBe('Error');
+        expect(event.code).toBe('MCP_TIMEOUT');
+        expect(event.message).toBe('WorkIQ timed out');
+    });
+    it('all events have a timestamp', () => {
+        const events = [
+            createTextDeltaEvent('x'),
+            createActivityEvent('y'),
+            createToolCallEvent('t', {}),
+            createToolResultEvent('t', {}),
+            createPhaseChangedEvent('Discover', 'Ideate'),
+            createErrorEvent('E', 'msg'),
+        ];
+        for (const e of events) {
+            expect(e.timestamp).toBeTruthy();
+            expect(typeof e.timestamp).toBe('string');
+        }
+    });
+});

package/dist/tests/unit/shared/markdownRenderer.spec.js

@@ -0,0 +1,35 @@
+/**
+ * Unit tests for markdown renderer.
+ */
+import { describe, it, expect } from 'vitest';
+import { renderMarkdown } from '../../../src/shared/markdownRenderer.js';
+describe('renderMarkdown', () => {
+    it('renders a heading', () => {
+        const output = renderMarkdown('# Hello World');
+        expect(output).toBeTruthy();
+        expect(output.length).toBeGreaterThan(0);
+    });
+    it('renders a list', () => {
+        const output = renderMarkdown('- One\n- Two\n- Three');
+        expect(output).toContain('One');
+        expect(output).toContain('Two');
+    });
+    it('renders a code block', () => {
+        const output = renderMarkdown('```json\n{"key": "value"}\n```');
+        expect(output).toContain('key');
+    });
+    it('returns plain text in non-TTY mode', () => {
+        const output = renderMarkdown('# Hello World', { isTTY: false });
+        // Should not contain ANSI codes in non-TTY mode
+        expect(output).toContain('Hello World');
+    });
+    it('handles empty string', () => {
+        const output = renderMarkdown('');
+        expect(output).toBe('');
+    });
+    it('handles raw Markdown preservation in non-TTY json mode', () => {
+        const output = renderMarkdown('# Title\n\nBody text', { isTTY: false, jsonMode: true });
+        // In json mode, return raw markdown
+        expect(output).toContain('# Title');
+    });
+});

package/dist/tests/unit/shared/markdownRendererChunks.spec.js

@@ -0,0 +1,70 @@
+/**
+ * Tests for markdownRenderer handling of partial/incremental chunks (T081).
+ *
+ * Verifies that renderMarkdown doesn't crash on partial markdown input
+ * (split headings, incomplete bold, partial tables).
+ */
+import { describe, it, expect } from 'vitest';
+import { renderMarkdown } from '../../../src/shared/markdownRenderer.js';
+describe('renderMarkdown incremental chunk handling (T081)', () => {
+    it('handles a partial heading (no newline)', () => {
+        // During streaming, a heading might arrive without a trailing newline
+        const result = renderMarkdown('## Start of head', { isTTY: true });
+        expect(result).toBeTruthy();
+        expect(result).toContain('Start of head');
+    });
+    it('handles incomplete bold syntax', () => {
+        // Bold started but not closed
+        const result = renderMarkdown('Some **bold text without', { isTTY: true });
+        expect(result).toBeTruthy();
+        expect(result).toContain('bold text without');
+    });
+    it('handles incomplete code block', () => {
+        // Code block opened but not closed
+        const result = renderMarkdown('```typescript\nconst x = 1;\n', { isTTY: true });
+        expect(result).toBeTruthy();
+        expect(result).toContain('const x = 1');
+    });
+    it('handles partial table row', () => {
+        const result = renderMarkdown('| Column 1 | Column 2 |\n| ----', { isTTY: true });
+        expect(result).toBeTruthy();
+    });
+    it('handles empty chunk', () => {
+        const result = renderMarkdown('', { isTTY: true });
+        expect(result).toBe('');
+    });
+    it('handles single character chunk', () => {
+        const result = renderMarkdown('H', { isTTY: true });
+        expect(result).toBeTruthy();
+    });
+    it('handles newline-only chunk without throwing', () => {
+        const result = renderMarkdown('\n', { isTTY: true });
+        // A newline-only chunk may produce empty string; it must not throw
+        expect(typeof result).toBe('string');
+    });
+    it('handles incomplete link syntax', () => {
+        const result = renderMarkdown('Click [here](http://example', { isTTY: true });
+        expect(result).toBeTruthy();
+    });
+    it('handles partial list item', () => {
+        const result = renderMarkdown('- Item one\n- Item tw', { isTTY: true });
+        expect(result).toBeTruthy();
+        expect(result).toContain('Item one');
+    });
+    it('renders complete markdown correctly in TTY mode', () => {
+        const md = '## Title\n\n- **Bold item**\n- Regular item\n\n```js\nconst x = 1;\n```\n';
+        const result = renderMarkdown(md, { isTTY: true });
+        expect(result).toContain('Title');
+        expect(result).toContain('Bold item');
+        expect(result).toContain('Regular item');
+    });
+    it('returns raw markdown in JSON mode regardless of content', () => {
+        const md = '## Partial **heading';
+        const result = renderMarkdown(md, { isTTY: true, jsonMode: true });
+        expect(result).toBe(md);
+    });
+    it('handles non-TTY mode with partial markdown', () => {
+        const result = renderMarkdown('**incomplete bold', { isTTY: false });
+        expect(result).toBeTruthy();
+    });
+});

package/dist/tests/unit/shared/tableRenderer.spec.js

@@ -0,0 +1,34 @@
+/**
+ * Unit tests for table renderer.
+ */
+import { describe, it, expect } from 'vitest';
+import { renderTable } from '../../../src/shared/tableRenderer.js';
+describe('renderTable', () => {
+    it('renders a simple table', () => {
+        const output = renderTable({
+            head: ['Name', 'Score'],
+            rows: [
+                ['Idea A', '85'],
+                ['Idea B', '72'],
+            ],
+        });
+        expect(output).toContain('Name');
+        expect(output).toContain('Score');
+        expect(output).toContain('Idea A');
+        expect(output).toContain('85');
+    });
+    it('handles empty rows', () => {
+        const output = renderTable({
+            head: ['Col1'],
+            rows: [],
+        });
+        expect(output).toContain('Col1');
+    });
+    it('renders without headers', () => {
+        const output = renderTable({
+            rows: [['a', 'b'], ['c', 'd']],
+        });
+        expect(output).toContain('a');
+        expect(output).toContain('d');
+    });
+});

package/dist/vitest.config.js

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        globals: true,
+        setupFiles: ['tests/setup/loadEnv.ts'],
+        include: ['tests/**/*.{test,spec}.ts'],
+        exclude: ['tests/live/**', 'tests/fixtures/**'],
+        coverage: {
+            enabled: true,
+            provider: 'v8',
+        },
+        testTimeout: 10_000, // Default timeout for tests (can be overridden per test)
+    },
+});

package/dist/vitest.live.config.js

@@ -0,0 +1,18 @@
+/**
+ * Vitest config for live (slow) tests that hit the real Copilot SDK.
+ * Run with: npm run test:live
+ */
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        globals: true,
+        setupFiles: ['tests/setup/loadEnv.ts'],
+        include: ['tests/live/**/*.{test,spec}.ts'],
+        testTimeout: 120_000,
+        hookTimeout: 60_000,
+        coverage: {
+            enabled: true,
+            provider: 'v8',
+        },
+    },
+});

package/docs/README.md

@@ -0,0 +1,35 @@
+# sofIA CLI Documentation
+
+sofIA is an AI Discovery Workshop CLI that guides facilitators through the structured process of discovering, ideating, designing, selecting, and planning AI solutions for business needs.
+
+## Table of Contents
+
+- [CLI Usage](./cli-usage.md) — Commands, flags, and examples
+- [Session Model](./session-model.md) — Session lifecycle, phases, and persistence
+- [Export Format](./export-format.md) — Exported artifacts and summary JSON structure
+- [Environment Variables](./environment.md) — Configuration via environment
+- [Architecture](./architecture.md) — Module overview and data flow
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start an interactive workshop
+npm run start -- workshop
+
+# Check session status
+npm run start -- status
+
+# Generate a PoC from a completed session
+npm run start -- dev --session <id>
+
+# Export session artifacts
+npm run start -- export --session <id>
+```
+
+For the full specification, see:
+
+- Workshop phases (Discover → Plan): [specs/001-cli-workshop-rebuild/](../specs/001-cli-workshop-rebuild/)
+- PoC generation & Ralph loop (Develop): [specs/002-poc-generation/](../specs/002-poc-generation/)

package/docs/architecture.md

@@ -0,0 +1,169 @@
+# Architecture
+
+## Module Overview
+
+```
+src/
+├── cli/                     # CLI entrypoints and command handlers
+│   ├── index.ts             # Main entrypoint (commander setup)
+│   ├── workshopCommand.ts   # Interactive workshop menu and flow
+│   ├── developCommand.ts    # `sofia dev` — PoC generation handler
+│   ├── statusCommand.ts     # Session status display
+│   ├── exportCommand.ts     # Artifact export handler
+│   ├── directCommands.ts    # Non-interactive direct command mode
+│   ├── ioContext.ts         # TTY/non-TTY detection, JSON mode, I/O
+│   └── preflight.ts         # Pre-flight environment checks
+├── develop/                 # PoC generation & Ralph loop
+│   ├── index.ts             # Barrel export
+│   ├── ralphLoop.ts         # Autonomous iteration orchestrator
+│   ├── pocScaffolder.ts     # PoC project scaffolding + output validation
+│   ├── codeGenerator.ts     # LLM-driven code generation & prompt building
+│   ├── testRunner.ts        # Test execution and result parsing
+│   ├── mcpContextEnricher.ts# MCP-driven context enrichment (Context7, Azure, web search)
+│   └── githubMcpAdapter.ts  # GitHub MCP repo creation adapter
+├── loop/
+│   └── conversationLoop.ts  # Multi-turn conversation orchestrator
+├── phases/
+│   ├── phaseHandlers.ts     # Phase handler factory (one per phase)
+│   └── phaseExtractors.ts   # JSON block extraction + Zod validation
+├── sessions/
+│   ├── sessionStore.ts      # Read/write session JSON files
+│   ├── sessionManager.ts    # Backtracking, phase transitions
+│   ├── exportWriter.ts      # Markdown + summary.json generation
+│   └── exportPaths.ts       # Export directory path resolution
+├── mcp/
+│   ├── mcpManager.ts        # MCP server connection manager
+│   └── webSearch.ts         # Azure AI Foundry Bing Search tool
+├── prompts/
+│   └── promptLoader.ts      # Cached prompt template composition
+├── logging/
+│   └── logger.ts            # Pino logger with PII redaction
+├── shared/
+│   ├── schemas/
+│   │   └── session.ts       # Zod schemas for all session entities
+│   ├── copilotClient.ts     # Copilot SDK abstraction + test fakes
+│   ├── errorClassifier.ts   # Error categorization (9 types)
+│   ├── events.ts            # Activity/telemetry event model
+│   ├── markdownRenderer.ts  # marked + marked-terminal rendering
+│   ├── tableRenderer.ts     # cli-table3 wrapper
+│   └── data/
+│       ├── cards.json        # AI Envisioning Cards dataset
+│       └── cardsLoader.ts    # Cards dataset loader
+└── vendor/
+    └── zod.ts               # Re-export of zod/v4
+```
+
+## Data Flow
+
+```
+User Input
+    │
+    ▼
+┌─────────────────┐     ┌──────────────────┐
+│  CLI Commands   │────▶│  workshopCommand  │
+│  (index.ts)     │     │  statusCommand    │
+│                 │     │  exportCommand    │
+│                 │     │  directCommands   │
+└─────────────────┘     └────────┬─────────┘
+                                 │
+                    ┌────────────▼───────────┐
+                    │   ConversationLoop     │
+                    │   (multi-turn chat)    │
+                    └────────────┬───────────┘
+                                 │
+              ┌──────────────────┼──────────────────┐
+              ▼                  ▼                   ▼
+     ┌────────────────┐  ┌──────────────┐  ┌──────────────────┐
+     │ PhaseHandlers  │  │ CopilotClient│  │ SessionStore     │
+     │ (per-phase     │  │ (SDK or fake)│  │ (JSON persist)   │
+     │  logic)        │  └──────────────┘  └──────────────────┘
+     └────────┬───────┘
+              │
+       ┌──────┴──────┐
+       ▼              ▼
+┌──────────────┐  ┌─────────────────┐
+│ promptLoader │  │ phaseExtractors │
+│ (templates)  │  │ (Zod parse)     │
+└──────────────┘  └─────────────────┘
+```
+
+## Key Design Patterns
+
+### PhaseHandler Interface
+
+Each workshop phase implements the `PhaseHandler` interface:
+
+```typescript
+interface PhaseHandler {
+  phase: PhaseValue;
+  buildSystemPrompt(session: WorkshopSession): string;
+  getReferences(session: WorkshopSession): Reference[];
+  extractResult(text: string): unknown;
+  isComplete(session: WorkshopSession): boolean;
+}
+```
+
+### ConversationLoop
+
+The `ConversationLoop` orchestrates multi-turn conversations between the user, the Copilot client, and the active `PhaseHandler`. It handles:
+
+- Streaming responses with real-time rendering
+- Activity/telemetry event emission
+- Ctrl+C signal handling for graceful shutdown
+- Session persistence after every turn
+
+### LoopIO Interface
+
+I/O is abstracted behind `LoopIO` for testability:
+
+- **TTY mode:** Interactive prompts via terminal
+- **Non-TTY mode:** Reads from stdin, writes JSON to stdout
+- **JSON mode:** Activity events go to stderr, structured data to stdout
+
+### Error Classification
+
+Errors are classified into 9 categories with recovery hints:
+
+| Category     | Recoverable | Example               |
+| ------------ | ----------- | --------------------- |
+| `connection` | Yes         | Network unreachable   |
+| `dns`        | Yes         | DNS resolution failed |
+| `timeout`    | Yes         | Request timed out     |
+| `auth`       | No          | Invalid credentials   |
+| `rate-limit` | Yes         | Too many requests     |
+| `not-found`  | No          | Resource not found    |
+| `validation` | No          | Invalid input         |
+| `mcp`        | Yes         | MCP server down       |
+| `internal`   | No          | Unexpected error      |
+
+### Pre-flight Checks
+
+Before starting a workshop, `runPreflightChecks()` runs environment validations in parallel:
+
+- Copilot SDK connectivity
+- MCP server readiness
+- Web search tool availability
+
+Each check reports pass/warn/fail with a message. Required checks block startup; optional checks emit warnings.
+
+## Testing Architecture
+
+```
+tests/
+├── unit/           # Single-module tests with mocks
+├── integration/    # Multi-module flow tests
+└── e2e/            # PTY-based interactive tests
+```
+
+- **Test runner:** Vitest with v8 coverage
+- **Mocking:** `vi.mock()` at module boundaries
+- **Fakes:** `createFakeCopilotClient()` for deterministic chat responses
+- **TDD workflow:** Red → Green → Review for all new behavior
+
+## Related
+
+- Feature 001 spec: [specs/001-cli-workshop-rebuild/spec.md](../specs/001-cli-workshop-rebuild/spec.md)
+- Feature 001 plan: [specs/001-cli-workshop-rebuild/plan.md](../specs/001-cli-workshop-rebuild/plan.md)
+- Feature 002 spec: [specs/002-poc-generation/spec.md](../specs/002-poc-generation/spec.md)
+- Feature 002 plan: [specs/002-poc-generation/plan.md](../specs/002-poc-generation/plan.md)
+- Research notes: [specs/001-cli-workshop-rebuild/research.md](../specs/001-cli-workshop-rebuild/research.md)