@mytechtoday/augment-sdd 1.0.0

package/src/extension.ts

@@ -0,0 +1,77 @@
+import * as vscode from 'vscode';
+import { initLogger, log, revealOutputChannel } from './utils/logger';
+import { detectCli } from './utils/detectCli';
+import { generateOpenSpec } from './commands/generateOpenSpec';
+import { generateBeads } from './commands/generateBeads';
+import { executeBeadsBatch } from './commands/executeBeadsBatch';
+import { fullPipeline } from './commands/fullPipeline';
+
+/** CLI definitions: name on PATH and the npm package to install if missing. */
+const REQUIRED_CLIS: { name: string; pkg: string }[] = [
+  { name: 'auggie',   pkg: 'auggie' },
+  { name: 'openspec', pkg: 'openspec' },
+  { name: 'bd',       pkg: '@beads/cli' },
+];
+
+/**
+ * Run CLI presence checks on activation. For each missing CLI, show an error
+ * message with the exact `npm install -g <pkg>` command and a "View Logs" button.
+ */
+async function checkRequiredClis(): Promise<void> {
+  for (const { name, pkg } of REQUIRED_CLIS) {
+    const found = await detectCli(name);
+    if (!found) {
+      log(`CLI not found on PATH: ${name} (install with: npm install -g ${pkg})`);
+      const action = await vscode.window.showErrorMessage(
+        `Augment SDD: Required CLI "${name}" not found. Install it with: npm install -g ${pkg}`,
+        'View Logs'
+      );
+      if (action === 'View Logs') {
+        revealOutputChannel();
+      }
+    } else {
+      log(`CLI detected: ${name}`);
+    }
+  }
+}
+
+export function activate(context: vscode.ExtensionContext): void {
+  // Create the Output Channel first and initialise the shared logger so all
+  // subsequent code (including commands) can call log() / revealOutputChannel().
+  const outputChannel = vscode.window.createOutputChannel('Augment SDD');
+  initLogger(outputChannel);
+  context.subscriptions.push(outputChannel);
+
+  log('Augment SDD extension activating…');
+
+  // Run CLI detection (non-blocking — failures are surfaced as error messages).
+  checkRequiredClis().catch(err => {
+    log(`CLI detection error: ${String(err)}`);
+  });
+
+  // Register commands (implementations wired in subsequent beads).
+  context.subscriptions.push(
+    vscode.commands.registerCommand('augmentSdd.generateOpenSpec', async () => {
+      await generateOpenSpec();
+    }),
+
+    vscode.commands.registerCommand('augmentSdd.generateBeads', async () => {
+      await generateBeads();
+    }),
+
+    vscode.commands.registerCommand('augmentSdd.executeBeadsBatch', async () => {
+      await executeBeadsBatch();
+    }),
+
+    vscode.commands.registerCommand('augmentSdd.fullPipeline', async () => {
+      await fullPipeline();
+    })
+  );
+
+  log('Augment SDD extension activated.');
+}
+
+export function deactivate(): void {
+  // Nothing to clean up; subscriptions are disposed automatically.
+}
+

package/src/parsers/parseBeadUpdates.ts

@@ -0,0 +1,26 @@
+/**
+ * parseBeadUpdates — Sentinel line parser for Bead 7.
+ *
+ * Extracts all lines that match the Auggie completion sentinel format
+ * from a free-form text response.  Each matched line can be executed
+ * directly as a CLI command via runCli.
+ *
+ * Design D4: Sentinel-based parsing is format-agnostic — it works
+ * regardless of how much prose Auggie wraps around the commands.
+ */
+
+/**
+ * Extract all `bd update <ID> --status done` lines from Auggie output.
+ *
+ * @param output  Raw text returned by `auggie --print --quiet`.
+ * @returns       Array of matched command strings (may be empty).
+ *
+ * @example
+ * parseBeadUpdates('done\nbd update bd-abc --status done\nmore text')
+ * // => ['bd update bd-abc --status done']
+ */
+export function parseBeadUpdates(output: string): string[] {
+  const matches = [...output.matchAll(/^bd update \S+ --status done$/gm)];
+  return matches.map(m => m[0]);
+}
+

package/src/parsers/parseTasksMarkdown.ts

@@ -0,0 +1,61 @@
+/**
+ * parseTasksMarkdown — heading-based task extractor for Auggie-generated tasks.md.
+ *
+ * Design (D3): Uses a deterministic heading-based regex (`/^#{1,3}\s+(.+)/gm`)
+ * to extract task titles and their body text.  No external parser dependency is
+ * required; Auggie's structured output is regular enough for this approach.
+ *
+ * Each H1–H3 heading becomes a Bead title; the body text between that heading
+ * and the next heading (or EOF) becomes the Bead description.
+ */
+
+/** A single extracted task ready to be created as a Bead. */
+export interface BeadTask {
+  /** The heading text, trimmed (becomes the `bd create` title). */
+  title: string;
+  /** All text between this heading and the next, trimmed (becomes the description). */
+  description: string;
+}
+
+/**
+ * Parse `content` (the raw text of a `tasks.md` file) into an ordered array of
+ * `{ title, description }` objects.
+ *
+ * - Recognises H1, H2, and H3 headings (`#`, `##`, `###`).
+ * - The heading line itself is the title; everything after it up to the next
+ *   heading (or end-of-file) is the description (whitespace-trimmed).
+ * - Returns an empty array when no headings are found.
+ *
+ * @param content  Raw markdown text of a `tasks.md` file.
+ */
+export function parseTasksMarkdown(content: string): BeadTask[] {
+  const headingRegex = /^#{1,3}\s+(.+)/gm;
+  const tasks: BeadTask[] = [];
+
+  // Collect all heading positions and titles in one pass.
+  const positions: Array<{ index: number; title: string }> = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = headingRegex.exec(content)) !== null) {
+    positions.push({ index: match.index, title: match[1].trim() });
+  }
+
+  // For each heading, extract the body as everything between its start and the
+  // start of the next heading (or end-of-file).
+  for (let i = 0; i < positions.length; i++) {
+    const { index, title } = positions[i];
+    const nextIndex = i + 1 < positions.length ? positions[i + 1].index : content.length;
+
+    // Slice the segment, skip the heading line itself, then trim whitespace.
+    const segment = content.slice(index, nextIndex);
+    const firstNewline = segment.indexOf('\n');
+    const description = firstNewline >= 0
+      ? segment.slice(firstNewline + 1).trim()
+      : '';
+
+    tasks.push({ title, description });
+  }
+
+  return tasks;
+}
+

package/src/test/integration/executeBeadsBatch.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Integration tests for executeBeadsBatch command.
+ * IT-3: 3 beads ready — all 3 bd update commands executed successfully.
+ * IT-4: Partial failure — second bd update fails; others succeed, warning shown.
+ *
+ * Strategy: stub cp.spawn via sinon so no real CLIs are invoked.
+ */
+import * as assert from 'assert';
+import * as cp    from 'child_process';
+import * as fs    from 'fs';
+import * as os    from 'os';
+import * as path  from 'path';
+import * as sinon from 'sinon';
+import * as vscode from 'vscode';
+import { EventEmitter } from 'events';
+import { executeBeadsBatch } from '../../commands/executeBeadsBatch';
+
+// ---------------------------------------------------------------------------
+// Fake process factory
+// ---------------------------------------------------------------------------
+function fakeProc(opts: { stdout?: string; stderr?: string; code?: number }): cp.ChildProcess {
+  const stdoutEE = new EventEmitter();
+  const stderrEE = new EventEmitter();
+  const procEE   = new EventEmitter();
+  const proc = {
+    stdout:         stdoutEE,
+    stderr:         stderrEE,
+    kill:           () => { /* noop */ },
+    on:             procEE.on.bind(procEE),
+    once:           procEE.once.bind(procEE),
+    removeListener: procEE.removeListener.bind(procEE),
+    emit:           procEE.emit.bind(procEE),
+  };
+  setImmediate(() => {
+    if (opts.stdout) { stdoutEE.emit('data', Buffer.from(opts.stdout)); }
+    if (opts.stderr) { stderrEE.emit('data', Buffer.from(opts.stderr)); }
+    procEE.emit('close', opts.code ?? 0);
+  });
+  return proc as unknown as cp.ChildProcess;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const FAKE_BEADS = JSON.stringify([
+  { id: 'bd-a1', title: 'Bead A1', description: 'Do A1' },
+  { id: 'bd-b2', title: 'Bead B2', description: 'Do B2' },
+  { id: 'bd-b3', title: 'Bead B3', description: 'Do B3' },
+]);
+
+const AUGGIE_SENTINELS =
+  'bd update bd-a1 --status done\n' +
+  'bd update bd-b2 --status done\n' +
+  'bd update bd-b3 --status done';
+
+function stubWorkspace(dir: string): () => void {
+  const orig = Object.getOwnPropertyDescriptor(vscode.workspace, 'workspaceFolders');
+  Object.defineProperty(vscode.workspace, 'workspaceFolders', {
+    configurable: true,
+    get: () => [{ uri: vscode.Uri.file(dir), name: 'test', index: 0 }],
+  });
+  return () => {
+    if (orig) { Object.defineProperty(vscode.workspace, 'workspaceFolders', orig); }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+suite('executeBeadsBatch — integration tests', () => {
+  let tmpDir:    string;
+  let restoreWF: () => void;
+  let spawnStub: sinon.SinonStub;
+  let infoStub:  sinon.SinonStub;
+  let warnStub:  sinon.SinonStub;
+  let errStub:   sinon.SinonStub;
+
+  setup(() => {
+    tmpDir    = fs.mkdtempSync(path.join(os.tmpdir(), 'augsdd-batch-'));
+    restoreWF = stubWorkspace(tmpDir);
+    spawnStub = sinon.stub(cp, 'spawn') as sinon.SinonStub;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    infoStub  = sinon.stub(vscode.window, 'showInformationMessage' as any).resolves(undefined);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    warnStub  = sinon.stub(vscode.window, 'showWarningMessage' as any).resolves(undefined);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    errStub   = sinon.stub(vscode.window, 'showErrorMessage' as any).resolves(undefined);
+  });
+
+  teardown(() => {
+    sinon.restore();
+    restoreWF();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test('IT-3: 3 beads ready — all 3 bd update commands executed', async () => {
+    // Call order: bd ready, auggie, bd update ×3
+    spawnStub.onCall(0).returns(fakeProc({ stdout: FAKE_BEADS, code: 0 }));
+    spawnStub.onCall(1).returns(fakeProc({ stdout: AUGGIE_SENTINELS, code: 0 }));
+    spawnStub.onCall(2).returns(fakeProc({ stdout: '', code: 0 }));
+    spawnStub.onCall(3).returns(fakeProc({ stdout: '', code: 0 }));
+    spawnStub.onCall(4).returns(fakeProc({ stdout: '', code: 0 }));
+
+    await executeBeadsBatch();
+
+    assert.strictEqual(spawnStub.callCount, 5, 'spawn should be called 5 times total');
+    assert.ok(infoStub.called, 'success info message should be shown');
+    assert.ok(!warnStub.called, 'no warning should be shown on clean success');
+    assert.ok(!errStub.called, 'no error should be shown on clean success');
+  });
+
+  test('IT-4: partial failure — second bd update fails, warning shown', async () => {
+    // bd ready → auggie → bd-a1 ok → bd-b2 FAIL → bd-b3 ok
+    spawnStub.onCall(0).returns(fakeProc({ stdout: FAKE_BEADS, code: 0 }));
+    spawnStub.onCall(1).returns(fakeProc({ stdout: AUGGIE_SENTINELS, code: 0 }));
+    spawnStub.onCall(2).returns(fakeProc({ stdout: '', code: 0 }));
+    spawnStub.onCall(3).returns(fakeProc({ stdout: '', stderr: 'not found', code: 1 }));
+    spawnStub.onCall(4).returns(fakeProc({ stdout: '', code: 0 }));
+
+    await executeBeadsBatch();
+
+    assert.ok(warnStub.called, 'warning message should be shown on partial failure');
+    assert.ok(!errStub.called, 'no hard error should be shown on partial failure');
+    // Verify all 5 spawns happened (pipeline did not abort)
+    assert.strictEqual(spawnStub.callCount, 5, 'all 3 bd update attempts should be made');
+  });
+
+});
+

package/src/test/integration/generateOpenSpec.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Integration tests for generateOpenSpec command.
+ * IT-1: Happy path — proposal.md written, validate passes.
+ * IT-2: Auggie returns empty output on both attempts → showErrorMessage called.
+ *
+ * Strategy: stub cp.spawn via sinon so no real CLIs are invoked.
+ * A temp directory is created on each test and wired as the workspace root.
+ */
+import * as assert from 'assert';
+import * as cp    from 'child_process';
+import * as fs    from 'fs';
+import * as os    from 'os';
+import * as path  from 'path';
+import * as sinon from 'sinon';
+import * as vscode from 'vscode';
+import { EventEmitter } from 'events';
+import { generateOpenSpec } from '../../commands/generateOpenSpec';
+
+// ---------------------------------------------------------------------------
+// Fake process factory (mirrors the one in runCli.test.ts)
+// ---------------------------------------------------------------------------
+function fakeProc(opts: { stdout?: string; code?: number }): cp.ChildProcess {
+  const stdoutEE = new EventEmitter();
+  const procEE   = new EventEmitter();
+  const proc = {
+    stdout:         stdoutEE,
+    stderr:         new EventEmitter(),
+    kill:           () => { /* noop */ },
+    on:             procEE.on.bind(procEE),
+    once:           procEE.once.bind(procEE),
+    removeListener: procEE.removeListener.bind(procEE),
+    emit:           procEE.emit.bind(procEE),
+  };
+  setImmediate(() => {
+    if (opts.stdout) { stdoutEE.emit('data', Buffer.from(opts.stdout)); }
+    procEE.emit('close', opts.code ?? 0);
+  });
+  return proc as unknown as cp.ChildProcess;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeTempWorkspace(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'augsdd-it-'));
+  // .jira folder with a single markdown ticket for auto-detection
+  const jiraDir = path.join(dir, '.jira');
+  fs.mkdirSync(jiraDir);
+  fs.writeFileSync(path.join(jiraDir, 'TICKET-1.md'), '# Ticket\nDetails');
+  // openspec/changes/<id> must exist so findNewestChangeDir works
+  const changeDir = path.join(dir, 'openspec', 'changes', 'test-change');
+  fs.mkdirSync(changeDir, { recursive: true });
+  return dir;
+}
+
+function stubWorkspace(dir: string): () => void {
+  const orig = Object.getOwnPropertyDescriptor(vscode.workspace, 'workspaceFolders');
+  Object.defineProperty(vscode.workspace, 'workspaceFolders', {
+    configurable: true,
+    get: () => [{ uri: vscode.Uri.file(dir), name: 'test', index: 0 }],
+  });
+  return () => {
+    if (orig) { Object.defineProperty(vscode.workspace, 'workspaceFolders', orig); }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+suite('generateOpenSpec — integration tests', () => {
+  let tmpDir   = '';
+  let restoreWF: () => void;
+  let spawnStub: sinon.SinonStub;
+  let infoStub:  sinon.SinonStub;
+  let errStub:   sinon.SinonStub;
+
+  setup(() => {
+    tmpDir    = makeTempWorkspace();
+    restoreWF = stubWorkspace(tmpDir);
+    spawnStub = sinon.stub(cp, 'spawn') as sinon.SinonStub;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    infoStub  = sinon.stub(vscode.window, 'showInformationMessage' as any).resolves(undefined);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    errStub   = sinon.stub(vscode.window, 'showErrorMessage' as any).resolves(undefined);
+  });
+
+  teardown(() => {
+    sinon.restore();
+    restoreWF();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test('IT-1: happy path — proposal.md written, validate exits 0', async () => {
+    // Spawn sequence: init → instructions → auggie → validate
+    spawnStub.onCall(0).returns(fakeProc({ stdout: '', code: 0 }));
+    spawnStub.onCall(1).returns(fakeProc({ stdout: '{"template":"Write a proposal."}', code: 0 }));
+    spawnStub.onCall(2).returns(fakeProc({ stdout: '# Proposal\nContent here.', code: 0 }));
+    spawnStub.onCall(3).returns(fakeProc({ stdout: 'OK', code: 0 }));
+
+    await generateOpenSpec();
+
+    // proposal.md must have been written
+    const proposalPath = path.join(tmpDir, 'openspec', 'changes', 'test-change', 'proposal.md');
+    assert.ok(fs.existsSync(proposalPath), 'proposal.md should exist');
+    const content = fs.readFileSync(proposalPath, 'utf8');
+    assert.ok(content.includes('Proposal'), 'proposal.md should contain Auggie output');
+
+    // Success info message shown, no error
+    assert.ok(infoStub.called, 'showInformationMessage should be called on success');
+    assert.ok(!errStub.called, 'showErrorMessage should NOT be called on success');
+  });
+
+  test('IT-2: Auggie returns empty on both attempts → showErrorMessage called', async () => {
+    // init → instructions → auggie (empty) → auggie retry (empty)
+    spawnStub.onCall(0).returns(fakeProc({ stdout: '', code: 0 }));
+    spawnStub.onCall(1).returns(fakeProc({ stdout: '{"template":"template"}', code: 0 }));
+    spawnStub.onCall(2).returns(fakeProc({ stdout: '', code: 0 }));
+    spawnStub.onCall(3).returns(fakeProc({ stdout: '', code: 0 }));
+
+    await generateOpenSpec();
+
+    // Error message must be shown; no proposal file written
+    assert.ok(errStub.called, 'showErrorMessage should be called after two empty Auggie attempts');
+    const proposalPath = path.join(tmpDir, 'openspec', 'changes', 'test-change', 'proposal.md');
+    assert.ok(!fs.existsSync(proposalPath), 'proposal.md should NOT be written on failure');
+  });
+
+});
+

package/src/test/runTest.ts

@@ -0,0 +1,15 @@
+import * as path from 'path';
+import { runTests } from '@vscode/test-electron';
+
+async function main(): Promise<void> {
+  const extensionDevelopmentPath = path.resolve(__dirname, '../../');
+  const extensionTestsPath = path.resolve(__dirname, './suite/index');
+
+  await runTests({ extensionDevelopmentPath, extensionTestsPath });
+}
+
+main().catch(err => {
+  console.error('Failed to run tests:', err);
+  process.exit(1);
+});
+

package/src/test/suite/index.ts

@@ -0,0 +1,37 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import Mocha from 'mocha';
+
+/** Recursively collect all *.test.js files under `dir`. */
+function findTestFiles(dir: string): string[] {
+  const results: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findTestFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.test.js')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+export function run(): Promise<void> {
+  const mocha = new Mocha({ ui: 'tdd', color: true, timeout: 10_000 });
+
+  const testsRoot = path.resolve(__dirname, '..');
+  for (const f of findTestFiles(testsRoot)) {
+    mocha.addFile(f);
+  }
+
+  return new Promise<void>((resolve, reject) => {
+    mocha.run(failures => {
+      if (failures > 0) {
+        reject(new Error(`${failures} test(s) failed.`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+

package/src/test/unit/parseBeadUpdates.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Unit tests for parseBeadUpdates.ts
+ * UT-5: parses valid sentinel lines from Auggie output
+ * UT-6: returns empty array when no sentinel lines found
+ */
+import * as assert from 'assert';
+import { parseBeadUpdates } from '../../parsers/parseBeadUpdates';
+
+suite('parseBeadUpdates — unit tests', () => {
+
+  test('UT-5: parses bd update lines from Auggie output', () => {
+    const output =
+      'some text\n' +
+      'bd update bd-a1 --status done\n' +
+      'more text\n' +
+      'bd update bd-b2 --status done';
+
+    const lines = parseBeadUpdates(output);
+    assert.deepStrictEqual(lines, [
+      'bd update bd-a1 --status done',
+      'bd update bd-b2 --status done',
+    ]);
+  });
+
+  test('UT-6: returns empty array when no sentinel lines found', () => {
+    const lines = parseBeadUpdates('Auggie did not finish');
+    assert.deepStrictEqual(lines, []);
+  });
+
+  test('ignores lines that are partial / malformed sentinels', () => {
+    const output =
+      'bd update --status done\n' +              // missing id
+      '  bd update bd-x1 --status done\n' +      // leading spaces (not at start)
+      'bd update bd-x2 --status pending\n' +     // wrong status
+      'bd update bd-x3 --status done';           // valid
+
+    const lines = parseBeadUpdates(output);
+    assert.deepStrictEqual(lines, ['bd update bd-x3 --status done']);
+  });
+
+  test('handles CRLF line endings', () => {
+    const output = 'preamble\r\nbd update bd-crlf --status done\r\npostamble';
+    const lines = parseBeadUpdates(output);
+    assert.deepStrictEqual(lines, ['bd update bd-crlf --status done']);
+  });
+
+});
+

package/src/test/unit/parseTasksMarkdown.test.ts

@@ -0,0 +1,41 @@
+/**
+ * Unit tests for parseTasksMarkdown.ts
+ * UT-4: Headings extracted as task titles with descriptions
+ */
+import * as assert from 'assert';
+import { parseTasksMarkdown, BeadTask } from '../../parsers/parseTasksMarkdown';
+
+suite('parseTasksMarkdown — unit tests', () => {
+
+  test('UT-4: extracts headings as task titles', () => {
+    const md = '## Task 1\nDo this\n## Task 2\nDo that';
+    const tasks: BeadTask[] = parseTasksMarkdown(md);
+    assert.deepStrictEqual(tasks.map(t => t.title), ['Task 1', 'Task 2']);
+  });
+
+  test('extracts body text as task description', () => {
+    const md = '## Alpha\nFirst line\nSecond line\n## Beta\nOther';
+    const tasks = parseTasksMarkdown(md);
+    assert.strictEqual(tasks[0].description, 'First line\nSecond line');
+    assert.strictEqual(tasks[1].description, 'Other');
+  });
+
+  test('returns empty array when no headings are found', () => {
+    const tasks = parseTasksMarkdown('No headings here.');
+    assert.deepStrictEqual(tasks, []);
+  });
+
+  test('handles H1, H2, and H3 headings', () => {
+    const md = '# One\na\n## Two\nb\n### Three\nc';
+    const tasks = parseTasksMarkdown(md);
+    assert.deepStrictEqual(tasks.map(t => t.title), ['One', 'Two', 'Three']);
+  });
+
+  test('trims extra whitespace from titles', () => {
+    const md = '##   Spaced Title   \nBody';
+    const tasks = parseTasksMarkdown(md);
+    assert.strictEqual(tasks[0].title, 'Spaced Title');
+  });
+
+});
+

package/src/test/unit/runCli.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Unit tests for runCli.ts
+ * UT-1: resolves with trimmed stdout on exit code 0
+ * UT-2: rejects on non-zero exit code
+ * UT-3: rejects on timeout
+ */
+import * as assert from 'assert';
+import * as cp from 'child_process';
+import * as sinon from 'sinon';
+import { EventEmitter } from 'events';
+import { runCli } from '../../utils/runCli';
+
+// ---------------------------------------------------------------------------
+// Fake ChildProcess factory
+// ---------------------------------------------------------------------------
+
+interface FakeProcOpts {
+  stdout?: string;
+  stderr?: string;
+  /** Exit code to emit on 'close'. If undefined, defaults to 0. */
+  code?: number | null;
+  /**
+   * If set, the process deliberately hangs for this many ms before emitting
+   * 'close'. Use with a runCli timeoutMs smaller than hangMs to test timeout.
+   */
+  hangMs?: number;
+}
+
+function fakeProc(opts: FakeProcOpts): cp.ChildProcess {
+  const stdoutEE = new EventEmitter();
+  const stderrEE = new EventEmitter();
+  const procEE   = new EventEmitter();
+
+  // Minimal object that satisfies what runCli actually accesses.
+  const proc = {
+    stdout:         stdoutEE,
+    stderr:         stderrEE,
+    kill:           () => { /* noop – timeout test relies on this */ },
+    on:             procEE.on.bind(procEE),
+    once:           procEE.once.bind(procEE),
+    removeListener: procEE.removeListener.bind(procEE),
+    emit:           procEE.emit.bind(procEE),
+  };
+
+  setImmediate(() => {
+    if (opts.stdout) { stdoutEE.emit('data', Buffer.from(opts.stdout)); }
+    if (opts.stderr) { stderrEE.emit('data', Buffer.from(opts.stderr)); }
+
+    if (opts.hangMs === undefined) {
+      procEE.emit('close', opts.code ?? 0);
+    } else {
+      // Deliberately hang so the runCli timer can fire first.
+      setTimeout(() => procEE.emit('close', null), opts.hangMs);
+    }
+  });
+
+  return proc as unknown as cp.ChildProcess;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+suite('runCli — unit tests', () => {
+
+  test('UT-1: resolves with trimmed stdout on exit code 0', async () => {
+    const stub = sinon.stub(cp, 'spawn').returns(
+      fakeProc({ stdout: 'hello\n', code: 0 })
+    );
+    try {
+      const result = await runCli('echo', ['hello'], '/tmp');
+      assert.strictEqual(result, 'hello');
+    } finally {
+      stub.restore();
+    }
+  });
+
+  test('UT-2: rejects on non-zero exit code', async () => {
+    const stub = sinon.stub(cp, 'spawn').returns(
+      fakeProc({ stdout: '', stderr: 'err', code: 1 })
+    );
+    try {
+      await assert.rejects(
+        runCli('false', [], '/tmp'),
+        /failed with exit code 1/
+      );
+    } finally {
+      stub.restore();
+    }
+  });
+
+  test('UT-3: rejects on timeout', async () => {
+    // hangMs (5 000) >> timeoutMs (100) → timer fires first, process is killed,
+    // promise rejects with a message containing "timed out".
+    const stub = sinon.stub(cp, 'spawn').returns(
+      fakeProc({ hangMs: 5_000, code: null })
+    );
+    try {
+      await assert.rejects(
+        runCli('sleep', ['5'], '/tmp', 100),
+        /timed out/i
+      );
+    } finally {
+      stub.restore();
+    }
+  });
+
+});
+