@mytechtoday/augment-sdd 1.0.0 → 1.1.0

package/src/extension.ts

@@ -1,77 +0,0 @@
-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

@@ -1,26 +0,0 @@
-/**
- * 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

@@ -1,61 +0,0 @@
-/**
- * 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

@@ -1,129 +0,0 @@
-/**
- * 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

@@ -1,129 +0,0 @@
-/**
- * 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

@@ -1,15 +0,0 @@
-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

@@ -1,37 +0,0 @@
-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

@@ -1,48 +0,0 @@
-/**
- * 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

@@ -1,41 +0,0 @@
-/**
- * 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

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