Skip to content

armgit / Ix

Public Imported from GitHub
0

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

17.9 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import chalk from "chalk";
import { PRE_CONNECTION_CODES, RESET_RECONCILIATION_ERROR } from "../client/transport.js";

import { llmError } from "./llm.js";
import { exitCodeFor } from "./outcome.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 `run-cli.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,
  extra: Array<[string, string]> = [],
): boolean {
  if (requestedFormat !== "llm") return false;
  console.log(llmError(code, message, [...extra, ...(hint ? [["hint", hint] as [string, string]] : [])]));
  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.
 */
export interface StructuredError {
  error: string;
  message: string;
  next?: string;
}

/**
 * Attempt to parse a structured error from a backend HTTP error message.
 * Backend errors arrive as "${status}: ${jsonBody}" from the API client.
 */
export function parseBackendError(errMessage: string): StructuredError | null {
  // Match "NNN: {json}" pattern from api.ts error throwing
  const match = errMessage.match(/^(\d{3}):\s*(.+)$/s);
  if (!match) return null;

  try {
    const body = JSON.parse(match[2]);
    if (body.error && body.message) {
      return {
        error: body.error,
        message: body.message,
        next: body.next ?? undefined,
      };
    }
  } catch {
    // Not valid JSON — fall through
  }
  return null;
}

/**
 * Render a structured error to stderr with clean formatting.
 * No stack traces, no internal jargon.
 */
export function renderStructuredError(err: StructuredError): void {
  console.error("");
  console.error(chalk.red(`  ${err.message}`));
  if (err.next) {
    console.error("");
    console.error(chalk.dim("  Next"));
    console.error(`  ${err.next}`);
  }
  console.error("");
}

export class CliUsageError extends Error {
  constructor(
    message: string,
    public readonly hint?: string,
  ) {
    super(message);
    this.name = "CliUsageError";
  }
}

export class CliResolutionError extends Error {
  constructor(
    message: string,
    public readonly hint?: string,
    public readonly detail?: string,
  ) {
    super(message);
    this.name = "CliResolutionError";
  }
}

/**
 * A graph read was asked for from a directory no registered workspace covers.
 *
 * This used to be answered anyway: the read fell back to whichever workspace
 * carried `default: true` -- an unrelated repository -- or, with no default,
 * ran unscoped across every workspace on the backend, which is how one
 * function came back as four rows from four checkouts of the same repo. Both
 * look like answers. Refusing, and saying how to map the directory, is the
 * only response that cannot be mistaken for one.
 *
 * Its `message` stands alone, because `ix mcp` runs commands in-process and
 * relays a thrown error's message as-is rather than through the renderer below.
 */
export class WorkspaceNotMappedError extends Error {
  readonly code = "workspace_not_mapped";
  constructor(
    public readonly dir: string,
    public readonly hint: string = workspaceNotMappedHint(dir),
  ) {
    super(`workspace_not_mapped: ${dir} is not inside a mapped Ix workspace, so there is no graph to answer from. ${hint}`);
    this.name = "WorkspaceNotMappedError";
  }
  /** The message without the code prefix or the hint, for renderers that carry both separately. */
  get summary(): string {
    return `${this.dir} is not inside a mapped Ix workspace, so there is no graph to answer from.`;
  }
}

/**
 * How to get a graph for `dir`. `ix map` with no argument maps the enclosing
 * git repository (see `resolveMapRoot`), so that is named when there is one;
 * outside a repository a bare `ix map` would fall back to the configured
 * default workspace, so the path is spelled out instead.
 */
export function workspaceNotMappedHint(dir: string, gitRoot?: string): string {
  const map = gitRoot
    ? `Run \`ix map\` here to map ${gitRoot}`
    : `Run \`ix map ${dir}\` to map this directory`;
  return `${map}, or run the command from inside a workspace that is already mapped (\`ix config show\` lists them).`;
}

/**
 * Format an error for display, unwrapping fetch `TypeError: fetch failed`
 * to expose the underlying transport cause (e.g. ECONNRESET, UND_ERR_SOCKET).
 *
 * Node's built-in fetch (undici) throws `TypeError('fetch failed')` on any
 * transport-level failure and stashes the real error in `err.cause`. Without
 * this unwrap, users see a bare "fetch failed" with no actionable detail —
 * see the Node 18 EOL / undici 5.x transport-drop bug report.
 */
export function formatFetchError(err: unknown): string {
  if (err === null || err === undefined) return String(err);
  const e = err as { message?: unknown; cause?: unknown };
  const base = typeof e.message === "string" && e.message.length > 0
    ? e.message
    : String(err);

  // "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) {
      parts.push(cause.code);
    }
    if (typeof cause.message === "string" && cause.message.length > 0) {
      parts.push(cause.message);
    } else if (parts.length === 0) {
      parts.push(String(e.cause));
    }
    return `${base} (${parts.join(": ")})`;
  }

  return base;
}

/**
 * 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.
 */
// The pre-connection codes are shared with the HTTP client, which needs the
// same "nothing was transmitted" judgement to decide whether a failed reset
// could have deleted anything. One definition, not two: a second hand-written
// copy is how the two drift apart. `UND_ERR_SOCKET` is added only here — see
// above for why it counts as unreachable for rendering but not for reset.
const UNREACHABLE_CODES = new Set([...PRE_CONNECTION_CODES, "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 { name?: unknown; code?: unknown; cause?: unknown } | null | undefined;
  // An error that carries its own instruction must not be re-explained by its
  // cause. Reset attaches the transport failure for IX_DEBUG, which would
  // otherwise render "start the backend, then check status" on top of a
  // "do not repeat this reset" warning — advising the retry it exists to stop.
  if (e?.name === RESET_RECONCILIATION_ERROR) return false;
  if (isUnreachableCode(e)) return true;
  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`).",
  };
}

/**
 * config.yaml does not parse. Every command reads it, so every command stops
 * here, naming the file rather than quietly running on defaults.
 */
export function configParseError(path: string, detail: string): StructuredError {
  return {
    error: "config_parse_error",
    message: `${path} is not valid YAML, so Ix will not run on a guess: ${detail}`,
    next: `Fix the file, or move it aside to start from defaults (your workspace registrations are in it): mv ${path} ${path}.broken`,
  };
}

/**
 * config.yaml could not be locked for a write. Nothing was written: Ix never
 * writes the file unlocked, because that is how parallel registrations lost
 * each other's workspaces.
 */
export function configLockError(detail: string): StructuredError {
  return {
    error: "config_lock_timeout",
    message: `Ix could not lock its config to write it: ${detail}`,
    next: "Wait for the other ix command to finish and run this one again.",
  };
}

/**
 * The backend answered 401 `local_token_required`: it was started with
 * IX_LOCAL_TOKEN and this CLI sent no token, or a different one.
 */
export function localTokenRequiredError(endpoint?: string): StructuredError {
  return {
    error: "local_token_required",
    message: `The Ix backend${endpoint ? ` at ${endpoint}` : ""} requires a token this CLI did not send or that it refused.`,
    next: isLocalEndpoint(endpoint)
      ? "Run `ix docker start --local-token` to give the backend this CLI's stored token, or set IX_TOKEN to the backend's token."
      : "This CLI sends its token (IX_TOKEN or the stored one) only to a backend on this machine. " +
        "Reach that backend through a local port forward (for example `ssh -L 8090:localhost:8090 <host>`) " +
        "and point IX_ENDPOINT at http://localhost:8090.",
  };
}

export function renderCliError(err: unknown, debug = false, endpoint?: string): void {
  if (err instanceof CliUsageError || err instanceof CliResolutionError) {
    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`));
    }
    process.exit(1);
  }

  if (err instanceof WorkspaceNotMappedError) {
    if (requestedFormat === "json") {
      console.log(JSON.stringify({ error: err.code, message: err.summary, dir: err.dir, next: err.hint }));
    } else if (!emitLlmError(err.code, err.summary, err.hint, [["dir", err.dir]])) {
      renderStructuredError({ error: err.code, message: err.summary, next: err.hint });
    }
    // Its own code, so an agent knows to map rather than retry (outcome.ts).
    process.exit(exitCodeFor("not_mapped"));
  }

  const e = err as any;

  if (isBackendUnreachable(err)) {
    const unreachable = backendUnreachableError(endpoint);
    if (!emitLlmError(unreachable.error, unreachable.message, unreachable.next)) {
      renderStructuredError(unreachable);
    }
    if (debug) writeDebugDetail(err);
    process.exit(1);
  }

  if (e?.name === "ConfigParseError") {
    const broken = configParseError(e.path, e.detail);
    if (!emitLlmError(broken.error, broken.message, broken.next)) renderStructuredError(broken);
    if (debug) writeDebugDetail(err);
    process.exit(1);
  }

  if (e?.name === "ConfigLockError") {
    const locked = configLockError(e.detail);
    if (!emitLlmError(locked.error, locked.message, locked.next)) renderStructuredError(locked);
    if (debug) writeDebugDetail(err);
    process.exit(1);
  }

  if (e?.name === "LocalTokenRequiredError") {
    const refused = localTokenRequiredError(endpoint);
    if (!emitLlmError(refused.error, refused.message, refused.next)) {
      renderStructuredError(refused);
    }
    if (debug) writeDebugDetail(err);
    process.exit(1);
  }

  const structured = typeof e?.message === "string" ? parseBackendError(e.message) : null;
  if (structured) {
    if (!emitLlmError(structured.error, structured.message, structured.next)) {
      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);
  // `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);

  process.exit(1);
}