sofia-cli 0.1.1

package/tests/unit/shared/copilotClient.spec.ts

@@ -0,0 +1,185 @@
+/**
+ * Unit tests for CopilotClient abstraction.
+ *
+ * T050: SDK mcpServers forwarding
+ * T052: SDK hooks integration
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+import { createFakeCopilotClient } from '../../../src/shared/copilotClient.js';
+import type { SessionOptions } from '../../../src/shared/copilotClient.js';
+
+describe('CopilotClient', () => {
+  it('createFakeCopilotClient returns a client', () => {
+    const client = createFakeCopilotClient([{ role: 'assistant', content: 'Hello!' }]);
+    expect(client).toBeDefined();
+    expect(typeof client.createSession).toBe('function');
+  });
+
+  it('fake client session sends messages and gets responses', async () => {
+    const client = createFakeCopilotClient([{ role: 'assistant', content: 'I understand.' }]);
+    const session = await client.createSession({ systemPrompt: 'You are a facilitator.' });
+    const events: string[] = [];
+    for await (const event of session.send({ role: 'user', content: 'Tell me about AI' })) {
+      if (event.type === 'TextDelta') {
+        events.push(event.text);
+      }
+    }
+    expect(events.join('')).toBe('I understand.');
+  });
+
+  it('fake client supports multi-turn conversation', async () => {
+    const client = createFakeCopilotClient([
+      { role: 'assistant', content: 'First response' },
+      { role: 'assistant', content: 'Second response' },
+    ]);
+    const session = await client.createSession({ systemPrompt: 'Test' });
+
+    const first: string[] = [];
+    for await (const event of session.send({ role: 'user', content: 'Turn 1' })) {
+      if (event.type === 'TextDelta') first.push(event.text);
+    }
+    expect(first.join('')).toBe('First response');
+
+    const second: string[] = [];
+    for await (const event of session.send({ role: 'user', content: 'Turn 2' })) {
+      if (event.type === 'TextDelta') second.push(event.text);
+    }
+    expect(second.join('')).toBe('Second response');
+  });
+
+  it('fake client can simulate tool calls', async () => {
+    const client = createFakeCopilotClient(
+      [{ role: 'assistant', content: 'Let me search for that.' }],
+      {
+        tools: [{ name: 'web.search', description: 'Search the web' }],
+      },
+    );
+    const session = await client.createSession({ systemPrompt: 'Test' });
+    expect(session).toBeDefined();
+  });
+
+  // ── T050: SessionOptions.mcpServers forwarding ──────────────────────────
+
+  describe('SessionOptions.mcpServers (T050)', () => {
+    it('accepts mcpServers as a Record and forwards to createSession', async () => {
+      const mcpServers: SessionOptions['mcpServers'] = {
+        github: {
+          type: 'http',
+          url: 'https://api.githubcopilot.com/mcp/',
+          tools: ['search_repositories'],
+          timeout: 60_000,
+        },
+        context7: {
+          type: 'stdio',
+          command: 'npx',
+          args: ['-y', '@upstash/context7-mcp'],
+          tools: ['resolve-library-id', 'query-docs'],
+        },
+      };
+
+      // Spy on createSession to capture the options passed
+      const createSessionSpy = vi.fn();
+      const client = createFakeCopilotClient([{ role: 'assistant', content: 'OK' }]);
+      const originalCreateSession = client.createSession.bind(client);
+      client.createSession = async (opts: SessionOptions) => {
+        createSessionSpy(opts);
+        return originalCreateSession(opts);
+      };
+
+      const session = await client.createSession({
+        systemPrompt: 'Test',
+        mcpServers,
+      });
+
+      expect(createSessionSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          mcpServers: expect.objectContaining({
+            github: expect.objectContaining({
+              type: 'http',
+              url: 'https://api.githubcopilot.com/mcp/',
+            }),
+            context7: expect.objectContaining({ type: 'stdio', command: 'npx' }),
+          }),
+        }),
+      );
+      expect(session).toBeDefined();
+    });
+
+    it('does not include mcpServers when omitted', async () => {
+      const createSessionSpy = vi.fn();
+      const client = createFakeCopilotClient([{ role: 'assistant', content: 'OK' }]);
+      const originalCreateSession = client.createSession.bind(client);
+      client.createSession = async (opts: SessionOptions) => {
+        createSessionSpy(opts);
+        return originalCreateSession(opts);
+      };
+
+      await client.createSession({ systemPrompt: 'Test' });
+
+      const passedOpts = createSessionSpy.mock.calls[0][0] as SessionOptions;
+      expect(passedOpts.mcpServers).toBeUndefined();
+    });
+
+    it('does not include mcpServers when empty object', async () => {
+      const createSessionSpy = vi.fn();
+      const client = createFakeCopilotClient([{ role: 'assistant', content: 'OK' }]);
+      const originalCreateSession = client.createSession.bind(client);
+      client.createSession = async (opts: SessionOptions) => {
+        createSessionSpy(opts);
+        return originalCreateSession(opts);
+      };
+
+      await client.createSession({ systemPrompt: 'Test', mcpServers: {} });
+
+      const passedOpts = createSessionSpy.mock.calls[0][0] as SessionOptions;
+      expect(passedOpts.mcpServers).toEqual({});
+    });
+  });
+
+  // ── T052: SDK hooks integration ─────────────────────────────────────────
+
+  describe('SessionOptions hooks (T052)', () => {
+    it('accepts a hooks object with onPreToolUse and onPostToolUse callbacks', async () => {
+      const hooks: SessionOptions['hooks'] = {
+        onPreToolUse: vi.fn(),
+        onPostToolUse: vi.fn(),
+        onErrorOccurred: vi.fn(),
+      };
+
+      const createSessionSpy = vi.fn();
+      const client = createFakeCopilotClient([{ role: 'assistant', content: 'OK' }]);
+      const originalCreateSession = client.createSession.bind(client);
+      client.createSession = async (opts: SessionOptions) => {
+        createSessionSpy(opts);
+        return originalCreateSession(opts);
+      };
+
+      await client.createSession({
+        systemPrompt: 'Test',
+        hooks,
+      });
+
+      const passedOpts = createSessionSpy.mock.calls[0][0] as SessionOptions;
+      expect(passedOpts.hooks).toBeDefined();
+      expect(passedOpts.hooks!.onPreToolUse).toBe(hooks!.onPreToolUse);
+      expect(passedOpts.hooks!.onPostToolUse).toBe(hooks!.onPostToolUse);
+      expect(passedOpts.hooks!.onErrorOccurred).toBe(hooks!.onErrorOccurred);
+    });
+
+    it('does not include hooks when omitted', async () => {
+      const createSessionSpy = vi.fn();
+      const client = createFakeCopilotClient([{ role: 'assistant', content: 'OK' }]);
+      const originalCreateSession = client.createSession.bind(client);
+      client.createSession = async (opts: SessionOptions) => {
+        createSessionSpy(opts);
+        return originalCreateSession(opts);
+      };
+
+      await client.createSession({ systemPrompt: 'Test' });
+
+      const passedOpts = createSessionSpy.mock.calls[0][0] as SessionOptions;
+      expect(passedOpts.hooks).toBeUndefined();
+    });
+  });
+});

package/tests/unit/shared/errorClassifier.spec.ts

@@ -0,0 +1,152 @@
+/**
+ * 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,
+  type ErrorClassification,
+} 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: ErrorClassification = {
+        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: ErrorClassification = {
+        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: ErrorClassification = {
+        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: ErrorClassification = {
+        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: ErrorClassification = {
+        category: 'internal',
+        recoverable: false,
+        message: 'test',
+        originalError: err,
+      };
+      const msg = toUserMessage(classification);
+      expect(msg).not.toContain('at something');
+    });
+  });
+});

package/tests/unit/shared/events.spec.ts

@@ -0,0 +1,71 @@
+/**
+ * Unit tests for event model.
+ */
+import { describe, it, expect } from 'vitest';
+
+import {
+  createTextDeltaEvent,
+  createActivityEvent,
+  createToolCallEvent,
+  createToolResultEvent,
+  createPhaseChangedEvent,
+  createErrorEvent,
+  type SofiaEvent,
+} 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: SofiaEvent[] = [
+      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/tests/unit/shared/markdownRenderer.spec.ts

@@ -0,0 +1,42 @@
+/**
+ * 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/tests/unit/shared/markdownRendererChunks.spec.ts

@@ -0,0 +1,83 @@
+/**
+ * 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/tests/unit/shared/tableRenderer.spec.ts

@@ -0,0 +1,38 @@
+/**
+ * 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/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "rootDir": "./",
+    "outDir": "dist",
+    "baseUrl": "./",
+    "types": ["node", "vitest"],
+    "paths": {
+      "zod": ["src/vendor/zod"]
+    }
+  },
+  "include": ["src/**/*", "tests/**/*"]
+}

package/vitest.config.ts

@@ -0,0 +1,15 @@
+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/vitest.live.config.ts

@@ -0,0 +1,19 @@
+/**
+ * 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',
+    },
+  },
+});