@baseworks/cli 0.2.0

package/src/args.ts

@@ -0,0 +1,77 @@
+/**
+ * Lightweight arg/flag parser for Node CLI binaries.
+ *
+ * Supports:
+ *   --flag          → { flag: true }
+ *   --flag value    → { flag: 'value' }
+ *   --flag=value    → { flag: 'value' }
+ *   positional args → args[]
+ *
+ * Usage:
+ *   const { args, flags } = parseFlags(process.argv.slice(2));
+ *   if (flags.json) { ... }
+ *   const [ws, proj] = args;
+ */
+
+export interface ParsedArgs {
+  /** Positional (non-flag) arguments in order. */
+  args: string[];
+  /** Parsed flags. Values are string if the flag had a value, true if bare. */
+  flags: Record<string, string | boolean>;
+}
+
+export function parseFlags(argv: string[]): ParsedArgs {
+  const args:  string[]                    = [];
+  const flags: Record<string, string | boolean> = {};
+
+  let i = 0;
+  while (i < argv.length) {
+    const token = argv[i]!;
+
+    if (token.startsWith('--')) {
+      const eqIdx = token.indexOf('=');
+
+      if (eqIdx !== -1) {
+        // --flag=value
+        const key = token.slice(2, eqIdx);
+        const val = token.slice(eqIdx + 1);
+        flags[key] = val;
+      } else {
+        const key  = token.slice(2);
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+          // --flag value
+          flags[key] = next;
+          i++;
+        } else {
+          // bare --flag
+          flags[key] = true;
+        }
+      }
+    } else if (token.startsWith('-') && token.length === 2) {
+      // Short flag: -j  → json shorthand
+      flags[token.slice(1)] = true;
+    } else {
+      args.push(token);
+    }
+
+    i++;
+  }
+
+  return { args, flags };
+}
+
+/** Returns true if --json or -j flag is present in process.argv. */
+export function isJsonMode(argv = process.argv): boolean {
+  return argv.includes('--json') || argv.includes('-j');
+}
+
+/**
+ * Extract a named flag value from argv.
+ *   getFlag(process.argv, '--public-key')  → string | undefined
+ */
+export function getFlag(argv: string[], flag: string): string | undefined {
+  const i = argv.indexOf(flag);
+  if (i === -1) return undefined;
+  return argv[i + 1];
+}

package/src/client.ts

@@ -0,0 +1,80 @@
+/**
+ * Generic HTTP client factory for Node CLI binaries.
+ *
+ * Usage:
+ *   const { get, post, patch, del } = createApiClient(
+ *     () => cfg.token ?? process.env.MY_TOKEN,
+ *     () => cfg.apiBase ?? 'https://api.example.com',
+ *   );
+ */
+
+export interface ApiClient {
+  api<T>(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+  get<T>(path: string, headers?: Record<string, string>): Promise<T>;
+  post<T>(path: string, body: unknown, headers?: Record<string, string>): Promise<T>;
+  patch<T>(path: string, body: unknown, headers?: Record<string, string>): Promise<T>;
+  del<T>(path: string, headers?: Record<string, string>): Promise<T>;
+}
+
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly code:   string,
+    message: string,
+  ) { super(message); }
+}
+
+export function createApiClient(
+  getToken:        () => string | undefined,
+  getApiBase:      () => string,
+  getExtraHeaders?: () => Record<string, string>,
+): ApiClient {
+  async function api<T>(
+    method:   string,
+    path:     string,
+    body?:    unknown,
+    extra:    Record<string, string> = {},
+  ): Promise<T> {
+    const token = getToken();
+    const base  = getApiBase().replace(/\/$/, '');
+
+    const headers: Record<string, string> = {
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+      ...(getExtraHeaders ? getExtraHeaders() : {}),
+      ...extra,  // per-call headers override defaults
+    };
+
+    const res = await fetch(`${base}${path}`, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+
+    if (res.status === 204) return null as T;
+
+    const text = await res.text();
+    let data: unknown;
+    try { data = JSON.parse(text); } catch {
+      if (!res.ok) throw new ApiError(res.status, 'parse_error', `${res.status}: ${text}`);
+      return text as T;
+    }
+
+    if (!res.ok) {
+      const err = data as { error?: { code?: string; message?: string } };
+      const code = err?.error?.code ?? 'unknown';
+      const msg  = err?.error?.message ?? res.statusText;
+      throw new ApiError(res.status, code, `${res.status} ${code}: ${msg}`);
+    }
+
+    return data as T;
+  }
+
+  return {
+    api,
+    get:   <T>(path: string, h?: Record<string, string>) => api<T>('GET',    path, undefined, h),
+    post:  <T>(path: string, body: unknown, h?: Record<string, string>) => api<T>('POST',   path, body, h),
+    patch: <T>(path: string, body: unknown, h?: Record<string, string>) => api<T>('PATCH',  path, body, h),
+    del:   <T>(path: string, h?: Record<string, string>) => api<T>('DELETE', path, undefined, h),
+  };
+}

package/src/config-loader.ts

@@ -0,0 +1,68 @@
+/**
+ * Typed helpers for reading standard fields from a BaseConfig.
+ *
+ * Env var names are passed as parameters — this module has no knowledge of
+ * project-specific env vars (DTAB_TOKEN, ORBSEAL_TOKEN, etc.).
+ *
+ * Usage:
+ *   const cfg = ctx.loadConfig();
+ *   const token   = resolveToken(cfg,   { env: 'DTAB_TOKEN' });
+ *   const apiBase = resolveApiBase(cfg, { env: 'DTAB_API_URL', default: 'https://api.driptab.app' });
+ */
+
+import type { BaseConfig } from './context.js';
+
+// ─── Options ─────────────────────────────────────────────────────────────────
+
+export interface ResolveOptions {
+  /** Name of the environment variable to fall back to (e.g. 'DTAB_TOKEN'). */
+  env?: string;
+}
+
+export interface ResolveBaseOptions extends ResolveOptions {
+  /** Default value if neither config nor env has a value. */
+  default?: string;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Read `token` from config, falling back to the named env var.
+ * Returns undefined if neither is set.
+ */
+export function resolveToken(
+  cfg: BaseConfig,
+  opts: ResolveOptions = {},
+): string | undefined {
+  return (cfg.token as string | undefined)
+    ?? (opts.env ? process.env[opts.env] : undefined);
+}
+
+/**
+ * Read `apiBase` from config, falling back to the named env var,
+ * then to opts.default. Strips trailing slash.
+ */
+export function resolveApiBase(
+  cfg: BaseConfig,
+  opts: ResolveBaseOptions = {},
+): string {
+  const raw = (cfg.apiBase as string | undefined)
+    ?? (opts.env ? process.env[opts.env] : undefined)
+    ?? opts.default
+    ?? '';
+  return raw.replace(/\/$/, '');
+}
+
+/**
+ * Read an arbitrary string field from config by key,
+ * falling back to the named env var.
+ */
+export function resolveField(
+  cfg: BaseConfig,
+  key: string,
+  opts: ResolveOptions & { default?: string } = {},
+): string | undefined {
+  return (cfg[key] as string | undefined)
+    ?? (opts.env ? process.env[opts.env] : undefined)
+    ?? opts.default;
+}

package/src/context.ts

@@ -0,0 +1,124 @@
+/**
+ * Generic CLI context manager.
+ *
+ * Read resolution order (first found wins):
+ *   1. {cwd}/.{appName}/config.json   — project-local
+ *   2. {home}/.{appName}/config.json  — global fallback
+ *
+ * Write always targets {cwd}/.{appName}/config.json — so `dtab login`
+ * creates a project-local config wherever you run the command.
+ *
+ * Usage:
+ *   const ctx = createContextManager<DriptabContext>('dtab');
+ *   ctx.setContext({ org: 'acme', project: 'billing' });
+ *   const { org } = ctx.getContext() ?? {};
+ *   console.log(ctx.configPath); // shows which file will be written
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join }    from 'path';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface BaseConfig {
+  token?:   string;
+  apiBase?: string;
+  [key: string]: unknown;
+}
+
+export interface ContextManager<TContext extends Record<string, string | undefined>> {
+  /** Read the full config file (local first, then global). */
+  loadConfig(): BaseConfig & { context?: TContext };
+
+  /** Write the full config file to the active path (local if present, else global). */
+  saveConfig(cfg: BaseConfig & { context?: TContext }): void;
+
+  /** Return the stored context, or undefined if none set. */
+  getContext(): TContext | undefined;
+
+  /** Merge partial context into the stored context and persist. */
+  setContext(parts: Partial<TContext>): void;
+
+  /** Remove the stored context (keeps token/apiBase). */
+  clearContext(): void;
+
+  /**
+   * Active config file path — whichever was found (local or global).
+   * Recalculated on each access so it reflects the current working directory.
+   */
+  readonly configPath: string;
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+export function createContextManager<TContext extends Record<string, string | undefined>>(
+  appName: string,
+): ContextManager<TContext> {
+  const globalDir  = join(homedir(), `.${appName}`);
+  const globalPath = join(globalDir, 'config.json');
+
+  /**
+   * Resolve the active config path.
+   *
+   * Local ({cwd}/.{appName}/config.json) wins when:
+   *   - The config.json itself exists, OR
+   *   - The .{appName}/ directory exists (project is initialised but not yet logged in).
+   *
+   * Otherwise falls back to the global (~/.{appName}/config.json).
+   */
+  function resolveActivePath(): { cfgPath: string; cfgDir: string; isLocal: boolean } {
+    const localDir  = join(process.cwd(), `.${appName}`);
+    const localPath = join(localDir, 'config.json');
+    const isLocal   = existsSync(localPath) || existsSync(localDir);
+    return isLocal
+      ? { cfgPath: localPath, cfgDir: localDir, isLocal: true }
+      : { cfgPath: globalPath, cfgDir: globalDir, isLocal: false };
+  }
+
+  /** Read path — local dir or file present → local, else global. */
+  function resolveReadPath(): string {
+    return resolveActivePath().cfgPath;
+  }
+
+  /** Write path — same logic as read so reads and writes are always in sync. */
+  function resolveWritePath(): { cfgPath: string; cfgDir: string } {
+    const { cfgPath, cfgDir } = resolveActivePath();
+    return { cfgPath, cfgDir };
+  }
+
+  function loadConfig(): BaseConfig & { context?: TContext } {
+    const cfgPath = resolveReadPath();
+    if (!existsSync(cfgPath)) return {};
+    try { return JSON.parse(readFileSync(cfgPath, 'utf8')) as BaseConfig & { context?: TContext }; }
+    catch { return {}; }
+  }
+
+  function saveConfig(cfg: BaseConfig & { context?: TContext }): void {
+    const { cfgPath, cfgDir } = resolveWritePath();
+    mkdirSync(cfgDir, { recursive: true });
+    writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+  }
+
+  return {
+    get configPath() { return resolveWritePath().cfgPath; },
+    loadConfig,
+    saveConfig,
+
+    getContext(): TContext | undefined {
+      return loadConfig().context;
+    },
+
+    setContext(parts: Partial<TContext>): void {
+      const cfg = loadConfig();
+      cfg.context = { ...(cfg.context ?? {}), ...parts } as TContext;
+      saveConfig(cfg);
+    },
+
+    clearContext(): void {
+      const cfg = loadConfig();
+      delete cfg.context;
+      saveConfig(cfg);
+    },
+  };
+}

package/src/display.ts

@@ -0,0 +1,287 @@
+/**
+ * Terminal display primitives. Node.js only — TTY-aware ANSI colours.
+ */
+
+import { createInterface } from 'readline';
+
+// ─── Colors ───────────────────────────────────────────────────────────────────
+
+const isTTY = typeof process !== 'undefined' && process.stdout?.isTTY;
+
+export const clr = {
+  reset:  isTTY ? '\x1b[0m'  : '',
+  bold:   isTTY ? '\x1b[1m'  : '',
+  dim:    isTTY ? '\x1b[2m'  : '',
+  green:  isTTY ? '\x1b[32m' : '',
+  yellow: isTTY ? '\x1b[33m' : '',
+  cyan:   isTTY ? '\x1b[36m' : '',
+  red:    isTTY ? '\x1b[31m' : '',
+};
+
+// ─── Display helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Truncate a UUID or long ID to first `n` chars + `…`.
+ * Short IDs (no dash at pos 8) are returned as-is.
+ */
+export function truncateId(id: string, n = 8): string {
+  if (!id || id.length <= n + 1) return id;
+  const isUuid = /^[0-9a-f]{8}-/i.test(id);
+  return isUuid ? id.slice(0, n) + '…' : id;
+}
+
+/** Colorize a status string for terminal display. */
+export function statusColor(status: string): string {
+  const s = status.toLowerCase();
+  if (['active', 'succeeded', 'paid', 'completed'].includes(s))
+    return `${clr.green}${status}${clr.reset}`;
+  if (['canceled', 'cancelled', 'failed', 'expired', 'revoked'].includes(s))
+    return `${clr.dim}${status}${clr.reset}`;
+  if (['trialing', 'past_due', 'pending', 'draft'].includes(s))
+    return `${clr.yellow}${status}${clr.reset}`;
+  return status;
+}
+
+/** Print a dim summary line below a table. */
+export function summary(text: string): void {
+  console.log(`  ${clr.dim}${text}${clr.reset}`);
+}
+
+// ─── Table ────────────────────────────────────────────────────────────────────
+
+export type OutputFormat = 'table' | 'wide' | 'json' | 'yaml' | 'code';
+
+export interface ColDef<T> {
+  key:    keyof T;
+  label:  string;
+  fmt?:   (value: T[keyof T], row: T) => string;
+  /** If true, column is only shown in -o wide mode. */
+  wide?: boolean;
+  /** @deprecated use wide instead */
+  detail?: boolean;
+}
+
+function visibleLength(str: string): number {
+  return str.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+function padEnd(str: string, width: number): string {
+  return str + ' '.repeat(Math.max(0, width - visibleLength(str)));
+}
+
+export interface TableOpts {
+  /**
+   * Message shown when rows is empty. Use a hint to guide the user.
+   * Default: "(none)"
+   */
+  emptyHint?: string;
+}
+
+export function table<T extends Record<string, unknown>>(
+  rows: T[],
+  cols: ColDef<T>[],
+  opts: TableOpts & { wide?: boolean } = {},
+): void {
+  const isWide = opts.wide
+    ?? (process.argv.includes('--detail') || process.argv.includes('-d')
+        || process.argv.includes('-o') && process.argv[process.argv.indexOf('-o') + 1] === 'wide'
+        || process.argv.includes('--output') && process.argv[process.argv.indexOf('--output') + 1] === 'wide');
+
+  const visibleCols = cols.filter(c => !c.wide && !c.detail || isWide);
+
+  if (!rows.length) {
+    const msg = opts.emptyHint ?? '(none)';
+    console.log(`  ${clr.dim}${msg}${clr.reset}`);
+    return;
+  }
+
+  const widths = visibleCols.map((col, i) => {
+    const labelLen = col.label.length;
+    const maxVal   = Math.max(...rows.map(r => visibleLength(String(col.fmt ? col.fmt(r[col.key], r) : (r[col.key] ?? '—')))));
+    return Math.max(labelLen, maxVal, i);
+  });
+
+  console.log('');
+  const header = visibleCols.map((col, i) =>
+    padEnd(`${clr.bold}${clr.dim}${col.label}${clr.reset}`, widths[i] ?? col.label.length),
+  ).join('  ');
+  console.log('  ' + header);
+  console.log('  ' + widths.map(w => '─'.repeat(w)).join('  '));
+
+  for (const row of rows) {
+    const line = visibleCols.map((col, i) => {
+      const val = col.fmt ? col.fmt(row[col.key], row) : (row[col.key] ?? '—');
+      return padEnd(String(val), widths[i] ?? 0);
+    }).join('  ');
+    console.log('  ' + line);
+  }
+  console.log('');
+}
+
+// ─── Key-value ────────────────────────────────────────────────────────────────
+
+export function kv(pairs: [string, string][]): void {
+  const w = Math.max(...pairs.map(([k]) => k.length));
+  for (const [k, v] of pairs) {
+    console.log(`  ${clr.dim}${k.padEnd(w)}${clr.reset}  ${v}`);
+  }
+}
+
+// ─── Status messages ──────────────────────────────────────────────────────────
+
+export function success(msg: string): void {
+  console.log(`${clr.green}✓${clr.reset} ${msg}`);
+}
+
+export function warn(msg: string): void {
+  console.warn(`${clr.yellow}⚠${clr.reset}  ${msg}`);
+}
+
+export function fatal(msg: string): never {
+  console.error(`${clr.red}error:${clr.reset} ${msg}`);
+  process.exit(1);
+  throw new Error(msg); // unreachable — satisfies TS never
+}
+
+// ─── Prompt ───────────────────────────────────────────────────────────────────
+
+export function prompt(question: string): Promise<string> {
+  return new Promise(resolve => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (ans: string) => { rl.close(); resolve(ans.trim()); });
+  });
+}
+
+// ─── Subcommand help ─────────────────────────────────────────────────────────
+
+/**
+ * Lookup and print subcommand help, return true if help was printed.
+ * Use at the top of each command fn:
+ *
+ *   if (helpFor('account tokens', deps.args, deps.flags, HELP)) return;
+ *
+ * helpMap keys are subcommand paths WITHOUT the top-level command name,
+ * e.g. { 'tokens create': '...', 'tokens list': '...' }
+ */
+export function helpFor(
+  cmdName:  string,
+  args:     string[],
+  flags:    Record<string, string | boolean>,
+  helpMap:  Record<string, string>,
+): boolean {
+  if (!flags['help'] && !flags['h']) return false;
+  // Build lookup key from positional args (sub sub-sub …)
+  const key = args.join(' ').trim();
+  const text = (key && helpMap[key]) ?? helpMap[''] ?? null;
+  if (text) {
+    console.log(text);
+  } else {
+    // Print all known subcommands for this command
+    const lines = Object.entries(helpMap)
+      .filter(([k]) => k !== '')
+      .map(([k, v]) => `  ${cmdName} ${k.padEnd(28)}${v.split('\n')[0]}`);
+    console.log(`\n${clr.bold}${cmdName}${clr.reset}\n\n${lines.join('\n')}\n`);
+  }
+  return true;
+}
+
+// ─── JSON / text dual-mode output ────────────────────────────────────────────
+
+/**
+ * @deprecated Use printOutput instead.
+ * Kept for backward compatibility with legacy CliPlugin commands.
+ */
+export function printOrJson<T>(data: T, textFn: () => void, argv = process.argv): void {
+  if (argv.includes('--json') || argv.includes('-j')) {
+    console.log(JSON.stringify(data, null, 2));
+  } else {
+    textFn();
+  }
+}
+
+/**
+ * Universal output formatter for Commander-based commands.
+ *
+ * @param data      Raw data to output (array or object)
+ * @param format    Output format from -o/--output option
+ * @param renderFn  Called for table/wide; receives wide=true for -o wide
+ * @param codeKey   Key (or fn) used for -o code output. Falls back to short_id → id.
+ *
+ * Usage:
+ *   printOutput(plans, opts.output, (wide) => table(plans, cols, { wide }), 'code');
+ */
+export function printOutput<T extends Record<string, unknown>>(
+  data: T | T[],
+  format: string | undefined,
+  renderFn: (wide: boolean) => void,
+  codeKey?: string | ((item: T) => string),
+): void {
+  const fmt = (format ?? 'table') as OutputFormat;
+
+  switch (fmt) {
+    case 'json':
+      console.log(JSON.stringify(data, null, 2));
+      break;
+
+    case 'yaml': {
+      const toYaml = (v: unknown, indent = 0): string => {
+        const pad = ' '.repeat(indent);
+        if (v === null || v === undefined) return 'null';
+        if (typeof v === 'string')  return /[:\n#{}[\],&*?|<>=!%@`]/.test(v) ? `"${v.replace(/"/g, '\\"')}"` : v;
+        if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+        if (Array.isArray(v)) {
+          if (v.length === 0) return '[]';
+          return v.map(item => `${pad}- ${toYaml(item, indent + 2).trimStart()}`).join('\n');
+        }
+        if (typeof v === 'object') {
+          return Object.entries(v as Record<string, unknown>)
+            .map(([k, val]) => {
+              const rendered = toYaml(val, indent + 2);
+              return typeof val === 'object' && val !== null && !Array.isArray(val)
+                ? `${pad}${k}:\n${rendered}`
+                : `${pad}${k}: ${rendered}`;
+            }).join('\n');
+        }
+        return String(v);
+      };
+      console.log(toYaml(data));
+      break;
+    }
+
+    case 'code': {
+      const items = Array.isArray(data) ? data : [data];
+      for (const item of items) {
+        let code: string | undefined;
+        if (typeof codeKey === 'function') {
+          code = codeKey(item);
+        } else if (codeKey && item[codeKey] != null) {
+          code = String(item[codeKey]);
+        } else {
+          // fallback: slug → code → short_id → id
+          code = String(item['slug'] ?? item['code'] ?? item['short_id'] ?? item['id'] ?? '');
+        }
+        if (code) console.log(code);
+      }
+      break;
+    }
+
+    case 'wide':
+      renderFn(true);
+      break;
+
+    case 'table':
+    default:
+      renderFn(false);
+      break;
+  }
+}
+
+/**
+ * Returns the Commander output option definition string.
+ * Use with .addOption() or .option():
+ *
+ *   cmd.option(...outputOption())
+ */
+export function outputOption(): [string, string, string] {
+  return ['-o, --output <format>', 'Output format: table|wide|json|yaml|code', 'table'];
+}

package/src/fmt.ts

@@ -0,0 +1,59 @@
+/**
+ * Display formatters for common field types.
+ * All return ANSI-colored strings safe to pass to table/kv.
+ */
+
+import { clr } from './display.js';
+
+// ─── Date ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Format a date value for terminal display.
+ * Accepts:
+ *   - Unix ms timestamp (number)
+ *   - ISO 8601 string
+ *   - null / undefined → "—"
+ */
+export function fmtDate(val: string | number | null | undefined): string {
+  if (val === null || val === undefined) return `${clr.dim}—${clr.reset}`;
+  const d = typeof val === 'number' ? new Date(val) : new Date(val);
+  if (isNaN(d.getTime())) return `${clr.dim}—${clr.reset}`;
+  return `${clr.dim}${d.toISOString().slice(0, 10)}${clr.reset}`;
+}
+
+// ─── Role ─────────────────────────────────────────────────────────────────────
+
+export function fmtRole(role: string | null | undefined): string {
+  if (role === 'owner')  return `${clr.cyan}owner${clr.reset}`;
+  if (role === 'admin')  return `${clr.yellow}admin${clr.reset}`;
+  if (role === 'member') return 'member';
+  return `${clr.dim}${role ?? '—'}${clr.reset}`;
+}
+
+// ─── Status ───────────────────────────────────────────────────────────────────
+
+export function fmtStatus(revokedAt: string | null | undefined): string {
+  return revokedAt
+    ? `${clr.dim}revoked${clr.reset}`
+    : `${clr.green}active${clr.reset}`;
+}
+
+// ─── Boolean ──────────────────────────────────────────────────────────────────
+
+export function fmtBool(val: boolean | number | null | undefined): string {
+  return val ? `${clr.green}yes${clr.reset}` : `${clr.dim}no${clr.reset}`;
+}
+
+// ─── Count (zero is dimmed) ───────────────────────────────────────────────────
+
+export function fmtCount(n: number | null | undefined): string {
+  if (!n) return `${clr.dim}0${clr.reset}`;
+  return String(n);
+}
+
+// ─── ID (dimmed, truncated) ───────────────────────────────────────────────────
+
+export function fmtId(id: string | null | undefined): string {
+  if (!id) return `${clr.dim}—${clr.reset}`;
+  return `${clr.dim}${id}${clr.reset}`;
+}