@paybond/kit 0.9.8 → 0.11.0

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

@@ -0,0 +1,18 @@
+import { commandPath, type CliContext } from "../context.js";
+import { type CommandResult } from "../types.js";
+declare function readJsonFile(filePath: string): Promise<Record<string, unknown>>;
+export declare function handleLogin(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleInitWizard(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleInitGuardrail(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleInitAgentMiddleware(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleInitCompletion(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleMcpServe(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleMcpTools(ctx: CliContext): Promise<CommandResult>;
+export declare function handleMcpInstall(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleMcpVerifyConfig(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleDoctor(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleConfig(ctx: CliContext, subcommand: string, argv: string[]): Promise<CommandResult>;
+export declare function handleWhoami(ctx: CliContext): Promise<CommandResult>;
+export declare function handleVersion(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleDiagnose(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export { readJsonFile, commandPath };

package/dist/cli/commands/setup.js

@@ -0,0 +1,513 @@
+import { mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { readJsonBody } from "../automation.js";
+import { listConfigEntries, resolveConfigValue, setConfigValue, unsetConfigValue } from "../config.js";
+import { commandPath, withGateway } from "../context.js";
+import { assertApiKeyShape, resolveApiKey, resolvedDefaultsForDoctor } from "../credentials.js";
+import { runAgentMiddlewareDoctorCheck } from "../doctor-agent-middleware.js";
+import { packageVersion, runAgentMcpChecks } from "../doctor-agent.js";
+import { runCompletionCatalogDoctorChecks } from "../../doctor-completion.js";
+import { consumeBooleanFlag, consumeFlag } from "../globals.js";
+import { maskApiKey, redactConfigValue } from "../redact.js";
+import { mergeMcpToolPolicy, parseMcpToolAllowlist, parseMcpToolPolicy, resolveMcpToolPolicy, } from "../mcp-policy.js";
+import { parseMcpInstallFormat, parseMcpInstallHost, parseMcpInstallScope, planMcpInstall, } from "../mcp-install.js";
+import { verifyMcpInstallPlan } from "../mcp-verify-config.js";
+import { buildSupportDiagnostics, formatSupportDiagnosticsTable } from "../support-diagnostics.js";
+import { CliError } from "../types.js";
+import { main as runInitMain } from "../../init.js";
+import { parseCompletionInitArgs, scaffoldCompletionInit } from "../../completion-init.js";
+import { parseProjectInitArgv, runProjectInit } from "../../project-init.js";
+import { copyTemplateToDirectory, normalizeTemplateId, templateInitUsage, } from "../../template-init.js";
+import { parseArgs as parseLoginArgs, runLogin } from "../../login.js";
+import { main as runMcpServerMain } from "../../mcp-server.js";
+import { PaybondMCPServer } from "../../mcp-server.js";
+async function readJsonFile(filePath) {
+    return readJsonBody(filePath, process.stdin);
+}
+function loginResultData(result) {
+    const data = {
+        env_file: result.envPath,
+        key_masked: result.keyMasked,
+        key_written: result.keyWritten,
+        environment: result.environment,
+        tenant_id: result.tenantId,
+        tenant_uuid: result.tenantUuid,
+        verification_uri: result.verificationUri,
+        user_code: result.userCode,
+    };
+    if (result.expiresAt) {
+        data.expires_at = result.expiresAt;
+    }
+    return data;
+}
+export async function handleLogin(ctx, argv) {
+    if (argv[0] === "--help" || argv[0] === "-h") {
+        throw new CliError("help", { category: "usage", code: "cli.help" });
+    }
+    let parsed;
+    try {
+        parsed = parseLoginArgs(["login", ...argv]);
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "validation",
+            code: "cli.login.rejected",
+        });
+    }
+    if (parsed === "help") {
+        throw new CliError("help", { category: "usage", code: "cli.help" });
+    }
+    const options = {
+        ...parsed,
+        gateway: ctx.globals.gateway,
+        envFile: ctx.globals.envFile,
+        noOpen: ctx.globals.noOpen,
+    };
+    let result;
+    try {
+        result = await runLogin(options, {
+            cwd: ctx.cwd,
+            fetch: ctx.fetch,
+            humanOutput: ctx.globals.format !== "json",
+            stdout: {
+                write(chunk) {
+                    ctx.stdout.write(chunk);
+                    return true;
+                },
+            },
+            stderr: {
+                write(chunk) {
+                    ctx.stderr.write(chunk);
+                    return true;
+                },
+            },
+            sleep: ctx.deps.sleep,
+            openBrowser: ctx.deps.openBrowser,
+            now: ctx.deps.now,
+        });
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "validation",
+            code: "cli.login.failed",
+        });
+    }
+    return { data: loginResultData(result) };
+}
+export async function handleInitWizard(ctx, argv) {
+    let parsed;
+    try {
+        parsed = parseProjectInitArgv(argv);
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "usage",
+            code: "cli.usage.invalid_init",
+        });
+    }
+    if (parsed === "help") {
+        throw new CliError(templateInitUsage(), { category: "usage", code: "cli.help" });
+    }
+    try {
+        if (parsed.template) {
+            const result = await copyTemplateToDirectory({
+                cwd: ctx.cwd,
+                templateId: normalizeTemplateId(parsed.template),
+                framework: parsed.framework,
+                force: parsed.force,
+                writeStdout(line) {
+                    if (ctx.globals.format !== "json") {
+                        ctx.stdout.write(`${line}\n`);
+                    }
+                },
+            });
+            return { data: result };
+        }
+        const { template: _template, ...wizardOptions } = parsed;
+        const result = await runProjectInit({
+            cwd: ctx.cwd,
+            ...wizardOptions,
+            writeStdout(line) {
+                if (ctx.globals.format !== "json") {
+                    ctx.stdout.write(`${line}\n`);
+                }
+            },
+        });
+        return { data: result };
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "validation",
+            code: "cli.init.failed",
+        });
+    }
+}
+export async function handleInitGuardrail(ctx, argv) {
+    return handleInitScaffold(ctx, argv, "paid-tool-guard", "paybond-paid-tool-guard.ts");
+}
+export async function handleInitAgentMiddleware(ctx, argv) {
+    return handleInitScaffold(ctx, argv, "agent-middleware", "paybond-agent-middleware.ts");
+}
+async function handleInitScaffold(ctx, argv, defaultPreset, defaultOut) {
+    const code = await runInitMain(["--preset", defaultPreset, ...argv]);
+    if (code !== 0) {
+        throw new CliError(`init ${defaultPreset} failed`, { category: "validation", code: "cli.init.failed", exitCode: code });
+    }
+    const outFlag = consumeFlag(argv, "--out");
+    const frameworkFlag = consumeFlag(argv, "--framework");
+    return {
+        data: {
+            out: outFlag.value ?? defaultOut,
+            preset: defaultPreset,
+            framework: frameworkFlag.value ?? (defaultPreset === "agent-middleware" ? "generic" : "provider-agnostic"),
+            bytes_written: true,
+            completion_preset: "cost_and_completion",
+        },
+    };
+}
+export async function handleInitCompletion(ctx, argv) {
+    let parsed;
+    try {
+        const result = parseCompletionInitArgs(argv);
+        if (result === "help") {
+            throw new CliError("help", { category: "usage", code: "cli.help" });
+        }
+        parsed = result;
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "usage",
+            code: "cli.usage.invalid_init_completion",
+        });
+    }
+    try {
+        await scaffoldCompletionInit(parsed);
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "validation",
+            code: "cli.init.failed",
+        });
+    }
+    return {
+        data: {
+            out: parsed.out,
+            preset: parsed.preset,
+            bytes_written: true,
+        },
+    };
+}
+export async function handleMcpServe(ctx, argv) {
+    if (argv.length > 0 && argv[0] !== "--help" && argv[0] !== "-h") {
+        throw new CliError(`unexpected arguments: ${argv.join(" ")}`, { category: "usage", code: "cli.usage.unexpected_args" });
+    }
+    ctx.stderr.write("Starting Paybond MCP stdio server (stdout is reserved for MCP JSON-RPC).\n");
+    const code = runMcpServerMain([]);
+    if (code !== 0) {
+        throw new CliError("mcp serve failed", { category: "internal", code: "cli.mcp.serve_failed", exitCode: code });
+    }
+    return { data: { started: true } };
+}
+export async function handleMcpTools(ctx) {
+    const server = new PaybondMCPServer({ gatewayBaseUrl: ctx.globals.gateway, apiKey: "paybond_sk_sandbox_redacted_redacted_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" });
+    const tools = server.listTools().map((tool) => ({
+        name: tool.name,
+        title: tool.title ?? tool.name,
+        description: tool.description,
+    }));
+    return { data: { tools } };
+}
+export async function handleMcpInstall(ctx, argv) {
+    const hostFlag = consumeFlag(argv, "--host");
+    const formatFlag = consumeFlag(argv, "--format");
+    const scopeFlag = consumeFlag(argv, "--scope");
+    const outFlag = consumeFlag(argv, "--out");
+    const envFileFlag = consumeFlag(argv, "--env-file");
+    const toolPolicyFlag = consumeFlag(argv, "--tool-policy");
+    const toolAllowlistFlag = consumeFlag(argv, "--tool-allowlist");
+    let format;
+    let scope;
+    let installHost;
+    let toolPolicy;
+    try {
+        installHost = parseMcpInstallHost(hostFlag.value);
+        format = parseMcpInstallFormat(formatFlag.value, installHost);
+        scope = parseMcpInstallScope(scopeFlag.value);
+        toolPolicy = mergeMcpToolPolicy(parseMcpToolPolicy(toolPolicyFlag.value), parseMcpToolAllowlist(toolAllowlistFlag.value));
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "usage",
+            code: "cli.usage.invalid_mcp_install",
+        });
+    }
+    const plan = planMcpInstall({
+        host: installHost,
+        scope,
+        format,
+        envFile: envFileFlag.value ?? ctx.globals.envFile,
+        out: outFlag.value,
+        cwd: ctx.cwd,
+        home: process.env.HOME ?? process.env.USERPROFILE ?? ctx.cwd,
+        toolPolicy: resolveMcpToolPolicy(toolPolicy),
+    });
+    if (plan.printed) {
+        if (ctx.globals.format !== "json") {
+            ctx.stdout.write(plan.payload);
+        }
+    }
+    else {
+        const configPath = plan.configPath;
+        await mkdir(path.dirname(configPath), { recursive: true });
+        const { writeAtomicFileAsync } = await import("../automation.js");
+        await writeAtomicFileAsync(configPath, plan.payload, 0o600);
+    }
+    const data = {
+        host: plan.host,
+        scope: plan.scope,
+        format: plan.format,
+        config_path: plan.configPath,
+        server_command: plan.serverCommand.join(" "),
+        printed: plan.printed,
+    };
+    if (plan.toolPolicy?.policy) {
+        data.tool_policy = plan.toolPolicy.policy;
+        if (plan.toolPolicy.allowlist.length > 0) {
+            data.tool_allowlist = [...plan.toolPolicy.allowlist];
+        }
+    }
+    if (plan.printed && ctx.globals.format === "json") {
+        data.payload = plan.payload;
+    }
+    return { data };
+}
+export async function handleMcpVerifyConfig(ctx, argv) {
+    const hostFlag = consumeFlag(argv, "--host");
+    const formatFlag = consumeFlag(argv, "--format");
+    const envFileFlag = consumeFlag(argv, "--env-file");
+    const configFlag = consumeFlag(argv, "--config");
+    let installHost;
+    let format;
+    try {
+        installHost = parseMcpInstallHost(hostFlag.value);
+        format = parseMcpInstallFormat(formatFlag.value, installHost);
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "usage",
+            code: "cli.usage.invalid_mcp_verify_config",
+        });
+    }
+    const result = await verifyMcpInstallPlan({
+        host: installHost,
+        format,
+        envFile: envFileFlag.value ?? ctx.globals.envFile,
+        cwd: ctx.cwd,
+        home: process.env.HOME ?? process.env.USERPROFILE ?? ctx.cwd,
+        configPath: configFlag.value,
+    });
+    return {
+        data: {
+            ok: result.ok,
+            host: result.host,
+            source: result.source,
+            config_path: result.configPath,
+            message: result.message,
+            issues: result.issues,
+            tool_policy: result.toolPolicy?.policy ?? null,
+        },
+    };
+}
+export async function handleDoctor(ctx, argv) {
+    const agentFlag = consumeBooleanFlag(argv, "--agent");
+    const hostFlag = consumeFlag(agentFlag.rest, "--host");
+    const checks = [];
+    const defaults = resolvedDefaultsForDoctor(ctx.globals);
+    checks.push({
+        name: "runtime",
+        ok: true,
+        message: `node ${process.version}`,
+    });
+    checks.push({
+        name: "package",
+        ok: true,
+        message: "@paybond/kit",
+        details: { version: packageVersion() },
+    });
+    const envPath = path.isAbsolute(defaults.envFile)
+        ? path.resolve(defaults.envFile)
+        : path.resolve(ctx.cwd, defaults.envFile);
+    try {
+        await readFile(envPath, "utf8");
+        checks.push({ name: "env_file", ok: true, message: envPath });
+    }
+    catch {
+        checks.push({ name: "env_file", ok: false, message: `env file not found: ${envPath}` });
+    }
+    let apiKey = "";
+    try {
+        apiKey = await resolveApiKey(ctx.globals, ctx.cwd);
+        assertApiKeyShape(apiKey);
+        checks.push({ name: "key_shape", ok: true, message: maskApiKey(apiKey) });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        checks.push({ name: "key_shape", ok: false, message });
+    }
+    if (apiKey) {
+        try {
+            await withGateway(ctx, async (gateway) => {
+                await gateway.getJson("/v1/auth/principal");
+                return { data: {} };
+            });
+            checks.push({ name: "principal", ok: true, message: "principal lookup succeeded" });
+        }
+        catch (err) {
+            checks.push({
+                name: "principal",
+                ok: false,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (agentFlag.present) {
+        if (!apiKey) {
+            for (const name of [
+                "mcp_host_config",
+                "mcp_env_resolution",
+                "mcp_launch",
+                "mcp_initialize",
+                "mcp_tools_list",
+                "mcp_tool_schemas",
+                "mcp_stdout_purity",
+            ]) {
+                checks.push({ name, ok: false, message: "skipped MCP probe (missing API key)" });
+            }
+        }
+        else {
+            const agentChecks = await runAgentMcpChecks({
+                envFile: defaults.envFile,
+                cwd: ctx.cwd,
+                host: hostFlag.value ?? "generic",
+            });
+            checks.push(...agentChecks);
+        }
+        if (apiKey) {
+            checks.push(await runAgentMiddlewareDoctorCheck(ctx, apiKey));
+        }
+        else {
+            checks.push({
+                name: "agent_middleware_smoke",
+                ok: false,
+                message: "skipped (missing API key)",
+            });
+        }
+    }
+    const completionChecks = await runCompletionCatalogDoctorChecks({
+        cwd: ctx.cwd,
+        gateway: apiKey
+            ? {
+                async getJson(path) {
+                    const result = await withGateway(ctx, async (gateway) => {
+                        const body = await gateway.getJson(path);
+                        return { data: body };
+                    });
+                    return result.data;
+                },
+            }
+            : undefined,
+    });
+    checks.push(...completionChecks);
+    const summary = checks.every((check) => check.ok) ? "pass" : "fail";
+    return { data: { checks, summary } };
+}
+export async function handleConfig(ctx, subcommand, argv) {
+    if (subcommand === "list") {
+        const entries = await listConfigEntries(ctx.globals.profile);
+        return { data: { entries } };
+    }
+    if (subcommand === "get") {
+        const key = argv[0];
+        if (!key) {
+            throw new CliError("config get requires <key>", { category: "usage", code: "cli.usage.missing_key" });
+        }
+        const value = await resolveConfigValue(key, ctx.globals.profile);
+        if (value === undefined) {
+            throw new CliError(`config key not found: ${key}`, { category: "not_found", code: "cli.config.not_found" });
+        }
+        return { data: { key, value: redactConfigValue(key, value) } };
+    }
+    if (subcommand === "set") {
+        const key = argv[0];
+        const value = argv[1];
+        if (!key || value === undefined) {
+            throw new CliError("config set requires <key> <value>", { category: "usage", code: "cli.usage.missing_args" });
+        }
+        await setConfigValue(key, value, ctx.globals.profile);
+        return { data: { key, set: true } };
+    }
+    if (subcommand === "unset") {
+        const key = argv[0];
+        if (!key) {
+            throw new CliError("config unset requires <key>", { category: "usage", code: "cli.usage.missing_key" });
+        }
+        const removed = await unsetConfigValue(key, ctx.globals.profile);
+        return { data: { key, removed } };
+    }
+    throw new CliError(`unknown config subcommand: ${subcommand}`, { category: "usage", code: "cli.usage.unknown_command" });
+}
+export async function handleWhoami(ctx) {
+    return withGateway(ctx, async (gateway) => {
+        const principal = await gateway.getJson("/v1/auth/principal");
+        const stripped = { ...principal };
+        delete stripped.access_token;
+        delete stripped.refresh_token;
+        return {
+            data: {
+                tenant_id: String(principal.tenant_id ?? ""),
+                tenant_uuid: String(principal.tenant_uuid ?? ""),
+                environment: String(principal.environment ?? ""),
+                service_account_role: String(principal.service_account_role ?? ""),
+                principal: stripped,
+            },
+        };
+    });
+}
+export async function handleVersion(ctx, argv) {
+    const verboseFlag = consumeBooleanFlag(argv, "--verbose");
+    if (verboseFlag.rest.length > 0) {
+        throw new CliError(`unexpected arguments: ${verboseFlag.rest.join(" ")}`, {
+            category: "usage",
+            code: "cli.usage.unexpected_args",
+        });
+    }
+    if (verboseFlag.present) {
+        const diagnostics = await buildSupportDiagnostics(ctx);
+        return { data: diagnostics };
+    }
+    return { data: { version: packageVersion() } };
+}
+export async function handleDiagnose(ctx, argv) {
+    const redactedFlag = consumeBooleanFlag(argv, "--redacted");
+    if (redactedFlag.rest.length > 0) {
+        throw new CliError(`unexpected arguments: ${redactedFlag.rest.join(" ")}`, {
+            category: "usage",
+            code: "cli.usage.unexpected_args",
+        });
+    }
+    if (!redactedFlag.present) {
+        throw new CliError("paybond diagnose requires --redacted for support bundles", {
+            category: "usage",
+            code: "cli.diagnose.redacted_required",
+        });
+    }
+    const diagnostics = await buildSupportDiagnostics(ctx);
+    return {
+        data: {
+            redacted: true,
+            diagnostics,
+            lines: formatSupportDiagnosticsTable(diagnostics),
+        },
+    };
+}
+export { readJsonFile, commandPath };

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

@@ -0,0 +1,7 @@
+import { commandPath, type CliContext } from "../context.js";
+import { type CommandResult } from "../types.js";
+export declare function handleKeys(ctx: CliContext, subcommand: string, argv: string[]): Promise<CommandResult>;
+export declare function handleIntents(ctx: CliContext, subcommand: string, argv: string[]): Promise<CommandResult>;
+export declare function handleGuardrails(ctx: CliContext, subcommand: string, argv: string[]): Promise<CommandResult>;
+export declare function handleSpendAuthorize(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export { commandPath };