linear-sdk-cli 0.1.0

package/src/context.ts

@@ -0,0 +1,117 @@
+/**
+ * Per-invocation context: resolved config, lazily-created client, and the
+ * Output sink. Built once from the root program's global options and threaded
+ * into every command action.
+ */
+
+import type { LinearClient } from "@linear/sdk";
+import { resolveConfig, type ResolvedConfig } from "./config.js";
+import { createClient, setRetryReporter } from "./client.js";
+import { Output } from "./output/format.js";
+import { isDebugEnabled, shouldUseColor } from "./output/color.js";
+
+/**
+ * The globals as the parser actually stores them.
+ *
+ * This interface used to declare `noInput` while commander stored `input:
+ * false` — the field was never written by anything, stayed `undefined` forever,
+ * and the prompt guard built on it never fired. The two agree now because the
+ * flags are registered as plain booleans (`NoFlagOption` in lib/options.ts)
+ * whose keys we choose, rather than as commander negations whose keys we only
+ * assumed. `test/unit/options.test.ts` pins the keys against a real parse, so
+ * the type cannot quietly go back to describing a parser that does not exist.
+ */
+export interface GlobalOptions {
+  json?: boolean;
+  /** `--no-ansi`, or its alias `--no-color`. Present (true) only when passed. */
+  noAnsi?: boolean;
+  /** `--no-input`. Present (true) only when passed. */
+  noInput?: boolean;
+  apiKey?: string;
+  /** A key, or several — `issue list`/`mine`/`search` make `--team` repeatable. */
+  team?: string | string[];
+  workspace?: string;
+  limit?: number;
+  all?: boolean;
+  fields?: string[];
+  yes?: boolean;
+  quiet?: boolean;
+  debug?: boolean;
+}
+
+/** `--team` may arrive repeated (issue queries); single-team consumers take the first. */
+export function firstTeam(team: string | string[] | undefined): string | undefined {
+  return Array.isArray(team) ? team[0] : team;
+}
+
+export class Context {
+  readonly config: ResolvedConfig;
+  readonly output: Output;
+  readonly options: GlobalOptions;
+  readonly isTTY: boolean;
+  private _client?: LinearClient;
+
+  constructor(options: GlobalOptions) {
+    this.options = options;
+    this.config = resolveConfig({
+      // The issue queries accept `--team` several times; everything downstream
+      // of the config (the default team for creates, cycle lookups, …) is
+      // single-valued, so those commands read the full list off their own opts
+      // and the config sees the first key.
+      flags: {
+        apiKey: options.apiKey,
+        team: firstTeam(options.team),
+        workspace: options.workspace,
+      },
+    });
+    const color = shouldUseColor({
+      disabled: options.noAnsi,
+      json: options.json,
+      isTTY: process.stdout.isTTY === true,
+    });
+    // Four independent reasons not to prompt, and any one of them is enough.
+    // The first two are the user saying so; the last two are the situation
+    // saying so. `--json` counts because JSON is what a script or an agent
+    // asks for, and a prompt inside a pipeline is a hang, not a question —
+    // there is no one at the other end to answer it. Non-TTY stdout counts for
+    // the same reason: inquirer draws on stdout, so a redirect would send the
+    // question into the file the caller is collecting.
+    this.isTTY =
+      options.noInput !== true &&
+      options.json !== true &&
+      process.stdin.isTTY === true &&
+      process.stdout.isTTY === true;
+    this.output = new Output({
+      json: options.json === true,
+      color,
+      quiet: options.quiet === true,
+      debug: isDebugEnabled(options.debug),
+      fields: options.fields,
+      isTTY: process.stdout.isTTY === true,
+    });
+    // Rate-limit waits are status, so they go through the same sink as every
+    // other status line: stderr, silenced by --quiet, never on JSON stdout.
+    setRetryReporter((line) => this.output.info(line));
+  }
+
+  /** Lazily construct the Linear client (so `--help` never needs a key). */
+  get client(): LinearClient {
+    if (!this._client) this._client = createClient(this.config);
+    return this._client;
+  }
+
+  /** Default team key from flags/config (used when a command omits --team). */
+  get defaultTeam(): string | undefined {
+    return firstTeam(this.options.team) ?? this.config.team;
+  }
+
+  /**
+   * Resolve the effective page limit. `--all` means exhaust (Infinity), and so
+   * does `--limit 0` — the reference CLI's spelling for "no limit", accepted
+   * here so a transplanted script does not silently get the 50-row default.
+   */
+  get limit(): number {
+    if (this.options.all || this.options.limit === 0) return Infinity;
+    return this.options.limit && this.options.limit > 0 ? this.options.limit : 50;
+  }
+}

package/src/git.ts

@@ -0,0 +1,174 @@
+/**
+ * Git integration: infer the "current issue" from the branch name, build
+ * suggested branch names, and assemble commit trailers / `gh pr create` argv.
+ * Pure parsing/building logic is separated for unit testing.
+ */
+
+import { execFileSync } from "node:child_process";
+import { CliError } from "./lib/errors.js";
+
+/**
+ * Extract a Linear issue identifier (e.g. `TES-123`) from a git branch name.
+ * Linear's suggested branches look like `username/tes-123-title` or
+ * `tes-123-title`; we grab the first `<letters>-<digits>` token and uppercase
+ * the team key.
+ */
+export function branchToIssueId(branch: string | undefined | null): string | undefined {
+  if (!branch) return undefined;
+  // Strip any leading path segment(s) like `feature/` or `user/`.
+  const match = branch.match(/(?:^|[/_-])([a-zA-Z][a-zA-Z0-9]*)-(\d+)(?:$|[/_-])/);
+  if (!match) return undefined;
+  const [, key, num] = match;
+  if (!key || !num) return undefined;
+  return `${key.toUpperCase()}-${num}`;
+}
+
+/** Run a git command, returning trimmed stdout or undefined on any failure. */
+function git(args: string[], cwd?: string): string | undefined {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf8",
+    }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+export function currentBranch(cwd?: string): string | undefined {
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+  return branch && branch !== "HEAD" ? branch : undefined;
+}
+
+/** The issue identifier inferred from the current branch, if any. */
+export function currentIssueId(cwd?: string): string | undefined {
+  return branchToIssueId(currentBranch(cwd));
+}
+
+export function isGitRepo(cwd?: string): boolean {
+  return git(["rev-parse", "--is-inside-work-tree"], cwd) === "true";
+}
+
+/**
+ * The Linear magic-word phrase that links a commit or PR to an issue: `Fixes
+ * <ID>` closes the issue on merge; the `references` option gives `References
+ * <ID>`, which links without closing. Both are on Linear's list of recognized
+ * words (linear.app/docs/github); the word must sit directly before the id.
+ */
+export function buildTrailer(identifier: string, opts: { references?: boolean } = {}): string {
+  return `${opts.references ? "References" : "Fixes"} ${identifier}`;
+}
+
+/**
+ * The two git trailers `issue describe` and `issue pull-request` emit — the
+ * exact lines schpet/linear-cli writes (T `src/utils/jj.ts`), so a transplanted
+ * `git commit -m "$(linear issue describe)"` produces the same commit:
+ *
+ *     Linear-issue: Fixes TES-123
+ *     Linear-issue-url: https://linear.app/…/issue/TES-123/…
+ *
+ * Proper `Key: value` trailers rather than a bare `Fixes TES-123` line, on
+ * purpose: `git interpret-trailers` / `git log --format=%(trailers:key=Linear-issue)`
+ * and jj's `trailers` template can read them back (schpet's jj mode infers the
+ * current issue from exactly this trailer), while Linear still sees the magic
+ * word directly before the id and links — and closes — the issue. The URL line is
+ * for the humans reading the log.
+ */
+export function buildTrailers(
+  identifier: string,
+  url: string,
+  opts: { references?: boolean } = {},
+): string {
+  return `Linear-issue: ${buildTrailer(identifier, opts)}\nLinear-issue-url: ${url}`;
+}
+
+/**
+ * What `issue describe` prints: schpet's subject line (`ID Title`), a blank
+ * line, then the trailers. Piped into `git commit -m` / `jj describe -m` it is
+ * the whole message.
+ */
+export function buildDescription(
+  identifier: string,
+  title: string,
+  url: string,
+  opts: { references?: boolean } = {},
+): string {
+  return `${identifier} ${title}\n\n${buildTrailers(identifier, url, opts)}`;
+}
+
+/**
+ * The title and body `issue pull-request` hands to `gh pr create`: schpet's
+ * `ID Title` (a custom title is prefixed the same way), and the two trailers as
+ * the body — the URL for the humans, the magic word so Linear links (and, on
+ * merge, closes) the issue even when the branch name does not carry the id.
+ */
+export function buildPrContent(
+  issue: { identifier: string; title: string; url: string },
+  customTitle?: string,
+): { title: string; body: string } {
+  return {
+    title: `${issue.identifier} ${customTitle ?? issue.title}`,
+    body: buildTrailers(issue.identifier, issue.url),
+  };
+}
+
+export interface PrArgsInput {
+  title: string;
+  body: string;
+  base?: string;
+  head?: string;
+  draft?: boolean;
+  web?: boolean;
+}
+
+/**
+ * Build the argv passed to `gh pr create`. Title and body are always present;
+ * base/head/draft/web are included only when set. Pure + unit-tested so the
+ * exact flag wiring is verifiable without shelling out to `gh`.
+ */
+export function buildPrArgs(input: PrArgsInput): string[] {
+  const args = ["pr", "create", "--title", input.title, "--body", input.body];
+  if (input.base) args.push("--base", input.base);
+  if (input.head) args.push("--head", input.head);
+  if (input.draft) args.push("--draft");
+  if (input.web) args.push("--web");
+  return args;
+}
+
+export interface CheckoutResult {
+  branch: string;
+  created: boolean;
+}
+
+/** Run the mutating checkout command and retain git's explanation on failure. */
+function gitCheckout(args: string[], cwd?: string): void {
+  try {
+    execFileSync("git", args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8",
+    });
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException & { status?: number; stderr?: Buffer | string };
+    if (e.code === "ENOENT")
+      throw new CliError("Git is required to check out an issue branch.", "runtime");
+    const stderr = e.stderr ? e.stderr.toString().trim() : "";
+    throw new CliError(
+      stderr || `git ${args.join(" ")} exited with code ${e.status ?? 1}.`,
+      "runtime",
+    );
+  }
+}
+
+/** Checkout `branch`, creating it if it does not exist. */
+export function checkoutBranch(branch: string, cwd?: string): CheckoutResult {
+  const exists =
+    git(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], cwd) !== undefined;
+  if (exists) {
+    gitCheckout(["checkout", branch], cwd);
+    return { branch, created: false };
+  }
+  gitCheckout(["checkout", "-b", branch], cwd);
+  return { branch, created: true };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Programmatic entry point. Lets the CLI be embedded/tested without spawning.
+ */
+
+export { createProgram, VERSION } from "./cli.js";
+export { Context } from "./context.js";
+export { resolveConfig, type ResolvedConfig } from "./config.js";
+export { createClient } from "./client.js";
+export { CliError, ExitCode, normalizeError } from "./lib/errors.js";
+export { branchToIssueId, currentIssueId } from "./git.js";

package/src/lib/action.ts

@@ -0,0 +1,26 @@
+/**
+ * Wrap a command handler so it receives a built Context, the command's local
+ * options, and positionals — in that order. Errors propagate to the central
+ * boundary in bin/linear.ts.
+ *
+ * Commander invokes actions as (...positionals, localOpts, command).
+ */
+
+import type { Command } from "commander";
+import { Context, type GlobalOptions } from "../context.js";
+
+export type ActionHandler = (
+  ctx: Context,
+  opts: Record<string, any>,
+  ...positionals: any[]
+) => Promise<void> | void;
+
+export function action(handler: ActionHandler) {
+  return async (...args: any[]): Promise<void> => {
+    const command = args[args.length - 1] as Command;
+    const localOpts = (args[args.length - 2] ?? {}) as Record<string, any>;
+    const positionals = args.slice(0, -2);
+    const ctx = new Context(command.optsWithGlobals() as GlobalOptions);
+    await handler(ctx, localOpts, ...positionals);
+  };
+}

package/src/lib/body.ts

@@ -0,0 +1,172 @@
+/**
+ * Resolve a text body (issue/comment/document content) from, in priority:
+ *   1. an explicit positional/flag argument
+ *   2. --body-file <path>  ('-' reads stdin)
+ *   3. $EDITOR  (only when interactive)
+ *
+ * Returns undefined when no source is available and interaction is not allowed.
+ */
+
+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { CliError, usageError } from "./errors.js";
+
+export interface BodyInputs {
+  arg?: string;
+  file?: string;
+  /** Whether $EDITOR may be invoked (TTY + not --no-input/--json). */
+  interactive: boolean;
+  /**
+   * The user explicitly asked for the editor (`--editor`). Kept separate from
+   * `interactive` so an unavailable editor fails instead of silently producing
+   * an empty body — `--editor --json` used to create issues with no description
+   * at all, since `--json` implies non-interactive.
+   */
+  editorRequested?: boolean;
+  /** Initial content to seed the editor with. */
+  template?: string;
+}
+
+export function resolveBody(inputs: BodyInputs): string | undefined {
+  if (inputs.arg !== undefined) return validateInlineBody(inputs.arg);
+  if (inputs.file !== undefined) return readBodyFile(inputs.file);
+  if (inputs.interactive) return openEditor(inputs.template ?? "");
+  if (inputs.editorRequested) {
+    throw usageError(
+      "--editor needs an interactive terminal, and is unavailable under --json, --no-input, " +
+        "or when input/output is redirected. Pass the text directly or read it from a file.",
+    );
+  }
+  return undefined;
+}
+
+/**
+ * A quoted shell argument does not interpret `\n`. This is an especially easy
+ * mistake for an agent composing Markdown in one command: Linear then stores
+ * and renders the two literal characters, often across an entire issue body.
+ *
+ * Do not silently unescape them. A literal backslash-n can be intentional in
+ * source code, JSON, or a regular expression, and changing it would corrupt
+ * user data. File/stdin input is the unambiguous route for both real newlines
+ * and intentional escape syntax.
+ */
+export function validateInlineBody(body: string): string {
+  if (body.includes("\\n")) {
+    throw usageError(
+      "Inline text contains a literal \\n sequence; shell quotes do not turn it into a line break. " +
+        "Use this command's *-file option with '-' and provide the Markdown on stdin. " +
+        "If the literal \\n is intentional, file input preserves it unchanged.",
+    );
+  }
+  return body;
+}
+
+function readBodyFile(file: string): string {
+  if (file === "-") return readStdinSync();
+  try {
+    return readFileSync(file, "utf8");
+  } catch (err) {
+    throw usageError(`Cannot read body file '${file}': ${(err as Error).message}`);
+  }
+}
+
+export function readStdinSync(): string {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * The editor command, git's way: `$VISUAL`, then `$EDITOR`, then `vi` — and
+ * the value is a *command line*, not a program name. `code --wait`, `subl -w`,
+ * `vim -f`, `emacsclient -t` are how those editors are documented to be set,
+ * so it is split shell-style (quotes and backslashes honoured) into argv, and
+ * the file is appended. Exported for tests.
+ */
+export function editorCommand(env: NodeJS.ProcessEnv = process.env): {
+  raw: string;
+  argv: string[];
+} {
+  const raw = env.VISUAL || env.EDITOR || "vi";
+  return { raw, argv: shellSplit(raw) };
+}
+
+/**
+ * Split one line into words the way a POSIX shell would for a simple command:
+ * whitespace separates, single quotes are literal, double quotes allow `\"`
+ * and `\\`, an unquoted backslash escapes the next character. No expansions —
+ * `$HOME` stays `$HOME` — because an editor setting is not a shell script.
+ */
+export function shellSplit(line: string): string[] {
+  const out: string[] = [];
+  let cur = "";
+  let inWord = false;
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i]!;
+    if (quote === "'") {
+      if (c === "'") quote = null;
+      else cur += c;
+    } else if (quote === '"') {
+      if (c === '"') quote = null;
+      else if (c === "\\" && i + 1 < line.length && '"\\'.includes(line[i + 1]!)) cur += line[++i];
+      else cur += c;
+    } else if (c === "'" || c === '"') {
+      quote = c;
+      inWord = true;
+    } else if (c === "\\" && i + 1 < line.length) {
+      cur += line[++i];
+      inWord = true;
+    } else if (/\s/.test(c)) {
+      if (inWord) out.push(cur);
+      cur = "";
+      inWord = false;
+    } else {
+      cur += c;
+      inWord = true;
+    }
+  }
+  if (quote) throw usageError(`Unbalanced quote in editor setting: ${line}`);
+  if (inWord) out.push(cur);
+  return out;
+}
+
+function openEditor(template: string): string {
+  const { raw, argv } = editorCommand();
+  const [cmd, ...args] = argv;
+  if (!cmd) throw usageError("VISUAL/EDITOR is set but empty; set it to an editor on your PATH.");
+  const dir = mkdtempSync(join(tmpdir(), "linear-"));
+  const file = join(dir, "LINEAR_EDITMSG.md");
+  try {
+    writeFileSync(file, template, "utf8");
+    const r = spawnSync(cmd, [...args, file], { stdio: "inherit" });
+    if (r.error) {
+      const e = r.error as NodeJS.ErrnoException;
+      if (e.code === "ENOENT") {
+        const from = process.env.VISUAL
+          ? `VISUAL='${raw}'`
+          : process.env.EDITOR
+            ? `EDITOR='${raw}'`
+            : "the default, neither VISUAL nor EDITOR being set";
+        throw usageError(
+          `Editor '${cmd}' not found (from ${from}). Set VISUAL or EDITOR to an editor on your PATH.`,
+        );
+      }
+      throw new CliError(`Could not run editor '${raw}': ${e.message}`, "runtime");
+    }
+    if (r.status !== 0) {
+      // git aborts here too: an editor that failed did not save what you meant.
+      throw new CliError(
+        `Editor '${raw}' exited with status ${r.status ?? `signal ${r.signal}`}; nothing was saved.`,
+        "runtime",
+      );
+    }
+    return readFileSync(file, "utf8").trim();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/src/lib/errors.ts

@@ -0,0 +1,195 @@
+/**
+ * Error handling: a single `CliError` type the whole app throws, plus a
+ * normalizer that maps Linear SDK errors into stable codes + exit codes.
+ *
+ * Exit codes (documented in PLAN.md):
+ *   0 ok · 1 runtime/API · 2 usage · 3 not-found/ambiguous · 4 auth · 5 rate-limited
+ */
+
+export const ExitCode = {
+  Ok: 0,
+  Runtime: 1,
+  Usage: 2,
+  NotFound: 3,
+  Auth: 4,
+  RateLimited: 5,
+} as const;
+
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
+
+/** Stable machine-readable error codes surfaced in the JSON error envelope. */
+export type ErrorCode =
+  | "usage"
+  | "auth"
+  | "not_found"
+  | "ambiguous"
+  | "forbidden"
+  | "validation"
+  | "rate_limited"
+  | "network"
+  | "feature_not_accessible"
+  | "api"
+  | "runtime";
+
+const EXIT_BY_CODE: Record<ErrorCode, ExitCodeValue> = {
+  usage: ExitCode.Usage,
+  auth: ExitCode.Auth,
+  not_found: ExitCode.NotFound,
+  ambiguous: ExitCode.NotFound,
+  forbidden: ExitCode.Auth,
+  validation: ExitCode.Usage,
+  rate_limited: ExitCode.RateLimited,
+  network: ExitCode.Runtime,
+  feature_not_accessible: ExitCode.Runtime,
+  api: ExitCode.Runtime,
+  runtime: ExitCode.Runtime,
+};
+
+export class CliError extends Error {
+  readonly code: ErrorCode;
+  readonly exitCode: ExitCodeValue;
+  /** Extra detail surfaced only with --debug (e.g. raw GraphQL errors). */
+  readonly detail?: unknown;
+  /** A separately actionable hint; machine callers never have to parse prose. */
+  readonly suggestion?: string;
+
+  constructor(message: string, code: ErrorCode = "runtime", detail?: unknown, suggestion?: string) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.exitCode = EXIT_BY_CODE[code];
+    this.detail = detail;
+    this.suggestion = suggestion;
+  }
+}
+
+/** Convenience constructors for the common cases. */
+export const usageError = (m: string, suggestion?: string) =>
+  new CliError(m, "usage", undefined, suggestion);
+export const notFound = (m: string, suggestion?: string) =>
+  new CliError(m, "not_found", undefined, suggestion);
+export const ambiguous = (m: string, suggestion?: string) =>
+  new CliError(m, "ambiguous", undefined, suggestion);
+export const authError = (m: string, suggestion?: string) =>
+  new CliError(m, "auth", undefined, suggestion);
+
+/**
+ * Map an unknown thrown value (typically a Linear SDK error) into a CliError
+ * with a stable code. We classify by the SDK error class name + GraphQL error
+ * `extensions.type` so behavior is predictable across SDK versions.
+ */
+export function normalizeError(err: unknown): CliError {
+  if (err instanceof CliError) return err;
+
+  if (err instanceof Error) {
+    const name = err.constructor?.name ?? err.name ?? "";
+    const anyErr = err as Record<string, any>;
+    const gqlErrors: any[] =
+      [anyErr.errors, anyErr.response?.errors, anyErr.raw?.response?.errors].find(
+        (errors) => Array.isArray(errors) && errors.length > 0,
+      ) ?? [];
+    const type: string | undefined =
+      anyErr.type ?? gqlErrors[0]?.extensions?.type ?? gqlErrors[0]?.extensions?.code;
+    const message = pickMessage(err, gqlErrors);
+
+    // A request that never got an HTTP response is a transport failure, however
+    // the SDK labelled it (it says `UnknownLinearError`, type Unknown, for a
+    // refused connection). Classify by the socket error underneath.
+    const transport = transportFailure(anyErr);
+    let code = transport ? "network" : classify(name, type);
+    // Linear surfaces "could not find referenced X" as a validation error, but
+    // semantically it is a not-found — reclassify so `view <bad-id>` exits 3.
+    if (
+      (code === "validation" || code === "api") &&
+      /could ?n[o']t find|not found|does not exist|no such|referenced \w+\.?$/i.test(
+        messageCandidates(err, gqlErrors).join("; "),
+      )
+    ) {
+      code = "not_found";
+    }
+    // `--debug` detail: the GraphQL errors when there are any; otherwise what
+    // the transport said, since that is all there is to show.
+    const detail = gqlErrors.length ? gqlErrors : (transport ?? rawDetail(anyErr));
+    return new CliError(message, code, detail);
+  }
+
+  return new CliError(String(err), "runtime");
+}
+
+/**
+ * Socket / DNS / fetch failure codes as bun and node's fetch spell them (bun:
+ * `ConnectionRefused`, `FailedToOpenSocket`; node/undici: errno names and
+ * `UND_ERR_*`), plus a bare `TypeError: fetch failed`.
+ */
+const TRANSPORT_CODES =
+  /^(ConnectionRefused|ConnectionClosed|FailedToOpenSocket|ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|EHOSTUNREACH|ENETUNREACH|EPIPE|UND_ERR_\w+)$/;
+
+interface TransportDetail {
+  name?: string;
+  code?: string;
+  status?: undefined;
+}
+
+/**
+ * Detect a request that failed before any HTTP response existed. A real
+ * status — even a 5xx — is an answer from the API and is left to `classify`.
+ */
+function transportFailure(err: Record<string, any>): TransportDetail | undefined {
+  if (err.status !== undefined && err.status !== null) return undefined;
+  const raw = err.raw ?? err;
+  if (raw?.response?.status !== undefined) return undefined;
+  const candidates = [raw, raw?.cause, err.cause].filter(Boolean);
+  for (const c of candidates) {
+    const code = typeof c.code === "string" ? c.code : undefined;
+    if (code && TRANSPORT_CODES.test(code)) return { name: c.name, code };
+    if (c instanceof TypeError && /fetch failed|unable to connect|network/i.test(c.message ?? "")) {
+      return { name: c.name, code };
+    }
+  }
+  return undefined;
+}
+
+/** `{name, code, status}` from the SDK's raw error, when any of them is set. */
+function rawDetail(err: Record<string, any>): Record<string, unknown> | undefined {
+  const raw = err.raw;
+  const detail = {
+    name: raw?.name,
+    code: raw?.code,
+    status: err.status ?? raw?.response?.status,
+  };
+  return Object.values(detail).some((v) => v !== undefined) ? detail : undefined;
+}
+
+function classify(name: string, type: string | undefined): ErrorCode {
+  const n = `${name} ${type ?? ""}`.toLowerCase();
+  if (n.includes("authentication")) return "auth";
+  if (n.includes("ratelimit")) return "rate_limited";
+  if (n.includes("forbidden")) return "forbidden";
+  if (n.includes("featurenotaccessible") || n.includes("usagelimit"))
+    return "feature_not_accessible";
+  if (n.includes("invalidinput") || n.includes("validation")) return "validation";
+  if (n.includes("network")) return "network";
+  if (name.includes("LinearError") || name.includes("GraphQL")) return "api";
+  return "runtime";
+}
+
+function pickMessage(err: Error, gqlErrors: any[]): string {
+  const presentable = gqlErrors
+    .map((e) => e?.extensions?.userPresentableMessage)
+    .find((message) => typeof message === "string" && message.trim().length > 0);
+  if (presentable) return presentable;
+
+  const fromGql = gqlErrors
+    .map((e) => e?.message)
+    .filter(Boolean)
+    .join("; ");
+  return fromGql || err.message || "Unknown error";
+}
+
+/** All message forms are retained for classification even when a nicer one is displayed. */
+function messageCandidates(err: Error, gqlErrors: any[]): string[] {
+  return [
+    err.message,
+    ...gqlErrors.flatMap((error) => [error?.message, error?.extensions?.userPresentableMessage]),
+  ].filter((message): message is string => typeof message === "string" && message.length > 0);
+}