@typeship-ax/cli 0.22.0 → 0.23.1

package/src/arguments.ts

@@ -0,0 +1,242 @@
+/**
+ * Argument checks shared by the generated CLI and MCP server: coerce a value
+ * toward its schema where the intent is unambiguous, and report every
+ * problem, nested ones included, with the dotted path of the argument it
+ * belongs to. Generated by Typeship — https://typeship.dev
+ * No external dependencies.
+ */
+
+import { dateKindOf, relativeDate } from "./dates.js";
+
+export interface ArgumentIssue {
+  code: "UNKNOWN_ARGUMENT" | "INVALID_ARGUMENT" | "MISSING_ARGUMENT";
+  argument: string;
+  message: string;
+}
+
+export const normalizeName = (name: string): string => name.toLowerCase().replace(/[^a-z0-9]/g, "");
+
+function editDistance(a: string, b: string): number {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0]!;
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = prev[j]!;
+      prev[j] = Math.min(prev[j]! + 1, prev[j - 1]! + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+      diag = tmp;
+    }
+  }
+  return prev[b.length]!;
+}
+
+/** The closest accepted name: same letters ignoring case/punctuation first,
+ * then a small edit distance. Undefined when nothing is close. */
+export function closestName(name: string, known: string[]): string | undefined {
+  const exact = known.filter((k) => normalizeName(k) === normalizeName(name));
+  if (exact.length === 1) return exact[0];
+  if (exact.length > 1) return undefined;
+  let best: { name: string; d: number } | undefined;
+  for (const k of known) {
+    const d = editDistance(name.toLowerCase(), k.toLowerCase());
+    if (d <= Math.max(1, Math.floor(k.length / 4)) && (best === undefined || d < best.d)) best = { name: k, d };
+  }
+  return best?.name;
+}
+
+function schemaTypes(schema: Record<string, unknown>): string[] {
+  const t = schema.type;
+  if (typeof t === "string") return [t];
+  if (Array.isArray(t)) return t.filter((x): x is string => typeof x === "string");
+  return [];
+}
+
+/**
+ * Coerce one value toward its schema when the intent is unambiguous: the
+ * strings agents produce for booleans and numbers, a JSON string for an
+ * object or array, a scalar for a one-element array, an enum member in the
+ * wrong case. Returns the value to send, or a message when it can't be made
+ * to fit. Untyped schemas (unions, anything) pass through. The first
+ * problem only; checkValue reports every nested one.
+ */
+export function coerceValue(value: unknown, schema: Record<string, unknown>): { value: unknown } | { error: string } {
+  const issues: ArgumentIssue[] = [];
+  const out = checkValue(value, schema, "", issues);
+  return issues.length > 0 ? { error: issues[0]!.message } : { value: out };
+}
+
+/** Coerce one scalar-level value (type and enum) without looking inside it. */
+function coerceShallow(value: unknown, schema: Record<string, unknown>): { value: unknown } | { error: string } {
+  if (value === null || value === undefined) return { value };
+  // Date-shaped arguments take relative forms (-P7D, 7 days ago, today),
+  // resolved here so the API sees an absolute value.
+  const dateKind = dateKindOf(schema.format);
+  if (dateKind && typeof value === "string") {
+    const resolved = relativeDate(value, dateKind);
+    if (resolved && "error" in resolved) return { error: resolved.error };
+    if (resolved) value = resolved.value;
+  }
+  const types = schemaTypes(schema);
+  const enumValues = Array.isArray(schema.enum) ? schema.enum : undefined;
+  const accepts = (t: string) => types.length === 0 || types.includes(t);
+  const kind = Array.isArray(value) ? "array" : typeof value;
+
+  let out: unknown = value;
+  if (types.length > 0) {
+    if (kind === "boolean" && !accepts("boolean")) {
+      if (accepts("string")) out = String(value);
+      else return { error: "expected " + types.join(" or ") + ", got boolean" };
+    } else if (kind === "number" && !accepts("number") && !accepts("integer")) {
+      if (accepts("string")) out = String(value);
+      else if (accepts("array")) out = [value];
+      else return { error: "expected " + types.join(" or ") + ", got number" };
+    } else if (kind === "number" && accepts("integer") && !accepts("number") && !Number.isInteger(value)) {
+      return { error: "expected an integer, got " + String(value) };
+    } else if (kind === "string" && !accepts("string")) {
+      const s = (value as string).trim();
+      if (accepts("boolean") && /^(true|false|yes|no|1|0)$/i.test(s)) out = /^(true|yes|1)$/i.test(s);
+      else if ((accepts("integer") || accepts("number")) && s !== "" && !Number.isNaN(Number(s))) {
+        const n = Number(s);
+        if (accepts("integer") && !accepts("number") && !Number.isInteger(n)) return { error: "expected an integer, got \"" + s + "\"" };
+        out = n;
+      } else if ((accepts("object") || accepts("array")) && /^[[{]/.test(s)) {
+        try {
+          const parsed: unknown = JSON.parse(s);
+          const parsedKind = Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed;
+          if (!accepts(parsedKind)) return { error: "expected " + types.join(" or ") + ", got a JSON " + parsedKind + " in a string" };
+          out = parsed;
+        } catch {
+          return { error: "expected " + types.join(" or ") + ", got a string that is not valid JSON" };
+        }
+      } else if (accepts("array")) {
+        out = [value];
+      } else {
+        return { error: "expected " + types.join(" or ") + ", got string" };
+      }
+    } else if (kind === "object" && !accepts("object")) {
+      if (accepts("array")) out = [value];
+      else return { error: "expected " + types.join(" or ") + ", got object" };
+    } else if (kind === "array" && !accepts("array")) {
+      return { error: "expected " + types.join(" or ") + ", got array" };
+    }
+  }
+
+  if (enumValues && typeof out === "string" && !enumValues.includes(out)) {
+    const match = enumValues.filter((e) => typeof e === "string" && e.toLowerCase() === (out as string).toLowerCase());
+    if (match.length === 1) out = match[0];
+    else return { error: "must be one of " + enumValues.map((e) => JSON.stringify(e)).join(", ") + ", got " + JSON.stringify(out) };
+  }
+  return { value: out };
+}
+
+/** A nullable single-variant union (`anyOf: [X, {type: "null"}]`, the shape
+ * nullable GraphQL enums and objects take) validates as X; any other union
+ * passes through unchecked. */
+function nullableVariant(schema: Record<string, unknown>): Record<string, unknown> | undefined {
+  const variants = schema.anyOf ?? schema.oneOf;
+  if (!Array.isArray(variants) || variants.length !== 2 || schema.type !== undefined) return undefined;
+  const isNull = (v: unknown) => Boolean(v) && typeof v === "object" && (v as Record<string, unknown>).type === "null";
+  const others = variants.filter((v) => !isNull(v));
+  if (others.length !== 1 || !others[0] || typeof others[0] !== "object") return undefined;
+  return others[0] as Record<string, unknown>;
+}
+
+const MAX_CHECK_DEPTH = 16;
+
+/**
+ * Check one argument value against its schema, the way prepareCall checks
+ * top-level arguments, and return the value to send. Recurses into array
+ * items and object properties: types and enums are coerced where the intent
+ * is clear, required properties must be present, strings must match their
+ * pattern, and keys an object declares closed (`additionalProperties:
+ * false`, as every GraphQL input type is) must be known. Every problem is
+ * pushed to issues with its dotted path (input.priority, items[0].name).
+ */
+export function checkValue(
+  value: unknown,
+  schema: Record<string, unknown>,
+  path: string,
+  issues: ArgumentIssue[],
+  options: { skipPattern?: boolean; depth?: number } = {},
+): unknown {
+  const depth = options.depth ?? 0;
+  const at = (suffix: string) => path === "" ? suffix : path + ": " + suffix;
+  if (value === null || value === undefined) return value;
+  const variant = nullableVariant(schema);
+  if (variant) return checkValue(value, variant, path, issues, options);
+
+  const shallow = coerceShallow(value, schema);
+  if ("error" in shallow) {
+    issues.push({ code: "INVALID_ARGUMENT", argument: path, message: at(shallow.error) });
+    return value;
+  }
+  let out = shallow.value;
+  if (depth >= MAX_CHECK_DEPTH) return out;
+
+  if (typeof out === "string" && typeof schema.pattern === "string" && !options.skipPattern) {
+    let pattern: RegExp | undefined;
+    try { pattern = new RegExp(schema.pattern, "u"); } catch {
+      try { pattern = new RegExp(schema.pattern); } catch { /* not an ECMAScript pattern: never false-alarm */ }
+    }
+    if (pattern && !pattern.test(out)) {
+      issues.push({ code: "INVALID_ARGUMENT", argument: path, message: at("must match the pattern " + schema.pattern + ", got " + JSON.stringify(out)) });
+    }
+  }
+
+  // Array items: check each against the items schema when it has one.
+  if (Array.isArray(out) && schema.items && typeof schema.items === "object" && !Array.isArray(schema.items)) {
+    const itemSchema = schema.items as Record<string, unknown>;
+    out = out.map((item, i) => checkValue(item, itemSchema, path + "[" + i + "]", issues, { depth: depth + 1 }));
+  }
+
+  // Object properties: the same checks one level down, keyed by dotted path.
+  if (out && typeof out === "object" && !Array.isArray(out) && schema.properties && typeof schema.properties === "object") {
+    const properties = schema.properties as Record<string, Record<string, unknown>>;
+    const known = Object.keys(properties);
+    const closed = schema.additionalProperties === false;
+    const input = out as Record<string, unknown>;
+    const next: Record<string, unknown> = {};
+    const child = (key: string) => path === "" ? key : path + "." + key;
+    for (const [key, entry] of Object.entries(input)) {
+      if (entry === undefined) continue;
+      let name = key;
+      if (properties[key] === undefined && closed) {
+        const close = closestName(key, known);
+        if (close !== undefined && normalizeName(close) === normalizeName(key) && input[close] === undefined) {
+          name = close;
+        } else {
+          const accepted = known.length <= 20 ? " Accepted: " + known.join(", ") + "." : "";
+          issues.push({
+            code: "UNKNOWN_ARGUMENT",
+            argument: child(key),
+            message: "Unknown property \"" + child(key) + "\"" + (close !== undefined ? "; did you mean \"" + child(close) + "\"?" : ".") + accepted,
+          });
+          continue;
+        }
+      }
+      const propSchema = properties[name];
+      next[name] = propSchema && typeof propSchema === "object"
+        ? checkValue(entry, propSchema, child(name), issues, { depth: depth + 1, skipPattern: typeof entry === "string" && isMeReference(name, entry) })
+        : entry;
+    }
+    for (const name of Array.isArray(schema.required) ? schema.required as string[] : []) {
+      if (next[name] === undefined && properties[name] !== undefined) {
+        const description = properties[name]!.description;
+        issues.push({ code: "MISSING_ARGUMENT", argument: child(name), message: "Missing required property \"" + child(name) + "\"" + (description ? ": " + String(description).split("\n")[0] : ".") });
+      }
+    }
+    out = next;
+  }
+  return out;
+}
+
+export function userShapedReference(name: string): boolean {
+  const normalized = name.toLowerCase().replace(/[^a-z0-9]/g, "").replace(/ids?$/, "");
+  return ["user", "assignee", "owner", "member", "actor", "creator", "account", "profile", "subscriber"].includes(normalized);
+}
+
+/** "me" given for a user-shaped argument or property, resolved to the
+ * caller's ID through the identity tool. */
+export function isMeReference(name: string, value: string): boolean {
+  return value.trim().toLowerCase() === "me" && userShapedReference(name);
+}

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.",
       ],
     };
@@ -129,26 +135,77 @@ export function classifyApiError(
   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"]);
+  // 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")] };
+  }
+  // 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."] };
+  }
   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 && scopes.length) return scopeFailure();
   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 === 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 +231,24 @@ 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.";
+}
+
+/** 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 +312,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 +376,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 +417,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 +425,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 +433,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 +441,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 +449,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 +468,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 +491,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 +585,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. */
@@ -507,8 +626,10 @@ export function agentBlock(ctx: AgentContext, commands: CommandSummary[]): strin
     "",
     "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.",
+    ...((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`, `" + 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)") + ".",
     "- Lists: `--all` streams every page as NDJSON. Destructive commands need `--force`.",
@@ -535,12 +656,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,
@@ -704,3 +825,8 @@ 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()))];
+}