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
fix(cli): render backend-down as guidance instead of an undici stack trace (#333)
KageBinary8d4ba28f293e
diff --git a/ix-cli/src/cli/__tests__/errors.test.ts b/ix-cli/src/cli/__tests__/errors.test.tsnew file mode 100644index 00000000..a55dbc22--- /dev/null+++ b/ix-cli/src/cli/__tests__/errors.test.ts@@ -0,0 +1,223 @@+import { afterEach, describe, expect, it, vi } from "vitest";++import {+ CliResolutionError,+ CliUsageError,+ formatFetchError,+ isBackendUnreachable,+ renderCliError,+} from "../errors.js";++/** Node's fetch shape: `TypeError: fetch failed` with the real error nested. */+function fetchFailure(code: string): Error {+ const err = new TypeError("fetch failed");+ (err as { cause?: unknown }).cause = Object.assign(+ new Error(`connect ${code} 127.0.0.1:8090`),+ { code, errno: -111, syscall: "connect" },+ );+ return err;+}++/**+ * The same shape for a socket that was established and then died.+ *+ * The classifier keys on the code alone, so as an input this differs from+ * `fetchFailure` only in fields nothing reads. It is here to name the scenario+ * the mid-flight codes stand for — it is not a phase discriminator, and a code+ * moved into UNREACHABLE_CODES would not be caught by using this helper.+ */+function midFlightFailure(code: string): Error {+ const err = new TypeError("fetch failed");+ (err as { cause?: unknown }).cause = Object.assign(+ new Error(`read ${code} 127.0.0.1:8090`),+ { code, errno: -104, syscall: "read" },+ );+ return err;+}++/**+ * renderCliError writes to stderr and then exits. It reaches stderr two ways —+ * process.stderr.write directly, and console.error via renderStructuredError —+ * so both are captured here. Exit is turned into a throw so asserting on the+ * rendered output does not kill the test runner.+ */+function capture(fn: () => void): { out: string; exited: boolean } {+ let out = "";+ const write = vi+ .spyOn(process.stderr, "write")+ .mockImplementation((chunk: unknown) => {+ out += String(chunk);+ return true;+ });+ const log = vi+ .spyOn(console, "error")+ .mockImplementation((...args: unknown[]) => {+ out += args.map(String).join(" ") + "\n";+ });+ const exit = vi.spyOn(process, "exit").mockImplementation(((): never => {+ throw new Error("__exit__");+ }) as never);++ let exited = false;+ try {+ fn();+ } catch (err) {+ if ((err as Error).message === "__exit__") exited = true;+ else throw err;+ } finally {+ write.mockRestore();+ log.mockRestore();+ exit.mockRestore();+ }+ return { out, exited };+}++afterEach(() => {+ vi.restoreAllMocks();+});++describe("isBackendUnreachable", () => {+ it("detects a transport code nested under cause (Node fetch shape)", () => {+ expect(isBackendUnreachable(fetchFailure("ECONNREFUSED"))).toBe(true);+ expect(isBackendUnreachable(fetchFailure("EHOSTUNREACH"))).toBe(true);+ expect(isBackendUnreachable(fetchFailure("UND_ERR_CONNECT_TIMEOUT"))).toBe(true);+ });++ it("detects a transport code set directly on the error", () => {+ expect(isBackendUnreachable(Object.assign(new Error("nope"), { code: "ECONNREFUSED" }))).toBe(true);+ });++ it("does not claim unreachability for backend-authored errors", () => {+ // The backend answered — it just answered with an error. That must keep+ // rendering the real message rather than "start the backend".+ expect(isBackendUnreachable(new Error('500: {"error":"boom","message":"kaput"}'))).toBe(false);+ expect(isBackendUnreachable(new Error("something else"))).toBe(false);+ });++ it("tolerates null, undefined and non-error values", () => {+ expect(isBackendUnreachable(null)).toBe(false);+ expect(isBackendUnreachable(undefined)).toBe(false);+ expect(isBackendUnreachable("a string")).toBe(false);+ });++ it("does not claim unreachability for a connection dropped mid-flight", () => {+ // A connection that was working and then died is a different problem with a+ // different remedy; "start the backend" is the wrong thing to say about it.+ expect(isBackendUnreachable(midFlightFailure("ECONNRESET"))).toBe(false);+ expect(isBackendUnreachable(midFlightFailure("ETIMEDOUT"))).toBe(false);+ });++ it("claims unreachability when the port accepts but nothing serves", () => {+ // Measured shape of a container that is still booting, or a published port+ // with a dead container behind it: undici accepts, gets a FIN, and reports+ // "other side closed". That user does need `ix docker start` / `ix status`.+ expect(isBackendUnreachable(fetchFailure("UND_ERR_SOCKET"))).toBe(true);+ });+});++describe("renderCliError", () => {+ it("renders backend-down as actionable guidance, never a stack trace", () => {+ const { out, exited } = capture(() =>+ renderCliError(fetchFailure("ECONNREFUSED"), false, "http://localhost:8090"),+ );++ expect(exited).toBe(true);+ expect(out).toContain("Ix backend not reachable at http://localhost:8090");+ expect(out).toContain("ix docker start");+ // The whole point of the boundary: no Node internals, no absolute paths.+ expect(out).not.toContain("node:internal");+ expect(out).not.toContain("at async");+ });++ it("omits the endpoint when it cannot be resolved", () => {+ const { out } = capture(() => renderCliError(fetchFailure("ECONNREFUSED"), false, undefined));+ expect(out).toContain("Ix backend not reachable.");+ });++ it("unwraps a bare `fetch failed` so the transport cause is visible", () => {+ const { out } = capture(() =>+ renderCliError(Object.assign(new TypeError("fetch failed"), { cause: { message: "socket hang up" } })),+ );+ expect(out).toContain("socket hang up");+ });++ it("renders a structured backend error using its message and next step", () => {+ const { out } = capture(() =>+ renderCliError(new Error('404: {"error":"not_found","message":"No such entity","next":"Run ix map"}')),+ );+ expect(out).toContain("No such entity");+ expect(out).toContain("Run ix map");+ });++ it("renders usage errors with their hint", () => {+ const { out } = capture(() => renderCliError(new CliUsageError("Bad flag", "Try --kind class")));+ expect(out).toContain("Bad flag");+ expect(out).toContain("Try --kind class");+ });++ it("shows resolution detail only in debug mode", () => {+ const err = new CliResolutionError("Ambiguous", "Narrow it down", "3 candidates");+ expect(capture(() => renderCliError(err, false)).out).not.toContain("3 candidates");+ expect(capture(() => renderCliError(err, true)).out).toContain("3 candidates");+ });++ it("appends the stack only in debug mode", () => {+ const err = fetchFailure("ECONNREFUSED");+ err.stack = "TypeError: fetch failed\n at node:internal/deps/undici/undici:14976:13";+ expect(capture(() => renderCliError(err, false, "http://x")).out).not.toContain("node:internal");+ expect(capture(() => renderCliError(err, true, "http://x")).out).toContain("node:internal");+ });++ it("does not tell a remote user to start Docker", () => {+ // Pro syncs config.endpoint to a cloud instance; `ix docker start` cannot+ // fix that endpoint and starts a backend the user is not pointed at.+ const { out } = capture(() =>+ renderCliError(fetchFailure("ECONNREFUSED"), false, "https://prod.cloud.ix-infra.com"),+ );+ expect(out).toContain("Ix backend not reachable at https://prod.cloud.ix-infra.com");+ expect(out).not.toContain("ix docker start");+ expect(out).toContain("ix config get endpoint");+ });++ it("keeps the docker remedy for a loopback endpoint", () => {+ const { out } = capture(() =>+ renderCliError(fetchFailure("ECONNREFUSED"), false, "http://127.0.0.1:8090"),+ );+ expect(out).toContain("ix docker start");+ });++ it("shows the cause chain in debug mode when the error carries no stack", () => {+ // The case this module exists for: Node's fetch TypeError loses its frames+ // across the async boundary, so `err.stack` alone renders nothing useful.+ const err = fetchFailure("ECONNREFUSED");+ err.stack = undefined;+ const { out } = capture(() => renderCliError(err, true, "http://localhost:8090"));+ expect(out).toContain("ECONNREFUSED");+ });++ it("does not print arbitrary error properties in debug mode", () => {+ // This is the process-wide boundary. Dumping every own property of whatever+ // was thrown would put credentials into output the user pastes into an issue.+ const err = Object.assign(new Error("boom"), {+ request: { headers: { authorization: "Bearer sk-SECRET-TOKEN" } },+ });+ const { out } = capture(() => renderCliError(err, true));+ expect(out).toContain("boom");+ expect(out).not.toContain("sk-SECRET-TOKEN");+ });++ it("does not throw on null or undefined", () => {+ expect(capture(() => renderCliError(null)).exited).toBe(true);+ expect(capture(() => renderCliError(undefined)).exited).toBe(true);+ });+});++describe("formatFetchError", () => {+ it("appends the nested cause code and message", () => {+ expect(formatFetchError(fetchFailure("ECONNREFUSED"))).toContain("ECONNREFUSED");+ });++ it("passes non-fetch errors through untouched", () => {+ expect(formatFetchError(new Error("plain"))).toBe("plain");+ });+});diff --git a/ix-cli/src/cli/commands/upgrade.ts b/ix-cli/src/cli/commands/upgrade.tsindex 5c30ef3c..5554b3ef 100644--- a/ix-cli/src/cli/commands/upgrade.ts+++ b/ix-cli/src/cli/commands/upgrade.ts@@ -63,7 +63,22 @@ async function fetchLatestRelease(repo: string): Promise<string | null> {function readCache(): VersionCache | null {try {if (!existsSync(VERSION_CACHE)) return null;- return JSON.parse(readFileSync(VERSION_CACHE, "utf-8"));+ const parsed = JSON.parse(readFileSync(VERSION_CACHE, "utf-8"));+ // JSON.parse only proves it is JSON, not that it is *this* shape. A cache+ // file holding `{"latest": 123}` used to reach isNewer() and throw+ // "latest.split is not a function", which surfaced as a successful command+ // exiting 1. Every field that reaches isNewer() has to be checked, not just+ // `latest` — the optional two get there behind a bare truthiness test.+ const optionalString = (v: unknown) => v === undefined || typeof v === "string";+ if (+ typeof parsed?.latest !== "string" ||+ typeof parsed?.checkedAt !== "number" ||+ !optionalString(parsed.compassLatest) ||+ !optionalString(parsed.backendLatest)+ ) {+ return null;+ }+ return parsed as VersionCache;} catch {return null;}@@ -163,6 +178,11 @@ export async function checkForUpdate(): Promise<void> {if (hasCliUpdate || hasCompassUpdate || hasBackendUpdate) {printUpdateNotice(current, latest, !!hasCompassUpdate, !!hasBackendUpdate);}+ }).catch(() => {+ // Best-effort background check: it must never affect the command the user+ // actually ran. Without this catch the floating promise would reach the+ // process-level unhandledRejection handler and abort an otherwise+ // successful command.});}diff --git a/ix-cli/src/cli/errors.ts b/ix-cli/src/cli/errors.tsindex 9889ce16..97b6abf6 100644--- a/ix-cli/src/cli/errors.ts+++ b/ix-cli/src/cli/errors.ts@@ -86,7 +86,11 @@ export function formatFetchError(err: unknown): string {? e.message: String(err);- if (base.toLowerCase().includes("fetch failed") && e.cause) {+ // "terminated" is what undici reports when a connection dies after the+ // response headers — the commonest mid-flight shape, and one that carries no+ // detail at all without this unwrap.+ const lower = base.toLowerCase();+ if ((lower.includes("fetch failed") || lower.includes("terminated")) && e.cause) {const cause = e.cause as { code?: unknown; message?: unknown };const parts: string[] = [];if (typeof cause.code === "string" && cause.code.length > 0) {@@ -103,7 +107,93 @@ export function formatFetchError(err: unknown): string {return base;}-export function renderCliError(err: unknown, debug = false): void {+/**+ * Transport-level codes meaning "we did not get a working backend on the other+ * end", as opposed to the backend answering with an error. Node's fetch+ * surfaces these as `TypeError: fetch failed` with the real error under `cause`.+ *+ * `UND_ERR_SOCKET` ("other side closed") belongs here despite describing an+ * established socket: measured, it is what you get from a port that accepts and+ * then closes without answering — a container that is still booting, a dead+ * container behind a published port, a port-forward to nothing. That user does+ * need "start the backend, then check status".+ *+ * `ECONNRESET` and `ETIMEDOUT` are deliberately absent. Those are a connection+ * that was working and then died, which is a different problem with a different+ * remedy; they fall through to the generic path, which names the cause. The+ * connect-phase half of `ETIMEDOUT` does not need special handling: undici's+ * 10s connect timeout fires first and reports `UND_ERR_CONNECT_TIMEOUT`, which+ * is already listed here.+ */+const UNREACHABLE_CODES = new Set([+ "ECONNREFUSED",+ "ENOTFOUND",+ "EHOSTUNREACH",+ "ENETUNREACH",+ "EAI_AGAIN",+ "UND_ERR_CONNECT_TIMEOUT",+ "UND_ERR_SOCKET",+]);++function isUnreachableCode(e: { code?: unknown } | null | undefined): boolean {+ return typeof e?.code === "string" && UNREACHABLE_CODES.has(e.code);+}++/** True for an endpoint served from this machine, where `ix docker start` applies. */+function isLocalEndpoint(endpoint?: string): boolean {+ if (!endpoint) return true; // unresolved endpoint defaults to the local install+ return /^\w+:\/\/(localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0)(:\d+)?(\/|$)/i.test(endpoint);+}++/**+ * Under IX_DEBUG, print the error *and its cause chain*.+ *+ * `err.stack` alone is empty for the very case this module exists to handle:+ * Node's fetch rejects with a `TypeError: fetch failed` whose frames are lost+ * across the async boundary, so the whole diagnostic — ECONNREFUSED vs+ * ENOTFOUND vs a TLS failure — lives in `err.cause`. Printing only the stack+ * meant `IX_DEBUG=1` emitted one useless line for a backend-down error.+ *+ * Walks the chain by hand rather than handing the error to `util.inspect`.+ * This is the process-wide error boundary, and inspect prints every own+ * property of whatever was thrown; Pro holds a tunnel JWT and a long-lived+ * refresh token, so the day something throws an error carrying its own request+ * we would print credentials into output the user is about to paste into an+ * issue. Only stack, message and code are ever emitted.+ */+function writeDebugDetail(err: unknown): void {+ const lines: string[] = [];+ const seen = new Set<unknown>();+ let cur: unknown = err;++ while (cur !== null && cur !== undefined && !seen.has(cur)) {+ seen.add(cur);+ const e = cur as { stack?: unknown; message?: unknown; code?: unknown; cause?: unknown };+ const code = typeof e.code === "string" ? `${e.code}: ` : "";+ const body =+ typeof e.stack === "string" && e.stack.length > 0+ ? `${code}${e.stack}`+ : `${code}${typeof e.message === "string" ? e.message : String(cur)}`;+ lines.push(lines.length === 0 ? body : ` [cause] ${body}`);+ cur = typeof cur === "object" ? e.cause : undefined;+ }++ process.stderr.write(chalk.dim(`${lines.length > 0 ? lines.join("\n") : String(err)}\n`));+}++/**+ * True when the error is a failure to reach the backend at all. This is by far+ * the most common failure for a fresh install — the CLI is on PATH but the+ * Docker backend was never started — so it gets its own actionable message+ * instead of an undici stack trace.+ */+export function isBackendUnreachable(err: unknown): boolean {+ const e = err as { code?: unknown; cause?: unknown } | null | undefined;+ if (isUnreachableCode(e)) return true;+ return isUnreachableCode(e?.cause as { code?: unknown } | null | undefined);+}++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) {@@ -116,12 +206,35 @@ export function renderCliError(err: unknown, debug = false): void {}const e = err as any;- const msg = e?.message ?? String(err);- process.stderr.write(chalk.red(`Error: ${msg}\n`));- if (debug && e?.stack) {- process.stderr.write(chalk.dim(`${e.stack}\n`));+ 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`).",+ });+ if (debug) writeDebugDetail(err);+ process.exit(1);+ }++ const structured = typeof e?.message === "string" ? parseBackendError(e.message) : null;+ if (structured) {+ renderStructuredError(structured);+ if (debug) writeDebugDetail(err);+ process.exit(1);}+ // 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`));++ if (debug) writeDebugDetail(err);+process.exit(1);}diff --git a/ix-cli/src/cli/main.ts b/ix-cli/src/cli/main.tsindex 4ca63726..582e6ef6 100644--- a/ix-cli/src/cli/main.ts+++ b/ix-cli/src/cli/main.ts@@ -4,6 +4,8 @@ import { registerOssCommands, registerProStubs } from "./register/oss.js";import { tryLoadProCommands } from "./register/pro-loader.js";import { buildHelpText } from "./help-text.js";import { checkForUpdate } from "./commands/upgrade.js";+import { renderCliError } from "./errors.js";+import { getEndpoint } from "./config.js";import { readFileSync } from "fs";import { join, dirname } from "path";@@ -32,6 +34,30 @@ try {cliVersion = pkg.version || "0.0.0";} catch {}+// Set IX_DEBUG=1 to append stack traces to any rendered error.+const debug = process.env.IX_DEBUG === "1";++// 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.+function safeEndpoint(): string | undefined {+ try {+ return getEndpoint();+ } catch {+ return undefined;+ }+}++// Last line of defence. Without these, any rejection escaping a command — most+// commonly the backend not running — reaches Node's default handler and prints+// an undici stack trace that exposes internal paths and tells the user nothing.+process.on("unhandledRejection", (err: unknown) => {+ renderCliError(err, debug, safeEndpoint());+});+process.on("uncaughtException", (err: unknown) => {+ renderCliError(err, debug, safeEndpoint());+});+const program = new Command();program.name("ix")@@ -60,8 +86,19 @@ registerOssCommands(program);// Check for updates (non-blocking, cached 1hr) — skip for upgrade command itselfconst args = process.argv.slice(2);if (args[0] !== "upgrade") {- checkForUpdate();+ // Deliberately not awaited — but it must still be caught here. The catch+ // inside checkForUpdate only guards its inner fetch chain; the function's+ // own promise covers the synchronous cached-read path, and a corrupt+ // ~/.ix/.version-check.json makes that throw. Uncaught, the new+ // unhandledRejection handler then aborts a command that already succeeded.+ checkForUpdate().catch(() => {});}- program.parse();+ // parseAsync (not parse) so rejections from async action handlers surface+ // here instead of floating off as unhandled rejections.+ try {+ await program.parseAsync();+ } catch (err) {+ renderCliError(err, debug, safeEndpoint());+ }})();