@spec0/cli 0.1.0

package/dist/commands/api/show.js

@@ -0,0 +1,88 @@
+/**
+ * spec0 api show <ref> — single-API metadata.
+ *
+ * Backed by GET /apis/{apiId}/summary. Resolves <ref> via ref-resolver:
+ * accepts <org>/<api>, bare <api>, or a UUID.
+ */
+import chalk from "chalk";
+import { createOrgApiClient, is401 } from "../../lib/api-client.js";
+import { requireOrgContext } from "../../lib/auth-context.js";
+import { ExitCode } from "../../lib/exit-codes.js";
+import { emit, fail, resolveOutputContext } from "../../lib/output/index.js";
+import { resolveRef, resolveApiId } from "../../lib/ref-resolver.js";
+import { getDefaultOrgId, getOrgConfig } from "../../lib/config.js";
+export function registerApiShowCommand(api) {
+    api
+        .command("show <ref>")
+        .description("Show metadata for a single API (no spec body).")
+        .option("--org <uuid>", "Org id override")
+        .option("--output <format>", "Output format: text, json, or yaml (default: text)")
+        .action(async (ref, opts) => {
+        const outCtx = resolveOutputContext(opts);
+        let authCtx;
+        try {
+            authCtx = requireOrgContext(opts.org);
+        }
+        catch (e) {
+            fail(outCtx, ExitCode.AUTH_MISSING, e.message, {
+                hint: "Set SPEC0_TOKEN + SPEC0_ORG_ID, or run 'spec0 auth login'.",
+            });
+        }
+        const defaultOrg = (() => {
+            const id = process.env.PLATFORM_ORG_ID ?? getDefaultOrgId();
+            return id ? getOrgConfig(id)?.name : undefined;
+        })();
+        let parsed;
+        try {
+            parsed = resolveRef(ref, { defaultOrg });
+        }
+        catch (e) {
+            fail(outCtx, ExitCode.USAGE, e.message);
+        }
+        const client = createOrgApiClient(authCtx);
+        try {
+            const apiId = await resolveApiId(client, parsed);
+            const res = (await client.getJson(`/apis/${apiId}/summary`));
+            if (!res.api) {
+                fail(outCtx, ExitCode.NOT_FOUND, `No API found for ref '${ref}'.`, {
+                    hint: "Run 'spec0 api list' to see what exists in this org.",
+                });
+            }
+            emit(outCtx, res.api, renderApiShowText);
+        }
+        catch (err) {
+            if (is401(err)) {
+                fail(outCtx, ExitCode.AUTH_MISSING, "Token invalid or expired.", {
+                    hint: "Run 'spec0 auth login' or refresh SPEC0_TOKEN.",
+                });
+            }
+            if (err.message?.includes("No API named")) {
+                fail(outCtx, ExitCode.NOT_FOUND, err.message, {
+                    hint: "Run 'spec0 api list' to see what exists in this org.",
+                });
+            }
+            fail(outCtx, ExitCode.GENERIC, `api show failed: ${err.message}`);
+        }
+    });
+}
+function renderApiShowText(api) {
+    const lines = [];
+    lines.push(chalk.bold(`${api.apiName ?? "?"} ${chalk.gray(`v${api.version ?? "?"}`)}`));
+    if (api.description)
+        lines.push(api.description);
+    lines.push("");
+    lines.push(`  status:       ${api.status ?? "—"}`);
+    lines.push(`  team:         ${api.teamName ?? "—"}`);
+    lines.push(`  apiId:        ${api.apiId ?? "—"}`);
+    lines.push(`  operations:   ${api.operations?.length ?? 0}`);
+    lines.push(`  environments: ${api.apiEnvConfigs?.length ?? 0}`);
+    lines.push(`  subscribers:  ${api.subscriberCount ?? 0}`);
+    if (api.specSourceType)
+        lines.push(`  specSource:   ${api.specSourceType}`);
+    if (api.githubBlobUrl)
+        lines.push(`  github:       ${api.githubBlobUrl}`);
+    if (api.updatedAt)
+        lines.push(`  updated:      ${api.updatedAt}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=show.js.map

package/dist/commands/api/show.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"show.js","sourceRoot":"","sources":["../../../src/commands/api/show.ts"],"names":[],"mappings":"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"}

package/dist/commands/auth.d.ts

@@ -0,0 +1,6 @@
+/**
+ * spec0 auth login | logout | status | token | switch
+ */
+import { Command } from "commander";
+export declare function registerAuthCommands(program: Command): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/commands/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0CpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QAoJpD"}

package/dist/commands/auth.js

@@ -0,0 +1,166 @@
+/**
+ * spec0 auth login | logout | status | token | switch
+ */
+import chalk from "chalk";
+import { createServer } from "http";
+import { randomBytes } from "crypto";
+import open from "open";
+import { getConfig, getDefaultOrgId, getOrgConfig, setOrgConfig, setDefaultOrg, clearConfig, } from "../lib/config.js";
+import { resolvedPlatformAppUrl, resolvedPlatformApiUrl } from "../lib/platform-defaults.js";
+import { ExitCode, exit } from "../lib/exit-codes.js";
+function getAppUrl() {
+    return resolvedPlatformAppUrl();
+}
+function getApiUrl() {
+    return resolvedPlatformApiUrl();
+}
+function printAuthStatus() {
+    const defaultOrgId = getDefaultOrgId();
+    if (!defaultOrgId) {
+        console.log(chalk.yellow("Not logged in. Run 'spec0 auth login'."));
+        console.log(chalk.gray("For CI/CD, set SPEC0_TOKEN and SPEC0_ORG_ID environment variables."));
+        return;
+    }
+    const org = getOrgConfig(defaultOrgId);
+    if (!org) {
+        console.log(chalk.yellow("Org config missing. Run 'spec0 auth login'."));
+        return;
+    }
+    console.log(chalk.green("✓ Logged in"));
+    console.log(`  Org:     ${org.name}`);
+    console.log(`  API URL: ${org.apiUrl}`);
+    console.log(`  Key:     ${org.keyName ?? "(unnamed)"}`);
+}
+export function registerAuthCommands(program) {
+    // Top-level whoami shorthand
+    program
+        .command("whoami")
+        .description("Show the active org and authentication state")
+        .action(printAuthStatus);
+    const auth = program.command("auth").description("Authentication and org management");
+    auth
+        .command("login")
+        .description("Log in via browser and store credentials in ~/.spec0/config.json")
+        .option("--app-url <url>", "Web app origin for /cli-auth (overrides SPEC0_APP_URL)")
+        .option("--api-url <url>", "Backend API base (overrides SPEC0_API_URL)")
+        .action(async (opts) => {
+        const appUrl = opts.appUrl ?? getAppUrl();
+        const state = randomBytes(16).toString("hex");
+        const port = 38473 + (Math.floor(Math.random() * 1000) % 1000);
+        const redirectUri = `http://127.0.0.1:${port}/callback`;
+        const authUrl = new URL("/cli-auth", appUrl);
+        authUrl.searchParams.set("state", state);
+        authUrl.searchParams.set("redirect_uri", redirectUri);
+        console.log(chalk.blue("Opening browser for authentication..."));
+        console.log(chalk.gray(`If the browser doesn't open, visit: ${authUrl.toString()}`));
+        const result = await new Promise((resolve) => {
+            let resolved = false;
+            const doResolve = (r) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                resolve(r);
+            };
+            const server = createServer((req, res) => {
+                const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+                if (url.pathname === "/callback") {
+                    const token = url.searchParams.get("token");
+                    const orgId = url.searchParams.get("org");
+                    const orgName = url.searchParams.get("org_name") ?? "default";
+                    if (token && orgId) {
+                        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                        res.end(`<!DOCTYPE html><html><head><title>Spec0 CLI</title></head><body><p style="font-family:sans-serif;padding:2rem;">Authorization complete. You can close this window and return to the terminal.</p></body></html>`);
+                        doResolve({ token, orgId, orgName });
+                    }
+                    else {
+                        res.writeHead(400, { "Content-Type": "text/plain" });
+                        res.end("Missing token or org. Please try again.");
+                        doResolve({ error: "Missing token or org" });
+                    }
+                }
+                else {
+                    res.writeHead(404);
+                    res.end();
+                }
+                server.close();
+            });
+            server.listen(port, "127.0.0.1", () => {
+                open(authUrl.toString()).catch(() => { });
+            });
+            server.on("error", (err) => {
+                doResolve({ error: err.message });
+            });
+            const timeout = setTimeout(() => {
+                if (!resolved && server.listening) {
+                    server.close();
+                    doResolve({
+                        error: "Login timed out. Run 'spec0 auth login' again, or set SPEC0_TOKEN and SPEC0_ORG_ID for non-interactive use.",
+                    });
+                }
+            }, 120000);
+            server.on("close", () => clearTimeout(timeout));
+        });
+        if ("error" in result) {
+            console.error(chalk.red(result.error));
+            // Login-flow failed mid-way (browser closed, timeout, port error). Not
+            // "no creds" — the user tried to authenticate and the flow couldn't
+            // complete. Treat as generic failure; callers see a non-zero exit.
+            exit(ExitCode.GENERIC);
+        }
+        const keyName = `CLI — ${new Date().toISOString().slice(0, 10)}`;
+        const apiUrlForStore = opts.apiUrl?.trim()
+            ? opts.apiUrl.trim().replace(/\/$/, "")
+            : getApiUrl();
+        setOrgConfig(result.orgId, {
+            apiKey: result.token,
+            name: result.orgName,
+            apiUrl: apiUrlForStore,
+            keyName,
+        });
+        const config = getConfig();
+        if (!config.defaultOrg) {
+            setDefaultOrg(result.orgId);
+        }
+        console.log(chalk.green("Logged in successfully."));
+        console.log(`  Org: ${result.orgName}`);
+        console.log(`  API: ${apiUrlForStore}`);
+        console.log(`  Key: ${keyName}`);
+    });
+    auth
+        .command("logout")
+        .description("Deactivate key on server and clear local config")
+        .action(async () => {
+        clearConfig();
+        console.log(chalk.green("Logged out. Config cleared."));
+    });
+    auth
+        .command("status")
+        .description("Show the active org and authentication state")
+        .action(printAuthStatus);
+    auth
+        .command("token")
+        .description("Print token (for scripting: spec0 auth token | pbcopy)")
+        .action(async () => {
+        const defaultOrgId = getDefaultOrgId();
+        if (!defaultOrgId)
+            exit(ExitCode.AUTH_MISSING);
+        const org = getOrgConfig(defaultOrgId);
+        if (!org)
+            exit(ExitCode.AUTH_MISSING);
+        console.log(org.apiKey);
+    });
+    auth
+        .command("switch <org-name>")
+        .description("Switch default org")
+        .action(async (orgName) => {
+        const config = getConfig();
+        const entry = Object.entries(config.orgs).find(([, o]) => o.name === orgName);
+        if (!entry) {
+            console.error(chalk.red(`Org '${orgName}' not found.`));
+            exit(ExitCode.NOT_FOUND);
+        }
+        setDefaultOrg(entry[0]);
+        console.log(chalk.green(`Switched to org: ${orgName}`));
+    });
+}
+//# sourceMappingURL=auth.js.map

package/dist/commands/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"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"}

package/dist/commands/ci/generate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * spec0 ci generate github — emit a ready-to-commit GitHub Actions workflow.
+ *
+ * Wraps GET /api-management/cli/v1/ci-config. The backend renders the
+ * workflow YAML (including auth-secret references and the spec path filter),
+ * so the user just needs to drop it into `.github/workflows/`.
+ */
+import { Command } from "commander";
+export declare function registerCiGenerateCommand(ci: Command): void;
+//# sourceMappingURL=generate.d.ts.map

package/dist/commands/ci/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/ci/generate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBpC,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,OAAO,QA6EpD"}

package/dist/commands/ci/generate.js

@@ -0,0 +1,72 @@
+/**
+ * spec0 ci generate github — emit a ready-to-commit GitHub Actions workflow.
+ *
+ * Wraps GET /api-management/cli/v1/ci-config. The backend renders the
+ * workflow YAML (including auth-secret references and the spec path filter),
+ * so the user just needs to drop it into `.github/workflows/`.
+ */
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import chalk from "chalk";
+import { createOrgApiClient, is401 } from "../../lib/api-client.js";
+import { requireOrgContext } from "../../lib/auth-context.js";
+import { ExitCode } from "../../lib/exit-codes.js";
+import { emit, fail, progress, resolveOutputContext, } from "../../lib/output/index.js";
+export function registerCiGenerateCommand(ci) {
+    ci.command("generate")
+        .argument("<provider>", "CI provider (currently supported: github)")
+        .description("Generate a workflow file for <provider> that runs 'spec0 publish' on push.")
+        .option("--spec-file <path>", "Path to OpenAPI spec file", "openapi.yaml")
+        .option("--api-name <name>", "API name to embed in the workflow (default: spec filename)")
+        .option("--branch <branch>", "Git branch that triggers the workflow", "main")
+        .option("--write", "Write the workflow to its suggested path (default: print to stdout)")
+        .option("--org <uuid>", "Org id override")
+        .option("--output <format>", "Output format for metadata: text, json, yaml (default: text)")
+        .action(async (provider, opts) => {
+        const outCtx = resolveOutputContext(opts);
+        if (provider.toLowerCase() !== "github") {
+            fail(outCtx, ExitCode.USAGE, `Unsupported CI provider '${provider}'.`, {
+                hint: "Supported providers: github.",
+            });
+        }
+        let authCtx;
+        try {
+            authCtx = requireOrgContext(opts.org);
+        }
+        catch (e) {
+            fail(outCtx, ExitCode.AUTH_MISSING, e.message, {
+                hint: "Set SPEC0_TOKEN + SPEC0_ORG_ID, or run 'spec0 auth login'.",
+            });
+        }
+        const params = new URLSearchParams({
+            specFilePath: opts.specFile,
+            branch: opts.branch,
+        });
+        if (opts.apiName)
+            params.set("apiName", opts.apiName);
+        const client = createOrgApiClient(authCtx);
+        try {
+            const res = (await client.getJson(`/api-management/cli/v1/ci-config?${params.toString()}`));
+            if (opts.write) {
+                const target = resolve(process.cwd(), res.filePath ?? ".github/workflows/spec0-publish.yml");
+                mkdirSync(dirname(target), { recursive: true });
+                writeFileSync(target, res.workflowYaml ?? "", "utf-8");
+                progress(outCtx, chalk.green(`wrote ${target}`));
+                emit(outCtx, { filePath: target, bytes: (res.workflowYaml ?? "").length }, (d) => `Workflow written to ${d.filePath} (${d.bytes} bytes).`);
+            }
+            else {
+                // Dump the raw YAML on stdout so users can redirect to a file.
+                process.stdout.write(res.workflowYaml ?? "");
+            }
+        }
+        catch (err) {
+            if (is401(err)) {
+                fail(outCtx, ExitCode.AUTH_MISSING, "Token invalid or expired.", {
+                    hint: "Run 'spec0 auth login' or refresh SPEC0_TOKEN.",
+                });
+            }
+            fail(outCtx, ExitCode.GENERIC, `ci generate failed: ${err.message}`);
+        }
+    });
+}
+//# sourceMappingURL=generate.js.map

package/dist/commands/ci/generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../../src/commands/ci/generate.ts"],"names":[],"mappings":"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"}

package/dist/commands/ci/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerCiCommands(program: Command): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/ci/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/ci/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,QAGlD"}

package/dist/commands/ci/index.js

@@ -0,0 +1,6 @@
+import { registerCiGenerateCommand } from "./generate.js";
+export function registerCiCommands(program) {
+    const ci = program.command("ci").description("Generate CI configuration for CI/CD pipelines.");
+    registerCiGenerateCommand(ci);
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/ci/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/ci/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,CAAC,gDAAgD,CAAC,CAAC;IAC/F,yBAAyB,CAAC,EAAE,CAAC,CAAC;AAChC,CAAC"}

package/dist/commands/commands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * spec0 commands — self-describing manifest of every command the CLI ships.
+ *
+ * Designed for AI agents and scripts that want to discover capabilities
+ * without shelling out to `--help` and parsing prose. Walks the Commander
+ * tree at runtime, so the manifest is always in lockstep with the binary.
+ *
+ * Typical agent workflow:
+ *
+ *   1. `spec0 commands --output=json` → enumerate every command, its flags,
+ *      positional args, and description.
+ *   2. Pick the command that matches the task (e.g. "publish a spec" →
+ *      `publish`).
+ *   3. Invoke it with `--output=json` for machine-readable results, and
+ *      branch on exit codes (see the bundled `exitCodes` table).
+ */
+import { Command } from "commander";
+export declare function registerCommandsCommand(program: Command): void;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/commands/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6CpC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,QAcvD"}

package/dist/commands/commands.js

@@ -0,0 +1,127 @@
+/**
+ * spec0 commands — self-describing manifest of every command the CLI ships.
+ *
+ * Designed for AI agents and scripts that want to discover capabilities
+ * without shelling out to `--help` and parsing prose. Walks the Commander
+ * tree at runtime, so the manifest is always in lockstep with the binary.
+ *
+ * Typical agent workflow:
+ *
+ *   1. `spec0 commands --output=json` → enumerate every command, its flags,
+ *      positional args, and description.
+ *   2. Pick the command that matches the task (e.g. "publish a spec" →
+ *      `publish`).
+ *   3. Invoke it with `--output=json` for machine-readable results, and
+ *      branch on exit codes (see the bundled `exitCodes` table).
+ */
+import chalk from "chalk";
+import { ExitCode, exit } from "../lib/exit-codes.js";
+import { emit, resolveOutputContext } from "../lib/output/index.js";
+const EXIT_CODES = {
+    "0": "success",
+    "1": "generic / unclassified failure",
+    "2": "usage error (bad flags, missing args)",
+    "3": "not authenticated (no token / token expired)",
+    "4": "permission denied (403)",
+    "5": "resource not found (404)",
+    "6": "conflict (409 — e.g. name already taken)",
+    "7": "validation failed (422 — e.g. spec below min score)",
+    "8": "rate limited (429)",
+    "9": "upstream server error (5xx)",
+    "10": "network error (unreachable, timeout)",
+};
+export function registerCommandsCommand(program) {
+    program
+        .command("commands")
+        .description("List every command in a machine-readable manifest. Designed for AI agents and scripts.")
+        .argument("[pattern]", "Filter commands by substring match on name (case-insensitive)")
+        .option("--output <format>", "Output format: text, json, or yaml (default: text)")
+        .action((pattern, opts) => {
+        const ctx = resolveOutputContext(opts);
+        const manifest = buildManifest(program, pattern);
+        emit(ctx, manifest, renderText);
+        exit(ExitCode.SUCCESS);
+    });
+}
+function buildManifest(program, pattern) {
+    const needle = pattern?.toLowerCase();
+    const all = walkCommands(program, "");
+    const commands = needle ? all.filter((c) => c.name.toLowerCase().includes(needle)) : all;
+    return {
+        version: program.version() ?? "unknown",
+        commands,
+        exitCodes: EXIT_CODES,
+    };
+}
+function walkCommands(cmd, prefix) {
+    const out = [];
+    for (const sub of cmd.commands) {
+        // Skip commander's auto-generated `help` leaf — it's not a real operation.
+        if (sub.name() === "help")
+            continue;
+        const name = prefix ? `${prefix} ${sub.name()}` : sub.name();
+        // Only emit an entry when this node has an action (leaf command). Groups
+        // like `spec0 api` or `spec0 mock` exist purely to host subcommands and
+        // aren't themselves runnable.
+        const hasAction = hasRegisteredAction(sub);
+        if (hasAction) {
+            out.push({
+                name,
+                description: sub.description() || "",
+                usage: buildUsage(sub, name),
+                args: extractArgs(sub),
+                flags: extractFlags(sub),
+            });
+        }
+        // Recurse into subcommand groups.
+        if (sub.commands.length > 0) {
+            out.push(...walkCommands(sub, name));
+        }
+    }
+    return out;
+}
+// Commander doesn't expose "has action?" publicly; reach for the underlying
+// field. Commands registered via `.action(...)` set this; noun-only groups
+// (e.g. `spec0 api`) don't.
+function hasRegisteredAction(cmd) {
+    return typeof cmd._actionHandler === "function";
+}
+function buildUsage(cmd, name) {
+    const argSegments = cmd.registeredArguments
+        .map((a) => (a.required ? `<${a.name()}>` : `[${a.name()}]`))
+        .join(" ");
+    return `spec0 ${name}${argSegments ? ` ${argSegments}` : ""} [options]`;
+}
+function extractArgs(cmd) {
+    return cmd.registeredArguments.map((a) => ({
+        name: a.name(),
+        required: a.required,
+        description: a.description || undefined,
+    }));
+}
+function extractFlags(cmd) {
+    return cmd.options.map((o) => ({
+        flags: o.flags,
+        description: o.description,
+        defaultValue: o.defaultValue,
+    }));
+}
+function renderText(m) {
+    const lines = [];
+    lines.push(chalk.bold(`spec0 ${m.version} — command manifest`));
+    lines.push("");
+    lines.push(chalk.gray(`${m.commands.length} commands. For full detail, use --output=json.`));
+    lines.push("");
+    const nameWidth = Math.max(...m.commands.map((c) => c.name.length), 12);
+    for (const c of m.commands) {
+        const padded = c.name.padEnd(nameWidth);
+        lines.push(`  ${chalk.cyan(padded)}  ${c.description}`);
+    }
+    lines.push("");
+    lines.push(chalk.bold("Exit codes"));
+    for (const [code, label] of Object.entries(m.exitCodes)) {
+        lines.push(`  ${code.padStart(2)}  ${label}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=commands.js.map

package/dist/commands/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/commands/commands.ts"],"names":[],"mappings":"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"}

package/dist/commands/diff.d.ts

@@ -0,0 +1,6 @@
+/**
+ * spec0 diff — compare two OpenAPI specs (registry refs and/or local files)
+ */
+import { Command } from "commander";
+export declare function registerDiffCommand(program: Command): void;
+//# sourceMappingURL=diff.d.ts.map

package/dist/commands/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/commands/diff.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4DpC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,QAyDnD"}