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
feat(cli): answer a failure in the format the caller asked for (#689)
Ian Hock54f1a4a94cfe
diff --git a/ix-cli/src/cli/__tests__/llm-errors.test.ts b/ix-cli/src/cli/__tests__/llm-errors.test.tsnew file mode 100644index 00000000..b5137047--- /dev/null+++ b/ix-cli/src/cli/__tests__/llm-errors.test.ts@@ -0,0 +1,141 @@+// Copyright 2026 Ix Infrastructure Inc.++import { afterEach, describe, expect, it, vi } from "vitest";++import {+ CliUsageError,+ detectRequestedFormat,+ renderCliError,+ setErrorFormat,+} from "../errors.js";++/** Node's fetch shape: `TypeError: fetch failed` with the real error nested. */+function unreachable(): Error {+ const err = new TypeError("fetch failed");+ (err as { cause?: unknown }).cause = Object.assign(+ new Error("connect ECONNREFUSED 127.0.0.1:8090"),+ { code: "ECONNREFUSED" },+ );+ return err;+}++/**+ * Both streams, plus the exit. `renderCliError` reaches stderr two ways+ * (`process.stderr.write` and `console.error`) and stdout through+ * `console.log`; exit becomes a throw so an assertion can still run.+ */+function capture(fn: () => void): { out: string; err: string; exited: boolean } {+ let out = "";+ let err = "";+ const spies = [+ vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {+ out += args.map(String).join(" ") + "\n";+ }),+ vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {+ err += args.map(String).join(" ") + "\n";+ }),+ vi.spyOn(process.stderr, "write").mockImplementation((chunk: unknown) => {+ err += String(chunk);+ return true;+ }),+ ];+ const exit = vi.spyOn(process, "exit").mockImplementation(((): never => {+ throw new Error("__exit__");+ }) as never);++ let exited = false;+ try {+ fn();+ } catch (error) {+ if ((error as Error).message !== "__exit__") throw error;+ exited = true;+ } finally {+ for (const spy of spies) spy.mockRestore();+ exit.mockRestore();+ }+ return { out, err, exited };+}++afterEach(() => setErrorFormat(undefined));++describe("detectRequestedFormat", () => {+ it("reads both spellings of the flag", () => {+ expect(detectRequestedFormat(["search", "foo", "--format", "llm"])).toBe("llm");+ expect(detectRequestedFormat(["search", "foo", "--format=llm"])).toBe("llm");+ expect(detectRequestedFormat(["status", "--format", "json"])).toBe("json");+ });++ it("is undefined when the caller did not ask", () => {+ expect(detectRequestedFormat(["status"])).toBeUndefined();+ expect(detectRequestedFormat([])).toBeUndefined();+ });++ it("stops at `--`, so a search term is never read as a flag", () => {+ expect(detectRequestedFormat(["text", "--", "--format", "llm"])).toBeUndefined();+ });++ it("does not read IX_FORMAT — that default is not in effect yet", () => {+ const original = process.env.IX_FORMAT;+ process.env.IX_FORMAT = "llm";+ try {+ expect(detectRequestedFormat(["status"])).toBeUndefined();+ } finally {+ if (original === undefined) delete process.env.IX_FORMAT;+ else process.env.IX_FORMAT = original;+ }+ });+});++describe("renderCliError with --format llm", () => {+ it("answers a dead backend on stdout, as one record, and exits non-zero", () => {+ setErrorFormat("llm");+ const { out, err, exited } = capture(() =>+ renderCliError(unreachable(), false, "http://localhost:8090"),+ );+ expect(out.trimEnd().split("\n")).toEqual([+ 'error code=backend_unreachable message="Ix backend not reachable at http://localhost:8090." ' ++ 'hint="Start it with `ix docker start`, then check `ix status`."',+ ]);+ expect(err).toBe("");+ expect(exited).toBe(true);+ });++ it("keeps the prose on stderr when no format was asked for", () => {+ const { out, err } = capture(() =>+ renderCliError(unreachable(), false, "http://localhost:8090"),+ );+ expect(out).toBe("");+ expect(err).toContain("Ix backend not reachable");+ });++ it("carries the backend's own code, message and next step", () => {+ setErrorFormat("llm");+ const { out } = capture(() =>+ renderCliError(+ new Error('404: {"error":"workspace_not_found","message":"No such workspace","next":"Run ix map"}'),+ ),+ );+ expect(out.trim()).toBe(+ 'error code=workspace_not_found message="No such workspace" hint="Run ix map"',+ );+ });++ it("reports an unrecognised failure rather than guessing at a class for it", () => {+ setErrorFormat("llm");+ const { out } = capture(() => renderCliError(new Error("something odd")));+ expect(out.trim()).toBe('error code=cli_error message="something odd"');+ });++ it("gives a usage error its hint", () => {+ setErrorFormat("llm");+ const { out } = capture(() => renderCliError(new CliUsageError("Bad flag", "Try --kind class")));+ expect(out.trim()).toBe('error code=usage_error message="Bad flag" hint="Try --kind class"');+ });++ it("stays on one line however many the message had", () => {+ setErrorFormat("llm");+ const { out } = capture(() => renderCliError(new Error("line one\nline two")));+ expect(out.trimEnd().split("\n")).toHaveLength(1);+ expect(out).toContain("\\n");+ });+});diff --git a/ix-cli/src/cli/commands/status.ts b/ix-cli/src/cli/commands/status.tsindex 3105ef83..33d72875 100644--- a/ix-cli/src/cli/commands/status.ts+++ b/ix-cli/src/cli/commands/status.ts@@ -7,6 +7,7 @@ import { readBackendHealth } from "./upgrade.js";import { getEndpoint, resolveWorkspaceRoot } from "../config.js";import { detectStaleFiles } from "../stale.js";import { llmError, llmLine, printLlmLines } from "../llm.js";+import { backendUnreachableError, isBackendUnreachable } from "../errors.js";interface StatusStaleInfo {graphCompleted: boolean;@@ -114,13 +115,20 @@ export function registerStatusCommand(program: Command): void {}}} catch (err) {+ // Only a transport failure is "not reachable". Anything else — a 500+ // from a backend that is up, a malformed response — went out under+ // this message too, which sent people to restart a container that was+ // running fine. Those now reach the shared boundary, which names them.+ if (!isBackendUnreachable(err)) throw err;// The spec's uniform error record, so a consumer that pipes `--format// llm` parses the failure the same way it parses a result rather than// hitting an unparseable human sentence. Exit code is unchanged.+ const unreachable = backendUnreachableError(getEndpoint());if (opts.format === "llm") {- console.log(llmError("backend_unreachable", `Ix backend not reachable at ${getEndpoint()}`));+ console.log(llmError(unreachable.error, unreachable.message, [["hint", unreachable.next ?? null]]));} else {- console.error(`Ix backend not reachable at ${getEndpoint()}`);+ console.error(unreachable.message);+ if (unreachable.next) console.error(unreachable.next);}process.exit(1);}diff --git a/ix-cli/src/cli/errors.ts b/ix-cli/src/cli/errors.tsindex 4e89e725..003c2755 100644--- a/ix-cli/src/cli/errors.ts+++ b/ix-cli/src/cli/errors.ts@@ -2,6 +2,66 @@import chalk from "chalk";+import { llmError } from "./llm.js";++// ── Answering in the format the caller asked for ───────────────────────────++/**+ * The `--format` this run was invoked with, or undefined for the default.+ *+ * A failure is the one answer an agent is least equipped to guess at, and it+ * was the only one this CLI would not give in the format it had been asked+ * for: a backend that is down produced several lines of coloured prose on+ * stderr and nothing at all on stdout, so a caller parsing records saw an+ * empty stream and a non-zero exit with no reason attached.+ */+let requestedFormat: string | undefined;++/** Record the format for the error boundary. Called once, from `main.ts`. */+export function setErrorFormat(format: string | undefined): void {+ requestedFormat = format;+}++/**+ * The `--format` the caller typed, read straight off argv.+ *+ * Read from argv rather than from the parsed command because this has to work+ * before commander has parsed anything: the handler that calls+ * `renderCliError` is installed for `unhandledRejection` and+ * `uncaughtException`, which can fire at any point, including during+ * registration.+ *+ * Only what was typed. `IX_FORMAT` and `config.format` choose the default+ * elsewhere (#682); until that lands, honouring them here would answer in+ * records for a run whose payload came out as text.+ *+ * Stops at `--`, so a term that merely looks like a flag —+ * `ix text -- "--format llm"` — is not read as one.+ */+export function detectRequestedFormat(argv: readonly string[]): string | undefined {+ for (let i = 0; i < argv.length; i += 1) {+ const arg = argv[i];+ if (arg === "--") return undefined;+ if (arg.startsWith("--format=")) return arg.slice("--format=".length);+ if (arg === "--format") return argv[i + 1];+ }+ return undefined;+}++/**+ * Emit the failure as one record on stdout, or return false if the caller did+ * not ask for records.+ *+ * On stdout, not stderr: stdout is where the answer goes, and "there is no+ * answer, because X" is an answer. The human prose is then skipped rather than+ * printed alongside, so the caller gets exactly one report.+ */+function emitLlmError(code: string, message: string, hint?: string): boolean {+ if (requestedFormat !== "llm") return false;+ console.log(llmError(code, message, hint ? [["hint", hint]] : []));+ return true;+}+/*** Structured error with user-facing message and optional next-step guidance.* Parsed from backend JSON responses that include `error`, `message`, and `next` fields.@@ -195,11 +255,35 @@ export function isBackendUnreachable(err: unknown): boolean {return isUnreachableCode(e?.cause as { code?: unknown } | null | undefined);}+/**+ * The one description of a backend nobody answered at.+ *+ * Shared so a command that catches the failure itself — `ix status` does, to+ * keep its own shape — reports the same code, the same sentence and the same+ * next step as the process-wide boundary. It was two wordings before, one of+ * them with no next step at all.+ */+export function backendUnreachableError(endpoint?: string): StructuredError {+ return {+ error: "backend_unreachable",+ message: `Ix backend not reachable${endpoint ? ` at ${endpoint}` : ""}.`,+ // `ix docker start` only fixes a backend this machine is supposed to run.+ // Pro points `config.endpoint` at a cloud instance, where that advice is+ // both useless and actively wrong — it starts a backend you aren't using.+ next: isLocalEndpoint(endpoint)+ ? "Start it with `ix docker start`, then check `ix status`."+ : "Check your network, and that the endpoint is right (`ix config get endpoint`).",+ };+}+export function renderCliError(err: unknown, debug = false, endpoint?: string): void {if (err instanceof CliUsageError || err instanceof CliResolutionError) {- process.stderr.write(chalk.red(`Error: ${err.message}\n`));- if (err.hint) {- process.stderr.write(chalk.dim(`${err.hint}\n`));+ const code = err instanceof CliUsageError ? "usage_error" : "resolution_failed";+ if (!emitLlmError(code, err.message, err.hint)) {+ process.stderr.write(chalk.red(`Error: ${err.message}\n`));+ if (err.hint) {+ process.stderr.write(chalk.dim(`${err.hint}\n`));+ }}if (debug && err instanceof CliResolutionError && err.detail) {process.stderr.write(chalk.dim(`Detail: ${err.detail}\n`));@@ -210,23 +294,19 @@ export function renderCliError(err: unknown, debug = false, endpoint?: string):const e = err as any;if (isBackendUnreachable(err)) {- renderStructuredError({- error: "backend_unreachable",- message: `Ix backend not reachable${endpoint ? ` at ${endpoint}` : ""}.`,- // `ix docker start` only fixes a backend this machine is supposed to run.- // Pro points `config.endpoint` at a cloud instance, where that advice is- // both useless and actively wrong — it starts a backend you aren't using.- next: isLocalEndpoint(endpoint)- ? "Start it with `ix docker start`, then check `ix status`."- : "Check your network, and that the endpoint is right (`ix config get endpoint`).",- });+ const unreachable = backendUnreachableError(endpoint);+ if (!emitLlmError(unreachable.error, unreachable.message, unreachable.next)) {+ renderStructuredError(unreachable);+ }if (debug) writeDebugDetail(err);process.exit(1);}const structured = typeof e?.message === "string" ? parseBackendError(e.message) : null;if (structured) {- renderStructuredError(structured);+ if (!emitLlmError(structured.error, structured.message, structured.next)) {+ renderStructuredError(structured);+ }if (debug) writeDebugDetail(err);process.exit(1);}@@ -234,7 +314,11 @@ export function renderCliError(err: unknown, debug = false, endpoint?: string):// formatFetchError unwraps `fetch failed` so the transport cause is visible// rather than being hidden behind a message that says nothing.const msg = err === null || err === undefined ? String(err) : formatFetchError(err);- process.stderr.write(chalk.red(`Error: ${msg}\n`));+ // `cli_error` because nothing above recognised it: the code has to stay+ // stable and honest rather than guess at a class from the message text.+ if (!emitLlmError("cli_error", msg)) {+ process.stderr.write(chalk.red(`Error: ${msg}\n`));+ }if (debug) writeDebugDetail(err);diff --git a/ix-cli/src/cli/main.ts b/ix-cli/src/cli/main.tsindex e8363896..1505022c 100644--- a/ix-cli/src/cli/main.ts+++ b/ix-cli/src/cli/main.ts@@ -7,7 +7,7 @@ import { tryLoadProCommands } from "./register/pro-loader.js";import { buildHelpText } from "./help-text.js";import { checkForUpdate, updateCheckEnabled } from "./commands/upgrade.js";import { stderrIsTerminal } from "./stderr.js";-import { renderCliError } from "./errors.js";+import { detectRequestedFormat, renderCliError, setErrorFormat } from "./errors.js";import { getEndpoint } from "./config.js";import { readFileSync } from "fs";@@ -40,6 +40,12 @@ try {// Set IX_DEBUG=1 to append stack traces to any rendered error.const debug = process.env.IX_DEBUG === "1";+// Before anything can throw. The handlers below are installed for+// `unhandledRejection` and `uncaughtException`, which can fire before+// commander has parsed a thing, so the error boundary gets the format from+// argv rather than from a parsed command.+setErrorFormat(detectRequestedFormat(process.argv.slice(2)));+// Resolving the endpoint reads config off disk, which can itself fail. An// error renderer must never throw, so failure here just drops the endpoint// from the message rather than replacing one crash with another.