This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/aitimemachine/gitnexus/test/unit/local-cli-subprocess.test.ts
caelum0x 49b183818c Unify gitgram + aitimemachine into the monorepo (de-submodule) and merge vendored engines
Convert gitgram/ and aitimemachine/ from embedded git repos (which showed as
opaque submodule gitlinks on GitHub) into fully-tracked first-party content.

AITM now merges its 7 vendored repos as first-party engines:
- memory: beads (Go task DAG) + context7 (docs SDK), unified into saved_contexts
- git: vendored C git (bundled binary) + gitnexus (in-process code intelligence)
- agentic: a2a (@a2a-js/sdk) + pal (AITM-managed Python subprocess)

Includes the full session's product build: Gitgram web/mobile/backend features,
AITM website/CLI/MCP, the unified memory layer, engine build tooling
(scripts/build-engines.sh, Dockerfile, CI), docs (README, ENGINES.md, ARCHITECTURE.md),
and extensive test suites.

Build artifacts, node_modules, external/, and gemini-cli are gitignored.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-23 14:14:09 +03:00

626 lines
21 KiB
TypeScript

/**
* Integration-level tests for local CLI subprocess contracts.
*
* Validates the actual argv, stdin content, spawn options, and exit
* behavior for Claude and Codex providers — the layer that
* wiki-flags.test.ts mocks out. Uses a fake spawn that captures
* args and emits controlled events.
*/
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { EventEmitter } from 'events';
function makeFakeChild(opts?: {
exitCode?: number;
stdout?: string;
stderr?: string;
stdinEndBehavior?: 'normal' | 'epipe';
}) {
const child = new EventEmitter() as any;
child.stdout = new EventEmitter();
child.stderr = new EventEmitter();
child.stdin = new EventEmitter() as any;
child.pid = 12345;
child.kill = vi.fn();
let stdinContent = '';
child.stdin.end = vi.fn((data?: string) => {
if (data) stdinContent += data;
queueMicrotask(() => {
if (opts?.stdinEndBehavior === 'epipe') {
child.stdin.emit('error', new Error('write EPIPE'));
}
if (opts?.stdout) {
child.stdout.emit('data', Buffer.from(opts.stdout));
}
if (opts?.stderr) {
child.stderr.emit('data', Buffer.from(opts.stderr));
}
child.emit('close', opts?.exitCode ?? 0);
});
});
return { child, getStdin: () => stdinContent };
}
// ─── Claude CLI argv contract ─────────────────────────────────────────
describe('Claude CLI subprocess contract', () => {
let spawnSpy: ReturnType<typeof vi.fn>;
let fakeChild: ReturnType<typeof makeFakeChild>;
beforeEach(() => {
vi.resetModules();
fakeChild = makeFakeChild({ stdout: 'Claude response text' });
spawnSpy = vi.fn(() => fakeChild.child);
});
afterEach(() => {
vi.restoreAllMocks();
});
it('passes correct flags: -p --output-format text --no-session-persistence', async () => {
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('claude 1.0.0'),
spawn: spawnSpy,
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callClaudeLLM('user prompt', {});
const args = spawnSpy.mock.calls[0][1] as string[];
expect(args).toContain('-p');
expect(args).toContain('--output-format');
expect(args).toContain('text');
expect(args).toContain('--no-session-persistence');
});
it('appends --model only when model is set', async () => {
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('claude 1.0.0'),
spawn: spawnSpy,
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callClaudeLLM('prompt', { model: 'claude-sonnet-4-20250514' });
const args = spawnSpy.mock.calls[0][1] as string[];
expect(args).toContain('--model');
expect(args).toContain('claude-sonnet-4-20250514');
});
it('does not include --model when model is empty', async () => {
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('claude 1.0.0'),
spawn: spawnSpy,
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callClaudeLLM('prompt', {});
const args = spawnSpy.mock.calls[0][1] as string[];
expect(args).not.toContain('--model');
});
it('sends full prompt (system + separator + user) via stdin', async () => {
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('claude 1.0.0'),
spawn: spawnSpy,
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callClaudeLLM('user prompt', {}, 'system prompt');
const stdinText = fakeChild.getStdin();
expect(stdinText).toBe('system prompt\n\n---\n\nuser prompt');
});
it('sends only user prompt when no system prompt', async () => {
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('claude 1.0.0'),
spawn: spawnSpy,
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callClaudeLLM('just the user prompt', {});
expect(fakeChild.getStdin()).toBe('just the user prompt');
});
it('sets CI=1 and windowsHide=true in spawn options', async () => {
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('claude 1.0.0'),
spawn: spawnSpy,
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callClaudeLLM('prompt', {});
const spawnOpts = spawnSpy.mock.calls[0][2];
expect(spawnOpts.env.CI).toBe('1');
expect(spawnOpts.windowsHide).toBe(true);
});
it('rejects with exit code and stderr on non-zero exit', async () => {
fakeChild = makeFakeChild({ exitCode: 1, stderr: 'auth required' });
spawnSpy = vi.fn(() => fakeChild.child);
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('claude 1.0.0'),
spawn: spawnSpy,
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
await expect(callClaudeLLM('prompt', {})).rejects.toThrow(
'claude CLI exited with code 1: auth required',
);
});
it('rejects with actionable error on empty stdout', async () => {
fakeChild = makeFakeChild({ stdout: '' });
spawnSpy = vi.fn(() => fakeChild.child);
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('claude 1.0.0'),
spawn: spawnSpy,
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
await expect(callClaudeLLM('prompt', {})).rejects.toThrow('claude CLI returned empty output');
});
});
// ─── Codex CLI argv contract ──────────────────────────────────────────
describe('Codex CLI subprocess contract', () => {
let spawnSpy: ReturnType<typeof vi.fn>;
let fakeChild: ReturnType<typeof makeFakeChild>;
beforeEach(() => {
vi.resetModules();
fakeChild = makeFakeChild({ stdout: 'codex response' });
spawnSpy = vi.fn(() => fakeChild.child);
});
afterEach(() => {
vi.restoreAllMocks();
});
it('passes correct subcommand and flags: exec --sandbox read-only -c approval_policy', async () => {
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('codex 0.1.0'),
spawn: spawnSpy,
}));
const { callCodexLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callCodexLLM('prompt', { workingDirectory: '/repo' });
const args = spawnSpy.mock.calls[0][1] as string[];
expect(args).toContain('exec');
expect(args).toContain('--sandbox');
expect(args).toContain('read-only');
expect(args).toContain('-c');
expect(args).toContain('approval_policy="never"');
expect(args).toContain('--color');
expect(args).toContain('never');
});
it('includes --output-last-message with a temp file path', async () => {
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('codex 0.1.0'),
spawn: spawnSpy,
}));
const { callCodexLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callCodexLLM('prompt', { workingDirectory: '/repo' });
const args = spawnSpy.mock.calls[0][1] as string[];
const outputIdx = args.indexOf('--output-last-message');
expect(outputIdx).toBeGreaterThan(-1);
const outputPath = args[outputIdx + 1];
expect(outputPath).toContain('gitnexus-wiki-codex-');
expect(outputPath).toContain('last-message.txt');
});
it('passes --cd with the working directory', async () => {
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('codex 0.1.0'),
spawn: spawnSpy,
}));
const { callCodexLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callCodexLLM('prompt', { workingDirectory: '/my/repo' });
const args = spawnSpy.mock.calls[0][1] as string[];
const cdIdx = args.indexOf('--cd');
expect(cdIdx).toBeGreaterThan(-1);
expect(args[cdIdx + 1]).toBe('/my/repo');
});
it('ends args with - (stdin marker)', async () => {
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('codex 0.1.0'),
spawn: spawnSpy,
}));
const { callCodexLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callCodexLLM('prompt', { workingDirectory: '/repo' });
const args = spawnSpy.mock.calls[0][1] as string[];
expect(args[args.length - 1]).toBe('-');
});
it('sends full prompt via stdin', async () => {
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('codex 0.1.0'),
spawn: spawnSpy,
}));
const { callCodexLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callCodexLLM('user msg', { workingDirectory: '/repo' }, 'sys msg');
expect(fakeChild.getStdin()).toBe('sys msg\n\n---\n\nuser msg');
});
it('appends --model only when set', async () => {
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('codex 0.1.0'),
spawn: spawnSpy,
}));
const { callCodexLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callCodexLLM('prompt', { workingDirectory: '/repo', model: 'o3-pro' });
const args = spawnSpy.mock.calls[0][1] as string[];
expect(args).toContain('--model');
expect(args).toContain('o3-pro');
const modelIdx = args.indexOf('--model');
const stdinIdx = args.indexOf('-');
expect(modelIdx).toBeLessThan(stdinIdx);
});
});
// ─── Timeout behavior ─────────────────────────────────────────────────
describe('local CLI timeout', () => {
beforeEach(() => {
vi.resetModules();
vi.useFakeTimers();
});
afterEach(() => {
vi.useRealTimers();
vi.restoreAllMocks();
});
it('kills child process after requestTimeoutMs and rejects with timeout error', async () => {
const child = new EventEmitter() as any;
child.stdout = new EventEmitter();
child.stderr = new EventEmitter();
child.stdin = new EventEmitter() as any;
child.pid = 99;
child.kill = vi.fn();
child.stdin.end = vi.fn();
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('claude 1.0.0'),
spawn: vi.fn(() => child),
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
const promise = callClaudeLLM('prompt', { requestTimeoutMs: 5000 });
vi.advanceTimersByTime(5000);
child.emit('close', null);
await expect(promise).rejects.toThrow('claude CLI timed out after 5s');
});
it('uses taskkill /T /F /PID on Windows for process-tree kill', async () => {
const originalPlatform = process.platform;
Object.defineProperty(process, 'platform', { value: 'win32' });
try {
const child = new EventEmitter() as any;
child.stdout = new EventEmitter();
child.stderr = new EventEmitter();
child.stdin = new EventEmitter() as any;
child.pid = 42;
child.kill = vi.fn();
child.stdin.end = vi.fn();
const execFileSyncSpy = vi.fn().mockImplementation((cmd: string, args: string[]) => {
if (cmd !== 'taskkill') return 'claude 1.0.0';
return '';
});
vi.doMock('child_process', () => ({
execFileSync: execFileSyncSpy,
spawn: vi.fn(() => child),
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
const promise = callClaudeLLM('prompt', { requestTimeoutMs: 3000 });
vi.advanceTimersByTime(3000);
// Timeout fires, taskkill runs, but child hasn't emitted close yet.
// Emit close now to settle the promise.
child.emit('close', null);
await expect(promise).rejects.toThrow('claude CLI timed out after 3s');
const taskkillCalls = execFileSyncSpy.mock.calls.filter(
(c: unknown[]) => c[0] === 'taskkill',
);
expect(taskkillCalls.length).toBe(1);
expect(taskkillCalls[0][1]).toEqual(['/T', '/F', '/PID', '42']);
expect(child.kill).not.toHaveBeenCalled();
} finally {
Object.defineProperty(process, 'platform', { value: originalPlatform });
}
});
it('falls back to child.kill() when taskkill fails on Windows', async () => {
const originalPlatform = process.platform;
Object.defineProperty(process, 'platform', { value: 'win32' });
try {
const child = new EventEmitter() as any;
child.stdout = new EventEmitter();
child.stderr = new EventEmitter();
child.stdin = new EventEmitter() as any;
child.pid = 42;
child.kill = vi.fn();
child.stdin.end = vi.fn();
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockImplementation((cmd: string) => {
if (cmd === 'taskkill') throw new Error('taskkill: process not found');
return 'claude 1.0.0';
}),
spawn: vi.fn(() => child),
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
const promise = callClaudeLLM('prompt', { requestTimeoutMs: 2000 });
vi.advanceTimersByTime(2000);
child.emit('close', null);
await expect(promise).rejects.toThrow('claude CLI timed out after 2s');
expect(child.kill).toHaveBeenCalled();
} finally {
Object.defineProperty(process, 'platform', { value: originalPlatform });
}
});
it('does not set a kill timer when requestTimeoutMs is undefined', async () => {
const child = new EventEmitter() as any;
child.stdout = new EventEmitter();
child.stderr = new EventEmitter();
child.stdin = new EventEmitter() as any;
child.pid = 99;
child.kill = vi.fn();
child.stdin.end = vi.fn(() => {
queueMicrotask(() => {
child.stdout.emit('data', Buffer.from('response'));
child.emit('close', 0);
});
});
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('claude 1.0.0'),
spawn: vi.fn(() => child),
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
const response = await callClaudeLLM('prompt', {});
expect(response.content).toBe('response');
expect(child.kill).not.toHaveBeenCalled();
});
});
// ─── Codex output file fallback ───────────────────────────────────────
describe('Codex output file fallback', () => {
beforeEach(() => {
vi.resetModules();
});
afterEach(() => {
vi.restoreAllMocks();
});
it('uses stdout when output file is missing', async () => {
const fakeChild = makeFakeChild({ stdout: 'stdout content' });
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('codex 0.1.0'),
spawn: vi.fn(() => fakeChild.child),
}));
const { callCodexLLM } = await import('../../src/core/wiki/local-cli-client.js');
const result = await callCodexLLM('prompt', { workingDirectory: '/repo' });
expect(result.content).toBe('stdout content');
});
it('rejects when both stdout and output file are empty', async () => {
const fakeChild = makeFakeChild({ stdout: '' });
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('codex 0.1.0'),
spawn: vi.fn(() => fakeChild.child),
}));
const { callCodexLLM } = await import('../../src/core/wiki/local-cli-client.js');
await expect(callCodexLLM('prompt', { workingDirectory: '/repo' })).rejects.toThrow(
'codex CLI returned empty output',
);
});
});
// ─── detectLocalCLI diagnostics ───────────────────────────────────────
describe('detectLocalCLI diagnostics', () => {
beforeEach(() => {
vi.resetModules();
});
afterEach(() => {
vi.restoreAllMocks();
});
it('returns null and warns when CLI exists but --version fails (non-ENOENT)', async () => {
const warnSpy = vi.fn();
vi.doMock('../../src/core/logger.js', () => ({
logger: { info: vi.fn(), warn: warnSpy },
}));
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockImplementation(() => {
const err = new Error('exit code 1') as any;
err.status = 1;
throw err;
}),
spawn: vi.fn(),
}));
const { detectLocalCLI } = await import('../../src/core/wiki/local-cli-client.js');
const result = detectLocalCLI('claude');
expect(result).toBeNull();
expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('--version failed'));
});
it('returns null silently when CLI is truly not found (ENOENT)', async () => {
const warnSpy = vi.fn();
vi.doMock('../../src/core/logger.js', () => ({
logger: { info: vi.fn(), warn: warnSpy },
}));
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockImplementation(() => {
const err = new Error('ENOENT') as any;
err.code = 'ENOENT';
throw err;
}),
spawn: vi.fn(),
}));
const { detectLocalCLI } = await import('../../src/core/wiki/local-cli-client.js');
const result = detectLocalCLI('claude');
expect(result).toBeNull();
expect(warnSpy).not.toHaveBeenCalled();
});
});
// ─── onChunk progress callback ────────────────────────────────────────
describe('local CLI onChunk callback', () => {
beforeEach(() => {
vi.resetModules();
});
afterEach(() => {
vi.restoreAllMocks();
});
it('fires onChunk with cumulative stdout byte count', async () => {
const child = new EventEmitter() as any;
child.stdout = new EventEmitter();
child.stderr = new EventEmitter();
child.stdin = new EventEmitter() as any;
child.pid = 1;
child.stdin.end = vi.fn(() => {
queueMicrotask(() => {
child.stdout.emit('data', Buffer.from('chunk1'));
child.stdout.emit('data', Buffer.from('chunk2'));
child.emit('close', 0);
});
});
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('claude 1.0.0'),
spawn: vi.fn(() => child),
}));
const { callClaudeLLM } = await import('../../src/core/wiki/local-cli-client.js');
const chunks: number[] = [];
await callClaudeLLM('prompt', {}, undefined, { onChunk: (n) => chunks.push(n) });
expect(chunks).toEqual([6, 12]);
});
});
// ─── Codex CLI flag contract snapshot ─────────────────────────────────
describe('Codex CLI flag contract snapshot', () => {
beforeEach(() => {
vi.resetModules();
});
afterEach(() => {
vi.restoreAllMocks();
});
it('spawn args match the exact expected contract (flag rename = test failure)', async () => {
const fakeChild = makeFakeChild({ stdout: 'codex output' });
const spawnSpy = vi.fn(() => fakeChild.child);
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('codex 0.1.0'),
spawn: spawnSpy,
}));
const { callCodexLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callCodexLLM('prompt', { workingDirectory: '/repo', model: 'o3' });
const args = spawnSpy.mock.calls[0][1] as string[];
// The contract flags start at 'exec' — skip any platform argsPrefix
// (e.g., ['/d', '/s', '/c', 'codex'] on Windows cmd.exe fallback)
const execIdx = args.indexOf('exec');
expect(execIdx).toBeGreaterThanOrEqual(0);
const contractArgs = args.slice(execIdx);
// Strip the dynamic temp path for comparison
const outputMsgIdx = contractArgs.indexOf('--output-last-message');
const normalized = [...contractArgs];
if (outputMsgIdx !== -1) {
normalized[outputMsgIdx + 1] = '<TEMP_PATH>';
}
expect(normalized).toEqual([
'exec',
'--cd',
'/repo',
'--sandbox',
'read-only',
'-c',
'approval_policy="never"',
'--color',
'never',
'--output-last-message',
'<TEMP_PATH>',
'--model',
'o3',
'-',
]);
});
it('--model appears before - (stdin marker) and after --output-last-message', async () => {
const fakeChild = makeFakeChild({ stdout: 'codex output' });
const spawnSpy = vi.fn(() => fakeChild.child);
vi.doMock('child_process', () => ({
execFileSync: vi.fn().mockReturnValue('codex 0.1.0'),
spawn: spawnSpy,
}));
const { callCodexLLM } = await import('../../src/core/wiki/local-cli-client.js');
await callCodexLLM('prompt', { workingDirectory: '/repo', model: 'test-model' });
const args = spawnSpy.mock.calls[0][1] as string[];
const outputIdx = args.indexOf('--output-last-message');
const modelIdx = args.indexOf('--model');
const stdinIdx = args.lastIndexOf('-');
expect(outputIdx).toBeLessThan(modelIdx);
expect(modelIdx).toBeLessThan(stdinIdx);
expect(args[args.length - 1]).toBe('-');
});
});