@typeship-ax/cli 0.22.0 → 0.24.0

package/src/search.ts

@@ -0,0 +1,434 @@
+/**
+ * Operation search shared by the generated CLI (`docs search`) and MCP
+ * server (`search_docs`). Generated by Typeship — https://typeship.dev
+ *
+ * Agents describe a task ("assign issue", "list calls"), not an operation
+ * name, so ranking works on stems, weighs rare words over common ones
+ * (IDF), and reads the verb of the query against what each operation does:
+ * its HTTP method and whether its path names one item or a collection, or
+ * its GraphQL root field. GraphQL mutations are also indexed by their input
+ * fields, so "assign issue" finds issueUpdate through assigneeId.
+ * Deterministic and dependency-free.
+ */
+
+/** The parts of an operation search reads. The CLI and MCP operation
+ * specs both satisfy it. */
+export interface SearchableOperation {
+  tool: string;
+  resource?: string;
+  method?: string;
+  httpMethod: string;
+  path: string;
+  summary?: string;
+  description?: string;
+  paginated?: boolean;
+  deprecated?: boolean;
+  graphql?: { kind: string; field?: string };
+  params: readonly { name: string; enum?: readonly string[]; description?: string }[];
+  inputSchema?: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+}
+
+/** Reference matches per search page. */
+export const SEARCH_PAGE_SIZE = 10;
+
+type Action = "list" | "get" | "create" | "update" | "delete" | "search";
+
+/** Query verbs and the operation kinds they ask for, best first. */
+const VERBS: Record<string, Action[]> = {
+  list: ["list"], all: ["list"], browse: ["list"], enumerate: ["list"],
+  search: ["search", "list"], find: ["search", "list", "get"], query: ["search", "list"], lookup: ["get", "search"],
+  get: ["get", "list"], release: ["delete"], fetch: ["get", "list"], retrieve: ["get", "list"], read: ["get", "list"], show: ["get", "list"],
+  view: ["get", "list"], check: ["get"], describe: ["get"], inspect: ["get"], status: ["get"],
+  create: ["create"], add: ["create", "update"], new: ["create"], make: ["create"], send: ["create"], post: ["create"],
+  submit: ["create"], open: ["create"], start: ["create", "update"], upload: ["create", "update"], generate: ["create"],
+  buy: ["create"], purchase: ["create"], place: ["create"], invite: ["create"], write: ["create", "update"],
+  publish: ["create", "update"], register: ["create"],
+  update: ["update"], change: ["update"], edit: ["update"], modify: ["update"], set: ["update", "create"],
+  assign: ["update", "create"], rename: ["update"], move: ["update"], close: ["update", "delete"], reopen: ["update"],
+  mark: ["update"], archive: ["delete", "update"], unarchive: ["update"], enable: ["update"], disable: ["update"],
+  pause: ["update"], resume: ["update"], replace: ["update"], patch: ["update"], merge: ["update", "create"],
+  save: ["create", "update"], follow: ["create", "update"], unfollow: ["delete", "update"], comment: ["create"], reply: ["create"], request: ["create"], hang: ["update", "delete"],
+  delete: ["delete"], remove: ["delete", "update"], destroy: ["delete"], erase: ["delete"], drop: ["delete"],
+  revoke: ["delete"], cancel: ["delete", "update"], unassign: ["update", "delete"], clear: ["delete"],
+};
+
+/** Words that name the caller: "who am I", "my issues", "me". */
+const IDENTITY_WORDS = new Set(["who", "whoami", "me", "my", "mine", "myself", "self"]);
+const IDENTITY_TERMS = ["me", "self", "whoami", "authenticated"];
+
+/** An operation about the caller: GET /user, /me/…, a viewer or me root
+ * field, users_get_authenticated. */
+function isIdentityOperation(op: SearchableOperation): boolean {
+  if (op.graphql?.field) return /^(viewer|me|currentUser|whoami)$/.test(op.graphql.field);
+  const nameWords = words([op.tool, op.method ?? ""].join(" "));
+  if (nameWords.some((w) => w === "me" || w === "whoami" || w === "authenticated" || w === "self")) return true;
+  return /^(\/v\d+)?\/(me|user|self|whoami)(\/|$)/i.test(op.path) || /\/(users\/)?me(\/|$)/i.test(op.path);
+}
+
+/** Words that narrow a request rather than name the operation. */
+const QUALIFIERS = new Set(["yesterday", "today", "tomorrow", "recent", "recently", "latest", "last", "week", "month", "year", "daily"]);
+
+/** A few everyday words for what APIs call something else. */
+const SYNONYMS: Record<string, string[]> = {
+  now: ["current"], sms: ["message"], mms: ["message"], text: ["message"], document: ["file"], kyc: ["identity", "verification"],
+};
+
+const STOPWORDS = new Set([
+  "a", "an", "the", "to", "of", "for", "in", "on", "at", "from", "by", "with", "and", "or", "is", "are", "am", "be",
+  "do", "does", "it", "its", "this", "that", "these", "those", "into", "onto", "up", "how", "what", "which", "can",
+  "please", "via", "using", "some", "any", "there", "i", "you", "your", "we", "our",
+]);
+
+/** Field weights: a word in the operation's name says most about it. */
+const W_NAME = 10, W_SUMMARY = 6, W_PATH = 4, W_PARAM = 3, W_ENUM = 2, W_DESCRIPTION = 1.5, W_OUTPUT = 1;
+
+/** A light English stemmer: plurals, -ing/-ed, a few derivational
+ * suffixes, a trailing e. It only has to map a word and its common
+ * variants to one stem ("assignee", "assigned", "assigns" to "assign";
+ * "moderate", "moderations" to "moder"). */
+export function stem(word: string): string {
+  let w = word.toLowerCase();
+  if (w.length <= 3) return w;
+  if (w.endsWith("ies") && w.length > 4) w = w.slice(0, -3) + "y";
+  else if (/(sses|xes|ches|shes|zes)$/.test(w)) w = w.slice(0, -2);
+  else if (w.endsWith("s") && !/(ss|us|is)$/.test(w)) w = w.slice(0, -1);
+  let stripped = false;
+  if (w.endsWith("ly") && w.length >= 6) w = w.slice(0, -2);
+  for (const [suffix, min] of [["ing", 4], ["ed", 3]] as const) {
+    if (w.endsWith(suffix) && w.length - suffix.length >= min) {
+      w = w.slice(0, -suffix.length);
+      stripped = true;
+      break;
+    }
+  }
+  if (stripped) {
+    if (/(at|bl|iz)$/.test(w)) w += "e";
+    else if (/([^aeioulsz])\1$/.test(w)) w = w.slice(0, -1);
+  }
+  for (const [suffix, min] of [["ations", 4], ["ation", 4], ["ments", 4], ["ment", 4], ["ption", 4], ["ions", 4], ["ion", 4], ["ers", 4], ["er", 4], ["ee", 4], ["ate", 4]] as const) {
+    if (w.endsWith(suffix) && w.length - suffix.length >= min) {
+      w = w.slice(0, -suffix.length);
+      break;
+    }
+  }
+  if (w.endsWith("e") && w.length >= 5) w = w.slice(0, -1);
+  return w;
+}
+
+/** Lowercase words of two or more characters, with snake, kebab, camel and
+ * letter-digit seams split so "createAccount" and "accounts_create" share
+ * words. */
+function words(text: string): string[] {
+  return text.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([a-zA-Z])([0-9])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 2);
+}
+
+function stems(text: string): string[] {
+  return words(text).filter((w) => !STOPWORDS.has(w)).map(stem);
+}
+
+interface IndexedOperation {
+  /** stem -> best field weight, and the sum of the others. */
+  weights: Map<string, { best: number; rest: number }>;
+  /** Distinct stems of the operation's name, less its action word. */
+  nameStems: string[];
+  action: Action;
+  identity: boolean;
+  /** The summary's stems, for a query that is the summary. */
+  summary: string;
+  /** The stem of the name's verb ("add" in issue_add_label), if any. */
+  actionStem: string | null;
+  deprecated: boolean;
+}
+
+interface SearchIndex {
+  docs: IndexedOperation[];
+  /** Document frequency of each stem. */
+  df: Map<string, number>;
+  vocabulary: string[];
+}
+
+// A server keeps one operation list, and a hosted one filters the same
+// operation objects per request: cache by both.
+const INDEXES = new WeakMap<readonly SearchableOperation[], SearchIndex>();
+const INDEXED = new WeakMap<SearchableOperation, IndexedOperation>();
+
+const READ_ACTIONS: readonly Action[] = ["list", "get", "search"];
+const WRITE_ACTIONS: readonly Action[] = ["create", "update", "delete"];
+
+/** The first of `words` (in order) that names an allowed action. */
+function actionIn(candidates: string[], allowed: readonly Action[]): { action: Action; word: string } | undefined {
+  for (const word of candidates) {
+    const action = VERBS[word]?.[0];
+    if (action && allowed.includes(action)) return { action, word };
+  }
+  return undefined;
+}
+
+/** What an operation does, and the word of its name that says so: its
+ * name's verb when it has one, else its HTTP method and whether the path
+ * ends at one item or a collection. A read never creates, updates or
+ * deletes, whatever its name ("query comment" is a read of a comment). */
+function operationAction(op: SearchableOperation): { action: Action; word: string | null } {
+  const collection = (): Action => {
+    const segments = op.path.replace(/\.[a-z]+$/i, "").split("/").filter(Boolean);
+    const last = segments.at(-1) ?? "";
+    if (last.startsWith("{") || last.startsWith(":")) return "get";
+    return op.paginated ? "list" : "get";
+  };
+  if (op.graphql?.field) {
+    // issueUpdate, createIssue: the verb may sit at either end.
+    const fieldWords = words(op.graphql.field);
+    const read = op.graphql.kind !== "mutation";
+    const found = actionIn([...fieldWords].reverse(), read ? READ_ACTIONS : WRITE_ACTIONS);
+    if (found) return found;
+    return { action: read ? (op.paginated || /s$/.test(op.graphql.field) ? "list" : "get") : "update", word: null };
+  }
+  const verb = op.httpMethod.toUpperCase();
+  const read = verb === "GET" || verb === "HEAD";
+  const found = actionIn(words(op.method ?? ""), read ? READ_ACTIONS : [...WRITE_ACTIONS, "search"]);
+  if (found) return found;
+  if (verb === "DELETE") return { action: "delete", word: null };
+  if (verb === "PUT" || verb === "PATCH") return { action: "update", word: null };
+  if (verb === "POST") return { action: "create", word: null };
+  return { action: collection(), word: null };
+}
+
+/** Literal path words: no parameters, versions or date segments. */
+function pathWords(path: string): string {
+  return path.replace(/\.[a-z]+$/i, "").split("/").filter((s) => s && !/^[{:]/.test(s) && !/^v\d+$/i.test(s) && !/^\d/.test(s)).join(" ");
+}
+
+/** Property names and enum values of a schema, one level into objects,
+ * and one more for object-typed properties (a GraphQL input object). */
+function schemaWords(schema: unknown, depth: number, names: string[], enums: string[]): void {
+  if (!schema || typeof schema !== "object" || depth < 0) return;
+  const node = schema as Record<string, unknown>;
+  if (Array.isArray(node.enum)) for (const value of node.enum) if (typeof value === "string") enums.push(value);
+  for (const key of ["anyOf", "oneOf", "allOf"]) {
+    if (Array.isArray(node[key])) for (const part of node[key] as unknown[]) schemaWords(part, depth, names, enums);
+  }
+  if (node.items) schemaWords(node.items, depth, names, enums);
+  const properties = node.properties as Record<string, unknown> | undefined;
+  if (properties && typeof properties === "object") {
+    for (const [name, child] of Object.entries(properties)) {
+      names.push(name);
+      schemaWords(child, depth - 1, names, enums);
+    }
+  }
+}
+
+function outputWords(schema: unknown, depth: number, out: string[]): void {
+  if (!schema || typeof schema !== "object" || depth < 0) return;
+  const node = schema as Record<string, unknown>;
+  if (typeof node.description === "string") out.push(node.description.slice(0, 200));
+  if (node.items) outputWords(node.items, depth, out);
+  for (const key of ["anyOf", "oneOf", "allOf"]) {
+    if (Array.isArray(node[key])) for (const part of node[key] as unknown[]) outputWords(part, depth, out);
+  }
+  const properties = node.properties as Record<string, unknown> | undefined;
+  if (properties && typeof properties === "object") {
+    for (const [name, child] of Object.entries(properties)) {
+      out.push(name);
+      outputWords(child, depth - 1, out);
+    }
+  }
+}
+
+function firstSentence(text: string): string {
+  return /^(.{1,200}?[.!?])(\s|$)/s.exec(text.trim())?.[1] ?? "";
+}
+
+function indexOperation(op: SearchableOperation): IndexedOperation {
+  const weights = new Map<string, { best: number; rest: number }>();
+  const add = (text: string, weight: number) => {
+    for (const s of new Set(stems(text))) {
+      const entry = weights.get(s);
+      if (!entry) weights.set(s, { best: weight, rest: 0 });
+      else if (weight > entry.best) { entry.rest += entry.best; entry.best = weight; }
+      else entry.rest += weight;
+    }
+  };
+  // GraphQL tools are named query_<field> / mutation_<field>; the prefix is
+  // the kind, not a word a task would use.
+  const name = op.graphql?.field
+    ? [op.graphql.field]
+    : [op.tool, op.resource ?? "", op.method ?? ""];
+  add(name.join(" "), W_NAME);
+  // Without a summary, the description's first sentence plays its part.
+  const summary = op.summary?.trim() || firstSentence(op.description ?? "");
+  add(summary, W_SUMMARY);
+  add(pathWords(op.path), W_PATH);
+  const paramNames: string[] = [];
+  const enumValues: string[] = [];
+  const paramText: string[] = [];
+  for (const param of op.params) {
+    paramNames.push(param.name);
+    if (param.enum) enumValues.push(...param.enum);
+    if (param.description) paramText.push(param.description.split("\n")[0]!.slice(0, 200));
+  }
+  const properties = (op.inputSchema?.properties ?? {}) as Record<string, unknown>;
+  for (const child of Object.values(properties)) schemaWords(child, 1, paramNames, enumValues);
+  add(paramNames.join(" "), W_PARAM);
+  add(enumValues.join(" "), W_ENUM);
+  add(op.description ?? "", W_DESCRIPTION);
+  add(paramText.join(" "), W_OUTPUT);
+  const output: string[] = [];
+  outputWords(op.outputSchema, 2, output);
+  add(output.join(" "), W_OUTPUT);
+  const { action, word } = operationAction(op);
+  const actionStem = word === null ? null : stem(word);
+  const nameStems = [...new Set(stems(name.join(" ")))].filter((s) => s !== actionStem);
+  return { weights, nameStems, action, actionStem, identity: isIdentityOperation(op), summary: stems(summary).join(" "), deprecated: op.deprecated === true || /^deprecated\b/i.test(op.summary ?? "") };
+}
+
+function indexFor(ops: readonly SearchableOperation[]): SearchIndex {
+  const cached = INDEXES.get(ops);
+  if (cached) return cached;
+  const docs = ops.map((op) => {
+    let doc = INDEXED.get(op);
+    if (!doc) INDEXED.set(op, doc = indexOperation(op));
+    return doc;
+  });
+  const df = new Map<string, number>();
+  for (const doc of docs) for (const s of doc.weights.keys()) df.set(s, (df.get(s) ?? 0) + 1);
+  const index = { docs, df, vocabulary: [...df.keys()] };
+  INDEXES.set(ops, index);
+  return index;
+}
+
+/** A query stem's matches in the vocabulary: itself, and longer or
+ * shorter forms sharing a long prefix ("transcrib" and "transcript"),
+ * which count for less. */
+function variants(term: string, index: SearchIndex): Map<string, number> {
+  const out = new Map<string, number>();
+  if (index.df.has(term)) out.set(term, 1);
+  if (term.length < 5) return out;
+  for (const word of index.vocabulary) {
+    if (word === term || word.length < 5) continue;
+    let common = 0;
+    while (common < word.length && common < term.length && word[common] === term[common]) common++;
+    if (common >= 6 && Math.max(word.length, term.length) - common <= 3) out.set(word, 0.6);
+  }
+  return out;
+}
+
+interface QueryTerm {
+  /** Vocabulary stem -> match strength. */
+  matches: Map<string, number>;
+  /** How much the term counts: the task's object most, its verb and
+   * qualifiers ("yesterday") least. */
+  weight: number;
+  /** The query's verb: the operation kinds it asks for, best first. */
+  verb: Action[] | null;
+  /** The first noun, usually the object of the task. */
+  primary: boolean;
+  stem: string;
+}
+
+function parseQuery(query: string, index: SearchIndex): { terms: QueryTerm[]; verb: Action[] | null } {
+  const raw = words(query);
+  let verb: Action[] | null = null;
+  let identity = false;
+  const terms: QueryTerm[] = [];
+  const seen = new Set<string>();
+  for (const word of raw) {
+    if (IDENTITY_WORDS.has(word)) { identity = true; continue; }
+    if (STOPWORDS.has(word)) continue;
+    const s = stem(word);
+    if (seen.has(s)) continue;
+    seen.add(s);
+    const actions = VERBS[word] ?? VERBS[s] ?? null;
+    const isVerb = actions !== null && actions.length > 0 && verb === null;
+    if (isVerb) verb = actions;
+    const matches = variants(s, index);
+    for (const synonym of SYNONYMS[word] ?? []) for (const [v, strength] of variants(stem(synonym), index)) matches.set(v, Math.max(matches.get(v) ?? 0, strength * 0.8));
+    // The verb is scored against what the operation does, so its word
+    // counts for little; the first noun is usually the object of the task.
+    const qualifier = QUALIFIERS.has(word);
+    const primary = !isVerb && !qualifier && !terms.some((t) => t.primary);
+    const weight = isVerb || qualifier ? 0.3 : primary ? 1.3 : 1;
+    terms.push({ matches, weight, verb: isVerb ? actions : null, primary, stem: s });
+  }
+  if (identity) {
+    const matches = new Map<string, number>();
+    for (const t of IDENTITY_TERMS) for (const [s, strength] of variants(stem(t), index)) matches.set(s, Math.max(matches.get(s) ?? 0, strength));
+    terms.push({ matches, weight: 0.8, verb: null, primary: false, stem: "@me" });
+  }
+  return { terms, verb };
+}
+
+export interface RankedOperation<T> {
+  op: T;
+  score: number;
+}
+
+/**
+ * Operations for a free-text query, best first. Weak matches (under a
+ * fifth of the best score, or matching only the query's verb) are left
+ * out, and deprecated operations follow every current one.
+ */
+export function rankOperations<T extends SearchableOperation>(ops: readonly T[], query: string): RankedOperation<T>[] {
+  const index = indexFor(ops);
+  const { terms, verb } = parseQuery(query, index);
+  if (terms.length === 0) return [];
+  const idf = (s: string) => Math.log(1 + index.docs.length / (index.df.get(s) ?? index.docs.length));
+  const nonVerbTerms = terms.filter((t) => t.verb === null).length;
+  const primary = terms.find((t) => t.primary);
+  const verbStem = terms.find((t) => t.verb !== null)?.stem ?? null;
+  const identityTerm = terms.find((t) => t.stem === "@me");
+  const identityIdf = Math.log(1 + index.docs.length / Math.max(1, index.docs.filter((d) => d.identity).length));
+  const scored: { op: T; score: number; deprecated: boolean }[] = [];
+  const phrase = words(query).filter((w) => !STOPWORDS.has(w)).map(stem).join(" ");
+  index.docs.forEach((doc, position) => {
+    let score = 0;
+    let matchedNonVerb = 0;
+    let primaryInName = false;
+    let verbInName = false;
+    const covered = new Set<string>();
+    for (const term of terms) {
+      let best = term === identityTerm && doc.identity ? W_NAME * identityIdf : 0;
+      for (const [s, strength] of term.matches) {
+        const entry = doc.weights.get(s);
+        if (!entry) continue;
+        const value = (entry.best + 0.1 * Math.min(entry.rest, 10)) * strength * idf(s);
+        if (value > best) best = value;
+        if (doc.nameStems.includes(s)) {
+          covered.add(s);
+          if (term === primary) primaryInName = true;
+          // The query's verb as a noun of the name: upload_url for "upload".
+          if (term.verb !== null) verbInName = true;
+        }
+      }
+      if (best > 0 && term.verb === null) matchedNonVerb++;
+      score += best * term.weight;
+    }
+    if (score === 0) return;
+    if (nonVerbTerms > 0 && matchedNonVerb === 0) return;
+    // How much of the operation's name the query accounts for: call_list
+    // for "list calls" over sip_auth_calls_credential_list_mapping_delete.
+    const coverage = doc.nameStems.length === 0 ? 1 : covered.size / doc.nameStems.length;
+    score *= 0.6 + 0.8 * coverage;
+    // The query's verb against what the operation does.
+    if (verb) {
+      const rank = verb.indexOf(doc.action);
+      score *= rank === 0 ? 1.5 : rank > 0 ? 1.2 : doc.action === "search" && verb.includes("list") ? 1.2 : verbInName ? 1 : 0.55;
+      // The very word: issue_add_label for "add", over a generic create.
+      if (verbStem !== null && doc.actionStem === verbStem) score *= 1.2;
+    }
+    // Every query word matched: a stronger signal than any single word.
+    if (matchedNonVerb === nonVerbTerms && nonVerbTerms > 1) score *= 1.2;
+    if (phrase.includes(" ") && doc.nameStems.join(" ").includes(phrase)) score *= 1.2;
+    if (phrase.includes(" ") && doc.summary.includes(phrase)) score *= 1.3;
+    // The operation is named for the task's object: issue_update, not
+    // workflow_state_update, for "change issue state".
+    if (primaryInName) score *= 1.3;
+    scored.push({ op: ops[position]!, score, deprecated: doc.deprecated });
+  });
+  if (scored.length === 0) return [];
+  const top = Math.max(...scored.map((s) => s.score));
+  return scored
+    .filter((s) => s.score >= top * 0.2)
+    .sort((a, b) => Number(a.deprecated) - Number(b.deprecated) || b.score - a.score || a.op.tool.localeCompare(b.op.tool))
+    .map(({ op, score }) => ({ op, score: Math.round(score * 100) / 100 }));
+}

package/src/table.ts

@@ -0,0 +1,167 @@
+/**
+ * `--format table` for the generated CLI: an API result as text for a
+ * person at a terminal. Generated by Typeship — https://typeship.dev
+ *
+ * JSON stays the default and the automation format; this view is opt-in and
+ * lossy by design. Lists become columns chosen by name (identifiers, then
+ * names, then status-like fields) while they fit the terminal width; a single
+ * object becomes one "field  value" line per field in the same order. Cells longer than
+ * MAX_CELL characters end in "…", and the footer names every column or field
+ * that was left out. Pure: no I/O, so tests render without a terminal.
+ */
+
+/** The longest cell before it is cut with "…". */
+export const MAX_CELL = 40;
+/** A single object shows at most this many (flattened) fields. */
+export const MAX_FIELDS = 60;
+
+export interface TableOptions {
+  /** Terminal width in columns; lists add columns until it is used. */
+  width?: number;
+  /** Wraps header text, e.g. in bold when color is on. */
+  heading?: (text: string) => string;
+  /** The array property that holds a collection response's items ({data: [...]}). */
+  collectionField?: string | null;
+  /** The command's resource (shipments), so shipment_id is recognized as the row's identifier. */
+  resource?: string;
+}
+
+type Row = Record<string, unknown>;
+
+const ID_KEYS = new Set(["id", "sid", "uuid", "key", "slug", "code", "symbol", "number", "handle"]);
+const NAME_KEYS = new Set(["name", "display_name", "displayname", "friendly_name", "friendlyname", "title", "label", "email", "username", "login", "to", "from"]);
+const STATUS_KEYS = new Set(["status", "state"]);
+const DESCRIPTOR_KEYS = new Set(["type", "kind", "direction", "enabled", "active", "amount", "currency", "price", "total"]);
+
+/**
+ * Lower is shown first: identifiers, names, status, descriptors, everything
+ * else, dates, then references and URLs. `primaryId` is the row's own
+ * identifier when it is spelled like a reference (shipment_id with no id).
+ */
+function rank(key: string, primaryId: string | undefined): number {
+  const k = key.toLowerCase();
+  if (ID_KEYS.has(k) || key === primaryId) return 0;
+  if (NAME_KEYS.has(k)) return 1;
+  if (STATUS_KEYS.has(k)) return 2;
+  if (DESCRIPTOR_KEYS.has(k)) return 3;
+  if (/(^|_)(created|updated)(_at|_on)?$|^date_|^(created|updated)|At$/.test(key)) return 5;
+  if (/(_id|_sid|Id|_ids|_uri|_url|Url|Uri)$/.test(key) || k === "uri" || k === "url") return 6;
+  return 4;
+}
+
+/** Keys in display order. The resource's own *_id (shipment_id for shipments) counts as the identifier when no id-like key exists. */
+function byRank(keys: string[], resource: string | undefined): string[] {
+  const bare = (text: string) => text.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const own = resource ? bare(resource).replace(/ies$/, "y").replace(/(ses|xes|s)$/, (m) => m === "s" ? "" : m.slice(0, -2)) + "id" : undefined;
+  const primaryId = keys.some((key) => ID_KEYS.has(key.toLowerCase())) ? undefined
+    : keys.find((key) => bare(key) === own) ?? keys.find((key) => /(_id|Id)$/.test(key));
+  return keys.map((key, index) => ({ key, index, rank: rank(key, primaryId) })).sort((a, b) => a.rank - b.rank || a.index - b.index).map((c) => c.key);
+}
+
+function isPlainObject(value: unknown): value is Row {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function scalar(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value.replace(/\s+/g, " ").trim();
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    return value.every((v) => v === null || typeof v !== "object") ? value.map(scalar).join(", ") : "[" + value.length + " items]";
+  }
+  if (isPlainObject(value)) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return "{}";
+    return entries.every(([, v]) => v === null || typeof v !== "object")
+      ? entries.map(([k, v]) => k + "=" + scalar(v)).join(" ")
+      : "{" + entries.length + " fields}";
+  }
+  return String(value);
+}
+
+function cut(text: string, max: number): string {
+  return text.length > max ? text.slice(0, Math.max(1, max - 1)) + "…" : text;
+}
+
+function pad(text: string, width: number): string {
+  return text + " ".repeat(Math.max(0, width - text.length));
+}
+
+/** The rows and footer lines of a list-shaped result, or null for a single object. */
+function listOf(value: unknown, collectionField: string | null | undefined): { rows: unknown[]; footer: string[] } | null {
+  if (Array.isArray(value)) return { rows: value, footer: [] };
+  if (!isPlainObject(value)) return null;
+  // The CLI's page envelope: {items, hasMore, nextPage?, nextCommand?, request_id?}.
+  if (Array.isArray(value.items) && typeof value.hasMore === "boolean") {
+    return { rows: value.items, footer: typeof value.nextCommand === "string" ? ["More results: " + value.nextCommand] : [] };
+  }
+  if (collectionField && Array.isArray(value[collectionField])) {
+    const rest = Object.entries(value).filter(([k, v]) => k !== collectionField && v !== null && typeof v !== "object");
+    return { rows: value[collectionField] as unknown[], footer: rest.length ? [rest.map(([k, v]) => k + ": " + scalar(v)).join("  ")] : [] };
+  }
+  return null;
+}
+
+function renderRows(rows: unknown[], footer: string[], options: TableOptions): string {
+  const heading = options.heading ?? ((text: string) => text);
+  if (rows.length === 0) return ["No items.", ...footer].join("\n") + "\n";
+  if (!rows.every(isPlainObject)) {
+    return [...rows.map((row) => cut(scalar(row), Math.max(MAX_CELL, options.width ?? 120))), "", rows.length + (rows.length === 1 ? " item" : " items"), ...footer].join("\n") + "\n";
+  }
+  const keys: string[] = [];
+  for (const row of rows as Row[]) for (const key of Object.keys(row)) if (!keys.includes(key)) keys.push(key);
+  const ordered = byRank(keys, options.resource);
+  const width = Math.max(40, options.width ?? 120);
+  const shown: { key: string; width: number }[] = [];
+  let used = 0;
+  for (const key of ordered) {
+    const cells = (rows as Row[]).map((row) => cut(scalar(row[key]), MAX_CELL));
+    // A column empty in every row says nothing.
+    if (cells.every((cell) => cell === "")) continue;
+    const columnWidth = Math.max(Math.min(key.length, MAX_CELL), ...cells.map((cell) => cell.length));
+    if (shown.length > 0 && used + 2 + columnWidth > width) continue;
+    shown.push({ key, width: columnWidth });
+    used += (shown.length > 1 ? 2 : 0) + columnWidth;
+  }
+  const line = (cells: string[]) => cells.map((cell, i) => i === cells.length - 1 ? cell : pad(cell, shown[i]!.width)).join("  ").trimEnd();
+  const lines = [
+    heading(line(shown.map((c) => cut(c.key.toUpperCase(), c.width)))),
+    ...(rows as Row[]).map((row) => line(shown.map((c) => cut(scalar(row[c.key]), MAX_CELL)))),
+    "",
+  ];
+  const hidden = ordered.filter((key) => !shown.some((c) => c.key === key));
+  lines.push(rows.length + (rows.length === 1 ? " item" : " items") + (hidden.length ? "; not shown: " + hidden.join(", ") : ""));
+  return [...lines, ...footer].join("\n") + "\n";
+}
+
+/** One object as "field  value" lines, identifiers and status first; nested objects flatten to dotted paths. */
+function renderObject(value: Row, options: TableOptions): string {
+  const fields: [string, string][] = [];
+  const walk = (object: Row, prefix: string, depth: number) => {
+    const keys = depth === 0 ? byRank(Object.keys(object), options.resource) : Object.keys(object);
+    for (const key of keys) {
+      const v = object[key];
+      const path = prefix + key;
+      if (isPlainObject(v) && depth < 2 && Object.keys(v).length > 0) walk(v, path + ".", depth + 1);
+      else fields.push([path, scalar(v)]);
+    }
+  };
+  walk(value, "", 0);
+  if (fields.length === 0) return "No fields.\n";
+  const heading = options.heading ?? ((text: string) => text);
+  const shown = fields.slice(0, MAX_FIELDS);
+  const keyWidth = Math.min(MAX_CELL, Math.max(...shown.map(([key]) => key.length)));
+  const valueWidth = Math.max(MAX_CELL, (options.width ?? 120) - keyWidth - 2);
+  const lines = shown.map(([key, text]) => (heading(pad(cut(key, keyWidth), keyWidth)) + "  " + cut(text, valueWidth)).trimEnd());
+  if (fields.length > shown.length) lines.push("", (fields.length - shown.length) + " more fields not shown; use --format json or --fields.");
+  return lines.join("\n") + "\n";
+}
+
+/** The text --format table prints for a result that would otherwise print as JSON. */
+export function renderTable(value: unknown, options: TableOptions = {}): string {
+  const list = listOf(value, options.collectionField);
+  if (list) return renderRows(list.rows, list.footer, options);
+  if (isPlainObject(value)) return renderObject(value, options);
+  return scalar(value) + "\n";
+}