@typeship-ax/cli 0.22.0 → 0.24.0

package/src/cli-agent.ts

@@ -1,5 +1,5 @@
 /**
- * The agent contract of a generated CLI. Generated by typeship — https://typeship.dev
+ * 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
@@ -21,20 +21,25 @@ import { dirname, join, resolve } from "node:path";
 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
+  | "INSUFFICIENT_SCOPE"    // 403 (or missing_scope) on an operation that requires OAuth scopes
   | "PLAN_LIMIT"            // 402: the account's plan stops here
   | "NOT_FOUND"             // 404
   | "INVALID_REQUEST"       // 400/422 the API rejected the input
-  | "SPEC_INVALID"          // 422 whose error code is spec_error
+  | "SPEC_INVALID"          // 422 whose error code is spec_invalid (spec_error before the rename)
   | "RATE_LIMITED"          // 429
   | "SERVER_ERROR"          // 5xx
   | "NETWORK_ERROR"         // no response: DNS, TLS, timeout, refused
   | "VALIDATION_FAILED"     // --validate found parameters or a body that do not match the schema
   | "TTY_REQUIRED"          // a prompt was needed and there is no terminal
+  | "LOGIN_FAILED"          // browser, device or approval login did not complete
+  | "LOGIN_REQUIRED"        // a saved login cannot be used as is; sign in again
+  | "CREDENTIAL_STORE_UNAVAILABLE" // the OS credential store or saved credential file cannot be used
   | "CONFIRMATION_REQUIRED" // a destructive command needs --force
   | "INVALID_USAGE"         // wrong flags or arguments
   | "UNKNOWN_COMMAND"
   | "UNKNOWN_FLAG"
   | "MISSING_ARGUMENT"
+  | "FIELDS_UNMATCHED"      // the call ran, but a --fields path matched nothing in the result
   | "CALL_FAILED";          // anything else
 
 export interface Issue {
@@ -80,6 +85,7 @@ export function exitCodeFor(code: IssueCode): 1 | 2 {
     case "UNKNOWN_COMMAND":
     case "UNKNOWN_FLAG":
     case "MISSING_ARGUMENT":
+    case "FIELDS_UNMATCHED":
     case "TTY_REQUIRED":
     case "CONFIRMATION_REQUIRED":
       return 2;
@@ -91,13 +97,13 @@ export function exitCodeFor(code: IssueCode): 1 | 2 {
 /** Interpret an SDK error result: HTTP status, body, transport, validation. */
 export function classifyApiError(
   error: unknown,
-  context: { bin: string; hadCredential: boolean; docsUrl: string | null },
+  context: { bin: string; envPrefix: string; hadCredential: boolean; docsUrl: string | null; requiredScopes?: string[]; canLogin?: boolean },
 ): EnvelopeInput {
-  const e = (error ?? {}) as { name?: string; message?: string; status?: number; body?: unknown; violations?: unknown; direction?: string; target?: string; response?: { requestId?: string } };
+  const e = (error ?? {}) as { name?: string; message?: string; status?: number; code?: unknown; body?: unknown; violations?: unknown; direction?: string; target?: string; rateLimit?: { retryAt?: Date }; response?: { requestId?: string } };
   // 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.
+  // ("HTTP 404"). 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) {
     const nextStep = e.direction === "response"
@@ -107,12 +113,12 @@ export function classifyApiError(
         : "Correct the body fields named in detail.violations to match their constraints, then run the command again.";
     return { code: "VALIDATION_FAILED", message: base, detail: { ...(e.name ? { error: e.name } : {}), violations: e.violations }, nextSteps: [nextStep] };
   }
-  if (e.name === "TransportError" || (typeof e.status !== "number" && /fetch|ECONN|ENOTFOUND|timed out|TLS|abort/i.test(base))) {
+  if (e.name === "TransportError" || (e.name !== "PaginationError" && 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.",
+        "Check the base URL (--base-url, the " + context.envPrefix + "_BASE_URL variable, or '" + context.bin + " config base-url') and the network.",
         "Retry once with backoff; do not loop.",
       ],
     };
@@ -125,30 +131,93 @@ export function classifyApiError(
     ? (e.body as Record<string, unknown>).request_id ?? (e.body as Record<string, unknown>).requestId
     : undefined;
   const requestId = e.response?.requestId ?? (typeof bodyRequestId === "string" ? bodyRequestId : undefined);
-  const detail = { status, ...(e.name ? { error: e.name } : {}), ...(requestId ? { request_id: requestId } : {}), ...(e.body !== undefined ? { body: e.body } : {}) };
+  // An in-band GraphQL error keeps the vendor's code next to the normalized one.
+  const vendorCode = e.name === "GraphQLRequestError" ? graphqlVendorCode(error) : undefined;
+  const detail = { status, ...(e.name ? { error: e.name } : {}), ...(vendorCode ? { vendor_code: vendorCode } : {}), ...(requestId ? { request_id: requestId } : {}), ...(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."] };
+  // A rate limit can arrive as a 403 (GitHub); the SDK marks it either way.
+  if (status === 429 || e.rateLimit !== undefined) {
+    return { status: "action_required", code: "RATE_LIMITED", message, detail: { ...detail, ...(e.rateLimit?.retryAt ? { retry_at: isoSeconds(e.rateLimit.retryAt) } : {}) }, nextSteps: [rateLimitNextStep(e.rateLimit?.retryAt, "run the same command again")] };
   }
-  if (status === 403) return { code: "AUTH_INVALID", message, detail, nextSteps: ["The credential lacks access to this operation."] };
+  // A failure the API reported inside a 2xx body: classify by its code.
+  const scopes = context.requiredScopes ?? [];
+  const scopeFailure = (): EnvelopeInput => ({ code: "INSUFFICIENT_SCOPE", message: message + " This operation requires the OAuth scopes: " + scopes.join(", ") + ".", detail: { ...detail, required_scopes: scopes }, nextSteps: [
+    context.canLogin ? "Sign in again with those scopes: '" + context.bin + " login --scopes " + scopes.join(",") + "'." : "Use a token granted those scopes.",
+    "If the token already has them, the account may lack access to this resource.",
+  ] });
+  if (e.name === "PayloadError") {
+    if (scopes.length && /^missing_scope$/i.test(String(e.code))) return scopeFailure();
+    const reported = payloadFailureCode(e.code);
+    if (reported === "AUTH_INVALID") return { code: "AUTH_INVALID", message, detail, nextSteps: ["The API rejected the credential (" + String(e.code) + "). Check it is current: '" + context.bin + " auth check'."] };
+    if (reported === "RATE_LIMITED") return { status: "action_required", code: "RATE_LIMITED", message, detail, nextSteps: ["Wait, then run the same command again."] };
+    return { code: "CALL_FAILED", message, detail, nextSteps: ["The API reported a failure in a successful response; detail.body says why."] };
+  }
+  const unauthenticated = (): EnvelopeInput => 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."] };
+  const forbidden = (): EnvelopeInput => scopes.length ? scopeFailure() : { code: "AUTH_INVALID", message, detail, nextSteps: ["The credential lacks access to this operation."] };
+  // An in-band GraphQL error (HTTP 200): classified by the vendor's code.
+  if (e.name === "GraphQLRequestError") {
+    switch (vendorCode === undefined ? undefined : graphqlErrorClass(vendorCode)) {
+      case "not_found": return { code: "NOT_FOUND", message, detail, nextSteps: ["Check the id in the arguments; list the resource first to find the right one."] };
+      case "unauthenticated": return unauthenticated();
+      case "forbidden": return forbidden();
+      case "bad_input": return { code: "INVALID_REQUEST", message, detail, nextSteps: ["The API rejected an argument or the selection; the errors in detail.body name it (message, path). Fix that and run the command again."] };
+      case "rate_limited": return { status: "action_required", code: "RATE_LIMITED", message, detail, nextSteps: [rateLimitNextStep(undefined, "run the same command again")] };
+      default: return { code: "CALL_FAILED", message, detail };
+    }
+  }
+  if (status === 401) return unauthenticated();
+  if (status === 403) return forbidden();
   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 === 422 && (apiCode === "spec_invalid" || 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 detail.request_id."] };
   return { code: "CALL_FAILED", message, detail };
 }
 
+/** Login, saved-session and credential-store failures, recognised by error
+ * name (so this module needs no login runtime) on the error or its cause.
+ * Undefined when the error is none of them. */
+export function classifyAuthFailure(
+  error: unknown,
+  context: { bin: string; envVars: string[]; storeVariable: string },
+): EnvelopeInput | undefined {
+  const login = "'" + context.bin + " login'";
+  const environment = context.envVars.length ? ["Or supply credentials through the environment: " + context.envVars.join(", ") + "."] : [];
+  for (let node = error as { name?: unknown; message?: unknown; code?: unknown; cause?: unknown } | undefined, depth = 0; node && typeof node === "object" && depth < 4; node = node.cause as typeof node, depth++) {
+    const message = typeof node.message === "string" && node.message ? node.message : "Login failed.";
+    switch (node.name) {
+      case "DeviceFlowUnavailableError":
+        return { status: "action_required", code: "LOGIN_FAILED", message, nextSteps: ["Run " + login + " without --device to sign in through the browser.", ...environment] };
+      case "LoginPollingError":
+        if (node.code === "request_failed" && typeof (node as { providerError?: unknown }).providerError === "string") return { code: "LOGIN_FAILED", message, nextSteps: ["The provider rejected the login request. Check the client ID and that the application is registered for this sign-in flow, then run " + login + " again.", ...environment] };
+        if (node.code === "request_failed") return { code: "LOGIN_FAILED", message, nextSteps: ["Check the network and the login service, then run " + login + " again.", ...environment] };
+        if (node.code === "invalid_response") return { code: "LOGIN_FAILED", message, nextSteps: ["The login service's response did not match its contract. Retry " + login + " once; if it persists, report it to the API owner.", ...environment] };
+        return { code: "LOGIN_FAILED", message, nextSteps: ["Run " + login + " again and approve the new request.", ...environment] };
+      case "OAuthResponseError":
+        if (node.code === "request_failed" || node.code === "timed_out") return { code: "NETWORK_ERROR", message: "The OAuth provider could not be reached (" + String(node.code).replace("_", " ") + ").", nextSteps: ["Check the network and the provider, then run " + login + " again."] };
+        return { code: "LOGIN_FAILED", message: "The OAuth provider returned an unusable response (" + String(node.code).replace(/_/g, " ") + ").", nextSteps: ["Run " + login + " again. If it keeps failing, report it to the API owner.", ...environment] };
+      case "OAuthLoginError":
+        return { code: "LOGIN_FAILED", message, nextSteps: ["Run " + login + " again. If it keeps failing, the OAuth application settings may need attention from the API owner.", ...environment] };
+      case "OAuthSessionError":
+        return { status: "action_required", code: "LOGIN_REQUIRED", message, nextSteps: ["Run " + login + " to sign in again.", ...environment] };
+      case "CredentialStorageError":
+        return { status: "action_required", code: "CREDENTIAL_STORE_UNAVAILABLE", message, nextSteps: [
+          "Unlock or enable the OS credential store (macOS Keychain, Linux Secret Service or Windows DPAPI) and retry.",
+          ...environment,
+          "To use a plaintext file store instead, set " + context.storeVariable + "=file and run " + login + ".",
+        ] };
+    }
+  }
+  return undefined;
+}
+
 /** 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[] {
@@ -174,12 +243,46 @@ function extractUrl(body: unknown, keys: string[]): string | undefined {
   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];
+function isoSeconds(at: Date): string {
+  return new Date(Math.ceil(at.getTime() / 1000) * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+/** "Wait until <time>" when the API said when the limit resets. */
+export function rateLimitNextStep(retryAt: Date | undefined, then: string): string {
+  return retryAt instanceof Date && !Number.isNaN(retryAt.getTime())
+    ? "Rate limited: wait until " + isoSeconds(retryAt) + ", then " + then + "."
+    : "Rate limited: back off, then " + then + "; the SDK already honored any Retry-After within its ceiling.";
+}
+
+/** The vendor's own code on an in-band GraphQL error: the first error's
+ * extensions.code, or its type (GitHub). */
+function graphqlVendorCode(error: unknown): string | undefined {
+  const first = (error as { errors?: { extensions?: { code?: unknown }; type?: unknown }[] } | null)?.errors?.[0];
+  const code = first?.extensions?.code ?? first?.type;
+  return typeof code === "string" && code !== "" ? code : undefined;
+}
+
+/** GraphQL error codes whose meaning is settled (Apollo's standard codes,
+ * GitHub's types, Linear's codes), by recovery class. Any other code is
+ * passed through as is, with no guessed next step. The MCP server's
+ * classification uses the same table. */
+function graphqlErrorClass(code: string): "not_found" | "unauthenticated" | "forbidden" | "bad_input" | "rate_limited" | undefined {
+  const c = code.toUpperCase();
+  if (c === "NOT_FOUND") return "not_found";
+  if (c === "UNAUTHENTICATED" || c === "AUTHENTICATION_ERROR") return "unauthenticated";
+  if (c === "FORBIDDEN") return "forbidden";
+  if (c === "BAD_USER_INPUT" || c === "GRAPHQL_VALIDATION_FAILED" || c === "GRAPHQL_PARSE_FAILED" || c === "INPUT_ERROR") return "bad_input";
+  if (c === "RATE_LIMITED" || c === "RATELIMITED") return "rate_limited";
+  return undefined;
+}
+
+/** Error codes APIs report inside a 2xx body (Slack's `error`), mapped to
+ * the stable codes when their meaning is unambiguous. */
+export function payloadFailureCode(code: unknown): "AUTH_INVALID" | "RATE_LIMITED" | undefined {
+  if (typeof code !== "string") return undefined;
+  if (/^(not_authed|invalid_auth|token_revoked|token_expired|account_inactive|unauthorized|unauthenticated|forbidden|access_denied|missing_scope)$/i.test(code)) return "AUTH_INVALID";
+  if (/^(ratelimited|rate_limited|rate_limit_exceeded|too_many_requests)$/i.test(code)) return "RATE_LIMITED";
+  return undefined;
 }
 
 // ---- agent mode -------------------------------------------------------------
@@ -243,6 +346,33 @@ export interface McpClient {
   write: (existing: string, name: string, entry: McpEntry) => string;
   /** True when the client cannot speak the current MCP protocol; skipped by --all. */
   incompatible?: string;
+  /**
+   * How the client expands an environment variable inside a header value.
+   * Entries carry `${VAR}`; each client gets its own spelling, and a client
+   * that expands nothing gets no Authorization header rather than a literal
+   * one it would send as-is. Defaults to "dollar".
+   */
+  headerEnv?: "dollar" | "env-colon" | "brace-env" | "none";
+}
+
+const ENV_REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+/** Rewrite `${VAR}` header references into the client's syntax, or drop the headers that hold one. */
+function entryForClient(client: McpClient, entry: McpEntry): { entry: McpEntry; note?: string } {
+  const style = client.headerEnv ?? "dollar";
+  if (!entry.headers || style === "dollar") return { entry };
+  const headers: Record<string, string> = {};
+  const dropped: string[] = [];
+  for (const [name, value] of Object.entries(entry.headers)) {
+    if (style === "none" && value.search(ENV_REF) !== -1) dropped.push(name);
+    else headers[name] = style === "env-colon" ? value.replace(ENV_REF, "${env:$1}") : style === "brace-env" ? value.replace(ENV_REF, "{env:$1}") : value;
+  }
+  const next: McpEntry = { ...entry };
+  delete next.headers;
+  if (Object.keys(headers).length) next.headers = headers;
+  return dropped.length
+    ? { entry: next, note: client.label + " does not expand environment variables in headers, so the entry omits " + dropped.join(", ") + "; the client signs in with MCP authorization when the server supports it." }
+    : { entry: next };
 }
 
 function readOr(file: string, fallback: string): string {
@@ -280,9 +410,14 @@ function tomlMerge(existing: string, name: string, entry: McpEntry): string {
   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));
+    const envHeaders: string[] = [];
+    for (const [header, value] of Object.entries(entry.headers ?? {})) {
+      const envRef = /\$\{([A-Z0-9_]+)\}/.exec(value)?.[1];
+      if (!envRef) continue;
+      if (header.toLowerCase() === "authorization" && /^Bearer /.test(value)) lines.push("bearer_token_env_var = " + JSON.stringify(envRef));
+      else envHeaders.push(JSON.stringify(header) + " = " + JSON.stringify(envRef));
+    }
+    if (envHeaders.length) lines.push("env_http_headers = { " + envHeaders.join(", ") + " }");
   } else {
     lines.push("command = " + JSON.stringify(entry.command ?? "node"));
     lines.push("args = " + JSON.stringify(entry.args ?? []));
@@ -316,6 +451,7 @@ export const MCP_CLIENTS: McpClient[] = [
     label: "VS Code",
     file: (cwd) => join(cwd, ".vscode", "mcp.json"),
     detect: (cwd) => existsSync(join(cwd, ".vscode")) || existsSync(join(home(), ".vscode")),
+    headerEnv: "env-colon",
     write: (existing, name, entry) => jsonMerge(existing, ["servers"], name, standardEntry(entry)),
   },
   {
@@ -323,6 +459,7 @@ export const MCP_CLIENTS: McpClient[] = [
     label: "Windsurf",
     file: () => join(home(), ".codeium", "windsurf", "mcp_config.json"),
     detect: () => existsSync(join(home(), ".codeium", "windsurf")),
+    headerEnv: "env-colon",
     write: (existing, name, entry) => jsonMerge(existing, ["mcpServers"], name, entry.url ? { serverUrl: entry.url, ...(entry.headers ? { headers: entry.headers } : {}) } : stdioEntry(entry)),
   },
   {
@@ -330,6 +467,7 @@ export const MCP_CLIENTS: McpClient[] = [
     label: "Gemini CLI",
     file: () => join(home(), ".gemini", "settings.json"),
     detect: () => existsSync(join(home(), ".gemini")),
+    headerEnv: "none",
     write: (existing, name, entry) => jsonMerge(existing, ["mcpServers"], name, entry.url ? { httpUrl: entry.url, ...(entry.headers ? { headers: entry.headers } : {}) } : stdioEntry(entry)),
   },
   {
@@ -337,6 +475,7 @@ export const MCP_CLIENTS: McpClient[] = [
     label: "OpenCode",
     file: () => join(xdg(), "opencode", "opencode.json"),
     detect: () => existsSync(join(xdg(), "opencode")),
+    headerEnv: "brace-env",
     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 ?? [])] }),
   },
   {
@@ -344,6 +483,7 @@ export const MCP_CLIENTS: McpClient[] = [
     label: "Zed",
     file: () => join(xdg(), "zed", "settings.json"),
     detect: () => existsSync(join(xdg(), "zed")),
+    headerEnv: "none",
     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 ?? [] }),
   },
   {
@@ -362,10 +502,18 @@ export const MCP_CLIENTS: McpClient[] = [
     label: "Cursor",
     file: (cwd) => join(cwd, ".cursor", "mcp.json"),
     detect: () => existsSync(join(home(), ".cursor")),
+    headerEnv: "env-colon",
     write: (existing, name, entry) => jsonMerge(existing, ["mcpServers"], name, standardEntry(entry)),
   },
 ];
 
+// Every client's write receives entries in its own env-reference syntax,
+// whether it is called through writeMcpConfig or directly.
+for (const client of MCP_CLIENTS) {
+  const write = client.write;
+  client.write = (existing, name, entry) => write(existing, name, entryForClient(client, entry).entry);
+}
+
 export function findMcpClient(id: string): McpClient | undefined {
   return MCP_CLIENTS.find((c) => c.id === id);
 }
@@ -377,17 +525,19 @@ export interface McpWriteResult {
   note?: string;
 }
 
-/** Merge the entry into one client's config file. Never writes a literal secret: callers pass env references. */
+/** Merge the entry into one client's config file. Never writes a literal secret: callers pass `${VAR}` references, which each client receives in its own syntax. */
 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 adapted = entryForClient(client, entry);
   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 } : {}) };
+  const note = [client.incompatible, adapted.note].filter(Boolean).join(" ");
+  return { client: client.id, file, written: true, ...(note ? { note } : {}) };
 }
 
 /** Does a client's config already mention this server? For doctor. */
@@ -469,10 +619,13 @@ export interface AgentContext {
   version: string;
   envPrefix: string;
   authEnvVars: string[];
+  /** The API Spec is silent on authentication: say so instead of "no auth". */
+  authNotDeclared?: boolean;
   docsUrl: string | null;
   docsIndexUrl?: string | null;
   generatedOperationCount?: number;
-  omittedOperations?: { command: string; tool: string; method: string; path: string }[];
+  /** Operations in the API left out of a capped build; api.json lists them. */
+  omittedOperationCount?: number;
   /** 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. */
@@ -481,7 +634,6 @@ export interface AgentContext {
   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;
@@ -489,6 +641,7 @@ export function flagTypeLabel(f: CommandFlagSummary): string {
   return inline(f.enum) ?? f.type;
 }
 
+/** One line per command, pipe-delimited: the compact index that goes into AGENTS.md. */
 export function compactIndex(commands: CommandSummary[]): string {
   return commands
     .map((c) => {
@@ -498,27 +651,55 @@ export function compactIndex(commands: CommandSummary[]): string {
     .join("\n");
 }
 
+/** Bytes of command index the guide and AGENTS.md carry before they switch to one line per resource. */
+export const COMMAND_INDEX_BUDGET = 8_000;
+const RESOURCE_INDEX_NAMES = 12;
+
+/**
+ * One line per resource with its first command names, for an API whose
+ * per-command index would not fit COMMAND_INDEX_BUDGET. Resources past the
+ * budget are counted, not listed; help --json has them all.
+ */
+export function resourceIndex(bin: string, commands: CommandSummary[]): string {
+  const byResource = new Map<string, string[]>();
+  for (const c of commands) byResource.set(c.resource, [...(byResource.get(c.resource) ?? []), c.command]);
+  const lines: string[] = [];
+  let bytes = 0;
+  let listed = 0;
+  for (const [resource, names] of byResource) {
+    const more = names.length - RESOURCE_INDEX_NAMES;
+    const line = resource + ": " + names.slice(0, RESOURCE_INDEX_NAMES).join(", ") + (more > 0 ? ", … +" + more + " more" : "");
+    if (bytes + line.length + 1 > COMMAND_INDEX_BUDGET) break;
+    lines.push(line);
+    bytes += line.length + 1;
+    listed++;
+  }
+  if (listed < byResource.size) lines.push("… " + (byResource.size - listed) + " more resources: " + bin + " help --json");
+  return lines.join("\n");
+}
+
 /** The AGENTS.md block body. */
 export function agentBlock(ctx: AgentContext, commands: CommandSummary[]): string {
   const auth = ctx.authEnvVars.length ? ctx.authEnvVars.join(", ") : "(none)";
-  const index = ctx.docsIndexUrl ?? (ctx.docsUrl ? ctx.docsUrl.replace(/\/+$/, "") + "/llms.txt" : null);
+  const docsIndex = ctx.docsIndexUrl ?? (ctx.docsUrl ? ctx.docsUrl.replace(/\/+$/, "") + "/llms.txt" : null);
+  const index = compactIndex(commands);
   return [
     "## " + ctx.bin + " CLI (" + ctx.apiTitle + ")",
     "",
     "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.",
     "",
-    ...((ctx.omittedOperations?.length ?? 0) > 0 ? ["- Plan limit: generated " + (ctx.generatedOperationCount ?? commands.length) + " of " + ((ctx.generatedOperationCount ?? commands.length) + ctx.omittedOperations!.length) + " operations. Omitted: " + ctx.omittedOperations!.map((op) => "`" + op.tool + "` (" + op.method + " " + op.path + ")").join(", ") + ". These return `PLAN_LIMIT`; upgrade and regenerate before use."] : []),
-    "- 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: " + (index ? "`" + ctx.bin + " docs search <term> --json`; " + index : "`" + ctx.bin + " docs <resource> <command> --json` (a docs URL was not provided at generate time)") + ".",
+    ...((ctx.omittedOperationCount ?? 0) > 0 ? ["- Coverage: this build includes " + (ctx.generatedOperationCount ?? commands.length) + " of " + ((ctx.generatedOperationCount ?? commands.length) + ctx.omittedOperationCount!) + " operations; api.json lists the rest, and calling one returns `PLAN_LIMIT`."] : []),
+    ctx.authNotDeclared
+      ? "- Auth: not declared by the API Spec. If the API needs a token, set " + auth + " or run `" + ctx.bin + " login`; other headers go in `--header \"Name: value\"` or " + ctx.envPrefix + "_HEADERS. Never write a key into a file in this repo."
+      : "- Auth: " + auth + " in the environment, or `" + ctx.bin + " login`. Never write a key into a file in this repo.",
+    "- Discover: `" + ctx.bin + " help --json` indexes resources and command names; `" + ctx.bin + " help <resource> --json` lists a resource's commands; `" + ctx.bin + " help <resource> <command> --json` gives one command's flags. `" + ctx.bin + " help --json --all` prints every command with every flag at once. Humans: `" + ctx.bin + " --help`, `" + ctx.bin + " <resource> <command> --help`.",
+    "- Docs: " + (docsIndex ? "`" + ctx.bin + " docs search <term> --json`; " + docsIndex : "`" + ctx.bin + " docs <resource> <command> --json` (a docs URL was not provided at generate time)") + ".",
     "- 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),
-    "```",
+    ...(Buffer.byteLength(index) <= COMMAND_INDEX_BUDGET
+      ? ["Commands (resource command | METHOD path | required flags | summary):", "", "```", index, "```"]
+      : ["Commands by resource (" + commands.length + " commands; `" + ctx.bin + " help <resource> --json` lists a resource's commands with summaries):", "", "```", resourceIndex(ctx.bin, commands), "```"]),
   ].join("\n");
 }
 
@@ -535,12 +716,12 @@ export function agentGuide(ctx: AgentContext, commands: CommandSummary[]): Recor
     package: ctx.pkg,
     api: ctx.apiTitle,
     version: ctx.version,
-    generated_by: "typeship",
+    generated_by: "Typeship",
     guide: agentBlock(ctx, commands),
     first_command: first ? ctx.bin + " " + first.resource + " " + first.command : ctx.bin + " --help",
     docs_index_url: docsIndexUrl,
     docs_full_url: docsFullUrl,
-    ...((ctx.omittedOperations?.length ?? 0) > 0 ? { coverage: { generated_operations: ctx.generatedOperationCount ?? commands.length, total_operations: (ctx.generatedOperationCount ?? commands.length) + ctx.omittedOperations!.length, omitted_operations: ctx.omittedOperations } } : {}),
+    ...((ctx.omittedOperationCount ?? 0) > 0 ? { coverage: { generated_operations: ctx.generatedOperationCount ?? commands.length, total_operations: (ctx.generatedOperationCount ?? commands.length) + ctx.omittedOperationCount! } } : {}),
     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,
@@ -553,12 +734,13 @@ export function agentGuide(ctx: AgentContext, commands: CommandSummary[]): Recor
       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.",
+      discovery: "help --json is a bounded index of resources and command names. help <resource> --json pages through one resource's commands (next_command), help <resource> <command> --json is one command's flags, docs <resource> <command> --json its complete schemas, and docs search <term> --json finds commands by topic. help --json --all prints every command with every flag; on a large API it is large.",
     },
     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.",
+      "Run '" + ctx.bin + " help --json' for the command index, then '" + ctx.bin + " help <resource> <command> --json' for the command you need.",
       ...(ctx.hasMcp ? ["Run '" + ctx.bin + " mcp install --all' if this session has an MCP-capable client."] : []),
     ],
   };
@@ -704,3 +886,126 @@ export function summarizeDoctor(checks: DoctorCheck[]): { status: "ok" | "action
     next_steps: failing.map((c) => c.fix).filter((f): f is string => Boolean(f)),
   };
 }
+
+/** Every OAuth scope an operation's security requirements name, in order. */
+export function requiredScopes(security: Record<string, string[]>[] | undefined): string[] {
+  return [...new Set((security ?? []).flatMap((requirement) => Object.values(requirement).flat()))];
+}
+
+// ---- request preview (--dry-run) ----------------------------------------------
+
+/** What --dry-run prints: the request an API command would send, with
+ * every credential replaced by "<redacted>". Nothing in it was sent. */
+export interface RequestPreview {
+  dry_run: true;
+  sent: false;
+  message: string;
+  request: {
+    method: string;
+    url: string;
+    path: string;
+    query: Record<string, string | string[]>;
+    headers: Record<string, string>;
+    body?: unknown;
+  };
+}
+
+export const REDACTED = "<redacted>";
+
+/** Header and query names that carry credentials, whatever the API calls
+ * them: Authorization, Cookie, X-Api-Key, api_key, access_token, a session
+ * or signature. */
+const SENSITIVE_NAME = /^(authorization|proxy-authorization|cookie|cookie2|set-cookie)$|api[-_]?key|apikey|token|secret|password|passwd|session|signature|credential|^key$|^auth$/i;
+
+function redactText(text: string, secrets: string[]): string {
+  let out = text;
+  for (const secret of secrets) if (secret.length >= 4) out = out.split(secret).join(REDACTED);
+  return out;
+}
+
+/**
+ * The request a dry run captured, as --dry-run shows it. `sensitiveNames`
+ * are the header and query names the API's security schemes bind; `secrets`
+ * are the resolved credential values, redacted wherever they appear (a
+ * token pasted into a body field, a key in a URL).
+ */
+export async function requestPreview(
+  input: { method: string; url: string; headers: Record<string, string>; body?: unknown },
+  options: { sensitiveNames?: string[]; secrets?: string[] } = {},
+): Promise<RequestPreview> {
+  const secrets = [...new Set((options.secrets ?? []).filter((s) => typeof s === "string" && s.length >= 4))].sort((a, b) => b.length - a.length);
+  const named = new Set((options.sensitiveNames ?? []).map((n) => n.toLowerCase()));
+  const sensitive = (name: string) => named.has(name.toLowerCase()) || SENSITIVE_NAME.test(name);
+  const url = new URL(input.url);
+  const query: Record<string, string | string[]> = {};
+  for (const [name, raw] of url.searchParams) {
+    const value = sensitive(name) ? REDACTED : redactText(raw, secrets);
+    const previous = query[name];
+    query[name] = previous === undefined ? value : Array.isArray(previous) ? [...previous, value] : [previous, value];
+  }
+  const encodedSecrets = [...secrets, ...secrets.map(encodeURIComponent)];
+  const search = [...url.searchParams].map(([name, raw]) => encodeURIComponent(name) + "=" + (sensitive(name) ? REDACTED : redactText(encodeURIComponent(raw), encodedSecrets))).join("&");
+  const shownUrl = url.origin + redactText(url.pathname, encodedSecrets) + (search ? "?" + search : "");
+  const headers: Record<string, string> = {};
+  for (const [name, value] of Object.entries(input.headers)) {
+    headers[name] = sensitive(name) ? REDACTED : redactText(value, secrets);
+  }
+  const contentType = Object.entries(input.headers).find(([name]) => name.toLowerCase() === "content-type")?.[1] ?? "";
+  const body = await previewBody(input.body, contentType, secrets);
+  return {
+    dry_run: true,
+    sent: false,
+    message: "Dry run: nothing was sent to the API. This is the request the command would send, with credentials redacted.",
+    request: {
+      method: input.method,
+      url: shownUrl,
+      path: redactText(url.pathname, encodedSecrets),
+      query,
+      headers,
+      ...(body !== undefined ? { body } : {}),
+    },
+  };
+}
+
+async function previewBody(body: unknown, contentType: string, secrets: string[]): Promise<unknown> {
+  if (body === undefined || body === null) return undefined;
+  const redactValue = (value: unknown): unknown => {
+    if (typeof value === "string") return redactText(value, secrets);
+    if (Array.isArray(value)) return value.map(redactValue);
+    if (value && typeof value === "object") return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([k, v]) => [k, SENSITIVE_NAME.test(k) && typeof v === "string" && secrets.some((s) => v.includes(s)) ? REDACTED : redactValue(v)]));
+    return value;
+  };
+  if (typeof body === "string") {
+    if (/json/i.test(contentType)) {
+      try { return redactValue(JSON.parse(body)); } catch { /* shown as text */ }
+    }
+    return redactText(body, secrets);
+  }
+  if (typeof FormData !== "undefined" && body instanceof FormData) {
+    const parts: Record<string, unknown>[] = [];
+    for (const [name, value] of body.entries()) {
+      parts.push(typeof value === "string"
+        ? { name, value: redactText(value, secrets) }
+        : { name, filename: (value as File).name, ...((value as Blob).type ? { type: (value as Blob).type } : {}), bytes: (value as Blob).size });
+    }
+    return { multipart: parts };
+  }
+  if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) return redactText(body.toString(), secrets);
+  if (typeof Blob !== "undefined" && body instanceof Blob) return { binary: true, bytes: body.size, ...(body.type ? { type: body.type } : {}) };
+  if (body instanceof Uint8Array || body instanceof ArrayBuffer) return { binary: true, bytes: body.byteLength };
+  return { stream: true };
+}
+
+/** --dry-run for a person: the request line, then query, headers and body. */
+export function formatRequestPreview(preview: RequestPreview): string {
+  const { request } = preview;
+  const lines = ["Dry run: nothing was sent. Credentials are redacted.", "", request.method + " " + request.url];
+  const headers = Object.entries(request.headers);
+  if (headers.length) lines.push("", "Headers:", ...headers.map(([name, value]) => "  " + name + ": " + value));
+  if (request.body !== undefined) {
+    lines.push("", "Body:");
+    const text = typeof request.body === "string" ? request.body : JSON.stringify(request.body, null, 2);
+    lines.push(...text.split("\n").map((line) => "  " + line));
+  }
+  return lines.join("\n") + "\n";
+}