@paybond/kit 0.10.0 → 0.11.1

package/dist/cli/commands/dev.d.ts

@@ -0,0 +1,7 @@
+import type { CliContext } from "../context.js";
+import { type CommandResult } from "../types.js";
+export declare function handleDevSmoke(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleDevTrace(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleDevUp(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleDevLoop(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleDev(ctx: CliContext, subcommand: string, argv: string[]): Promise<CommandResult>;

package/dist/cli/commands/dev.js

@@ -0,0 +1,348 @@
+import { resolve } from "node:path";
+import { activateOfflineDevMode, createOfflineDevGatewayFetch, isProductionApiKey, } from "../../dev/offline-gateway.js";
+import { runDevWiremockUp } from "../../dev/wiremock-up.js";
+import { appendDevAuditLog, activateDevTraceCollector, buildDevStartupBannerLines, DEV_DEFAULT_POLICY_FILE, DEV_DEFAULT_PRESET, devTraceUrl, finalizeDevTraceCollector, recordSmokeTraceEvent, } from "../../dev/trace-buffer.js";
+import { startDevTraceServer } from "../../dev/trace-server.js";
+import { getSolutionSmokeDefaults } from "../../solutions/catalog.js";
+import { describeCredentialSource, loadEnvFile } from "../credentials.js";
+import { colorize, shouldUseColor } from "../color.js";
+import { consumeBooleanFlag, consumeFlag } from "../globals.js";
+import { CliError } from "../types.js";
+import { handleAgentSandboxSmoke } from "./agent.js";
+import { handleLogin } from "./setup.js";
+import { handlePolicyInit, handlePolicyValidateTools } from "./policy.js";
+import { scheduleCliCommandTelemetry } from "../telemetry.js";
+function devCliError(message, options) {
+    return new CliError(message, {
+        category: options.category ?? "validation",
+        code: options.code,
+        details: options.details ?? {},
+    });
+}
+function appendDevLoopTraceLine(checklistLines, traceUrl, globals) {
+    const useColor = shouldUseColor(globals);
+    return [...checklistLines, colorize(`✓ Trace → ${traceUrl}`, "green", useColor)];
+}
+function writeDevStartupBanner(ctx) {
+    for (const line of buildDevStartupBannerLines()) {
+        ctx.stderr.write(`${line}\n`);
+    }
+}
+function rejectOfflineWithProductionKey(apiKey) {
+    const trimmed = apiKey?.trim();
+    if (trimmed && isProductionApiKey(trimmed)) {
+        throw devCliError("offline dev mode cannot be used with production API keys (paybond_sk_live_...); unset PAYBOND_API_KEY or use a sandbox key", { code: "cli.dev.offline_production_key", category: "validation" });
+    }
+}
+async function assertOfflineDevCredentialsSafe(ctx) {
+    rejectOfflineWithProductionKey(process.env.PAYBOND_API_KEY);
+    if (process.env.PAYBOND_API_KEY?.trim()) {
+        return;
+    }
+    const fromFile = await loadEnvFile(ctx.globals.envFile, ctx.cwd);
+    rejectOfflineWithProductionKey(fromFile);
+}
+function beginOfflineDevSession(ctx) {
+    const { restore } = activateOfflineDevMode();
+    return {
+        ctx: {
+            ...ctx,
+            fetch: createOfflineDevGatewayFetch(),
+        },
+        restore,
+    };
+}
+async function finalizeSmokeResult(ctx, preset, smokeResult, offline = false) {
+    const bind = smokeResult.data.bind;
+    const execute = smokeResult.data.execute;
+    const defaults = getSolutionSmokeDefaults(preset);
+    const resultBody = execute.tool_result && typeof execute.tool_result === "object" && !Array.isArray(execute.tool_result)
+        ? execute.tool_result
+        : defaults.resultBody;
+    const traceEvent = finalizeDevTraceCollector(resultBody, ctx.cwd) ??
+        recordSmokeTraceEvent({
+            preset,
+            bind,
+            execute,
+            resultBody,
+        }, ctx.cwd);
+    const auditLog = await appendDevAuditLog(ctx.cwd, {
+        kind: "dev.smoke",
+        recorded_at: traceEvent.recorded_at,
+        preset,
+        bind,
+        execute,
+        offline,
+    });
+    const traceUrl = devTraceUrl();
+    return {
+        data: {
+            ...smokeResult.data,
+            offline,
+            trace_url: `${traceUrl}/runs/${encodeURIComponent(traceEvent.id)}`,
+            audit_log: auditLog,
+        },
+        warnings: smokeResult.warnings,
+    };
+}
+async function runDevSmokeCore(ctx, preset, offline) {
+    activateDevTraceCollector({ preset, cwd: ctx.cwd });
+    const smokeArgv = ["--preset", preset];
+    const smokeResult = await handleAgentSandboxSmoke(ctx, smokeArgv);
+    return finalizeSmokeResult(ctx, preset, smokeResult, offline);
+}
+export async function handleDevSmoke(ctx, argv) {
+    if (argv[0] === "--help" || argv[0] === "-h") {
+        throw new CliError("help", { category: "usage", code: "cli.help" });
+    }
+    let rest = argv;
+    const offlineFlag = consumeBooleanFlag(rest, "--offline");
+    rest = offlineFlag.rest;
+    const presetFlag = consumeFlag(rest, "--preset");
+    if (presetFlag.rest.length > 0) {
+        throw devCliError(`unexpected arguments: ${presetFlag.rest.join(" ")}`, {
+            code: "cli.usage.unexpected_args",
+            category: "usage",
+        });
+    }
+    const preset = presetFlag.value?.trim() || DEV_DEFAULT_PRESET;
+    if (offlineFlag.present) {
+        await assertOfflineDevCredentialsSafe(ctx);
+    }
+    const offlineSession = offlineFlag.present ? beginOfflineDevSession(ctx) : null;
+    try {
+        const result = await runDevSmokeCore(offlineSession?.ctx ?? ctx, preset, offlineFlag.present);
+        scheduleCliCommandTelemetry(offlineSession?.ctx ?? ctx, {
+            commandPath: "dev smoke",
+            offline: offlineFlag.present,
+        });
+        return result;
+    }
+    finally {
+        offlineSession?.restore();
+    }
+}
+export async function handleDevTrace(ctx, argv) {
+    if (argv[0] === "--help" || argv[0] === "-h") {
+        throw new CliError("help", { category: "usage", code: "cli.help" });
+    }
+    const portFlag = consumeFlag(argv, "--port");
+    if (portFlag.rest.length > 0) {
+        throw devCliError(`unexpected arguments: ${portFlag.rest.join(" ")}`, {
+            code: "cli.usage.unexpected_args",
+            category: "usage",
+        });
+    }
+    const port = portFlag.value ? Number.parseInt(portFlag.value, 10) : undefined;
+    if (port !== undefined && (!Number.isFinite(port) || port <= 0 || port > 65535)) {
+        throw devCliError("dev trace --port must be a valid TCP port", {
+            code: "cli.usage.invalid_port",
+            category: "usage",
+        });
+    }
+    const credentials = await describeCredentialSource(ctx.globals, ctx.cwd);
+    if (credentials.source === "missing") {
+        ctx.stderr.write("No PAYBOND_API_KEY configured. Run paybond dev smoke --offline or paybond login, then paybond dev smoke.\n");
+    }
+    let traceUrl = devTraceUrl(port);
+    const server = await startDevTraceServer({
+        port,
+        cwd: ctx.cwd,
+        onListen(url) {
+            traceUrl = url;
+            ctx.stderr.write(`Paybond dev trace dashboard listening on ${url}\n`);
+            ctx.stderr.write("Press Ctrl+C to stop.\n");
+        },
+    });
+    await new Promise((resolvePromise) => {
+        const shutdown = () => {
+            server.close(() => resolvePromise());
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+    });
+    return {
+        data: {
+            trace_url: traceUrl,
+            port: port ?? devTraceUrl().match(/:(\d+)/)?.[1] ?? "9477",
+            events: [],
+        },
+    };
+}
+export async function handleDevUp(ctx, argv) {
+    if (argv[0] === "--help" || argv[0] === "-h") {
+        throw new CliError("help", { category: "usage", code: "cli.help" });
+    }
+    let rest = argv;
+    const downFlag = consumeBooleanFlag(rest, "--down");
+    rest = downFlag.rest;
+    const portFlag = consumeFlag(rest, "--port");
+    if (portFlag.rest.length > 0) {
+        throw devCliError(`unexpected arguments: ${portFlag.rest.join(" ")}`, {
+            code: "cli.usage.unexpected_args",
+            category: "usage",
+        });
+    }
+    const port = portFlag.value ? Number.parseInt(portFlag.value, 10) : undefined;
+    if (port !== undefined && (!Number.isFinite(port) || port <= 0 || port > 65535)) {
+        throw devCliError("dev up --port must be a valid TCP port", {
+            code: "cli.usage.invalid_port",
+            category: "usage",
+        });
+    }
+    try {
+        const result = await runDevWiremockUp({ port, down: downFlag.present });
+        if (result.status === "stopped") {
+            ctx.stderr.write(`Stopped WireMock container ${result.container_name}.\n`);
+        }
+        else if (result.status === "already_running") {
+            ctx.stderr.write(`WireMock already running at ${result.gateway_url}\n`);
+        }
+        else {
+            ctx.stderr.write(`WireMock Gateway listening at ${result.gateway_url}\n`);
+            ctx.stderr.write(`Mappings loaded from ${result.wiremock_dir}\n`);
+        }
+        if (result.next_commands.length > 0) {
+            ctx.stderr.write("Next:\n");
+            for (const command of result.next_commands) {
+                ctx.stderr.write(`  ${command}\n`);
+            }
+        }
+        return { data: result };
+    }
+    catch (err) {
+        throw devCliError(err instanceof Error ? err.message : String(err), {
+            code: "cli.dev.wiremock_failed",
+            category: "validation",
+        });
+    }
+}
+export async function handleDevLoop(ctx, argv) {
+    if (argv[0] === "--help" || argv[0] === "-h") {
+        throw new CliError("help", { category: "usage", code: "cli.help" });
+    }
+    let rest = argv;
+    const offlineFlag = consumeBooleanFlag(rest, "--offline");
+    rest = offlineFlag.rest;
+    const policyFlag = consumeFlag(rest, "--policy-file");
+    rest = policyFlag.rest;
+    const noLoginFlag = consumeBooleanFlag(rest, "--no-login");
+    rest = noLoginFlag.rest;
+    if (rest.length > 0) {
+        throw devCliError(`unexpected arguments: ${rest.join(" ")}`, {
+            code: "cli.usage.unexpected_args",
+            category: "usage",
+        });
+    }
+    const policyFile = policyFlag.value?.trim() || DEV_DEFAULT_POLICY_FILE;
+    const steps = [];
+    const bannerLines = buildDevStartupBannerLines();
+    if (offlineFlag.present) {
+        await assertOfflineDevCredentialsSafe(ctx);
+    }
+    const offlineSession = offlineFlag.present ? beginOfflineDevSession(ctx) : null;
+    const activeCtx = offlineSession?.ctx ?? ctx;
+    writeDevStartupBanner(ctx);
+    try {
+        if (offlineFlag.present) {
+            steps.push({
+                name: "login",
+                ok: true,
+                skipped: true,
+                message: "offline mode (no PAYBOND_API_KEY required)",
+            });
+        }
+        else {
+            const credentials = await describeCredentialSource(ctx.globals, ctx.cwd);
+            if (credentials.source === "missing" && !noLoginFlag.present) {
+                const loginResult = await handleLogin(ctx, []);
+                steps.push({ name: "login", ok: true, data: loginResult.data });
+            }
+            else {
+                steps.push({
+                    name: "login",
+                    ok: credentials.source !== "missing",
+                    skipped: credentials.source !== "missing",
+                    message: credentials.source === "missing" ? "missing credentials; run paybond login" : "credentials present",
+                });
+                if (credentials.source === "missing") {
+                    throw devCliError("dev loop requires sandbox credentials; run paybond login, pass --offline, or omit --no-login", {
+                        code: "cli.dev.missing_credentials",
+                        category: "validation",
+                        details: { steps },
+                    });
+                }
+            }
+        }
+        const initResult = await handlePolicyInit(activeCtx, [
+            "--preset",
+            DEV_DEFAULT_PRESET,
+            "--out",
+            policyFile,
+            "--force",
+        ]);
+        steps.push({ name: "policy_init", ok: true, data: initResult.data });
+        const validateResult = await handlePolicyValidateTools(activeCtx, [
+            "--file",
+            policyFile,
+            "--local-only",
+        ]);
+        const validateData = validateResult.data;
+        steps.push({
+            name: "validate_tools",
+            ok: validateData.valid === true,
+            data: validateData,
+        });
+        if (validateData.valid !== true) {
+            throw devCliError("dev loop failed policy validate-tools --local-only", {
+                code: "cli.dev.validate_failed",
+                category: "validation",
+                details: { steps },
+            });
+        }
+        const smokeResult = await runDevSmokeCore(activeCtx, DEV_DEFAULT_PRESET, offlineFlag.present);
+        steps.push({ name: "smoke", ok: true, data: smokeResult.data });
+        const traceUrl = String(smokeResult.data.trace_url ?? devTraceUrl());
+        const auditLog = String(smokeResult.data.audit_log ?? resolve(ctx.cwd, ".paybond/dev-audit.jsonl"));
+        const smokeChecklist = Array.isArray(smokeResult.data.checklist_lines)
+            ? smokeResult.data.checklist_lines
+            : [];
+        scheduleCliCommandTelemetry(activeCtx, {
+            commandPath: "dev loop",
+            offline: offlineFlag.present,
+        });
+        return {
+            data: {
+                offline: offlineFlag.present,
+                steps,
+                smoke: smokeResult.data,
+                trace_url: traceUrl,
+                audit_log: auditLog,
+                banner_lines: bannerLines,
+                checklist_lines: appendDevLoopTraceLine(smokeChecklist, traceUrl, ctx.globals),
+            },
+            warnings: smokeResult.warnings,
+        };
+    }
+    finally {
+        offlineSession?.restore();
+    }
+}
+export async function handleDev(ctx, subcommand, argv) {
+    if (subcommand === "smoke") {
+        return handleDevSmoke(ctx, argv);
+    }
+    if (subcommand === "trace") {
+        return handleDevTrace(ctx, argv);
+    }
+    if (subcommand === "loop") {
+        return handleDevLoop(ctx, argv);
+    }
+    if (subcommand === "up") {
+        return handleDevUp(ctx, argv);
+    }
+    throw devCliError(`unknown dev subcommand: dev ${subcommand}`, {
+        code: "cli.usage.unknown_command",
+        category: "usage",
+    });
+}

package/dist/cli/commands/discovery.js

@@ -156,11 +156,11 @@ export async function handleAuditExports(ctx, subcommand, argv) {
                         code: "cli.audit.missing_download_token",
                     });
                 }
-                const bundleUrl = gatewayUrl(ctx.globals.gateway, `/v1/compliance/audit-exports/${encodeURIComponent(jobId)}/bundle?token=${encodeURIComponent(token)}`);
-                const apiKey = await import("../credentials.js").then((mod) => mod.resolveApiKey(ctx.globals, ctx.cwd));
+                const bundleUrl = gatewayUrl(ctx.globals.gateway, `/v1/compliance/audit-exports/${encodeURIComponent(jobId)}/bundle`);
                 const response = await ctx.fetch(bundleUrl, {
+                    method: "POST",
                     headers: {
-                        authorization: `Bearer ${apiKey}`,
+                        authorization: `Bearer ${token}`,
                         "x-request-id": ctx.globals.requestId,
                     },
                 });

package/dist/cli/commands/policy.d.ts

@@ -0,0 +1,13 @@
+import { type CliContext } from "../context.js";
+import { type CommandResult } from "../types.js";
+export declare function handlePolicyPresetsList(_ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handlePolicyPresetsShow(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handlePolicyInit(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handlePolicyInitOrg(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handlePolicyExtend(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handlePolicyValidateTools(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handlePolicyTemplates(_ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handlePolicyPreview(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handlePolicyImportMcpReceipt(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handlePolicyValidateEvidence(_ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handlePolicyImportX402Receipt(ctx: CliContext, argv: string[]): Promise<CommandResult>;