@paybond/kit 0.9.7 → 0.10.0

package/dist/cli/router.js

@@ -0,0 +1,275 @@
+import { commandPath, createContext } from "./context.js";
+import { handleA2a, handleAuditExports, handleMandates, handleReceipts, handleSignal, } from "./commands/discovery.js";
+import { handleConfig, handleDoctor, handleDiagnose, handleInitGuardrail, handleLogin, handleMcpInstall, handleMcpServe, handleMcpTools, handleMcpVerifyConfig, handleVersion, handleWhoami, } from "./commands/setup.js";
+import { handleGuardrails, handleIntents, handleKeys, handleSpendAuthorize, } from "./commands/workflows.js";
+import { failureEnvelope, prepareCommandOutput, successEnvelope, writeEnvelope, writeTableLines } from "./envelope.js";
+import { defaultGlobalOptions, parseCliArgv } from "./globals.js";
+import { deprecatedAliasWarning } from "./automation.js";
+import { helpForCommand } from "./help.js";
+import { generateRequestId } from "./request-id.js";
+import { colorize, shouldUseColor } from "./color.js";
+import { formatUnknownCommandMessage } from "./suggest.js";
+import { handleCompletionCommand, handleExamplesCommand, handleHelpCommand, handleOnboarding, } from "./ux.js";
+import { CliError, EXIT_SUCCESS, } from "./types.js";
+function isHelp(argv) {
+    return argv.length === 0 || argv.includes("--help") || argv.includes("-h");
+}
+function renderTable(command, result, globals) {
+    const useColor = shouldUseColor(globals);
+    const lines = [colorize(`${command}: ok`, "green", useColor)];
+    for (const [key, value] of Object.entries(result.data)) {
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            lines.push(`${key}: ${JSON.stringify(value)}`);
+        }
+        else if (Array.isArray(value)) {
+            lines.push(`${key}: ${value.length} item(s)`);
+        }
+        else {
+            lines.push(`${key}: ${String(value)}`);
+        }
+    }
+    if (result.warnings?.length) {
+        lines.push(colorize(`warnings: ${result.warnings.join("; ")}`, "yellow", useColor));
+    }
+    return lines;
+}
+function toErrorShape(err) {
+    if (err instanceof CliError) {
+        if (err.message === "help") {
+            return {
+                shape: { category: "usage", code: "cli.help", message: "help" },
+                exitCode: EXIT_SUCCESS,
+            };
+        }
+        return {
+            shape: {
+                category: err.category,
+                code: err.code,
+                message: err.message,
+                details: err.details ?? {},
+            },
+            exitCode: err.exitCode,
+        };
+    }
+    return {
+        shape: {
+            category: "internal",
+            code: "cli.internal",
+            message: err instanceof Error ? err.message : String(err),
+            details: {},
+        },
+        exitCode: 1,
+    };
+}
+function outputFormatFromArgv(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--format" && argv[i + 1] === "json") {
+            return "json";
+        }
+        if (arg === "--format=json") {
+            return "json";
+        }
+    }
+    return "table";
+}
+function requestIdFromArgv(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--request-id" && argv[i + 1]) {
+            return argv[i + 1];
+        }
+        if (arg.startsWith("--request-id=")) {
+            return arg.slice("--request-id=".length);
+        }
+    }
+    return generateRequestId();
+}
+export async function runCli(argv, deps = {}) {
+    const stdout = deps.stdout ?? process.stdout;
+    const stderr = deps.stderr ?? process.stderr;
+    let globals;
+    let command;
+    try {
+        ({ globals, command } = parseCliArgv(argv));
+    }
+    catch (err) {
+        const { shape, exitCode } = toErrorShape(err);
+        if (shape.message === "help") {
+            stdout.write(`${helpForCommand("")}\n`);
+            return EXIT_SUCCESS;
+        }
+        if (outputFormatFromArgv(argv) === "json") {
+            writeEnvelope(stdout, failureEnvelope("paybond", { ...defaultGlobalOptions(), format: "json", requestId: requestIdFromArgv(argv) }, shape));
+        }
+        else {
+            stderr.write(`${shape.message}\n`);
+        }
+        return exitCode;
+    }
+    const ctx = createContext(globals, deps);
+    const aliasWarning = deprecatedAliasWarning(process.argv[1]);
+    if (aliasWarning) {
+        stderr.write(`${aliasWarning}\n`);
+    }
+    const helpPath = command.filter((part) => part !== "--help" && part !== "-h").join(" ");
+    if (isHelp(command)) {
+        const text = helpPath ? helpForCommand(helpPath) : helpForCommand("");
+        ctx.stdout.write(`${text}\n`);
+        return EXIT_SUCCESS;
+    }
+    let canonical = "";
+    let result;
+    try {
+        const [head, second, third] = command;
+        const tail = command.slice(2);
+        if (head === "help") {
+            canonical = "help";
+            result = handleHelpCommand(command.slice(1));
+        }
+        else if (head === "examples") {
+            canonical = "examples";
+            result = handleExamplesCommand(command.slice(1));
+        }
+        else if (head === "completion" && second) {
+            canonical = "completion";
+            result = handleCompletionCommand(command.slice(1));
+        }
+        else if (head === "onboarding") {
+            canonical = "onboarding";
+            result = await handleOnboarding(ctx, command.slice(1));
+        }
+        else if (head === "login") {
+            canonical = "login";
+            result = await handleLogin(ctx, command.slice(1));
+        }
+        else if (head === "init" && second === "guardrail") {
+            canonical = "init guardrail";
+            result = await handleInitGuardrail(ctx, command.slice(2));
+        }
+        else if (head === "mcp" && second === "serve") {
+            canonical = "mcp serve";
+            result = await handleMcpServe(ctx, command.slice(2));
+        }
+        else if (head === "mcp" && second === "install") {
+            canonical = "mcp install";
+            result = await handleMcpInstall(ctx, command.slice(2));
+        }
+        else if (head === "mcp" && second === "tools") {
+            canonical = "mcp tools";
+            result = await handleMcpTools(ctx);
+        }
+        else if (head === "mcp" && second === "verify-config") {
+            canonical = "mcp verify-config";
+            result = await handleMcpVerifyConfig(ctx, command.slice(2));
+        }
+        else if (head === "doctor") {
+            canonical = "doctor";
+            result = await handleDoctor(ctx, command.slice(1));
+        }
+        else if (head === "version") {
+            canonical = "version";
+            result = await handleVersion(ctx, command.slice(1));
+        }
+        else if (head === "diagnose") {
+            canonical = "diagnose";
+            result = await handleDiagnose(ctx, command.slice(1));
+        }
+        else if (head === "config" && second) {
+            canonical = commandPath(["config", second]);
+            result = await handleConfig(ctx, second, tail);
+        }
+        else if (head === "whoami") {
+            canonical = "whoami";
+            result = await handleWhoami(ctx);
+        }
+        else if (head === "keys" && second) {
+            canonical = commandPath(["keys", second]);
+            result = await handleKeys(ctx, second, tail);
+        }
+        else if (head === "intents" && second) {
+            canonical = commandPath(["intents", second]);
+            result = await handleIntents(ctx, second, tail);
+        }
+        else if (head === "guardrails" && second) {
+            canonical = commandPath(["guardrails", second]);
+            result = await handleGuardrails(ctx, second, tail);
+        }
+        else if (head === "spend" && second === "authorize") {
+            canonical = "spend authorize";
+            result = await handleSpendAuthorize(ctx, tail);
+        }
+        else if (head === "signal" && second) {
+            canonical = commandPath(["signal", second]);
+            result = await handleSignal(ctx, second, tail);
+        }
+        else if (head === "receipts" && second) {
+            canonical = commandPath(["receipts", second]);
+            result = await handleReceipts(ctx, second, tail);
+        }
+        else if (head === "mandates" && second) {
+            canonical = commandPath(["mandates", second]);
+            result = await handleMandates(ctx, second, tail);
+        }
+        else if (head === "a2a" && second) {
+            canonical = commandPath(["a2a", second]);
+            result = await handleA2a(ctx, second, tail);
+        }
+        else if (head === "audit" && second === "exports" && third) {
+            canonical = commandPath(["audit", "exports", third]);
+            result = await handleAuditExports(ctx, third, command.slice(3));
+        }
+        else {
+            throw new CliError(formatUnknownCommandMessage(command.join(" ")), {
+                category: "usage",
+                code: "cli.usage.unknown_command",
+            });
+        }
+        const output = prepareCommandOutput(canonical, globals, result);
+        if (globals.format === "json") {
+            writeEnvelope(ctx.stdout, successEnvelope(canonical, globals, { data: output.data, warnings: output.warnings }));
+        }
+        else if (output.automationPlain) {
+            ctx.stdout.write(`${JSON.stringify(output.data, null, 2)}\n`);
+            if (output.warnings.length) {
+                for (const warning of output.warnings) {
+                    ctx.stderr.write(`${warning}\n`);
+                }
+            }
+        }
+        else if (canonical === "help" || canonical === "examples") {
+            ctx.stdout.write(`${String(result.data.text ?? "")}\n`);
+        }
+        else if (canonical === "completion") {
+            ctx.stdout.write(String(result.data.script ?? ""));
+        }
+        else if (canonical === "version" && !("package_name" in result.data)) {
+            ctx.stdout.write(`${String(result.data.version ?? "")}\n`);
+        }
+        else if (canonical === "diagnose") {
+            const lines = Array.isArray(result.data.lines) ? result.data.lines : [];
+            for (const line of lines) {
+                ctx.stdout.write(`${line}\n`);
+            }
+        }
+        else if (canonical !== "login" && canonical !== "mcp serve") {
+            writeTableLines(ctx.stdout, renderTable(canonical, result, globals));
+        }
+        return EXIT_SUCCESS;
+    }
+    catch (err) {
+        const { shape, exitCode } = toErrorShape(err);
+        if (shape.message === "help") {
+            const text = helpPath ? helpForCommand(helpPath) : helpForCommand("");
+            ctx.stdout.write(`${text}\n`);
+            return EXIT_SUCCESS;
+        }
+        if (globals.format === "json") {
+            writeEnvelope(ctx.stdout, failureEnvelope(canonical || helpPath || "paybond", globals, shape));
+        }
+        else {
+            ctx.stderr.write(`${shape.message}\n`);
+        }
+        return exitCode;
+    }
+}

package/dist/cli/suggest.d.ts

@@ -0,0 +1,4 @@
+export declare function suggestCommandPath(input: string): string | undefined;
+export declare function suggestGlobalFlag(input: string): string | undefined;
+export declare function formatUnknownCommandMessage(input: string): string;
+export declare function formatUnknownGlobalFlagMessage(flag: string): string;

package/dist/cli/suggest.js

@@ -0,0 +1,58 @@
+import { COMMAND_PATHS, GLOBAL_FLAG_NAMES } from "./command-spec.js";
+function levenshtein(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    const matrix = Array.from({ length: rows }, () => Array(cols).fill(0));
+    for (let i = 0; i < rows; i += 1) {
+        matrix[i][0] = i;
+    }
+    for (let j = 0; j < cols; j += 1) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i < rows; i += 1) {
+        for (let j = 1; j < cols; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[a.length][b.length];
+}
+function bestSuggestion(input, candidates) {
+    const needle = input.trim().toLowerCase();
+    if (!needle) {
+        return undefined;
+    }
+    let best;
+    for (const candidate of candidates) {
+        const distance = levenshtein(needle, candidate.toLowerCase());
+        const threshold = Math.max(2, Math.floor(candidate.length / 3));
+        if (distance > threshold) {
+            continue;
+        }
+        if (!best || distance < best.distance) {
+            best = { value: candidate, distance };
+        }
+    }
+    return best?.value;
+}
+export function suggestCommandPath(input) {
+    return bestSuggestion(input, COMMAND_PATHS);
+}
+export function suggestGlobalFlag(input) {
+    const normalized = input.split("=")[0] ?? input;
+    return bestSuggestion(normalized, GLOBAL_FLAG_NAMES);
+}
+export function formatUnknownCommandMessage(input) {
+    const suggestion = suggestCommandPath(input);
+    if (suggestion) {
+        return `unknown command: ${input} (did you mean "${suggestion}"?)`;
+    }
+    return `unknown command: ${input}`;
+}
+export function formatUnknownGlobalFlagMessage(flag) {
+    const suggestion = suggestGlobalFlag(flag);
+    if (suggestion) {
+        return `unknown global flag: ${flag} (did you mean ${suggestion}?)`;
+    }
+    return `unknown global flag: ${flag}`;
+}

package/dist/cli/support-diagnostics.d.ts

@@ -0,0 +1,19 @@
+import { describeCredentialSource } from "./credentials.js";
+import type { CliContext } from "./context.js";
+export type SupportDiagnostics = {
+    package_name: string;
+    package_version: string;
+    runtime: string;
+    platform: {
+        os: string;
+        arch: string;
+    };
+    config_path: string;
+    env_file_path: string;
+    gateway_url: string;
+    request_id: string;
+    mcp_tool_count: number;
+    credential_source: Awaited<ReturnType<typeof describeCredentialSource>>;
+};
+export declare function buildSupportDiagnostics(ctx: CliContext): Promise<SupportDiagnostics>;
+export declare function formatSupportDiagnosticsTable(diagnostics: SupportDiagnostics): string[];

package/dist/cli/support-diagnostics.js

@@ -0,0 +1,47 @@
+import path from "node:path";
+import { configFilePath } from "./config.js";
+import { describeCredentialSource } from "./credentials.js";
+import { packageVersion } from "./doctor-agent.js";
+import { PaybondMCPServer } from "../mcp-server.js";
+function resolvedEnvFilePath(ctx) {
+    const envFile = ctx.globals.envFile;
+    return path.isAbsolute(envFile) ? path.resolve(envFile) : path.resolve(ctx.cwd, envFile);
+}
+export async function buildSupportDiagnostics(ctx) {
+    const server = new PaybondMCPServer({
+        gatewayBaseUrl: ctx.globals.gateway,
+        apiKey: "paybond_sk_sandbox_redacted_redacted_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    });
+    return {
+        package_name: "@paybond/kit",
+        package_version: packageVersion(),
+        runtime: `node ${process.version}`,
+        platform: {
+            os: process.platform,
+            arch: process.arch,
+        },
+        config_path: configFilePath(),
+        env_file_path: resolvedEnvFilePath(ctx),
+        gateway_url: ctx.globals.gateway,
+        request_id: ctx.globals.requestId,
+        mcp_tool_count: server.listTools().length,
+        credential_source: await describeCredentialSource(ctx.globals, ctx.cwd),
+    };
+}
+export function formatSupportDiagnosticsTable(diagnostics) {
+    const lines = [
+        `package: ${diagnostics.package_name} ${diagnostics.package_version}`,
+        `runtime: ${diagnostics.runtime}`,
+        `platform: ${diagnostics.platform.os} ${diagnostics.platform.arch}`,
+        `config_path: ${diagnostics.config_path}`,
+        `env_file_path: ${diagnostics.env_file_path}`,
+        `gateway_url: ${diagnostics.gateway_url}`,
+        `request_id: ${diagnostics.request_id}`,
+        `mcp_tool_count: ${diagnostics.mcp_tool_count}`,
+        `credential_source: ${JSON.stringify(diagnostics.credential_source)}`,
+    ];
+    if (diagnostics.credential_source.profile) {
+        lines.push(`profile: ${diagnostics.credential_source.profile}`);
+    }
+    return lines;
+}

package/dist/cli/types.d.ts

@@ -0,0 +1,72 @@
+export type OutputFormat = "table" | "json";
+export type ColorMode = "auto" | "always" | "never";
+export type ErrorCategory = "usage" | "auth" | "forbidden" | "validation" | "not_found" | "gone" | "confirmation_required" | "rate_limit" | "gateway" | "network" | "environment" | "internal";
+export type CliErrorDetails = Record<string, unknown>;
+export type CliErrorShape = {
+    category: ErrorCategory;
+    code: string;
+    message: string;
+    details?: CliErrorDetails;
+};
+export type CliEnvelope<T> = {
+    ok: boolean;
+    command: string;
+    data: T | null;
+    warnings: string[];
+    request_id: string;
+    error: CliErrorShape | null;
+};
+export type GlobalOptions = {
+    gateway: string;
+    envFile: string;
+    format: OutputFormat;
+    color: ColorMode;
+    profile?: string;
+    requestId: string;
+    yes: boolean;
+    noOpen: boolean;
+    /** Comma-separated field names for automation output (`--json`). */
+    jsonFields?: string;
+    /** jq-style filter expression (`--jq`). */
+    jqExpr?: string;
+};
+export type Writable = {
+    write(chunk: string): boolean;
+};
+export type CliDependencies = {
+    cwd?: string;
+    fetch?: typeof fetch;
+    stdout?: Writable;
+    stderr?: Writable;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    openBrowser?: (url: string) => Promise<boolean>;
+};
+export type CommandResult<T = Record<string, unknown>> = {
+    data: T;
+    warnings?: string[];
+};
+export declare const EXIT_SUCCESS = 0;
+export declare const EXIT_FAILURE = 1;
+export declare const EXIT_AUTH = 2;
+export declare const EXIT_FORBIDDEN = 3;
+export declare const EXIT_CONFIRMATION = 4;
+export declare const EXIT_GATEWAY = 5;
+export declare const EXIT_ENVIRONMENT = 6;
+export declare class CliError extends Error {
+    readonly category: ErrorCategory;
+    readonly code: string;
+    readonly exitCode: number;
+    readonly details?: CliErrorDetails;
+    constructor(message: string, options?: {
+        category?: ErrorCategory;
+        code?: string;
+        exitCode?: number;
+        details?: CliErrorDetails;
+    });
+}
+export declare function exitCodeForCategory(category: ErrorCategory): number;
+export declare function exitCodeForHttpStatus(status: number): {
+    exitCode: number;
+    category: ErrorCategory;
+};

package/dist/cli/types.js

@@ -0,0 +1,60 @@
+export const EXIT_SUCCESS = 0;
+export const EXIT_FAILURE = 1;
+export const EXIT_AUTH = 2;
+export const EXIT_FORBIDDEN = 3;
+export const EXIT_CONFIRMATION = 4;
+export const EXIT_GATEWAY = 5;
+export const EXIT_ENVIRONMENT = 6;
+export class CliError extends Error {
+    category;
+    code;
+    exitCode;
+    details;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "CliError";
+        this.category = options.category ?? "usage";
+        this.code = options.code ?? `cli.${this.category}`;
+        this.exitCode = options.exitCode ?? exitCodeForCategory(this.category);
+        this.details = options.details;
+    }
+}
+export function exitCodeForCategory(category) {
+    switch (category) {
+        case "auth":
+            return EXIT_AUTH;
+        case "forbidden":
+            return EXIT_FORBIDDEN;
+        case "confirmation_required":
+            return EXIT_CONFIRMATION;
+        case "gateway":
+        case "rate_limit":
+        case "network":
+            return EXIT_GATEWAY;
+        case "environment":
+            return EXIT_ENVIRONMENT;
+        default:
+            return EXIT_FAILURE;
+    }
+}
+export function exitCodeForHttpStatus(status) {
+    if (status === 401) {
+        return { exitCode: EXIT_AUTH, category: "auth" };
+    }
+    if (status === 403) {
+        return { exitCode: EXIT_FORBIDDEN, category: "forbidden" };
+    }
+    if (status === 404) {
+        return { exitCode: EXIT_FAILURE, category: "not_found" };
+    }
+    if (status === 410) {
+        return { exitCode: EXIT_FAILURE, category: "gone" };
+    }
+    if (status === 429) {
+        return { exitCode: EXIT_GATEWAY, category: "rate_limit" };
+    }
+    if (status >= 500) {
+        return { exitCode: EXIT_GATEWAY, category: "gateway" };
+    }
+    return { exitCode: EXIT_FAILURE, category: "validation" };
+}

package/dist/cli/ux.d.ts

@@ -0,0 +1,8 @@
+import type { CliContext } from "./context.js";
+import { type CommandResult } from "./types.js";
+export declare function resolveHelpPath(argv: string[]): string;
+export declare function renderHelpText(path: string): string;
+export declare function handleHelpCommand(argv: string[]): CommandResult;
+export declare function handleExamplesCommand(argv: string[]): CommandResult;
+export declare function handleCompletionCommand(argv: string[]): CommandResult;
+export declare function handleOnboarding(ctx: CliContext, argv: string[]): Promise<CommandResult>;