@paybond/kit 0.9.8 → 0.11.0

package/dist/cli/commands/workflows.js

@@ -0,0 +1,214 @@
+import { resolveJsonBody } from "../body.js";
+import { buildListQueryParams, extractNextCursor, partialResultsWarning, } from "../automation.js";
+import { commandPath, requireConfirmation, withGateway } from "../context.js";
+import { consumeFlag, parseOptionalNonNegativeInt, parseRequiredNonNegativeInt } from "../globals.js";
+import { maskApiKey, redactSensitiveFields } from "../redact.js";
+import { CliError } from "../types.js";
+export async function handleKeys(ctx, subcommand, argv) {
+    return withGateway(ctx, async (gateway) => {
+        if (subcommand === "list") {
+            const limitFlag = consumeFlag(argv, "--limit");
+            const cursorFlag = consumeFlag(argv, "--cursor");
+            const params = buildListQueryParams(limitFlag.value, cursorFlag.value, { limit: "50" });
+            const body = await gateway.getJson(`/v1/admin/api-keys?${params.toString()}`);
+            const items = Array.isArray(body.items) ? body.items : [];
+            const keys = items.map((item) => {
+                const row = item;
+                return {
+                    key_id: String(row.key_id ?? row.id ?? ""),
+                    key_masked: maskApiKey(`paybond_sk_${String(row.environment ?? "sandbox")}_${String(row.key_id ?? "redacted")}_redacted`),
+                    role: String(row.service_account_role ?? ""),
+                    created_at: String(row.created_at ?? ""),
+                    expires_at: row.expires_at ? String(row.expires_at) : null,
+                    status: row.revoked_at ? "revoked" : "active",
+                };
+            });
+            const nextCursor = extractNextCursor(body);
+            const warnings = partialResultsWarning(nextCursor) ? [partialResultsWarning(nextCursor)] : undefined;
+            const data = { keys };
+            if (nextCursor) {
+                data.next_cursor = nextCursor;
+            }
+            return { data, warnings };
+        }
+        if (subcommand === "create") {
+            const nameFlag = consumeFlag(argv, "--name");
+            const roleFlag = consumeFlag(argv, "--role");
+            const labelFlag = consumeFlag(argv, "--label");
+            if (!nameFlag.value || !roleFlag.value) {
+                throw new CliError("keys create requires --name and --role", { category: "usage", code: "cli.usage.missing_args" });
+            }
+            const body = await gateway.postJson("/v1/admin/api-keys", {
+                service_account_name: nameFlag.value,
+                service_account_role: roleFlag.value,
+                label: labelFlag.value ?? "",
+            });
+            const item = (body.item ?? {});
+            const rawApiKey = typeof body.api_key === "string" ? body.api_key : "";
+            const data = {
+                key_id: String(item.key_id ?? item.id ?? ""),
+                key_masked: rawApiKey ? maskApiKey(rawApiKey) : maskApiKey(""),
+                role: String(item.service_account_role ?? roleFlag.value),
+                created_at: String(item.created_at ?? ""),
+                status: "active",
+            };
+            if (rawApiKey) {
+                data.api_key = rawApiKey;
+            }
+            return { data };
+        }
+        const keyId = argv[0];
+        if (!keyId) {
+            throw new CliError(`keys ${subcommand} requires <key_id>`, { category: "usage", code: "cli.usage.missing_key_id" });
+        }
+        if (subcommand === "rotate") {
+            requireConfirmation(ctx.globals, "rotate API key");
+            const body = await gateway.postJson(`/v1/admin/api-keys/${encodeURIComponent(keyId)}/rotate`);
+            const item = (body.item ?? {});
+            const rawApiKey = typeof body.api_key === "string" ? body.api_key : "";
+            const data = {
+                key_id: String(item.key_id ?? keyId),
+                key_masked: rawApiKey ? maskApiKey(rawApiKey) : maskApiKey(""),
+                rotated: true,
+            };
+            if (rawApiKey) {
+                data.api_key = rawApiKey;
+            }
+            return { data };
+        }
+        if (subcommand === "revoke") {
+            requireConfirmation(ctx.globals, "revoke API key");
+            await gateway.deleteJson(`/v1/admin/api-keys/${encodeURIComponent(keyId)}`);
+            return { data: { key_id: keyId, revoked: true } };
+        }
+        throw new CliError(`unknown keys subcommand: ${subcommand}`, { category: "usage", code: "cli.usage.unknown_command" });
+    });
+}
+export async function handleIntents(ctx, subcommand, argv) {
+    return withGateway(ctx, async (gateway) => {
+        if (subcommand === "list") {
+            const statusFlag = consumeFlag(argv, "--status");
+            const limitFlag = consumeFlag(argv, "--limit");
+            const cursorFlag = consumeFlag(argv, "--cursor");
+            const params = buildListQueryParams(limitFlag.value, cursorFlag.value);
+            if (statusFlag.value) {
+                params.set("status", statusFlag.value);
+            }
+            const body = await gateway.getJson(`/harbor/operator/v1/intents?${params.toString()}`);
+            const redacted = redactSensitiveFields(body);
+            const nextCursor = extractNextCursor(redacted);
+            const warnings = partialResultsWarning(nextCursor) ? [partialResultsWarning(nextCursor)] : undefined;
+            if (nextCursor && !redacted.next_cursor) {
+                redacted.next_cursor = nextCursor;
+            }
+            return { data: redacted, warnings };
+        }
+        const intentId = argv[0];
+        if (subcommand === "get") {
+            if (!intentId) {
+                throw new CliError("intents get requires <intent_id>", { category: "usage", code: "cli.usage.missing_intent_id" });
+            }
+            const body = await gateway.getJson(`/harbor/operator/v1/intents/${encodeURIComponent(intentId)}`);
+            return { data: redactSensitiveFields(body) };
+        }
+        if (subcommand === "create") {
+            const { payload } = await resolveJsonBody(argv, {
+                missingMessage: "intents create requires --body <json-file> or --stdin",
+            });
+            const body = await gateway.postJson("/harbor/intents", payload);
+            return { data: redactSensitiveFields(body) };
+        }
+        if (!intentId) {
+            throw new CliError(`intents ${subcommand} requires <intent_id>`, { category: "usage", code: "cli.usage.missing_intent_id" });
+        }
+        if (subcommand === "fund") {
+            const { payload } = await resolveJsonBody(argv, { required: false });
+            const body = await gateway.postJson(`/harbor/intents/${encodeURIComponent(intentId)}/fund`, payload);
+            return { data: redactSensitiveFields(body) };
+        }
+        if (subcommand === "evidence") {
+            const { payload } = await resolveJsonBody(argv, {
+                missingMessage: "intents evidence requires --body <json-file> or --stdin",
+            });
+            const body = await gateway.postJson(`/harbor/intents/${encodeURIComponent(intentId)}/evidence`, payload);
+            return { data: redactSensitiveFields(body) };
+        }
+        if (subcommand === "settlement-confirm") {
+            const { payload } = await resolveJsonBody(argv, { required: false });
+            const body = await gateway.postJson(`/harbor/intents/${encodeURIComponent(intentId)}/settlement/confirm`, payload);
+            return { data: redactSensitiveFields(body) };
+        }
+        throw new CliError(`unknown intents subcommand: ${subcommand}`, { category: "usage", code: "cli.usage.unknown_command" });
+    });
+}
+export async function handleGuardrails(ctx, subcommand, argv) {
+    return withGateway(ctx, async (gateway) => {
+        if (subcommand === "bootstrap") {
+            const operationFlag = consumeFlag(argv, "--operation");
+            const spendFlag = consumeFlag(argv, "--requested-spend-cents");
+            const presetFlag = consumeFlag(argv, "--completion-preset");
+            if (!operationFlag.value || !spendFlag.value) {
+                throw new CliError("guardrails bootstrap requires --operation and --requested-spend-cents", { category: "usage", code: "cli.usage.missing_args" });
+            }
+            const spendCents = parseRequiredNonNegativeInt(spendFlag.value, "--requested-spend-cents");
+            const bodyPayload = {
+                operation: operationFlag.value,
+                requested_spend_cents: spendCents,
+            };
+            if (presetFlag.value) {
+                bodyPayload.completion_preset = presetFlag.value;
+            }
+            const body = await gateway.postJson("/v1/sandbox/guardrails/bootstrap", bodyPayload);
+            return {
+                data: redactSensitiveFields({
+                    tenant_id: String(body.tenant_id ?? ""),
+                    intent_id: String(body.intent_id ?? ""),
+                    capability_token: String(body.capability_token ?? ""),
+                    operation: String(body.operation ?? operationFlag.value),
+                    requested_spend_cents: Number(body.requested_spend_cents ?? spendCents),
+                    sandbox_lifecycle_status: String(body.sandbox_lifecycle_status ?? ""),
+                }),
+            };
+        }
+        if (subcommand === "evidence") {
+            const intentFlag = consumeFlag(argv, "--intent-id");
+            if (!intentFlag.value) {
+                throw new CliError("guardrails evidence requires --intent-id and --body <json-file>", { category: "usage", code: "cli.usage.missing_args" });
+            }
+            const { payload } = await resolveJsonBody(argv, {
+                missingMessage: "guardrails evidence requires --intent-id and --body <json-file> or --stdin",
+            });
+            const body = await gateway.postJson(`/v1/sandbox/guardrails/${encodeURIComponent(intentFlag.value)}/evidence`, payload);
+            return { data: body };
+        }
+        throw new CliError(`unknown guardrails subcommand: ${subcommand}`, { category: "usage", code: "cli.usage.unknown_command" });
+    });
+}
+export async function handleSpendAuthorize(ctx, argv) {
+    return withGateway(ctx, async (gateway) => {
+        const intentFlag = consumeFlag(argv, "--intent-id");
+        const tokenFlag = consumeFlag(argv, "--token");
+        const operationFlag = consumeFlag(argv, "--operation");
+        const spendFlag = consumeFlag(argv, "--requested-spend-cents");
+        if (!intentFlag.value || !tokenFlag.value || !operationFlag.value) {
+            throw new CliError("spend authorize requires --intent-id, --token, and --operation", { category: "usage", code: "cli.usage.missing_args" });
+        }
+        const spendCents = parseOptionalNonNegativeInt(spendFlag.value, "--requested-spend-cents");
+        const body = await gateway.postJson("/verify", {
+            intent_id: intentFlag.value,
+            token: tokenFlag.value,
+            operation: operationFlag.value,
+            requested_spend_cents: spendCents,
+        });
+        return {
+            data: {
+                authorized: Boolean(body.allow),
+                intent_id: String(body.intent_id ?? intentFlag.value),
+                operation: operationFlag.value,
+                requested_spend_cents: spendCents,
+                deny_reason: body.allow ? undefined : String(body.message ?? body.code ?? "denied"),
+            },
+        };
+    });
+}
+export { commandPath };

package/dist/cli/config.d.ts

@@ -0,0 +1,16 @@
+export type CliConfigFile = {
+    install_id?: string;
+    telemetry?: boolean;
+    profiles?: Record<string, {
+        env_file?: string;
+        gateway?: string;
+    }>;
+    values?: Record<string, string>;
+};
+export declare function configFilePath(): string;
+export declare function loadConfigFile(): Promise<CliConfigFile>;
+export declare function saveConfigFile(config: CliConfigFile): Promise<void>;
+export declare function resolveConfigValue(key: string, profile?: string): Promise<string | undefined>;
+export declare function setConfigValue(key: string, value: string, profile?: string): Promise<void>;
+export declare function unsetConfigValue(key: string, profile?: string): Promise<boolean>;
+export declare function listConfigEntries(profile?: string): Promise<Record<string, string>>;

package/dist/cli/config.js

@@ -0,0 +1,98 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { redactConfigValue } from "./redact.js";
+import { validateCliGateway } from "./globals.js";
+import { CliError } from "./types.js";
+export function configFilePath() {
+    const home = process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || "";
+    const base = process.env.XDG_CONFIG_HOME?.trim() || (home ? `${home}/.config` : ".config");
+    return `${base.replace(/\/+$/, "")}/paybond/config.json`;
+}
+export async function loadConfigFile() {
+    try {
+        const raw = await readFile(configFilePath(), "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+            return {};
+        }
+        throw new CliError(`unable to read CLI config: ${err instanceof Error ? err.message : String(err)}`, {
+            category: "environment",
+            code: "cli.environment.config_read_failed",
+        });
+    }
+}
+export async function saveConfigFile(config) {
+    const configPath = configFilePath();
+    const dir = configPath.replace(/\/[^/]+$/, "");
+    await mkdir(dir, { recursive: true });
+    await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+}
+export async function resolveConfigValue(key, profile) {
+    const config = await loadConfigFile();
+    if (profile) {
+        const profileValues = config.profiles?.[profile];
+        if (profileValues && key in profileValues) {
+            const value = profileValues[key];
+            return typeof value === "string" ? value : undefined;
+        }
+    }
+    return config.values?.[key];
+}
+export async function setConfigValue(key, value, profile) {
+    const storedValue = key.toLowerCase() === "gateway" ? validateCliGateway(value) : value;
+    const config = await loadConfigFile();
+    if (profile) {
+        config.profiles ??= {};
+        config.profiles[profile] ??= {};
+        config.profiles[profile][key] = storedValue;
+    }
+    else {
+        config.values ??= {};
+        config.values[key] = storedValue;
+    }
+    await saveConfigFile(config);
+}
+export async function unsetConfigValue(key, profile) {
+    const config = await loadConfigFile();
+    if (profile) {
+        const profileValues = config.profiles?.[profile];
+        if (!profileValues || !(key in profileValues)) {
+            return false;
+        }
+        delete profileValues[key];
+        await saveConfigFile(config);
+        return true;
+    }
+    if (!config.values || !(key in config.values)) {
+        return false;
+    }
+    delete config.values[key];
+    await saveConfigFile(config);
+    return true;
+}
+export async function listConfigEntries(profile) {
+    const config = await loadConfigFile();
+    const entries = {};
+    if (profile) {
+        const profileValues = config.profiles?.[profile] ?? {};
+        for (const [key, value] of Object.entries(profileValues)) {
+            if (typeof value === "string") {
+                entries[key] = redactConfigValue(key, value);
+            }
+        }
+        return entries;
+    }
+    for (const [key, value] of Object.entries(config.values ?? {})) {
+        entries[key] = redactConfigValue(key, value);
+    }
+    for (const [profileName, profileValues] of Object.entries(config.profiles ?? {})) {
+        for (const [key, value] of Object.entries(profileValues ?? {})) {
+            if (typeof value === "string") {
+                entries[`profiles.${profileName}.${key}`] = redactConfigValue(key, value);
+            }
+        }
+    }
+    return entries;
+}

package/dist/cli/context.d.ts

@@ -0,0 +1,22 @@
+import { type CliDependencies, type CommandResult, type GlobalOptions, type Writable } from "./types.js";
+export type GatewayJson = Record<string, unknown>;
+export type GatewayClient = {
+    getJson(path: string): Promise<GatewayJson>;
+    postJson(path: string, body?: GatewayJson): Promise<GatewayJson>;
+    deleteJson(path: string): Promise<GatewayJson>;
+};
+export declare function gatewayUrl(base: string, path: string): string;
+export declare function createGatewayClient(globals: GlobalOptions, apiKey: string, fetchFn: typeof fetch, extraHeaders?: Record<string, string>): GatewayClient;
+export type CliContext = {
+    globals: GlobalOptions;
+    cwd: string;
+    stdout: Writable;
+    stderr: Writable;
+    fetch: typeof fetch;
+    deps: CliDependencies;
+    gateway?: GatewayClient;
+};
+export declare function withGateway(ctx: CliContext, handler: (gateway: GatewayClient, apiKey: string) => Promise<CommandResult>, extraHeaders?: Record<string, string>): Promise<CommandResult>;
+export declare function requireConfirmation(globals: GlobalOptions, action: string): void;
+export declare function commandPath(parts: string[]): string;
+export declare function createContext(globals: GlobalOptions, deps?: CliDependencies): CliContext;

package/dist/cli/context.js

@@ -0,0 +1,110 @@
+import { resolveApiKeyWithMeta } from "./credentials.js";
+import { requireSecureGatewayUrl } from "../gateway-url.js";
+import { CliError, exitCodeForHttpStatus, } from "./types.js";
+export function gatewayUrl(base, path) {
+    return `${requireSecureGatewayUrl(base)}${path.startsWith("/") ? path : `/${path}`}`;
+}
+function parseGatewayErrorBody(body, status) {
+    const nested = body.error;
+    const gatewayCode = nested && typeof nested === "object" && !Array.isArray(nested)
+        ? String(nested.code ?? "")
+        : String(body.code ?? "");
+    const gatewayMessage = nested && typeof nested === "object" && !Array.isArray(nested)
+        ? String(nested.message ?? "")
+        : String(body.message ?? body.error_description ?? "gateway request failed");
+    const mapped = exitCodeForHttpStatus(status);
+    return new CliError(gatewayMessage || `Gateway HTTP ${status}`, {
+        category: mapped.category,
+        code: gatewayCode || `cli.gateway.http_${status}`,
+        exitCode: mapped.exitCode,
+        details: {
+            gateway_status: status,
+            gateway_code: gatewayCode || undefined,
+        },
+    });
+}
+async function parseJsonResponse(response) {
+    const text = await response.text();
+    if (!text.trim()) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // fall through
+    }
+    throw new CliError(`Gateway returned non-JSON response (${response.status}).`, {
+        category: "gateway",
+        code: "cli.gateway.non_json",
+        exitCode: 5,
+        details: { gateway_status: response.status },
+    });
+}
+export function createGatewayClient(globals, apiKey, fetchFn, extraHeaders = {}) {
+    const headers = {
+        authorization: `Bearer ${apiKey}`,
+        "content-type": "application/json",
+        "x-request-id": globals.requestId,
+        ...extraHeaders,
+    };
+    async function request(method, path, body) {
+        let response;
+        try {
+            response = await fetchFn(gatewayUrl(globals.gateway, path), {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (err) {
+            throw new CliError(err instanceof Error ? err.message : String(err), {
+                category: "network",
+                code: "cli.network.request_failed",
+                exitCode: 5,
+            });
+        }
+        const parsed = await parseJsonResponse(response);
+        if (!response.ok) {
+            throw parseGatewayErrorBody(parsed, response.status);
+        }
+        return parsed;
+    }
+    return {
+        getJson: (path) => request("GET", path),
+        postJson: (path, body) => request("POST", path, body),
+        deleteJson: (path) => request("DELETE", path),
+    };
+}
+export async function withGateway(ctx, handler, extraHeaders = {}) {
+    const resolved = await resolveApiKeyWithMeta(ctx.globals, ctx.cwd);
+    const gateway = createGatewayClient(ctx.globals, resolved.apiKey, ctx.fetch, extraHeaders);
+    const result = await handler(gateway, resolved.apiKey);
+    const warnings = [...(result.warnings ?? []), ...resolved.warnings];
+    return warnings.length ? { ...result, warnings } : result;
+}
+export function requireConfirmation(globals, action) {
+    if (!globals.yes) {
+        throw new CliError(`confirmation required; re-run with --yes to ${action}`, {
+            category: "confirmation_required",
+            code: "cli.confirmation.required",
+            exitCode: 4,
+        });
+    }
+}
+export function commandPath(parts) {
+    return parts.join(" ");
+}
+export function createContext(globals, deps = {}) {
+    return {
+        globals,
+        cwd: deps.cwd ?? process.cwd(),
+        stdout: deps.stdout ?? process.stdout,
+        stderr: deps.stderr ?? process.stderr,
+        fetch: deps.fetch ?? fetch,
+        deps,
+    };
+}

package/dist/cli/credentials.d.ts

@@ -0,0 +1,21 @@
+import { type GlobalOptions } from "./types.js";
+export declare function readEnvFileValue(body: string, key: string): string | undefined;
+export declare function loadEnvFile(envFile: string, cwd: string): Promise<string | undefined>;
+export type ResolvedApiKey = {
+    apiKey: string;
+    warnings: string[];
+};
+export declare function resolveApiKeyWithMeta(globals: GlobalOptions, cwd: string): Promise<ResolvedApiKey>;
+export declare function resolveApiKey(globals: GlobalOptions, cwd: string): Promise<string>;
+export type CredentialSourceDescription = {
+    source: "process_env" | "env_file" | "missing";
+    env_file?: string;
+    profile?: string;
+    key_masked?: string;
+};
+export declare function describeCredentialSource(globals: GlobalOptions, cwd: string): Promise<CredentialSourceDescription>;
+export declare function assertApiKeyShape(apiKey: string): void;
+export declare function resolvedDefaultsForDoctor(globals: GlobalOptions): {
+    gateway: string;
+    envFile: string;
+};

package/dist/cli/credentials.js

@@ -0,0 +1,141 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveConfigValue } from "./config.js";
+import { CLI_WARN_ENV_FALLBACK, formatWarning } from "./automation.js";
+import { DEFAULT_ENV_FILE, DEFAULT_GATEWAY, validateCliGateway } from "./globals.js";
+import { CliError } from "./types.js";
+function resolvePath(cwd, envFile) {
+    return path.isAbsolute(envFile) ? path.resolve(envFile) : path.resolve(cwd, envFile);
+}
+function quoteTrim(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+export function readEnvFileValue(body, key) {
+    const prefix = `${key}=`;
+    const exportPrefix = `export ${key}=`;
+    for (const rawLine of body.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        let value = "";
+        if (line.startsWith(exportPrefix)) {
+            value = line.slice(exportPrefix.length).trim();
+        }
+        else if (line.startsWith(prefix)) {
+            value = line.slice(prefix.length).trim();
+        }
+        else {
+            continue;
+        }
+        const unquoted = quoteTrim(value);
+        return unquoted || undefined;
+    }
+    return undefined;
+}
+export async function loadEnvFile(envFile, cwd) {
+    const envPath = resolvePath(cwd, envFile);
+    try {
+        const body = await readFile(envPath, "utf8");
+        return readEnvFileValue(body, "PAYBOND_API_KEY");
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+            return undefined;
+        }
+        throw new CliError(`unable to read env file ${envPath}`, {
+            category: "environment",
+            code: "cli.environment.env_file_read_failed",
+            details: { env_file: envPath },
+        });
+    }
+}
+export async function resolveApiKeyWithMeta(globals, cwd) {
+    const warnings = [];
+    const fromProcess = process.env.PAYBOND_API_KEY?.trim();
+    if (fromProcess) {
+        warnings.push(formatWarning(CLI_WARN_ENV_FALLBACK, "using PAYBOND_API_KEY from process environment"));
+        return { apiKey: fromProcess, warnings };
+    }
+    let envFile = globals.envFile;
+    let gateway = globals.gateway;
+    if (globals.profile) {
+        const profileEnvFile = await resolveConfigValue("env_file", globals.profile);
+        const profileGateway = await resolveConfigValue("gateway", globals.profile);
+        if (profileEnvFile) {
+            envFile = profileEnvFile;
+            warnings.push(formatWarning(CLI_WARN_ENV_FALLBACK, `using profile ${globals.profile} env_file`));
+        }
+        if (profileGateway) {
+            gateway = validateCliGateway(profileGateway);
+            warnings.push(formatWarning(CLI_WARN_ENV_FALLBACK, `using profile ${globals.profile} gateway`));
+        }
+    }
+    globals.envFile = envFile;
+    globals.gateway = gateway;
+    const fromFile = await loadEnvFile(envFile, cwd);
+    if (fromFile) {
+        return { apiKey: fromFile, warnings };
+    }
+    throw new CliError("missing PAYBOND_API_KEY; run paybond login or set PAYBOND_API_KEY", {
+        category: "auth",
+        code: "cli.auth.missing_api_key",
+        exitCode: 2,
+        details: { env_file: resolvePath(cwd, envFile) },
+    });
+}
+export async function resolveApiKey(globals, cwd) {
+    const resolved = await resolveApiKeyWithMeta(globals, cwd);
+    return resolved.apiKey;
+}
+export async function describeCredentialSource(globals, cwd) {
+    const { maskApiKey } = await import("./redact.js");
+    const fromProcess = process.env.PAYBOND_API_KEY?.trim();
+    if (fromProcess) {
+        return { source: "process_env", key_masked: maskApiKey(fromProcess) };
+    }
+    let envFile = globals.envFile;
+    const profile = globals.profile;
+    if (globals.profile) {
+        const profileEnvFile = await resolveConfigValue("env_file", globals.profile);
+        if (profileEnvFile) {
+            envFile = profileEnvFile;
+        }
+    }
+    const envPath = resolvePath(cwd, envFile);
+    try {
+        const fromFile = await loadEnvFile(envFile, cwd);
+        if (fromFile) {
+            return {
+                source: "env_file",
+                env_file: envPath,
+                profile: profile ?? undefined,
+                key_masked: maskApiKey(fromFile),
+            };
+        }
+    }
+    catch {
+        // fall through to missing
+    }
+    return {
+        source: "missing",
+        env_file: envPath,
+        profile: profile ?? undefined,
+    };
+}
+export function assertApiKeyShape(apiKey) {
+    if (!apiKey.startsWith("paybond_sk_")) {
+        throw new CliError("PAYBOND_API_KEY has an unexpected shape", {
+            category: "auth",
+            code: "cli.auth.invalid_api_key_shape",
+            exitCode: 2,
+        });
+    }
+}
+export function resolvedDefaultsForDoctor(globals) {
+    return {
+        gateway: globals.gateway || DEFAULT_GATEWAY,
+        envFile: globals.envFile || DEFAULT_ENV_FILE,
+    };
+}

package/dist/cli/doctor-agent-middleware.d.ts

@@ -0,0 +1,5 @@
+import type { CliContext } from "./context.js";
+import type { DoctorCheck } from "./doctor-agent.js";
+export declare const AGENT_MIDDLEWARE_SMOKE_NEXT = "paybond agent sandbox smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --result-body '{\"status\":\"ok\",\"cost_cents\":100}' --format json";
+/** Run sandbox middleware smoke as a doctor --agent check (uses ctx.fetch / project cwd). */
+export declare function runAgentMiddlewareDoctorCheck(ctx: CliContext, apiKey: string): Promise<DoctorCheck>;