sofia-cli 0.1.1

package/tests/unit/sessions/sessionManager.spec.ts

@@ -0,0 +1,174 @@
+/**
+ * Session manager tests (T043).
+ *
+ * Validates backtracking and artifact invalidation:
+ * - Moving to an earlier phase invalidates downstream artifacts
+ * - Session status is correctly updated on backtrack
+ * - Backtrack to same phase is a no-op
+ * - Cannot backtrack to a phase after the current one
+ */
+import { describe, it, expect } from 'vitest';
+
+import { backtrackSession } from '../../../src/sessions/sessionManager.js';
+import type { WorkshopSession } from '../../../src/shared/schemas/session.js';
+
+function createPopulatedSession(): WorkshopSession {
+  const now = new Date().toISOString();
+  return {
+    sessionId: 'bt-session',
+    schemaVersion: '1.0.0',
+    createdAt: now,
+    updatedAt: now,
+    phase: 'Plan',
+    status: 'Active',
+    participants: [],
+    artifacts: { generatedFiles: [] },
+    turns: [
+      { phase: 'Discover', sequence: 1, role: 'user', content: 'Business info', timestamp: now },
+      { phase: 'Discover', sequence: 2, role: 'assistant', content: 'Got it', timestamp: now },
+      { phase: 'Ideate', sequence: 3, role: 'user', content: 'Ideas please', timestamp: now },
+      { phase: 'Ideate', sequence: 4, role: 'assistant', content: 'Here are ideas', timestamp: now },
+      { phase: 'Design', sequence: 5, role: 'user', content: 'Evaluate', timestamp: now },
+      { phase: 'Design', sequence: 6, role: 'assistant', content: 'Evaluation done', timestamp: now },
+      { phase: 'Select', sequence: 7, role: 'user', content: 'Pick one', timestamp: now },
+      { phase: 'Select', sequence: 8, role: 'assistant', content: 'Selected', timestamp: now },
+    ],
+    businessContext: {
+      businessDescription: 'Test Corp',
+      challenges: ['Growth'],
+    },
+    workflow: {
+      activities: [{ id: 'a1', name: 'Activity' }],
+      edges: [],
+    },
+    ideas: [
+      { id: 'i1', title: 'Idea 1', description: 'First idea', workflowStepIds: ['a1'] },
+    ],
+    evaluation: {
+      method: 'feasibility-value-matrix',
+      ideas: [{ ideaId: 'i1', feasibility: 8, value: 9 }],
+    },
+    selection: {
+      ideaId: 'i1',
+      selectionRationale: 'Best fit',
+      confirmedByUser: true,
+      confirmedAt: now,
+    },
+    plan: {
+      milestones: [
+        { id: 'm1', title: 'M1', items: ['First milestone'] },
+      ],
+    },
+  };
+}
+
+describe('sessionManager', () => {
+  describe('backtrackSession', () => {
+    it('backtracking to Discover invalidates all data including Discover', () => {
+      const session = createPopulatedSession();
+      const result = backtrackSession(session, 'Discover');
+
+      expect(result.success).toBe(true);
+      expect(result.session.phase).toBe('Discover');
+      // Backtracking clears the target phase data too (will be re-run)
+      expect(result.session.businessContext).toBeUndefined();
+      expect(result.session.workflow).toBeUndefined();
+      expect(result.session.ideas).toBeUndefined();
+      expect(result.session.evaluation).toBeUndefined();
+      expect(result.session.selection).toBeUndefined();
+      expect(result.session.plan).toBeUndefined();
+    });
+
+    it('backtracking to Ideate preserves Discover data, clears Ideate+', () => {
+      const session = createPopulatedSession();
+      const result = backtrackSession(session, 'Ideate');
+
+      expect(result.success).toBe(true);
+      expect(result.session.phase).toBe('Ideate');
+      // Discover data preserved
+      expect(result.session.businessContext).toBeDefined();
+      expect(result.session.workflow).toBeDefined();
+      // Ideate and downstream cleared (Ideate is the target, so it's re-run)
+      expect(result.session.ideas).toBeUndefined();
+      expect(result.session.evaluation).toBeUndefined();
+      expect(result.session.selection).toBeUndefined();
+      expect(result.session.plan).toBeUndefined();
+    });
+
+    it('backtracking to Design clears evaluation and downstream', () => {
+      const session = createPopulatedSession();
+      const result = backtrackSession(session, 'Design');
+
+      expect(result.success).toBe(true);
+      expect(result.session.phase).toBe('Design');
+      // Preserve Discover + Ideate
+      expect(result.session.businessContext).toBeDefined();
+      expect(result.session.ideas).toBeDefined();
+      // Design target + downstream cleared
+      expect(result.session.evaluation).toBeUndefined();
+      expect(result.session.selection).toBeUndefined();
+      expect(result.session.plan).toBeUndefined();
+    });
+
+    it('backtracking to Select preserves evaluation', () => {
+      const session = createPopulatedSession();
+      const result = backtrackSession(session, 'Select');
+
+      expect(result.success).toBe(true);
+      expect(result.session.phase).toBe('Select');
+      expect(result.session.evaluation).toBeDefined();
+      expect(result.session.selection).toBeUndefined();
+      expect(result.session.plan).toBeUndefined();
+    });
+
+    it('backtracking to same phase is a no-op', () => {
+      const session = createPopulatedSession();
+      const result = backtrackSession(session, 'Plan');
+
+      expect(result.success).toBe(true);
+      expect(result.session.phase).toBe('Plan');
+      // All data preserved
+      expect(result.session.plan).toBeDefined();
+      expect(result.session.selection).toBeDefined();
+      expect(result.invalidatedPhases).toEqual([]);
+    });
+
+    it('backtracking forward fails', () => {
+      const session = createPopulatedSession();
+      session.phase = 'Ideate';
+      const result = backtrackSession(session, 'Plan');
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Cannot backtrack forward');
+    });
+
+    it('removes turns from invalidated phases', () => {
+      const session = createPopulatedSession();
+      const result = backtrackSession(session, 'Ideate');
+
+      // Only Discover turns should remain
+      const turns = result.session.turns!;
+      expect(turns.every(t => t.phase === 'Discover')).toBe(true);
+      expect(turns.length).toBe(2);
+    });
+
+    it('updates session status and timestamp on backtrack', () => {
+      const session = createPopulatedSession();
+      // Force an old timestamp
+      session.updatedAt = '2020-01-01T00:00:00Z';
+      const result = backtrackSession(session, 'Discover');
+
+      expect(result.session.status).toBe('Active');
+      expect(result.session.updatedAt).not.toBe('2020-01-01T00:00:00Z');
+    });
+
+    it('reports which phases were invalidated', () => {
+      const session = createPopulatedSession();
+      const result = backtrackSession(session, 'Ideate');
+
+      expect(result.invalidatedPhases).toEqual(
+        expect.arrayContaining(['Ideate', 'Design', 'Select', 'Plan']),
+      );
+    });
+  });
+});

package/tests/unit/sessions/sessionStore.spec.ts

@@ -0,0 +1,136 @@
+/**
+ * Unit tests for session persistence adapter.
+ *
+ * Contract: .sofia/sessions/<sessionId>.json
+ * - Atomic write (write-then-rename)
+ * - Persists after every turn
+ * - Preserves unknown fields
+ * - Never persists secrets
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { SessionStore } from '../../../src/sessions/sessionStore.js';
+import type { WorkshopSession } from '../../../src/shared/schemas/session.js';
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function minimalSession(id: string = 'sess-001'): WorkshopSession {
+  return {
+    sessionId: id,
+    schemaVersion: '1',
+    createdAt: '2026-01-01T00:00:00Z',
+    updatedAt: '2026-01-01T00:00:00Z',
+    phase: 'Discover',
+    status: 'Active',
+    participants: [],
+    artifacts: { generatedFiles: [] },
+  };
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe('SessionStore', () => {
+  let tmpDir: string;
+  let store: SessionStore;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'sofia-test-'));
+    store = new SessionStore(tmpDir);
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('saves and loads a session', async () => {
+    const session = minimalSession();
+    await store.save(session);
+    const loaded = await store.load('sess-001');
+    expect(loaded.sessionId).toBe('sess-001');
+    expect(loaded.phase).toBe('Discover');
+  });
+
+  it('creates the sessions directory on first save', async () => {
+    const nestedDir = join(tmpDir, 'nested', 'sessions');
+    const nestedStore = new SessionStore(nestedDir);
+    await nestedStore.save(minimalSession());
+    const files = await readdir(nestedDir);
+    expect(files).toContain('sess-001.json');
+  });
+
+  it('overwrites existing session file on re-save', async () => {
+    const session = minimalSession();
+    await store.save(session);
+    const updated = { ...session, updatedAt: '2026-06-01T00:00:00Z', phase: 'Ideate' as const };
+    await store.save(updated);
+    const loaded = await store.load('sess-001');
+    expect(loaded.phase).toBe('Ideate');
+    expect(loaded.updatedAt).toBe('2026-06-01T00:00:00Z');
+  });
+
+  it('preserves unknown fields (forward compatibility)', async () => {
+    const session = minimalSession() as WorkshopSession & { futureField: string };
+    session.futureField = 'hello-future';
+    await store.save(session);
+    const loaded = await store.load('sess-001');
+    expect((loaded as Record<string, unknown>).futureField).toBe('hello-future');
+  });
+
+  it('throws when loading a non-existent session', async () => {
+    await expect(store.load('nonexistent')).rejects.toThrow();
+  });
+
+  it('lists sessions', async () => {
+    await store.save(minimalSession('a'));
+    await store.save(minimalSession('b'));
+    const ids = await store.list();
+    expect(ids.sort()).toEqual(['a', 'b']);
+  });
+
+  it('returns empty list when no sessions exist', async () => {
+    const ids = await store.list();
+    expect(ids).toEqual([]);
+  });
+
+  it('checks existence of a session', async () => {
+    await store.save(minimalSession());
+    expect(await store.exists('sess-001')).toBe(true);
+    expect(await store.exists('nope')).toBe(false);
+  });
+
+  it('writes valid JSON that can be parsed independently', async () => {
+    await store.save(minimalSession());
+    const filePath = join(tmpDir, 'sess-001.json');
+    const raw = await readFile(filePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    expect(parsed.sessionId).toBe('sess-001');
+  });
+
+  it('deletes a session', async () => {
+    await store.save(minimalSession());
+    expect(await store.exists('sess-001')).toBe(true);
+    await store.delete('sess-001');
+    expect(await store.exists('sess-001')).toBe(false);
+  });
+
+  it('handles concurrent saves to different sessions', async () => {
+    await Promise.all([
+      store.save(minimalSession('c1')),
+      store.save(minimalSession('c2')),
+      store.save(minimalSession('c3')),
+    ]);
+    const ids = await store.list();
+    expect(ids.sort()).toEqual(['c1', 'c2', 'c3']);
+  });
+
+  it('rejects session with invalid schema on load', async () => {
+    // Write an invalid file directly
+    const { writeFile, mkdir } = await import('node:fs/promises');
+    await mkdir(tmpDir, { recursive: true });
+    await writeFile(join(tmpDir, 'bad.json'), JSON.stringify({ invalid: true }));
+    await expect(store.load('bad')).rejects.toThrow();
+  });
+});

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

@@ -0,0 +1,211 @@
+/**
+ * Tests for ActivitySpinner module (T084).
+ *
+ * Verifies spinner lifecycle methods: startThinking, startToolCall,
+ * completeToolCall, stop, isActive, TTY/JSON suppression, and
+ * that ora is configured with discardStdin: false to avoid
+ * conflicting with the app's readline on process.stdin.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Writable } from 'node:stream';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ActivitySpinner, createNoOpSpinner } from '../../../src/shared/activitySpinner.js';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Create a writable stream that captures output. */
+function createCaptureStream(): Writable & { getOutput: () => string } {
+  const chunks: string[] = [];
+  const stream = new Writable({
+    write(chunk, _encoding, callback) {
+      chunks.push(chunk.toString());
+      callback();
+    },
+  });
+  (stream as Writable & { getOutput: () => string }).getOutput = () => chunks.join('');
+  return stream as Writable & { getOutput: () => string };
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe('ActivitySpinner (T084)', () => {
+  describe('TTY mode (enabled)', () => {
+    let stream: ReturnType<typeof createCaptureStream>;
+    let spinner: ActivitySpinner;
+
+    beforeEach(() => {
+      stream = createCaptureStream();
+      spinner = new ActivitySpinner({
+        isTTY: true,
+        isJsonMode: false,
+        stream,
+      });
+    });
+
+    it('startThinking() starts a spinner', () => {
+      spinner.startThinking();
+      expect(spinner.isActive()).toBe(true);
+      spinner.stop();
+    });
+
+    it('startToolCall() starts/updates spinner with tool name', () => {
+      spinner.startToolCall('WorkIQ');
+      expect(spinner.isActive()).toBe(true);
+      spinner.stop();
+    });
+
+    it('startThinking() then startToolCall() transitions spinner text', () => {
+      spinner.startThinking();
+      expect(spinner.isActive()).toBe(true);
+      spinner.startToolCall('Context7');
+      expect(spinner.isActive()).toBe(true);
+      spinner.stop();
+    });
+
+    it('completeToolCall() stops spinner and prints summary', () => {
+      spinner.startToolCall('WorkIQ');
+      spinner.completeToolCall('WorkIQ', 'Found 12 processes');
+
+      expect(spinner.isActive()).toBe(false);
+      // Summary output is now handled by io.writeToolSummary(),
+      // not by the spinner itself.
+    });
+
+    it('stop() clears any active spinner', () => {
+      spinner.startThinking();
+      expect(spinner.isActive()).toBe(true);
+      spinner.stop();
+      expect(spinner.isActive()).toBe(false);
+    });
+
+    it('isActive() returns false when no spinner is running', () => {
+      expect(spinner.isActive()).toBe(false);
+    });
+
+    it('stop() is safe to call when no spinner is active', () => {
+      expect(() => spinner.stop()).not.toThrow();
+    });
+
+    it('completeToolCall() works even if spinner was already stopped', () => {
+      spinner.completeToolCall('GitHub', '3 repos found');
+      // Should not throw; summary output handled by io.writeToolSummary()
+    });
+
+    it('handles multiple sequential tool calls', () => {
+      // First tool
+      spinner.startToolCall('WorkIQ');
+      spinner.completeToolCall('WorkIQ', 'Found 5 processes');
+
+      // Second tool
+      spinner.startToolCall('Context7');
+      spinner.completeToolCall('Context7', '12 docs retrieved');
+
+      // Spinner should be inactive after all tools complete
+      expect(spinner.isActive()).toBe(false);
+      // Summary output handled by io.writeToolSummary(), not the spinner
+    });
+  });
+
+  describe('non-TTY mode (disabled)', () => {
+    let stream: ReturnType<typeof createCaptureStream>;
+    let spinner: ActivitySpinner;
+
+    beforeEach(() => {
+      stream = createCaptureStream();
+      spinner = new ActivitySpinner({
+        isTTY: false,
+        isJsonMode: false,
+        stream,
+      });
+    });
+
+    it('startThinking() is a no-op', () => {
+      spinner.startThinking();
+      expect(spinner.isActive()).toBe(false);
+    });
+
+    it('startToolCall() is a no-op', () => {
+      spinner.startToolCall('WorkIQ');
+      expect(spinner.isActive()).toBe(false);
+    });
+
+    it('completeToolCall() is a no-op (no output)', () => {
+      spinner.completeToolCall('WorkIQ', 'Found stuff');
+      expect(stream.getOutput()).toBe('');
+    });
+
+    it('stop() is safe and a no-op', () => {
+      expect(() => spinner.stop()).not.toThrow();
+    });
+  });
+
+  describe('JSON mode (disabled)', () => {
+    let stream: ReturnType<typeof createCaptureStream>;
+    let spinner: ActivitySpinner;
+
+    beforeEach(() => {
+      stream = createCaptureStream();
+      spinner = new ActivitySpinner({
+        isTTY: true,
+        isJsonMode: true,
+        stream,
+      });
+    });
+
+    it('all operations are no-ops in JSON mode', () => {
+      spinner.startThinking();
+      expect(spinner.isActive()).toBe(false);
+      spinner.startToolCall('WorkIQ');
+      expect(spinner.isActive()).toBe(false);
+      spinner.completeToolCall('WorkIQ', 'data');
+      expect(stream.getOutput()).toBe('');
+      spinner.stop();
+    });
+  });
+
+  describe('createNoOpSpinner', () => {
+    it('returns a spinner where all operations are no-ops', () => {
+      const noop = createNoOpSpinner();
+      expect(noop.isActive()).toBe(false);
+      noop.startThinking();
+      expect(noop.isActive()).toBe(false);
+      noop.startToolCall('TestTool');
+      expect(noop.isActive()).toBe(false);
+      noop.stop();
+    });
+  });
+
+  describe('ora configuration', () => {
+    it('creates ora with discardStdin: false to avoid stdin conflicts', () => {
+      const stream = createCaptureStream();
+      const spinner = new ActivitySpinner({ isTTY: true, isJsonMode: false, stream });
+
+      // Start thinking to trigger ora creation
+      spinner.startThinking();
+
+      // Access the internal ora instance to verify the option.
+      // ora stores options in a private field, but we can verify behaviour
+      // by checking that the spinner was created (isActive) and that our
+      // code explicitly passes discardStdin: false in the source.
+      expect(spinner.isActive()).toBe(true);
+
+      // Verify via source inspection: read the activitySpinner source and
+      // confirm discardStdin: false is present in all ora() calls
+      const __dirname = path.dirname(fileURLToPath(import.meta.url));
+      const source = fs.readFileSync(
+        path.resolve(__dirname, '../../../src/shared/activitySpinner.ts'),
+        'utf8',
+      );
+      // Count ora constructor calls vs discardStdin: false occurrences
+      const oraCallCount = (source.match(/ora\(\{/g) || []).length;
+      const discardFalseCount = (source.match(/discardStdin:\s*false/g) || []).length;
+      expect(oraCallCount).toBeGreaterThan(0);
+      expect(discardFalseCount).toBe(oraCallCount);
+
+      spinner.stop();
+    });
+  });
+});

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

@@ -0,0 +1,89 @@
+/**
+ * Cards loader tests.
+ *
+ * Validates that the AI Discovery Cards dataset:
+ * - Loads and validates against the Zod schema
+ * - Filters cards by category
+ * - Searches cards by keyword
+ * - Caches the dataset after first load
+ */
+import { describe, it, expect } from 'vitest';
+
+import { loadCardsDataset, getCardsByCategory, searchCards } from '../../../src/shared/data/cardsLoader.js';
+
+describe('cardsLoader', () => {
+  it('loads the cards dataset successfully', async () => {
+    const dataset = await loadCardsDataset();
+    expect(dataset).toBeDefined();
+    expect(dataset.categories).toBeInstanceOf(Array);
+    expect(dataset.categories.length).toBeGreaterThan(0);
+    expect(dataset.cards).toBeInstanceOf(Array);
+    expect(dataset.cards.length).toBeGreaterThan(0);
+  });
+
+  it('cards have required fields', async () => {
+    const dataset = await loadCardsDataset();
+    for (const card of dataset.cards) {
+      expect(card.cardId).toBeDefined();
+      expect(card.category).toBeDefined();
+      expect(card.title).toBeDefined();
+      expect(card.description).toBeDefined();
+      expect(card.typicalScenarios).toBeInstanceOf(Array);
+      expect(card.azureServices).toBeInstanceOf(Array);
+    }
+  });
+
+  it('categories are non-empty strings', async () => {
+    const dataset = await loadCardsDataset();
+    for (const cat of dataset.categories) {
+      expect(typeof cat).toBe('string');
+      expect(cat.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('filters cards by category', async () => {
+    const dataset = await loadCardsDataset();
+    const firstCategory = dataset.categories[0];
+    const filtered = await getCardsByCategory(firstCategory);
+
+    expect(filtered.length).toBeGreaterThan(0);
+    expect(filtered.every(c => c.category === firstCategory)).toBe(true);
+  });
+
+  it('returns empty array for unknown category', async () => {
+    const filtered = await getCardsByCategory('NonexistentCategory123');
+    expect(filtered).toEqual([]);
+  });
+
+  it('searches cards by keyword in title', async () => {
+    const dataset = await loadCardsDataset();
+    const firstCard = dataset.cards[0];
+    // Search for a word from the first card's title
+    const keyword = firstCard.title.split(' ')[0];
+    const results = await searchCards(keyword);
+
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.some(c => c.cardId === firstCard.cardId)).toBe(true);
+  });
+
+  it('searches cards case-insensitively', async () => {
+    const dataset = await loadCardsDataset();
+    const firstCard = dataset.cards[0];
+    const keyword = firstCard.title.split(' ')[0].toLowerCase();
+    const results = await searchCards(keyword);
+
+    expect(results.length).toBeGreaterThan(0);
+  });
+
+  it('returns empty for unmatched search', async () => {
+    const results = await searchCards('xyzzy_nonexistent_query_99999');
+    expect(results).toEqual([]);
+  });
+
+  it('caches dataset on subsequent loads', async () => {
+    const first = await loadCardsDataset();
+    const second = await loadCardsDataset();
+    // Same object reference (cached)
+    expect(first).toBe(second);
+  });
+});