@typeship-ax/cli 0.22.0 → 0.23.1

package/dist/cli-agent.js

@@ -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
@@ -27,6 +27,7 @@ export function exitCodeFor(code) {
         case "UNKNOWN_COMMAND":
         case "UNKNOWN_FLAG":
         case "MISSING_ARGUMENT":
+        case "FIELDS_UNMATCHED":
         case "TTY_REQUIRED":
         case "CONFIRMATION_REQUIRED":
             return 2;
@@ -38,9 +39,9 @@ export function exitCodeFor(code) {
 export function classifyApiError(error, context) {
     const e = (error ?? {});
     // 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"
@@ -50,12 +51,12 @@ export function classifyApiError(error, context) {
                 : "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.",
             ],
         };
@@ -72,11 +73,33 @@ export function classifyApiError(error, context) {
     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 = () => ({ 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) {
@@ -84,11 +107,7 @@ export function classifyApiError(error, context) {
     }
     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")
+    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."] };
@@ -96,6 +115,43 @@ export function classifyApiError(error, context) {
         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, context) {
+    const login = "'" + context.bin + " login'";
+    const environment = context.envVars.length ? ["Or supply credentials through the environment: " + context.envVars.join(", ") + "."] : [];
+    for (let node = error, depth = 0; node && typeof node === "object" && depth < 4; node = node.cause, 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.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) {
@@ -122,13 +178,25 @@ function extractUrl(body, keys) {
     }
     return undefined;
 }
-function extractRetryAfter(e) {
-    const headers = e.headers;
-    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) {
+    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, then) {
+    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) {
+    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;
 }
 /**
  * --mode agent beats <PREFIX>_MODE=agent beats "no terminal on either end".
@@ -166,6 +234,28 @@ export function detectHarness(env = process.env) {
         return "devin";
     return null;
 }
+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, entry) {
+    const style = client.headerEnv ?? "dollar";
+    if (!entry.headers || style === "dollar")
+        return { entry };
+    const headers = {};
+    const dropped = [];
+    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 = { ...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, fallback) {
     try {
         return readFileSync(file, "utf8");
@@ -201,10 +291,18 @@ function tomlMerge(existing, name, entry) {
     const lines = [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 = [];
+        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"));
@@ -238,6 +336,7 @@ export const MCP_CLIENTS = [
         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)),
     },
     {
@@ -245,6 +344,7 @@ export const MCP_CLIENTS = [
         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)),
     },
     {
@@ -252,6 +352,7 @@ export const MCP_CLIENTS = [
         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)),
     },
     {
@@ -259,6 +360,7 @@ export const MCP_CLIENTS = [
         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 ?? [])] }),
     },
     {
@@ -266,6 +368,7 @@ export const MCP_CLIENTS = [
         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 ?? [] }),
     },
     {
@@ -284,23 +387,32 @@ export const MCP_CLIENTS = [
         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) {
     return MCP_CLIENTS.find((c) => c.id === id);
 }
-/** 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, cwd, name, entry) {
     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. */
 export function mcpConfigured(client, cwd, name) {
@@ -371,8 +483,10 @@ export function agentBlock(ctx, commands) {
         "",
         "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`.",
@@ -401,12 +515,12 @@ export function agentGuide(ctx, commands) {
         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,
@@ -544,3 +658,7 @@ export function summarizeDoctor(checks) {
         next_steps: failing.map((c) => c.fix).filter((f) => Boolean(f)),
     };
 }
+/** Every OAuth scope an operation's security requirements name, in order. */
+export function requiredScopes(security) {
+    return [...new Set((security ?? []).flatMap((requirement) => Object.values(requirement).flat()))];
+}