Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.