linear-sdk-cli 0.1.0

package/src/output/color.ts

@@ -0,0 +1,52 @@
+/**
+ * Resolve terminal colour and debug policy in one place. Both the per-command
+ * Context and the top-level error boundary use these helpers, so a parse-time
+ * failure behaves exactly like an API result.
+ */
+
+export interface ColorPolicy {
+  /** An explicit CLI opt-out (`--no-ansi` / `--no-color`). */
+  disabled?: boolean;
+  /** JSON is a byte-oriented machine format and never carries terminal ANSI. */
+  json?: boolean;
+  /** TTY state of the stream that will receive the text. */
+  isTTY?: boolean;
+  env?: NodeJS.ProcessEnv;
+}
+
+/** Values conventionally used to turn a forcing variable off. */
+function isFalse(value: string): boolean {
+  return value === "0" || value.toLowerCase() === "false";
+}
+
+/**
+ * Whether human output should contain ANSI colour.
+ *
+ * Precedence is deliberately conservative:
+ *
+ *   CLI opt-out / JSON > NO_COLOR > FORCE_COLOR > CLICOLOR_FORCE > TTY
+ *
+ * `FORCE_COLOR=0` is also an explicit opt-out, matching the convention used by
+ * Node tooling. `CLICOLOR_FORCE=0` merely means "do not force". This lets a
+ * caller keep colour while stdout is connected to a pager without ever
+ * putting ANSI into JSON.
+ */
+export function shouldUseColor(policy: ColorPolicy): boolean {
+  if (policy.disabled === true || policy.json === true) return false;
+
+  const env = policy.env ?? process.env;
+  if (env.NO_COLOR !== undefined) return false;
+
+  if (env.FORCE_COLOR !== undefined) {
+    return !isFalse(env.FORCE_COLOR);
+  }
+  if (env.CLICOLOR_FORCE !== undefined && !isFalse(env.CLICOLOR_FORCE)) return true;
+
+  return policy.isTTY === true;
+}
+
+/** `--debug` and LINEAR_DEBUG are equivalent, with the flag always additive. */
+export function isDebugEnabled(explicit: boolean | undefined, env = process.env): boolean {
+  const value = env.LINEAR_DEBUG?.toLowerCase();
+  return explicit === true || value === "1" || value === "true";
+}

package/src/output/format.ts

@@ -0,0 +1,238 @@
+/**
+ * The Output object: the single sink for everything a command prints.
+ *
+ * JSON-mode contract (locked — scripts depend on it):
+ *   - machine JSON is the ONLY thing written to stdout
+ *   - lists → bare array, single resource → bare object, mutations → affected
+ *     object (or {success,id} when there is no body)
+ *   - status/progress/pagination notes → stderr
+ *   - errors → {"error":{"message","code", …optional additive fields}} on stderr + non-zero exit
+ */
+
+import pc from "picocolors";
+import type { CliError } from "../lib/errors.js";
+import {
+  renderTable,
+  renderDetail,
+  selectColumns,
+  selectPairs,
+  projectFields,
+  type Column,
+} from "./table.js";
+import { sanitizeForTerminal } from "./sanitize.js";
+import { renderMarkdown } from "./markdown.js";
+import { pageOutput, shouldUsePager } from "./pager.js";
+import { hasMoreResults } from "../lib/pagination.js";
+
+export interface OutputOptions {
+  json: boolean;
+  color: boolean;
+  quiet: boolean;
+  debug: boolean;
+  /** `--fields`: table columns / detail lines (human), top-level keys (json). */
+  fields?: string[];
+  /** Injectable terminal facts; default to stdout's live state. */
+  isTTY?: boolean;
+  terminalRows?: number;
+  terminalColumns?: number;
+  /** Used only to resolve PAGER when long-form output is eligible. */
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface ListOutputOptions {
+  /** JSON rows may be richer/differently shaped than the human table rows. */
+  jsonRows?: unknown[];
+  /** Context shown instead of the default `(no results)` in human mode. */
+  empty?: string;
+}
+
+export interface MarkdownOutputOptions {
+  /** Leave Markdown syntax intact (terminal controls are still removed). */
+  raw?: boolean;
+  /** Commands with `--no-pager` pass false. Defaults to enabled. */
+  pager?: boolean;
+}
+
+export class Output {
+  private readonly opts: OutputOptions;
+  private readonly colors: ReturnType<typeof pc.createColors>;
+
+  constructor(opts: OutputOptions) {
+    this.opts = opts;
+    // Do not rely on picocolors' module-load-time environment detection:
+    // CLICOLOR_FORCE and per-stream TTY policy are resolved by Context.
+    this.colors = pc.createColors(opts.color);
+  }
+
+  get json(): boolean {
+    return this.opts.json;
+  }
+
+  get color(): boolean {
+    return this.opts.color;
+  }
+
+  /** Emit a primary result: JSON in json-mode, else run the human renderer. */
+  emit(value: unknown, human: () => void): void {
+    if (this.opts.json) {
+      this.writeJson(value);
+    } else {
+      human();
+    }
+  }
+
+  /**
+   * Emit a list as a table (human) or bare array (json). `--fields` narrows
+   * both: the table's columns (or any row key), and the JSON objects' keys.
+   */
+  list<T>(
+    rows: T[],
+    columns: Column<T>[],
+    jsonRowsOrOptions?: unknown[] | ListOutputOptions,
+    legacyOptions?: Pick<ListOutputOptions, "empty">,
+  ): void {
+    const options: ListOutputOptions = Array.isArray(jsonRowsOrOptions)
+      ? { jsonRows: jsonRowsOrOptions, ...legacyOptions }
+      : (jsonRowsOrOptions ?? {});
+    if (hasMoreResults(rows)) {
+      this.info(
+        `Showing ${rows.length} results; more exist. Use --all or increase --limit to see them.`,
+      );
+    }
+    if (this.opts.json) {
+      this.writeJson(projectFields(options.jsonRows ?? rows, this.opts.fields));
+      return;
+    }
+    const cols = selectColumns(columns, this.opts.fields, rows[0]);
+    process.stdout.write(
+      renderTable(rows, cols, { color: this.opts.color, empty: options.empty }) + "\n",
+    );
+  }
+
+  /**
+   * Emit a single record as a detail block (human) or bare object (json).
+   * `--fields` narrows both: the block's labelled lines, and the JSON keys.
+   */
+  detail(jsonValue: unknown, pairs: Array<[string, unknown]>): void {
+    if (this.opts.json) {
+      this.writeJson(projectFields(jsonValue, this.opts.fields));
+      return;
+    }
+    const shown = selectPairs(pairs, this.opts.fields);
+    process.stdout.write(renderDetail(shown, { color: this.opts.color }) + "\n");
+  }
+
+  /**
+   * Stdout line (human mode only); in json mode this is suppressed. Sanitized:
+   * `issue title` prints API data bare, and a title can carry escapes.
+   */
+  line(text = ""): void {
+    if (!this.opts.json) process.stdout.write(sanitizeForTerminal(text) + "\n");
+  }
+
+  /**
+   * Render a long Markdown body for a human, optionally through a pager.
+   *
+   * Non-TTY output keeps the original Markdown so pipes/files receive stable,
+   * reusable text. JSON mode writes nothing — callers normally put this inside
+   * `emit(value, () => output.markdown(...))`, but the guard prevents an
+   * accidental second stdout value. Both human paths remain terminal-sanitized.
+   */
+  markdown(text: string, options: MarkdownOutputOptions = {}): void {
+    if (this.opts.json) return;
+
+    const isTTY = this.opts.isTTY ?? process.stdout.isTTY === true;
+    const columns = this.opts.terminalColumns ?? process.stdout.columns ?? 80;
+    const rows = this.opts.terminalRows ?? process.stdout.rows;
+    const content =
+      isTTY && options.raw !== true
+        ? renderMarkdown(text, { color: this.opts.color, width: columns })
+        : sanitizeForTerminal(text);
+    const output = content.endsWith("\n") ? content : `${content}\n`;
+
+    if (
+      shouldUsePager(output, {
+        enabled: options.pager,
+        json: this.opts.json,
+        isTTY,
+        rows,
+        columns,
+      }) &&
+      pageOutput(output, { env: this.opts.env })
+    ) {
+      return;
+    }
+    process.stdout.write(output);
+  }
+
+  /** Status/progress to stderr. Suppressed by --quiet. */
+  info(text: string): void {
+    if (!this.opts.quiet) process.stderr.write(sanitizeForTerminal(text) + "\n");
+  }
+
+  success(text: string): void {
+    if (!this.opts.quiet)
+      process.stderr.write(this.colors.green("✓ ") + sanitizeForTerminal(text) + "\n");
+  }
+
+  warn(text: string): void {
+    process.stderr.write(this.colors.yellow("! ") + sanitizeForTerminal(text) + "\n");
+  }
+
+  /**
+   * A destructive action the user declined at the confirmation prompt.
+   *
+   * Declining is not a failure, so this is not the error envelope — but it is
+   * not silence either. In JSON mode it is a real result on stdout, so a
+   * pipeline still gets something parseable back instead of nothing; in human
+   * mode it is a stderr note. The caller sets the exit code (see
+   * `EXIT_CANCELLED` in lib/prompt.ts), which is what stops
+   * `linear issue delete X && …` from running the `&&` side.
+   */
+  cancelled(action: string): void {
+    if (this.opts.json) {
+      this.writeJson({ cancelled: true, action });
+      return;
+    }
+    if (!this.opts.quiet) {
+      process.stderr.write(
+        this.colors.yellow("! ") + `Cancelled: ${sanitizeForTerminal(action)}\n`,
+      );
+    }
+  }
+
+  /**
+   * Print a normalized error envelope to stderr.
+   *
+   * In JSON mode `--debug` detail goes *inside* the envelope. It used to be
+   * appended afterwards as a second, plaintext block, which meant the one
+   * combination a caller reaches for when a scripted call misbehaves —
+   * `--json --debug` — was the one that produced unparseable output:
+   * `linear … --json --debug 2>&1 | jq` died on "Invalid numeric literal".
+   */
+  error(err: CliError): void {
+    const showDetail = this.opts.debug && err.detail !== undefined;
+    if (this.opts.json) {
+      // `message` and `code` keep their positions; `detail` is additive, and
+      // absent entirely without --debug.
+      const error: Record<string, unknown> = { message: err.message, code: err.code };
+      if (err.suggestion !== undefined) error.suggestion = err.suggestion;
+      if (showDetail) error.detail = err.detail;
+      process.stderr.write(JSON.stringify({ error }) + "\n");
+      return;
+    }
+    // An error message can quote API data (a name that matched several, …).
+    process.stderr.write(this.colors.red("error: ") + sanitizeForTerminal(err.message) + "\n");
+    if (err.suggestion !== undefined) {
+      process.stderr.write(this.colors.dim("hint: ") + sanitizeForTerminal(err.suggestion) + "\n");
+    }
+    if (showDetail) {
+      const detail = JSON.stringify(err.detail, null, 2) ?? String(err.detail);
+      process.stderr.write(this.colors.dim("detail: ") + sanitizeForTerminal(detail) + "\n");
+    }
+  }
+
+  private writeJson(value: unknown): void {
+    process.stdout.write(JSON.stringify(value, null, this.opts.json ? 2 : 0) + "\n");
+  }
+}

package/src/output/markdown.ts

@@ -0,0 +1,133 @@
+/**
+ * A small, dependency-free Markdown renderer for terminal output.
+ *
+ * This intentionally implements the Markdown constructs that occur in Linear
+ * bodies rather than pretending to be a CommonMark parser. The important
+ * properties for the CLI are deterministic readable text, optional ANSI, and
+ * sanitizing API-controlled bytes *before* adding any of our own escapes.
+ */
+
+import pc from "picocolors";
+import { sanitizeForTerminal } from "./sanitize.js";
+
+export interface MarkdownRenderOptions {
+  color?: boolean;
+  /** Used for horizontal rules. Wrapping itself is left to the terminal. */
+  width?: number;
+}
+
+/** Render the useful subset of Markdown used by issue/document/project bodies. */
+export function renderMarkdown(markdown: string, options: MarkdownRenderOptions = {}): string {
+  const colors = pc.createColors(options.color === true);
+  const width = Math.max(10, options.width ?? 80);
+  // CR and terminal controls disappear here. JSON paths never call this and
+  // therefore retain the exact API bytes (escaped by JSON.stringify).
+  const source = sanitizeForTerminal(markdown);
+  const lines = source.split("\n");
+  const rendered: string[] = [];
+  let fence: "```" | "~~~" | undefined;
+
+  for (const original of lines) {
+    const fenceMatch = original.match(/^\s*(```|~~~)/);
+    if (fenceMatch) {
+      const marker = fenceMatch[1] as "```" | "~~~";
+      if (!fence) fence = marker;
+      else if (fence === marker) fence = undefined;
+      // Fence markers and their language labels are presentation syntax.
+      continue;
+    }
+
+    if (fence) {
+      rendered.push(`    ${colors.cyan(original)}`.trimEnd());
+      continue;
+    }
+
+    const heading = original.match(/^\s{0,3}(#{1,6})\s+(.+?)\s*#*\s*$/);
+    if (heading) {
+      const text = inline(heading[2] ?? "", options.color === true);
+      rendered.push(
+        heading[1]?.length === 1 ? colors.underline(colors.bold(text)) : colors.bold(text),
+      );
+      continue;
+    }
+
+    if (/^\s{0,3}((\*\s*){3,}|(-\s*){3,}|(_\s*){3,})$/.test(original)) {
+      rendered.push(colors.dim("─".repeat(Math.min(width, 72))));
+      continue;
+    }
+
+    const quote = original.match(/^(\s*)>\s?(.*)$/);
+    if (quote) {
+      rendered.push(
+        `${quote[1] ?? ""}${colors.dim("│")} ${colors.dim(inline(quote[2] ?? "", options.color === true))}`,
+      );
+      continue;
+    }
+
+    const task = original.match(/^(\s*)[-+*]\s+\[([ xX])\]\s+(.*)$/);
+    if (task) {
+      rendered.push(
+        `${task[1] ?? ""}${task[2]?.toLowerCase() === "x" ? "☑" : "☐"} ${inline(task[3] ?? "", options.color === true)}`,
+      );
+      continue;
+    }
+
+    const bullet = original.match(/^(\s*)[-+*]\s+(.*)$/);
+    if (bullet) {
+      rendered.push(`${bullet[1] ?? ""}• ${inline(bullet[2] ?? "", options.color === true)}`);
+      continue;
+    }
+
+    const ordered = original.match(/^(\s*)(\d+)[.)]\s+(.*)$/);
+    if (ordered) {
+      rendered.push(
+        `${ordered[1] ?? ""}${ordered[2]}. ${inline(ordered[3] ?? "", options.color === true)}`,
+      );
+      continue;
+    }
+
+    rendered.push(inline(original, options.color === true));
+  }
+
+  // Opening a malformed/unclosed fence must not make content disappear; its
+  // body has already been emitted as code. Trim only trailing blank lines so
+  // Output can own the single final newline consistently.
+  while (rendered.at(-1) === "") rendered.pop();
+  return rendered.join("\n");
+}
+
+/** Inline Markdown, with code spans shielded from emphasis/link processing. */
+function inline(value: string, color: boolean): string {
+  const colors = pc.createColors(color);
+  const pieces = value.split(/(`+[^`]*`+)/g);
+  return pieces
+    .map((piece) => {
+      if (/^`+[^`]*`+$/.test(piece)) {
+        const ticks = piece.match(/^`+/)?.[0].length ?? 1;
+        return colors.cyan(piece.slice(ticks, -ticks));
+      }
+
+      return piece
+        .replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (_all, alt: string, url: string) => {
+          const label = alt.trim() ? `image: ${alt.trim()}` : "image";
+          return `${colors.dim(`[${label}]`)} (${url})`;
+        })
+        .replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_all, label: string, url: string) => {
+          return `${colors.underline(label)} (${url})`;
+        })
+        .replace(/<((?:https?|mailto):[^>]+)>/g, "$1")
+        .replace(/<br\s*\/?>/gi, " ")
+        .replace(/<\/?[A-Za-z][^>]*>/g, "")
+        .replace(/\*\*([^*]+)\*\*/g, (_all, text: string) => colors.bold(text))
+        .replace(/__([^_]+)__/g, (_all, text: string) => colors.bold(text))
+        .replace(/~~([^~]+)~~/g, (_all, text: string) => colors.strikethrough(text))
+        .replace(/(^|[^*])\*([^*\n]+)\*(?!\*)/g, (_all, before: string, text: string) => {
+          return `${before}${colors.italic(text)}`;
+        })
+        .replace(/(^|[^_])_([^_\n]+)_(?!_)/g, (_all, before: string, text: string) => {
+          return `${before}${colors.italic(text)}`;
+        })
+        .replace(/\\([\\`*_[\]{}()#+.!|>~-])/g, "$1");
+    })
+    .join("");
+}

package/src/output/pager.ts

@@ -0,0 +1,131 @@
+/** Conditional, portable pager support for long human output. */
+
+import { spawnSync } from "node:child_process";
+import { displayWidth } from "./sanitize.js";
+
+export interface PagerCommand {
+  command: string;
+  args: string[];
+}
+
+export interface PagerDecision {
+  enabled?: boolean;
+  json?: boolean;
+  isTTY?: boolean;
+  rows?: number;
+  columns?: number;
+}
+
+/** Count terminal rows, including the wrapping a terminal applies to long lines. */
+export function terminalLineCount(content: string, columns = 80): number {
+  const width = Math.max(1, columns);
+  return content.split("\n").reduce((count, line) => {
+    return count + Math.max(1, Math.ceil(displayWidth(line) / width));
+  }, 0);
+}
+
+/** Page only deliberately-enabled, long, interactive human output. */
+export function shouldUsePager(content: string, decision: PagerDecision): boolean {
+  if (decision.enabled === false || decision.json === true || decision.isTTY !== true) return false;
+  const rows = decision.rows && decision.rows > 2 ? decision.rows : 52;
+  return terminalLineCount(content, decision.columns ?? 80) > rows - 2;
+}
+
+/**
+ * Resolve `$PAGER` followed by platform fallbacks. The environment value is a
+ * command line, not a shell program: quotes/backslashes are honoured, while
+ * expansions and redirections are deliberately not executed.
+ */
+export function pagerCommands(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): PagerCommand[] {
+  const commands: PagerCommand[] = [];
+  const configured = env.PAGER?.trim();
+  if (configured) {
+    const argv = splitCommand(configured);
+    if (argv.length) commands.push({ command: argv[0]!, args: argv.slice(1) });
+  }
+
+  if (platform === "win32") {
+    commands.push({ command: "more.com", args: [] });
+  } else {
+    // -R passes through our SGR colour, -X leaves the terminal contents visible.
+    commands.push({ command: "less", args: ["-R", "-X"] });
+    commands.push({ command: "more", args: [] });
+  }
+
+  const seen = new Set<string>();
+  return commands.filter(({ command, args }) => {
+    const key = JSON.stringify([command, args]);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export interface PageOptions {
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  /** Test seam; production uses spawnSync without a shell. */
+  run?: (candidate: PagerCommand, content: string, env: NodeJS.ProcessEnv) => boolean;
+}
+
+/** Try the configured pager and fallbacks. False means the caller should print directly. */
+export function pageOutput(content: string, options: PageOptions = {}): boolean {
+  const env = options.env ?? process.env;
+  const run = options.run ?? runPager;
+  for (const candidate of pagerCommands(env, options.platform)) {
+    if (run(candidate, content, env)) return true;
+  }
+  return false;
+}
+
+function runPager(candidate: PagerCommand, content: string, env: NodeJS.ProcessEnv): boolean {
+  const result = spawnSync(candidate.command, candidate.args, {
+    input: content,
+    stdio: ["pipe", "inherit", "inherit"],
+    env,
+  });
+  return !result.error && result.status === 0;
+}
+
+/** A non-evaluating, shell-like argv splitter for PAGER. */
+function splitCommand(line: string): string[] {
+  const out: string[] = [];
+  let current = "";
+  let inWord = false;
+  let quote: '"' | "'" | undefined;
+
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i]!;
+    if (quote === "'") {
+      if (char === "'") quote = undefined;
+      else current += char;
+    } else if (quote === '"') {
+      if (char === '"') quote = undefined;
+      else if (char === "\\" && i + 1 < line.length && '"\\'.includes(line[i + 1]!)) {
+        current += line[++i];
+      } else current += char;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+      inWord = true;
+    } else if (char === "\\" && i + 1 < line.length) {
+      current += line[++i];
+      inWord = true;
+    } else if (/\s/.test(char)) {
+      if (inWord) out.push(current);
+      current = "";
+      inWord = false;
+    } else {
+      current += char;
+      inWord = true;
+    }
+  }
+
+  // A malformed environment setting should not abort an otherwise successful
+  // CLI command; ignore it and continue to the portable fallbacks.
+  if (quote) return [];
+  if (inWord) out.push(current);
+  return out;
+}

package/src/output/sanitize.ts

@@ -0,0 +1,76 @@
+/**
+ * Terminal hygiene for human output.
+ *
+ * Everything the CLI prints for a human is, at some point, text that came from
+ * Linear — and anyone who can create an issue in a workspace can put terminal
+ * escape sequences in a title. Written raw, those drive every teammate's
+ * terminal: colour and cursor movement are the harmless end; an OSC-8 sequence
+ * makes a fake hyperlink, an OSC-0 rewrites the window title, and a `\r` lets
+ * later text overwrite what a reader thought they had already seen. Verified
+ * live (TES-623): a title created as `\e[31mRED\e[0m \e]8;;https://evil…`
+ * reached `issue list`, `issue view` and `issue title` byte-for-byte.
+ *
+ * `--json` output is untouched — JSON escapes control characters, and a script
+ * is owed the exact bytes. This is for the table, the detail block, the bare
+ * scalar lines, and the status/error lines: whatever a person reads.
+ */
+
+/**
+ * Whole escape sequences first, so `\e[31m` disappears rather than leaving a
+ * literal `[31m` behind:
+ *
+ *   - CSI  `ESC [` params intermediates final   (colour, cursor, erase)
+ *   - OSC  `ESC ]` … BEL | ST                    (hyperlinks, window title)
+ *   - DCS/SOS/PM/APC  `ESC P|X|^|_` … ST
+ *   - any other two/three-byte `ESC` sequence
+ *   - the 8-bit C1 spellings of CSI (0x9B) and OSC (0x9D)
+ *
+ * Spelled as `\uXXXX` escapes so no literal control byte lives in this source.
+ */
+const ESCAPE_SEQUENCES = new RegExp(
+  [
+    "\\u001B\\[[0-?]*[ -/]*[@-~]",
+    "\\u009B[0-?]*[ -/]*[@-~]",
+    "\\u001B\\][^\\u0007\\u001B\\u009C]*(?:\\u0007|\\u001B\\\\|\\u009C)?",
+    "\\u009D[^\\u0007\\u001B\\u009C]*(?:\\u0007|\\u001B\\\\|\\u009C)?",
+    "\\u001B[PX^_][^\\u001B\\u009C]*(?:\\u001B\\\\|\\u009C)?",
+    "\\u001B[ -/]*[0-~]",
+  ].join("|"),
+  "g",
+);
+
+/**
+ * Then whatever control characters remain: C0 except `\t` and `\n` (a
+ * description is multi-line and that is the point of it), DEL, C1, and the
+ * bidi embedding/override characters, which can make `a → b` read as `b → a`.
+ * Same set as `config.ts` uses for TOML errors, minus the two whitespace
+ * characters human output needs.
+ */
+const CONTROL_CHARS = new RegExp(
+  // eslint-disable-next-line no-control-regex
+  "[\\u0000-\\u0008\\u000B-\\u001F\\u007F-\\u009F\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u2069]",
+  "g",
+);
+
+/** Strip anything in `text` that could drive a terminal rather than be read on it. */
+export function sanitizeForTerminal(text: string): string {
+  return text.replace(ESCAPE_SEQUENCES, "").replace(CONTROL_CHARS, "");
+}
+
+// Built via fromCharCode to avoid a control char in a regex literal (no-control-regex).
+const ANSI_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+const stripAnsi = (s: string): string => s.replace(ANSI_RE, "");
+
+/**
+ * The number of terminal columns `s` occupies. Our own SGR colour is
+ * zero-width; a CJK character or an emoji is two. `s.length` counted UTF-16
+ * code units, so a table with a Japanese title, or one emoji, mis-aligned every
+ * column after it. Bun's `stringWidth` knows East Asian width and grapheme
+ * clusters; the fallback (a non-Bun runtime, which the package does not
+ * support) is the old count.
+ */
+export function displayWidth(s: string): number {
+  const bun = (globalThis as { Bun?: { stringWidth?: (s: string) => number } }).Bun;
+  if (bun?.stringWidth) return bun.stringWidth(s);
+  return stripAnsi(s).length;
+}