Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
// Copyright 2026 Ix Infrastructure Inc.
import { existsSync, mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { Command } from "commander";
import { afterEach, describe, expect, it, vi } from "vitest";
import { noteResolutionNotices, printJson } from "../format.js";
import { acquireMapLock, lockPathForTest } from "../single-flight.js";
import { createInProcessRunner, resolveDefaultRunner, runCurrentIx } from "../../mcp/runner.js";
const resetReadScope = vi.hoisted(() => vi.fn());
vi.mock("../resolve.js", async (importOriginal) => ({
...(await importOriginal<typeof import("../resolve.js")>()),
resetReadScope,
}));
/**
* A stand-in command tree. The capture machinery is what is under test here,
* not the Ix commands, and a real one would need a backend.
*/
function createTestProgram(): Command {
const program = new Command();
program.name("ix").version("test-version").exitOverride();
program
.command("say")
.argument("<text>")
.option("--path <path>", "optional scope")
.action((text: string, opts: { path?: string }) => {
console.log(`out:${text}${opts.path ? ` path:${opts.path}` : ""}`);
});
program
.command("boom")
.action(() => {
console.error("fatal detail");
// The shape `ix status` and `ix text` use on their error paths.
process.exit(1);
});
program
.command("soft-fail")
.action(() => {
console.log("error code=backend_error message=offline");
// The shape most commands use: report on stdout, flag via exitCode.
process.exitCode = 1;
});
program
.command("slow")
.option("--delay <ms>", "how long to run past the caller's patience", "5000")
.option("--tag <tag>", "marker identifying which invocation printed", "slow")
.action(async (opts: { delay: string; tag: string }) => {
await new Promise((resolve) => setTimeout(resolve, Number(opts.delay)));
console.log(`done:${opts.tag}`);
});
program
.command("flood")
.action(() => {
for (let i = 0; i < 20; i += 1) console.log("x".repeat(100));
});
// A command that outlives its timeout and *then* reports failure the way
// `ix map` does — the shape that used to be charged to whichever call was
// running by the time it landed.
program
.command("late-fail")
.option("--delay <ms>", "how long before it reports failure", "150")
.action(async (opts: { delay: string }) => {
await new Promise((resolve) => setTimeout(resolve, Number(opts.delay)));
process.exitCode = 1;
});
// Stands in for `ix map`, which takes a single-flight lock and leaves it to
// process exit to release.
program
.command("map")
.option("--hold <ms>", "keep working after taking the lock", "0")
.option("--hang", "take the lock and never finish")
.action(async (opts: { hold: string; hang?: boolean }) => {
const workspace = process.env.IX_TEST_WORKSPACE ?? "workspace";
const lock = acquireMapLock(workspace, "ix map test");
if (!lock) {
console.log("coalesced");
return;
}
if (opts.hang) await new Promise(() => {});
await new Promise((resolve) => setTimeout(resolve, Number(opts.hold)));
// Whether the lock this command took is still its own by the time it
// finishes — anything releasing it mid-run reopens the window.
console.log(existsSync(lockPathForTest(workspace)) ? "mapped" : "lock-taken-mid-run");
});
program.command("ingest").action(() => console.log("ingested"));
// A json command whose target resolved with a notice, then failed before it
// printed (a backend error after resolution).
program.command("resolve-then-fail").action(() => {
noteResolutionNotices([{ code: "fuzzy_match", target: "Old" }]);
throw new Error("backend went away");
});
program.command("emit-json").action(() => printJson({ ok: true }));
// Never settles: a hung backend call, or a rejection that used to end the
// process and is now only logged by the server's error handlers.
program.command("hang").action(async () => {
await new Promise(() => {});
});
return program;
}
function testRunner() {
return createInProcessRunner({ version: "test-version", createProgram: createTestProgram });
}
/**
* Run a body against a throwaway lock directory.
*
* Any test whose commands reach `acquireMapLock` needs this: without it the
* lock lands in the developer's real `~/.ix/locks` and can block their own
* `ix map` for twenty minutes.
*/
async function withLockDir(body: () => Promise<void>): Promise<void> {
const dir = mkdtempSync(join(tmpdir(), "ix-mcp-lock-"));
const previous = { lockDir: process.env.IX_LOCK_DIR, workspace: process.env.IX_TEST_WORKSPACE };
process.env.IX_LOCK_DIR = dir;
process.env.IX_TEST_WORKSPACE = join(dir, "workspace");
try {
await body();
} finally {
if (previous.lockDir === undefined) delete process.env.IX_LOCK_DIR;
else process.env.IX_LOCK_DIR = previous.lockDir;
if (previous.workspace === undefined) delete process.env.IX_TEST_WORKSPACE;
else process.env.IX_TEST_WORKSPACE = previous.workspace;
rmSync(dir, { recursive: true, force: true });
}
}
const originalSubprocessFlag = process.env.IX_MCP_SUBPROCESS;
/**
* Longer than the slowest command any test here abandons and then waits for.
*
* Every test pays it, so it is kept close to what the slowest one needs rather
* than padded: at 500 it added ~11s to this file alone. The two commands that
* never settle are unaffected either way — their grace is what bounds them.
*/
const DRAIN_MS = 250;
afterEach(async () => {
if (originalSubprocessFlag === undefined) delete process.env.IX_MCP_SUBPROCESS;
else process.env.IX_MCP_SUBPROCESS = originalSubprocessFlag;
// Several tests deliberately abandon a command at its timeout, and an
// abandoned command outlives the test that started it. The runner's state is
// module-level, so while one is in flight every later test sees exit codes
// distrusted and a lock held — which is correct behaviour, and silently
// changes what an unrelated assertion observes. Draining here rather than at
// the end of each body means a failing assertion cannot skip it.
await new Promise((resolve) => setTimeout(resolve, DRAIN_MS));
});
describe("in-process ix runner", () => {
it("captures command stdout instead of writing it to the process", async () => {
const run = testRunner();
const result = await run(["say", "hello"]);
expect(result).toEqual({ ok: true, stdout: "out:hello\n", stderr: "" });
});
it("turns a command's process.exit into a failed result without exiting", async () => {
const run = testRunner();
const result = await run(["boom"]);
expect(result.ok).toBe(false);
expect(result.stderr).toContain("fatal detail");
// Reaching this line at all is the assertion that matters: a real
// process.exit here would have taken the MCP server down.
expect(await run(["say", "still alive"])).toMatchObject({ ok: true });
});
it("reports process.exitCode failures and leaves the host exit code alone", async () => {
const run = testRunner();
process.exitCode = undefined;
const result = await run(["soft-fail"]);
expect(result.ok).toBe(false);
expect(result.stdout).toBe("error code=backend_error message=offline\n");
expect(process.exitCode).toBeUndefined();
});
it("does not hand one command's resolution notices to the next json call", async () => {
const run = testRunner();
expect((await run(["resolve-then-fail"])).ok).toBe(false);
const next = await run(["emit-json"]);
expect(JSON.parse(next.stdout)).toEqual({ ok: true });
});
it("does not leak option values from one run into the next", async () => {
const run = testRunner();
const scoped = await run(["say", "a", "--path", "src/mcp"]);
const unscoped = await run(["say", "b"]);
expect(scoped.stdout).toBe("out:a path:src/mcp\n");
// Commander keeps parsed values on the Command object, so a cached program
// would answer "out:b path:src/mcp" here.
expect(unscoped.stdout).toBe("out:b\n");
});
it("keeps concurrent calls' output and exit status separate", async () => {
const run = testRunner();
const [first, second, third] = await Promise.all([
run(["say", "one"]),
run(["soft-fail"]),
run(["say", "three"]),
]);
expect(first).toEqual({ ok: true, stdout: "out:one\n", stderr: "" });
expect(second.ok).toBe(false);
expect(third).toEqual({ ok: true, stdout: "out:three\n", stderr: "" });
});
it("fails a run that outlives its timeout", async () => {
const run = testRunner();
// Bounded rather than left on the 5s default: an abandoned command stays
// in flight after the test that started it, and while one is alive the
// runner distrusts process.exitCode and holds off releasing locks — so a
// long orphan silently changes what later tests in this file observe.
const result = await run(["slow", "--delay", "200"], 50);
expect(result.ok).toBe(false);
expect(result.stderr).toContain("timed out after 50ms");
});
it("stays usable after a timeout rather than stranding the queue", async () => {
const run = testRunner();
await run(["slow", "--delay", "200"], 50);
expect(await run(["say", "after"])).toMatchObject({ ok: true, stdout: "out:after\n" });
});
it("keeps a timed-out command's late output out of the next call's result", async () => {
const run = testRunner();
// Abandoned at 50ms but still printing at ~150ms.
const timedOut = await run(["slow", "--delay", "150", "--tag", "orphan"], 50);
// Starts once the queue advances (~50ms) and is still running at ~150ms,
// so it is the call the orphan's write would otherwise be misfiled into.
const covering = await run(["slow", "--delay", "250", "--tag", "covering"], 5_000);
expect(timedOut.ok).toBe(false);
expect(covering).toEqual({ ok: true, stdout: "done:covering\n", stderr: "" });
});
it("does not charge a timed-out command's late exit code to the next call", async () => {
const run = testRunner();
process.exitCode = undefined;
// Abandoned at 50ms; sets process.exitCode = 1 at ~150ms.
const timedOut = await run(["late-fail", "--delay", "150"], 50);
// Runs across that moment. Its own command succeeds.
const covering = await run(["slow", "--delay", "250", "--tag", "covering"], 5_000);
expect(timedOut.ok).toBe(false);
// The orphan's write is the only thing that could make this false, and a
// successful lookup reported as a failure hides its answer inside an
// `error` string the agent cannot tell from a real fault.
expect(covering).toEqual({ ok: true, stdout: "done:covering\n", stderr: "" });
expect(process.exitCode).toBeUndefined();
});
it("trusts process.exitCode again once no orphan is in flight", async () => {
const run = testRunner();
process.exitCode = undefined;
await run(["late-fail", "--delay", "60"], 30);
// Long enough for the orphan to finish and leave the set.
await run(["slow", "--delay", "150", "--tag", "drain"], 5_000);
// Distrust must be temporary: a genuinely failing command still fails.
expect(await run(["soft-fail"])).toMatchObject({ ok: false });
});
it("releases the map single-flight lock when the command ends, not the process", async () => {
await withLockDir(async () => {
const run = testRunner();
const first = await run(["map"]);
const second = await run(["map"]);
expect(first.stdout).toBe("mapped\n");
// The lock records the server's own live PID, so it never ages out as
// stale. Held across calls, every later ix_map coalesced into an empty
// success while the graph was never refreshed.
expect(second.stdout).toBe("mapped\n");
});
});
it("does not release a running command's lock when an orphan settles", async () => {
await withLockDir(async () => {
const run = testRunner();
// Abandoned at 40ms, settles at ~150ms — part-way through the map below.
const orphan = run(["slow", "--delay", "150", "--tag", "orphan"], 40);
const mapped = run(["map", "--hold", "400"]);
expect((await orphan).ok).toBe(false);
// Releasing every lock the process holds drops more than the
// finishing command's, so an orphan settling mid-map deleted the lock of
// the map that was still running — reopening the exact window
// single-flight exists to close.
expect((await mapped).stdout).toBe("mapped\n");
});
});
it("does not release a still-running command's lock when its own grace fires", async () => {
await withLockDir(async () => {
const run = createInProcessRunner({
version: "test-version",
createProgram: createTestProgram,
orphanGraceMs: 60,
// This map ignores the abort (as work the run signal cannot reach
// does), and is abandoned at once rather than waited for.
abortSettleMs: 0,
});
// Abandoned at 40ms, grace fires at ~100ms, still working until ~400ms.
// The grace drops the exit-code distrust; the lock is a separate lifetime
// and stays with the command that is still using it.
expect((await run(["map", "--hold", "400"], 40)).ok).toBe(false);
await new Promise((resolve) => setTimeout(resolve, 200));
// An unrelated command completing must not take the running map's lock
// with it — releasing everything held is what did, one call later than
// the grace itself.
expect((await run(["say", "unrelated"], 5_000)).stdout).toBe("out:unrelated\n");
expect((await run(["map"], 5_000)).stdout).toBe("coalesced\n");
});
});
it("releases the lock of a command that overran its grace once it finishes", async () => {
await withLockDir(async () => {
const run = createInProcessRunner({
version: "test-version",
createProgram: createTestProgram,
orphanGraceMs: 40,
});
// The other direction: holding every lock back to protect a running
// command stranded the ones whose command had genuinely finished, and the
// next ix_map coalesced forever. Ownership is what lets both hold.
await run(["map", "--hold", "250"], 30);
await new Promise((resolve) => setTimeout(resolve, 400));
expect((await run(["map"], 5_000)).stdout).toBe("mapped\n");
});
});
it("invalidates the read scope for a command that never settles at all", async () => {
await withLockDir(async () => {
const run = createInProcessRunner({
version: "test-version",
createProgram: createTestProgram,
orphanGraceMs: 40,
});
resetReadScope.mockClear();
// A hung `ix map` has no settle to hang the invalidation off, so the
// grace has to carry it — otherwise the pre-map scope stays pinned for
// the life of the server with nothing left to clear it.
await run(["map", "--hang"], 30);
await new Promise((resolve) => setTimeout(resolve, 150));
expect(resetReadScope).toHaveBeenCalled();
});
});
it("stops distrusting the exit code once an abandoned command overruns its grace", async () => {
await withLockDir(async () => {
const run = createInProcessRunner({
version: "test-version",
createProgram: createTestProgram,
orphanGraceMs: 60,
});
process.exitCode = undefined;
// Never settles, so nothing will ever remove it from the orphan set.
// Left unbounded, every later failure reports ok and no lock is ever
// released again — both for the life of the server.
await run(["hang"], 30);
await new Promise((resolve) => setTimeout(resolve, 120));
expect(await run(["soft-fail"], 30)).toMatchObject({ ok: false });
expect((await run(["map"], 30)).stdout).toBe("mapped\n");
expect((await run(["map"], 30)).stdout).toBe("mapped\n");
});
});
it("invalidates the read-scope cache after a command that can change it", async () => {
await withLockDir(async () => {
const run = testRunner();
resetReadScope.mockClear();
await run(["say", "read"]);
expect(resetReadScope).not.toHaveBeenCalled();
// `ix map` can stitch the repo into a System server-side; every later read
// in the session would otherwise still scope to the pre-map workspace.
await run(["map"]);
await run(["ingest"]);
expect(resetReadScope).toHaveBeenCalledTimes(2);
});
});
it("invalidates the read-scope cache after a failed run", async () => {
const run = testRunner();
resetReadScope.mockClear();
// A failed read is often "no workspace here"; the next call must look the
// scope up again rather than answer from the one that just failed.
expect(await run(["soft-fail"])).toMatchObject({ ok: false });
expect(resetReadScope).toHaveBeenCalledTimes(1);
expect(await run(["boom"])).toMatchObject({ ok: false });
expect(resetReadScope).toHaveBeenCalledTimes(2);
await run(["say", "read"]);
expect(resetReadScope).toHaveBeenCalledTimes(2);
});
it("fails the run when output is truncated to protect the server heap", async () => {
const run = createInProcessRunner({
createProgram: createTestProgram,
maxOutputBytes: 500,
});
const result = await run(["flood"]);
expect(result.ok).toBe(false);
expect(result.stdout.length).toBeLessThanOrEqual(500);
expect(result.stderr).toContain("exceeded 500 bytes and was truncated");
});
it("applies the output cap to thrown error messages", async () => {
const run = createInProcessRunner({
maxOutputBytes: 500,
createProgram: () => {
const program = new Command();
program.command("throw-long").action(() => {
throw new Error("E".repeat(2_000));
});
return program;
},
});
const result = await run(["throw-long"]);
expect(result.ok).toBe(false);
expect(Buffer.byteLength(result.stderr)).toBeLessThanOrEqual(500);
expect(result.stderr).toContain("exceeded 500 bytes and was truncated");
expect(result.stderr).not.toContain("E".repeat(500));
});
it("keeps the failure reason when the cap already fired before the throw", async () => {
// Routing thrown text through appendChunk means it is dropped outright once
// the cap has fired, so a crash reaches the client as nothing but "output
// exceeded N bytes" — exactly when an operator most needs the reason.
const run = createInProcessRunner({
maxOutputBytes: 500,
createProgram: () => {
const program = new Command();
program.command("flood-then-throw").action(() => {
for (let i = 0; i < 20; i += 1) console.log("x".repeat(100));
throw new Error("backend refused the connection");
});
return program;
},
});
const result = await run(["flood-then-throw"]);
expect(result.ok).toBe(false);
expect(result.stderr).toContain("exceeded 500 bytes and was truncated");
expect(result.stderr).toContain("backend refused the connection");
});
it("reports an unknown command as a failure with commander's message", async () => {
const run = testRunner();
const result = await run(["not-a-command"]);
expect(result.ok).toBe(false);
expect(result.stderr).toContain("not-a-command");
});
it("treats --version as a success rather than a usage error", async () => {
const run = testRunner();
const result = await run(["--version"]);
expect(result.ok).toBe(true);
expect(result.stdout).toContain("test-version");
});
});
describe("installServerErrorHandlers", () => {
it("replaces the CLI's exit-on-error handlers with reporting ones", async () => {
const { installServerErrorHandlers } = await import("../../mcp/runner.js");
const before = {
uncaught: process.listeners("uncaughtException"),
unhandled: process.listeners("unhandledRejection"),
};
const exit = vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
try {
installServerErrorHandlers();
const handler = process.listeners("uncaughtException").at(-1) as (err: unknown) => void;
handler(new Error("stray rejection from a fire-and-forget fetch"));
// main.ts's handlers end in process.exit(1) on every path. For a server
// that is the whole session and all 22 tools, over an error that belonged
// to one tool call.
expect(exit).not.toHaveBeenCalled();
// And they are gone, not merely outnumbered: one handler each, ours.
expect(process.listeners("uncaughtException")).toHaveLength(1);
expect(process.listeners("unhandledRejection")).toHaveLength(1);
} finally {
exit.mockRestore();
process.removeAllListeners("uncaughtException");
process.removeAllListeners("unhandledRejection");
for (const listener of before.uncaught) process.on("uncaughtException", listener);
for (const listener of before.unhandled) process.on("unhandledRejection", listener);
}
});
});
describe("resolveDefaultRunner", () => {
it("runs in-process by default", () => {
delete process.env.IX_MCP_SUBPROCESS;
expect(resolveDefaultRunner({ createProgram: createTestProgram })).not.toBe(runCurrentIx);
});
it("falls back to the child process when IX_MCP_SUBPROCESS=1", () => {
process.env.IX_MCP_SUBPROCESS = "1";
expect(resolveDefaultRunner({ createProgram: createTestProgram })).toBe(runCurrentIx);
});
});