@typeship-ax/cli 0.6.0

package/dist/cli-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-agent.d.ts","sourceRoot":"","sources":["../src/cli-agent.ts"],"names":[],"mappings":"AAgBA;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,cAAc,GACd,YAAY,GACZ,WAAW,GACX,iBAAiB,GACjB,cAAc,GACd,cAAc,GACd,cAAc,GACd,eAAe,GACf,mBAAmB,GACnB,cAAc,GACd,uBAAuB,GACvB,eAAe,GACf,iBAAiB,GACjB,cAAc,GACd,kBAAkB,GAClB,gBAAgB,CAAC;AAErB,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,qGAAqG;IACrG,MAAM,EAAE,OAAO,GAAG,iBAAiB,CAAC;IACpC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ,CAQvD;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,CAAC,GAAG,CAAC,CAYlD;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACvE,aAAa,CA8Cf;AAqCD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACvC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAMxD;AAED,uGAAuG;AACvG,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,IAAI,CAUjF;AAID,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,GAAG,KAAK,GAAG,gBAAgB,CAAC;AAE5I,MAAM,WAAW,QAAQ;IACvB,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,yEAAyE;IACzE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,+CAA+C;IAC/C,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,KAAK,MAAM,CAAC;IACnE,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAqDD,eAAO,MAAM,WAAW,EAAE,SAAS,EAqElC,CAAC;AAEF,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAE/D;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,iHAAiH;AACjH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,cAAc,CAU5G;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAGnF;AAID;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAiB/G;AAMD,sHAAsH;AACtH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAMjF;AAID,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC1C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,kEAAkE;IAClE,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IACxC,KAAK,EAAE,kBAAkB,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,sDAAsD;IACtD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wFAAwF;AACxF,oGAAoG;AACpG,wBAAgB,aAAa,CAAC,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAI3D;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,MAAM,CAO/D;AAED,gCAAgC;AAChC,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,MAAM,CAmBhF;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiCjG;AAID,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC3C,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,yHAAyH;AACzH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAAG,mBAAmB,CAUjI;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAQ/F;AAED;;0EAE0E;AAC1E,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAOnG;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAWtI;AAID;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,OAAO,CAOxF;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,CAgBpF;AAED,4CAA4C;AAC5C,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAQzE;AAID,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG;IAAE,MAAM,EAAE,IAAI,GAAG,iBAAiB,CAAC;IAAC,MAAM,EAAE,WAAW,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAOxI"}

package/dist/cli-agent.js

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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}