@typeship-ax/cli 0.6.0

package/src/cli-agent.ts

@@ -0,0 +1,685 @@
+/**
+ * The agent contract of a generated CLI. Generated by typeship — https://typeship.dev
+ *
+ * Everything a coding agent needs from a command-line tool and a human does
+ * not: a JSON error envelope with stable codes and next steps, agent-mode
+ * detection, MCP client registration across the agents on a machine, an
+ * AGENTS.md block, `agent-guide` and `doctor`. Pure helpers over node:fs;
+ * cli.ts wires them to the commands. Zero dependencies.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+// ---- error envelope ---------------------------------------------------------
+
+/**
+ * Stable codes an agent can branch on. The message is for people; the code
+ * is the contract. Additive only.
+ */
+export type IssueCode =
+  | "NO_AUTH"               // no credential resolved and the API said 401
+  | "AUTH_INVALID"          // a credential was sent and the API said 401/403
+  | "PLAN_LIMIT"            // 402: the account's plan stops here
+  | "NOT_FOUND"             // 404
+  | "INVALID_REQUEST"       // 400/422 the API rejected the input
+  | "SPEC_INVALID"          // 422 with the API's spec_error (typeship's own API)
+  | "RATE_LIMITED"          // 429
+  | "SERVER_ERROR"          // 5xx
+  | "NETWORK_ERROR"         // no response: DNS, TLS, timeout, refused
+  | "VALIDATION_FAILED"     // --validate found the body does not match the schema
+  | "TTY_REQUIRED"          // a prompt was needed and there is no terminal
+  | "CONFIRMATION_REQUIRED" // a destructive command needs --force
+  | "INVALID_USAGE"         // wrong flags or arguments
+  | "UNKNOWN_COMMAND"
+  | "UNKNOWN_FLAG"
+  | "MISSING_ARGUMENT"
+  | "COMMAND_FAILED";       // anything else
+
+export interface Issue {
+  code: IssueCode;
+  message: string;
+}
+
+export interface Envelope {
+  /** error: it failed. action_required: it stopped on purpose and next_steps says what unblocks it. */
+  status: "error" | "action_required";
+  issues: Issue[];
+  /** Where to read more; the docs site when one is configured. */
+  docs_url?: string;
+  /** Ordered, concrete, copy-pastable. Empty when there is nothing to suggest. */
+  next_steps: string[];
+  /** The API's own error body, the transport error, or the validation violations. */
+  detail?: unknown;
+}
+
+export interface EnvelopeInput {
+  status?: Envelope["status"];
+  code: IssueCode;
+  message: string;
+  docsUrl?: string | null;
+  nextSteps?: string[];
+  detail?: unknown;
+}
+
+export function envelope(input: EnvelopeInput): Envelope {
+  return {
+    status: input.status ?? "error",
+    issues: [{ code: input.code, message: input.message }],
+    ...(input.docsUrl ? { docs_url: input.docsUrl } : {}),
+    next_steps: input.nextSteps ?? [],
+    ...(input.detail !== undefined ? { detail: input.detail } : {}),
+  };
+}
+
+/** Exit code convention: 0 ok, 1 the request or command failed, 2 usage. */
+export function exitCodeFor(code: IssueCode): 1 | 2 {
+  switch (code) {
+    case "INVALID_USAGE":
+    case "UNKNOWN_COMMAND":
+    case "UNKNOWN_FLAG":
+    case "MISSING_ARGUMENT":
+    case "TTY_REQUIRED":
+    case "CONFIRMATION_REQUIRED":
+      return 2;
+    default:
+      return 1;
+  }
+}
+
+/** Interpret an SDK error result: HTTP status, body, transport, validation. */
+export function classifyApiError(
+  error: unknown,
+  context: { bin: string; hadCredential: boolean; docsUrl: string | null },
+): EnvelopeInput {
+  const e = (error ?? {}) as { name?: string; message?: string; status?: number; body?: unknown; violations?: unknown };
+  // The message is the API's own words when it sent any, else the SDK's
+  // (the spec's response description). The error class name rides in
+  // detail, not in front of the message: "NotFoundError: No such account
+  // (no such account)" said one thing three times.
+  const base = e.message ? e.message : String(error);
+  if (e.violations !== undefined) {
+    return { code: "VALIDATION_FAILED", message: base, detail: { ...(e.name ? { error: e.name } : {}), violations: e.violations }, nextSteps: ["Fix the fields named in detail.violations, or drop --validate to send the body as is."] };
+  }
+  if (e.name === "TransportError" || (typeof e.status !== "number" && /fetch|ECONN|ENOTFOUND|timed out|TLS|abort/i.test(base))) {
+    return {
+      code: "NETWORK_ERROR",
+      message: base,
+      nextSteps: [
+        "Check the base URL (--base-url, the " + context.bin.toUpperCase().replace(/[^A-Z0-9]/g, "_") + "_BASE_URL variable, or '" + context.bin + " config base-url') and the network.",
+        "Retry once with backoff; do not loop.",
+      ],
+    };
+  }
+  const status = typeof e.status === "number" ? e.status : 0;
+  const body = e.body as { errors?: { code?: string; message?: string }[]; error?: unknown; message?: unknown } | undefined;
+  const apiCode = body?.errors?.[0]?.code;
+  const apiMessage = body?.errors?.[0]?.message ?? (typeof body?.message === "string" ? body.message : undefined) ?? (typeof body?.error === "string" ? body.error : undefined);
+  const detail = { status, ...(e.name ? { error: e.name } : {}), ...(e.body !== undefined ? { body: e.body } : {}) };
+  const same = apiMessage !== undefined && (apiMessage.toLowerCase() === base.toLowerCase() || base.toLowerCase().includes(apiMessage.toLowerCase()) || apiMessage.toLowerCase().includes(base.toLowerCase()));
+  const message = apiMessage === undefined ? base : same ? apiMessage : apiMessage + " (" + base + ")";
+  const upgradeUrl = extractUrl(e.body, ["upgrade_url", "upgradeUrl", "signup_url", "claim_url"]);
+  if (status === 401) {
+    return context.hadCredential
+      ? { code: "AUTH_INVALID", message, detail, nextSteps: ["The credential was rejected. Check it is current: '" + context.bin + " auth check', then '" + context.bin + " login --help' to store a new one."] }
+      : { status: "action_required", code: "NO_AUTH", message, detail, nextSteps: ["No credential was sent. Set the auth env var, pass --token, or run '" + context.bin + " login'.", "'" + context.bin + " auth check' shows what the CLI would send."] };
+  }
+  if (status === 403) return { code: "AUTH_INVALID", message, detail, nextSteps: ["The credential lacks access to this operation."] };
+  if (status === 402) {
+    return { status: "action_required", code: "PLAN_LIMIT", message, detail, nextSteps: [upgradeUrl ? "Lift the limit at " + upgradeUrl + ", then run the same command again." : "The account's plan stops here; upgrade it, then run the same command again.", "Do not retry the same call as is."] };
+  }
+  if (status === 404) return { code: "NOT_FOUND", message, detail, nextSteps: notFoundNextSteps(message) };
+  if (status === 429) {
+    const retryAfter = extractRetryAfter(e);
+    return { status: "action_required", code: "RATE_LIMITED", message, detail, nextSteps: [retryAfter ? "Wait " + retryAfter + " seconds, then run the same command again." : "Back off and retry once; the SDK already retried with the server's Retry-After."] };
+  }
+  if (status === 422 && apiCode === "spec_error") return { code: "SPEC_INVALID", message, detail, nextSteps: ["The API rejected the spec it was given; the message says why.", context.docsUrl ? "Look the message up: '" + context.bin + " docs search \"" + (apiMessage ?? "").slice(0, 60).replace(/"/g, "'") + "\"'." : "Fix the spec and run again."] };
+  if (status === 400 || status === 422 || status === 409 || status === 413) return { code: "INVALID_REQUEST", message, detail, nextSteps: ["Read detail.body for the field the API named; run the command with --help for its flags."] };
+  if (status >= 500) return { code: "SERVER_ERROR", message, detail, nextSteps: ["Retry once with backoff. If it persists, report the request id in detail.body."] };
+  return { code: "COMMAND_FAILED", message, detail };
+}
+
+/** A file lookup needs path guidance, not the generic advice for a missing
+ * resource id. Prefer the API's own index when its message names one. */
+function notFoundNextSteps(message: string): string[] {
+  if (/\bfiles_index\b/i.test(message)) {
+    return ["Read files_index on the generation, choose an exact path it lists, then run the command again with that path."];
+  }
+  if (/\bfile\b/i.test(message) && /\bpaths?\b/i.test(message)) {
+    return ["Check the requested file path against the API's file listing, then run the command again with an exact path."];
+  }
+  return ["Check the resource id; list the resource first."];
+}
+
+function extractUrl(body: unknown, keys: string[]): string | undefined {
+  if (!body || typeof body !== "object") return undefined;
+  const record = body as Record<string, unknown>;
+  for (const key of keys) {
+    const direct = record[key];
+    if (typeof direct === "string") return direct;
+    for (const value of Object.values(record)) {
+      if (value && typeof value === "object" && typeof (value as Record<string, unknown>)[key] === "string") return (value as Record<string, string>)[key];
+    }
+  }
+  return undefined;
+}
+
+function extractRetryAfter(e: { headers?: unknown; body?: unknown }): string | undefined {
+  const headers = e.headers as { get?: (name: string) => string | null } | undefined;
+  const fromHeader = headers?.get?.("retry-after");
+  if (fromHeader) return fromHeader;
+  const match = /retry after (\d+)s/i.exec(JSON.stringify(e.body ?? ""));
+  return match?.[1];
+}
+
+// ---- agent mode -------------------------------------------------------------
+
+export interface AgentModeInput {
+  flagMode: string | boolean | undefined;
+  envMode: string | undefined;
+  stdoutIsTTY: boolean;
+  stdinIsTTY: boolean;
+}
+
+/**
+ * --mode agent beats <PREFIX>_MODE=agent beats "no terminal on either end".
+ * In agent mode nothing prompts, browsers are not opened, and every stop is
+ * an action_required envelope with next_steps.
+ */
+export function agentMode(input: AgentModeInput): boolean {
+  if (input.flagMode === "agent") return true;
+  if (input.flagMode === "human" || input.flagMode === "interactive") return false;
+  if (input.envMode === "agent") return true;
+  if (input.envMode === "human" || input.envMode === "interactive") return false;
+  return !input.stdoutIsTTY && !input.stdinIsTTY;
+}
+
+/** Which agent harness is running us, from its environment; analytics and AGENTS.md placement only. */
+export function detectHarness(env: NodeJS.ProcessEnv = process.env): string | null {
+  if (env.CLAUDECODE || env.CLAUDE_CODE || env.CLAUDE_CODE_ENTRYPOINT) return "claude-code";
+  if (env.CURSOR_TRACE_ID || env.CURSOR_AGENT) return "cursor";
+  if (env.CODEX_SANDBOX || env.CODEX_CI || env.OPENAI_CODEX) return "codex";
+  if (env.GEMINI_CLI || env.GEMINI_API_KEY && env.GEMINI_SANDBOX) return "gemini-cli";
+  if (env.WINDSURF_SESSION || env.CODEIUM_AGENT) return "windsurf";
+  if (env.OPENCODE || env.OPENCODE_SESSION) return "opencode";
+  if (env.AMP_SESSION || env.AMP_AGENT) return "amp";
+  if (env.DEVIN_SESSION) return "devin";
+  return null;
+}
+
+// ---- MCP clients ------------------------------------------------------------
+
+export type McpClientId = "claude-code" | "cursor" | "codex" | "vscode" | "windsurf" | "gemini-cli" | "opencode" | "zed" | "claude-desktop";
+
+export interface McpEntry {
+  /** A hosted endpoint: {type:"http", url, headers?} */
+  url?: string;
+  /** Header name → value; values may be env references like ${VAR}. */
+  headers?: Record<string, string>;
+  /** A local stdio server: command + args. */
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+export interface McpClient {
+  id: McpClientId;
+  label: string;
+  /** Where the config lives; project-scoped clients resolve against cwd. */
+  file: (cwd: string) => string;
+  /** Presence test: is this client on the machine (or in this project)? */
+  detect: (cwd: string) => boolean;
+  /** Merge an entry into the file's contents. */
+  write: (existing: string, name: string, entry: McpEntry) => string;
+  /** True when the client cannot speak the current MCP protocol; skipped by --all. */
+  incompatible?: string;
+}
+
+function readOr(file: string, fallback: string): string {
+  try {
+    return readFileSync(file, "utf8");
+  } catch {
+    return fallback;
+  }
+}
+
+function jsonMerge(existing: string, path: string[], name: string, value: unknown): string {
+  let doc: Record<string, unknown> = {};
+  try {
+    doc = JSON.parse(existing) as Record<string, unknown>;
+  } catch {
+    doc = {};
+  }
+  let cursor = doc;
+  for (const key of path) {
+    const next = cursor[key];
+    if (!next || typeof next !== "object" || Array.isArray(next)) cursor[key] = {};
+    cursor = cursor[key] as Record<string, unknown>;
+  }
+  cursor[name] = value;
+  return JSON.stringify(doc, null, 2) + "\n";
+}
+
+const httpEntry = (entry: McpEntry) => ({ type: "http", url: entry.url, ...(entry.headers ? { headers: entry.headers } : {}) });
+const stdioEntry = (entry: McpEntry) => ({ command: entry.command, args: entry.args ?? [], ...(entry.env ? { env: entry.env } : {}) });
+const standardEntry = (entry: McpEntry) => (entry.url ? httpEntry(entry) : stdioEntry(entry));
+
+/** TOML for Codex's config.toml: append or replace the [mcp_servers.<name>] table. */
+function tomlMerge(existing: string, name: string, entry: McpEntry): string {
+  const header = "[mcp_servers." + name + "]";
+  const lines: string[] = [header];
+  if (entry.url) {
+    lines.push("url = " + JSON.stringify(entry.url));
+    const auth = entry.headers?.Authorization ?? entry.headers?.authorization;
+    const envRef = auth ? /\$\{([A-Z0-9_]+)\}/.exec(auth)?.[1] : undefined;
+    if (envRef) lines.push("bearer_token_env_var = " + JSON.stringify(envRef));
+  } else {
+    lines.push("command = " + JSON.stringify(entry.command ?? "node"));
+    lines.push("args = " + JSON.stringify(entry.args ?? []));
+  }
+  const block = lines.join("\n") + "\n";
+  const pattern = new RegExp("\\[mcp_servers\\." + name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "\\][\\s\\S]*?(?=\\n\\[|$)");
+  if (pattern.test(existing)) return existing.replace(pattern, block.trimEnd() + "\n");
+  return (existing.trimEnd() + (existing.trim() ? "\n\n" : "")) + block;
+}
+
+const home = () => homedir();
+const xdg = () => process.env.XDG_CONFIG_HOME ?? join(home(), ".config");
+
+export const MCP_CLIENTS: McpClient[] = [
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    file: (cwd) => join(cwd, ".mcp.json"),
+    detect: () => existsSync(join(home(), ".claude")) || existsSync(join(home(), ".claude.json")),
+    write: (existing, name, entry) => jsonMerge(existing, ["mcpServers"], name, standardEntry(entry)),
+  },
+  {
+    id: "codex",
+    label: "Codex CLI",
+    file: () => join(home(), ".codex", "config.toml"),
+    detect: () => existsSync(join(home(), ".codex")),
+    write: (existing, name, entry) => tomlMerge(existing, name, entry),
+  },
+  {
+    id: "vscode",
+    label: "VS Code",
+    file: (cwd) => join(cwd, ".vscode", "mcp.json"),
+    detect: (cwd) => existsSync(join(cwd, ".vscode")) || existsSync(join(home(), ".vscode")),
+    write: (existing, name, entry) => jsonMerge(existing, ["servers"], name, standardEntry(entry)),
+  },
+  {
+    id: "windsurf",
+    label: "Windsurf",
+    file: () => join(home(), ".codeium", "windsurf", "mcp_config.json"),
+    detect: () => existsSync(join(home(), ".codeium", "windsurf")),
+    write: (existing, name, entry) => jsonMerge(existing, ["mcpServers"], name, entry.url ? { serverUrl: entry.url, ...(entry.headers ? { headers: entry.headers } : {}) } : stdioEntry(entry)),
+  },
+  {
+    id: "gemini-cli",
+    label: "Gemini CLI",
+    file: () => join(home(), ".gemini", "settings.json"),
+    detect: () => existsSync(join(home(), ".gemini")),
+    write: (existing, name, entry) => jsonMerge(existing, ["mcpServers"], name, entry.url ? { httpUrl: entry.url, ...(entry.headers ? { headers: entry.headers } : {}) } : stdioEntry(entry)),
+  },
+  {
+    id: "opencode",
+    label: "OpenCode",
+    file: () => join(xdg(), "opencode", "opencode.json"),
+    detect: () => existsSync(join(xdg(), "opencode")),
+    write: (existing, name, entry) => jsonMerge(existing, ["mcp"], name, entry.url ? { type: "remote", url: entry.url, ...(entry.headers ? { headers: entry.headers } : {}) } : { type: "local", command: [entry.command ?? "node", ...(entry.args ?? [])] }),
+  },
+  {
+    id: "zed",
+    label: "Zed",
+    file: () => join(xdg(), "zed", "settings.json"),
+    detect: () => existsSync(join(xdg(), "zed")),
+    write: (existing, name, entry) => jsonMerge(existing, ["context_servers"], name, entry.url ? { source: "custom", url: entry.url, ...(entry.headers ? { headers: entry.headers } : {}) } : { source: "custom", command: entry.command ?? "node", args: entry.args ?? [] }),
+  },
+  {
+    id: "claude-desktop",
+    label: "Claude Desktop",
+    file: () => process.platform === "darwin"
+      ? join(home(), "Library", "Application Support", "Claude", "claude_desktop_config.json")
+      : process.platform === "win32"
+        ? join(process.env.APPDATA ?? join(home(), "AppData", "Roaming"), "Claude", "claude_desktop_config.json")
+        : join(xdg(), "Claude", "claude_desktop_config.json"),
+    detect: () => existsSync(dirname(MCP_CLIENTS.find((c) => c.id === "claude-desktop")!.file(""))),
+    write: (existing, name, entry) => jsonMerge(existing, ["mcpServers"], name, stdioEntry(entry)),
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    file: (cwd) => join(cwd, ".cursor", "mcp.json"),
+    detect: () => existsSync(join(home(), ".cursor")),
+    write: (existing, name, entry) => jsonMerge(existing, ["mcpServers"], name, standardEntry(entry)),
+    incompatible: "Cursor does not yet speak MCP 2026-07-28, which is the only version this server serves; the entry is written but Cursor will not connect until it does.",
+  },
+];
+
+export function findMcpClient(id: string): McpClient | undefined {
+  return MCP_CLIENTS.find((c) => c.id === id);
+}
+
+export interface McpWriteResult {
+  client: McpClientId;
+  file: string;
+  written: boolean;
+  note?: string;
+}
+
+/** Merge the entry into one client's config file. Never writes a literal secret: callers pass env references. */
+export function writeMcpConfig(client: McpClient, cwd: string, name: string, entry: McpEntry): McpWriteResult {
+  const file = client.file(cwd);
+  if (!entry.url && client.id === "claude-desktop" && !entry.command) {
+    return { client: client.id, file, written: false, note: "Claude Desktop reads only stdio servers from its config file; add a remote server as a connector in the app." };
+  }
+  const existing = readOr(file, "");
+  const next = client.write(existing, name, entry);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, next);
+  return { client: client.id, file, written: true, ...(client.incompatible ? { note: client.incompatible } : {}) };
+}
+
+/** Does a client's config already mention this server? For doctor. */
+export function mcpConfigured(client: McpClient, cwd: string, name: string): boolean {
+  const text = readOr(client.file(cwd), "");
+  return text.includes('"' + name + '"') || text.includes("[mcp_servers." + name + "]");
+}
+
+// ---- AGENTS.md block ----------------------------------------------------------
+
+/**
+ * Upsert a marked block into a repo's agent instructions. Idempotent: the
+ * block between the markers is replaced, everything else is untouched, and
+ * a missing file is created. Returns the file written and whether the
+ * block already existed.
+ */
+export function upsertAgentBlock(file: string, marker: string, body: string): { file: string; updated: boolean } {
+  const start = "<!-- " + marker + " start -->";
+  const end = "<!-- " + marker + " end -->";
+  const block = start + "\n" + body.trim() + "\n" + end + "\n";
+  const existing = readOr(file, "");
+  const pattern = new RegExp(escapeRegExp(start) + "[\\s\\S]*?" + escapeRegExp(end) + "\\n?");
+  let next: string;
+  let updated = false;
+  if (pattern.test(existing)) {
+    next = existing.replace(pattern, block);
+    updated = true;
+  } else {
+    next = (existing.trimEnd() + (existing.trim() ? "\n\n" : "")) + block;
+  }
+  mkdirSync(dirname(resolve(file)), { recursive: true });
+  writeFileSync(file, next);
+  return { file, updated };
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** AGENTS.md by default; CLAUDE.md when only it exists, or when running under Claude Code and AGENTS.md is absent. */
+export function agentInstructionsFile(cwd: string, harness: string | null): string {
+  const agents = join(cwd, "AGENTS.md");
+  const claude = join(cwd, "CLAUDE.md");
+  if (existsSync(agents)) return agents;
+  if (existsSync(claude)) return claude;
+  return harness === "claude-code" ? claude : agents;
+}
+
+// ---- command index + guide ------------------------------------------------
+
+export interface CommandFlagSummary {
+  flag: string;
+  /** string | number | boolean | array | object | json | file */
+  type: string;
+  /** Element type of an array flag. */
+  items?: { type: string; enum?: string[] };
+  enum?: string[];
+  required: boolean;
+  description?: string;
+}
+
+export interface CommandSummary {
+  resource: string;
+  command: string;
+  method: string;
+  path: string;
+  summary?: string;
+  paginated: boolean;
+  destructive: boolean;
+  /** required | optional | none — what the spec's security says. */
+  auth?: "required" | "optional" | "none";
+  flags: CommandFlagSummary[];
+}
+
+export interface AgentContext {
+  bin: string;
+  pkg: string;
+  apiTitle: string;
+  version: string;
+  envPrefix: string;
+  authEnvVars: string[];
+  docsUrl: string | null;
+  /** The API's hosted MCP endpoint, when it has one. */
+  mcpUrl: string | null;
+  /** Skills repository (owner/name) an agent can install with npx skills add. */
+  skillsRepo: string | null;
+  hasMcp: boolean;
+  builtins: string[];
+}
+
+/** One line per command, pipe-delimited: the compact index that goes into AGENTS.md. */
+/** string, number, usd|eur, string[], usd|eur[], object, json — the type as a reader expects it. */
+export function flagTypeLabel(f: CommandFlagSummary): string {
+  const inline = (values: string[] | undefined) => values && values.join("|").length <= 24 ? values.join("|") : values ? "enum" : undefined;
+  if (f.type === "array") return (inline(f.items?.enum) ?? f.items?.type ?? "json") + "[]";
+  return inline(f.enum) ?? f.type;
+}
+
+export function compactIndex(commands: CommandSummary[]): string {
+  return commands
+    .map((c) => {
+      const required = c.flags.filter((f) => f.required).map((f) => "--" + f.flag + (f.type === "boolean" ? "" : " <" + flagTypeLabel(f) + ">"));
+      return c.resource + " " + c.command + " | " + c.method + " " + c.path + (required.length ? " | " + required.join(" ") : "") + (c.summary ? " | " + c.summary : "") + (c.auth === "none" ? " | no auth" : "");
+    })
+    .join("\n");
+}
+
+/** The AGENTS.md block body. */
+export function agentBlock(ctx: AgentContext, commands: CommandSummary[]): string {
+  const auth = ctx.authEnvVars.length ? ctx.authEnvVars.join(", ") : "(none)";
+  return [
+    "## " + ctx.bin + " CLI (" + ctx.apiTitle + ")",
+    "",
+    "Generated by typeship. API commands write JSON on stdout; discovery commands take --json. Errors are JSON on stderr ({status, issues[{code,message}], next_steps}), exit 0/1/2. Non-interactive under an agent: no prompts, no browsers.",
+    "",
+    "- Auth: " + auth + " in the environment, or `" + ctx.bin + " login`. Never write a key into a file in this repo.",
+    "- Discover: `" + ctx.bin + " --help`, `" + ctx.bin + " <resource> <command> --help`, `" + ctx.bin + " help --json` (machine-readable), `" + ctx.bin + " agent-guide --format json`.",
+    "- Docs: " + (ctx.docsUrl ? "`" + ctx.bin + " docs search <term> --json`; " + ctx.docsUrl + "/llms.txt" : "`" + ctx.bin + " docs <resource> <command> --json`") + ".",
+    "- Lists: `--all` streams every page as NDJSON. Destructive commands need `--force`.",
+    ...(ctx.hasMcp ? ["- MCP: `" + ctx.bin + " mcp install --all` registers this API's MCP server with the agent clients on this machine" + (ctx.mcpUrl ? " (hosted: " + ctx.mcpUrl + ")" : "") + "."] : []),
+    "",
+    "Commands (resource command | METHOD path | required flags | summary):",
+    "",
+    "```",
+    compactIndex(commands),
+    "```",
+  ].join("\n");
+}
+
+/** What `agent-guide --format json` returns. */
+export function agentGuide(ctx: AgentContext, commands: CommandSummary[]): Record<string, unknown> {
+  const first = commands.find((c) => c.method === "GET" && c.flags.every((f) => !f.required)) ?? commands[0];
+  return {
+    name: ctx.bin,
+    package: ctx.pkg,
+    api: ctx.apiTitle,
+    version: ctx.version,
+    generated_by: "typeship",
+    guide: agentBlock(ctx, commands),
+    first_command: first ? ctx.bin + " " + first.resource + " " + first.command : ctx.bin + " --help",
+    docs_index_url: ctx.docsUrl ? ctx.docsUrl.replace(/\/+$/, "") + "/llms.txt" : null,
+    docs_full_url: ctx.docsUrl ? ctx.docsUrl.replace(/\/+$/, "") + "/llms-full.txt" : null,
+    hosted_mcp_url: ctx.mcpUrl,
+    local_mcp: ctx.hasMcp ? ctx.bin + "-mcp (stdio) or '" + ctx.bin + " mcp install --all'" : null,
+    skills_install: ctx.skillsRepo ? "npx skills add " + ctx.skillsRepo : null,
+    auth_env_vars: ctx.authEnvVars,
+    conventions: {
+      output: "API commands return JSON on stdout; discovery commands take --json. --fields a,b.c keeps only those paths (per item for lists); --all streams NDJSON for paginated lists; SSE operations stream NDJSON events.",
+      errors: "JSON envelope on stderr: {status: 'error'|'action_required', issues: [{code, message}], docs_url?, next_steps: [], detail?}. Branch on issues[].code.",
+      exit_codes: { "0": "ok", "1": "the request or command failed", "2": "usage: wrong flags, missing arguments, or a confirmation was required" },
+      agent_mode: "--mode agent, " + ctx.envPrefix + "_MODE=agent, or no terminal on stdin and stdout: no prompts, no browsers, --yes implied for non-destructive stops.",
+      destructive: "Commands classified as destructive need --force (or --yes); without it they return CONFIRMATION_REQUIRED with the exact command to run.",
+      flags: "Positional path arguments first, then --flags. Array flags take a comma list, the flag repeated, or a JSON array; object flags take JSON. --data '<json>' merges under field flags (@<file> reads a file, - reads stdin).",
+      pagination: "Paginated commands return {items, hasMore, nextPage, nextCommand}: run nextCommand for the next page, or --all walks every page.",
+    },
+    builtins: ctx.builtins,
+    next_steps: [
+      ...(ctx.authEnvVars.length ? ["Set " + ctx.authEnvVars[0] + " in the environment or run '" + ctx.bin + " login'."] : []),
+      "Run '" + ctx.bin + " auth check'.",
+      "Run '" + ctx.bin + " help --json' for the command index, or read the AGENTS.md block '" + ctx.bin + " init' writes.",
+      ...(ctx.hasMcp ? ["Run '" + ctx.bin + " mcp install --all' if this session has an MCP-capable client."] : []),
+    ],
+  };
+}
+
+// ---- skills ---------------------------------------------------------------------
+
+export interface SkillsInstallResult {
+  status: "installed" | "skipped" | "failed";
+  repo: string | null;
+  detail?: string;
+}
+
+/** Install a skills repository through the skills CLI (npx skills add). Best effort: init reports, never fails on it. */
+export function installSkills(repo: string | null, options: { global?: boolean; agent?: string | null } = {}): SkillsInstallResult {
+  if (!repo) return { status: "skipped", repo: null, detail: "No skills repository is configured for this CLI." };
+  const args = ["-y", "skills", "add", repo, "-y", ...(options.global === false ? [] : ["-g"])];
+  if (options.agent) args.push("-a", options.agent);
+  // Windows resolves npx to npx.cmd, which only a shell can start.
+  const result = spawnSync("npx", args, { encoding: "utf8", timeout: 120_000, stdio: ["ignore", "pipe", "pipe"], shell: process.platform === "win32" });
+  if (result.error || result.status !== 0) {
+    return { status: "failed", repo, detail: (result.stderr || result.stdout || result.error?.message || "npx skills add failed").toString().trim().slice(-400) };
+  }
+  return { status: "installed", repo };
+}
+
+// ---- file bundles ------------------------------------------------------------------
+
+/**
+ * A response that carries files: an array property whose items have string
+ * `path` and `content`. typeship's own generate call is one; any API that
+ * returns generated or exported files is another. `--out <dir>` writes them.
+ */
+export function bundleProperty(outputSchema: Record<string, unknown> | undefined): string | null {
+  const props = outputSchema?.properties as Record<string, { type?: string; items?: { properties?: Record<string, { type?: string }>; required?: string[] } }> | undefined;
+  if (!props) return null;
+  for (const [name, schema] of Object.entries(props)) {
+    const item = schema.items;
+    if (schema.type === "array" && item?.properties?.path && item.properties.content) return name;
+  }
+  return null;
+}
+
+/** A non-page response whose result is a collection wrapped in one array
+ * property (`{data: [...]}` is the common shape). `--fields` applies to
+ * each item while preserving that envelope, just as it does for pages. */
+export function collectionProperty(outputSchema: Record<string, unknown> | undefined): string | null {
+  const props = outputSchema?.properties as Record<string, { type?: string | string[] }> | undefined;
+  const names = props ? Object.keys(props) : [];
+  if (!props || names.length !== 1) return null;
+  const name = names[0]!;
+  const type = props[name]?.type;
+  return type === "array" || (Array.isArray(type) && type.includes("array")) ? name : null;
+}
+
+export function writeBundle(dir: string, files: { path: string; content: string }[]): { dir: string; written: number; paths: string[] } {
+  const paths: string[] = [];
+  for (const file of files) {
+    const rel = file.path.replace(/^\/+/, "");
+    if (rel.split(/[\\/]/).includes("..")) continue;
+    const full = join(dir, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, file.content);
+    paths.push(rel);
+  }
+  return { dir, written: paths.length, paths };
+}
+
+// ---- claims ----------------------------------------------------------------------------
+
+/**
+ * A response that carries a claim: an object property `claim` with a string
+ * `url` (typeship's anonymous generate is one). The CLI tells the person
+ * where to claim and leaves a breadcrumb in the working directory so a
+ * later session (or `doctor`) can list what is still unclaimed.
+ */
+export function claimProperty(outputSchema: Record<string, unknown> | undefined): boolean {
+  type Variant = { properties?: Record<string, unknown>; oneOf?: Variant[]; anyOf?: Variant[] };
+  const props = outputSchema?.properties as Record<string, Variant> | undefined;
+  const claim = props?.claim;
+  if (!claim) return false;
+  const hasUrl = (v: Variant): boolean => Boolean(v.properties && "url" in v.properties) || (v.oneOf ?? v.anyOf ?? []).some(hasUrl);
+  return hasUrl(claim);
+}
+
+export interface ClaimBreadcrumb {
+  url: string;
+  expires_at?: string;
+  command: string;
+  created_at: string;
+}
+
+export function breadcrumbFile(cwd: string, bin: string): string {
+  return join(cwd, "." + bin, "claims.json");
+}
+
+/** Append a claim to .<bin>/claims.json (git-ignored when a .gitignore exists). */
+export function recordClaim(cwd: string, bin: string, crumb: ClaimBreadcrumb): string {
+  const file = breadcrumbFile(cwd, bin);
+  let list: ClaimBreadcrumb[] = [];
+  try {
+    list = JSON.parse(readFileSync(file, "utf8")) as ClaimBreadcrumb[];
+  } catch { /* none yet */ }
+  list.push(crumb);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(list, null, 2) + "\n");
+  const gitignore = join(cwd, ".gitignore");
+  if (existsSync(gitignore)) {
+    const text = readFileSync(gitignore, "utf8");
+    const line = "." + bin + "/";
+    if (!text.split("\n").some((l) => l.trim() === line || l.trim() === "." + bin)) writeFileSync(gitignore, text.trimEnd() + "\n" + line + "\n");
+  }
+  return file;
+}
+
+/** Claims on file that have not expired. */
+export function pendingClaims(cwd: string, bin: string): ClaimBreadcrumb[] {
+  try {
+    const list = JSON.parse(readFileSync(breadcrumbFile(cwd, bin), "utf8")) as ClaimBreadcrumb[];
+    const now = Date.now();
+    return list.filter((c) => !c.expires_at || new Date(c.expires_at).getTime() > now);
+  } catch {
+    return [];
+  }
+}
+
+// ---- doctor --------------------------------------------------------------------------
+
+export interface DoctorCheck {
+  name: string;
+  ok: boolean;
+  detail?: string;
+  fix?: string;
+}
+
+export function summarizeDoctor(checks: DoctorCheck[]): { status: "ok" | "action_required"; checks: DoctorCheck[]; next_steps: string[] } {
+  const failing = checks.filter((c) => !c.ok);
+  return {
+    status: failing.length === 0 ? "ok" : "action_required",
+    checks,
+    next_steps: failing.map((c) => c.fix).filter((f): f is string => Boolean(f)),
+  };
+}