@paybond/kit 0.9.8 → 0.11.0

package/dist/cli/telemetry.js

@@ -0,0 +1,94 @@
+import { createHash, randomUUID } from "node:crypto";
+import { platform } from "node:os";
+import { loadConfigFile, saveConfigFile } from "./config.js";
+import { packageVersion } from "./doctor-agent.js";
+import { isLocalGatewayHost } from "../gateway-url.js";
+const INSTALL_ID_HASH_PREFIX = "paybond-kit-cli:";
+function telemetryEnvDisabled() {
+    const raw = process.env.PAYBOND_TELEMETRY?.trim().toLowerCase();
+    return raw === "0" || raw === "false" || raw === "off" || raw === "no";
+}
+function telemetryEnvForced() {
+    const raw = process.env.PAYBOND_TELEMETRY?.trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
+function isCiEnvironment() {
+    const ci = process.env.CI?.trim().toLowerCase();
+    return ci === "true" || ci === "1";
+}
+function isLocalGateway(gateway) {
+    try {
+        return isLocalGatewayHost(new URL(gateway).hostname);
+    }
+    catch {
+        return true;
+    }
+}
+export function hashCliInstallId(installId) {
+    return createHash("sha256").update(`${INSTALL_ID_HASH_PREFIX}${installId}`).digest("hex");
+}
+export async function resolveCliInstallId() {
+    const config = await loadConfigFile();
+    const existing = config.install_id?.trim();
+    if (existing) {
+        return existing;
+    }
+    const installId = randomUUID();
+    await saveConfigFile({ ...config, install_id: installId });
+    return installId;
+}
+export async function cliTelemetryEnabled(gateway) {
+    if (telemetryEnvDisabled() || isCiEnvironment()) {
+        return false;
+    }
+    if (telemetryEnvForced()) {
+        return true;
+    }
+    const config = await loadConfigFile();
+    if (config.telemetry === false) {
+        return false;
+    }
+    return !isLocalGateway(gateway);
+}
+/**
+ * Fire-and-forget adoption telemetry for successful local dev commands.
+ * Failures are swallowed so CLI workflows never depend on analytics.
+ */
+export async function reportCliCommandSuccess(ctx, input) {
+    if (!(await cliTelemetryEnabled(ctx.globals.gateway))) {
+        return;
+    }
+    const installId = await resolveCliInstallId();
+    const body = {
+        command_path: input.commandPath,
+        success: true,
+        offline: input.offline,
+        kit_version: packageVersion(),
+        runtime: "node",
+        install_id_sha256: hashCliInstallId(installId),
+        os_name: platform(),
+        client_context: {
+            format: ctx.globals.format,
+        },
+    };
+    const url = `${ctx.globals.gateway.replace(/\/+$/, "")}/v1/public/analytics/kit-cli`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 2_000);
+    try {
+        await ctx.fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        // Telemetry must never block or fail the CLI command.
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export function scheduleCliCommandTelemetry(ctx, input) {
+    void reportCliCommandSuccess(ctx, input);
+}

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>;

package/dist/cli/ux.js

@@ -0,0 +1,164 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { COMMAND_EXAMPLES, COMPLETION_SCRIPTS, WORKFLOWS } from "./command-spec.js";
+import { resolvedDefaultsForDoctor } from "./credentials.js";
+import { helpForCommand } from "./help.js";
+import { consumeFlag } from "./globals.js";
+import { planMcpInstall, parseMcpInstallFormat, parseMcpInstallHost, parseMcpInstallScope } from "./mcp-install.js";
+import { CliError } from "./types.js";
+import { handleDoctor } from "./commands/setup.js";
+export function resolveHelpPath(argv) {
+    return argv.filter((part) => part !== "--help" && part !== "-h").join(" ");
+}
+export function renderHelpText(path) {
+    return helpForCommand(path);
+}
+export function handleHelpCommand(argv) {
+    const helpPath = resolveHelpPath(argv);
+    return { data: { text: renderHelpText(helpPath), path: helpPath || "paybond" } };
+}
+export function handleExamplesCommand(argv) {
+    const filterPath = argv.filter((part) => part !== "--help" && part !== "-h").join(" ");
+    const lines = [];
+    if (!filterPath) {
+        lines.push("Workflows:");
+        for (const workflow of WORKFLOWS) {
+            lines.push("", workflow.title);
+            if (workflow.description) {
+                lines.push(workflow.description);
+            }
+            for (const example of workflow.examples) {
+                lines.push(`  $ ${example}`);
+            }
+            if (workflow.next) {
+                lines.push(`  Next: ${workflow.next}`);
+            }
+        }
+        lines.push("", "Commands:");
+    }
+    const entries = filterPath
+        ? Object.entries(COMMAND_EXAMPLES).filter(([commandPath]) => commandPath === filterPath || commandPath.startsWith(`${filterPath} `))
+        : Object.entries(COMMAND_EXAMPLES);
+    if (filterPath && entries.length === 0) {
+        throw new CliError(`no examples found for: ${filterPath}`, {
+            category: "usage",
+            code: "cli.usage.unknown_command",
+        });
+    }
+    for (const [commandPath, examples] of entries) {
+        lines.push("", `paybond ${commandPath}`);
+        for (const example of examples) {
+            lines.push(`  $ ${example}`);
+        }
+    }
+    return { data: { text: lines.join("\n").trim(), filter: filterPath || null, count: entries.length } };
+}
+export function handleCompletionCommand(argv) {
+    const shell = argv[0];
+    if (!shell || shell === "--help" || shell === "-h") {
+        throw new CliError("completion requires bash|zsh|fish", {
+            category: "usage",
+            code: "cli.usage.missing_completion_shell",
+        });
+    }
+    const script = COMPLETION_SCRIPTS[shell];
+    if (!script) {
+        throw new CliError(`unsupported completion shell: ${shell} (expected bash|zsh|fish)`, {
+            category: "usage",
+            code: "cli.usage.invalid_completion_shell",
+        });
+    }
+    return { data: { shell, script } };
+}
+export async function handleOnboarding(ctx, argv) {
+    const hostFlag = consumeFlag(argv, "--host");
+    let installHost = "generic";
+    try {
+        if (hostFlag.present) {
+            installHost = parseMcpInstallHost(hostFlag.value);
+        }
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "usage",
+            code: "cli.usage.invalid_mcp_install",
+        });
+    }
+    const steps = [];
+    steps.push({
+        name: "runtime",
+        ok: true,
+        message: `node ${process.version}`,
+    });
+    const defaults = resolvedDefaultsForDoctor(ctx.globals);
+    const envPath = path.isAbsolute(defaults.envFile)
+        ? path.resolve(defaults.envFile)
+        : path.resolve(ctx.cwd, defaults.envFile);
+    let loggedIn = false;
+    try {
+        const { resolveApiKey } = await import("./credentials.js");
+        const apiKey = await resolveApiKey(ctx.globals, ctx.cwd);
+        loggedIn = true;
+        const { maskApiKey } = await import("./redact.js");
+        steps.push({
+            name: "login",
+            ok: true,
+            message: `credentials found (${maskApiKey(apiKey)})`,
+        });
+    }
+    catch (err) {
+        steps.push({
+            name: "login",
+            ok: false,
+            message: err instanceof Error ? err.message : String(err),
+            command: "paybond login",
+        });
+    }
+    const guardrailPath = path.resolve(ctx.cwd, "paybond-paid-tool-guard.ts");
+    let guardrailExists = false;
+    try {
+        await access(guardrailPath);
+        guardrailExists = true;
+    }
+    catch {
+        guardrailExists = false;
+    }
+    steps.push({
+        name: "guardrail",
+        ok: guardrailExists,
+        message: guardrailExists ? `found ${guardrailPath}` : `guardrail file not found (${guardrailPath})`,
+        command: guardrailExists ? undefined : "paybond init guardrail",
+    });
+    const plan = planMcpInstall({
+        host: installHost,
+        scope: parseMcpInstallScope("local"),
+        format: parseMcpInstallFormat(undefined, installHost),
+        envFile: defaults.envFile,
+        cwd: ctx.cwd,
+        home: process.env.HOME ?? process.env.USERPROFILE ?? ctx.cwd,
+    });
+    steps.push({
+        name: "mcp_config",
+        ok: true,
+        message: `preview ready for host=${plan.host} (non-destructive --scope local)`,
+        command: `paybond mcp install --host ${plan.host} --scope local`,
+    });
+    const doctor = await handleDoctor(ctx, loggedIn ? ["--agent"] : []);
+    const doctorOk = String(doctor.data.summary) === "pass";
+    steps.push({
+        name: "doctor",
+        ok: doctorOk,
+        message: `doctor ${doctor.data.summary}`,
+        command: doctorOk ? undefined : "paybond doctor --agent",
+    });
+    const summary = steps.every((step) => step.ok) ? "pass" : "fail";
+    return {
+        data: {
+            steps,
+            summary,
+            env_file: envPath,
+            mcp_preview: plan.printed ? plan.payload : undefined,
+            doctor_checks: doctor.data.checks,
+        },
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export { runCli } from "./cli/router.js";

package/dist/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { runCli } from "./cli/router.js";
+async function invokedFromCLI() {
+    const scriptPath = process.argv[1];
+    if (!scriptPath) {
+        return false;
+    }
+    async function realFileURL(filePath) {
+        let resolved = path.resolve(filePath);
+        try {
+            resolved = await fs.realpath(resolved);
+        }
+        catch {
+            // keep absolute path
+        }
+        const href = pathToFileURL(resolved).href;
+        return href.startsWith("file:///var/") ? href.replace("file:///var/", "file:///private/var/") : href;
+    }
+    return (await realFileURL(scriptPath)) === (await realFileURL(fileURLToPath(import.meta.url)));
+}
+invokedFromCLI().then((invoked) => {
+    if (!invoked) {
+        return;
+    }
+    runCli(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    }, (err) => {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+    });
+}, (err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});
+export { runCli } from "./cli/router.js";

package/dist/completion-catalog-digest.d.ts

@@ -0,0 +1,2 @@
+/** Generated by kit/scripts/sync-completion-catalog.mjs — do not edit. */
+export declare const BUNDLED_COMPLETION_CATALOG_SHA256_HEX: "6b3fc4f2c568bd9de61e96c18b345c815a4ffea73fc1212f2e6fe601817a8483";

package/dist/completion-catalog-digest.js

@@ -0,0 +1,2 @@
+/** Generated by kit/scripts/sync-completion-catalog.mjs — do not edit. */
+export const BUNDLED_COMPLETION_CATALOG_SHA256_HEX = "6b3fc4f2c568bd9de61e96c18b345c815a4ffea73fc1212f2e6fe601817a8483";

package/dist/completion-catalog-integrity.d.ts

@@ -0,0 +1,2 @@
+/** Verifies raw catalog bytes against the bundled SHA-256 digest. */
+export declare function verifyBundledCompletionCatalogIntegrity(raw: Buffer | string): void;

package/dist/completion-catalog-integrity.js

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+import { BUNDLED_COMPLETION_CATALOG_SHA256_HEX } from "./completion-catalog-digest.js";
+const INTEGRITY_SKIP = "skip";
+function integrityCheckSkipped() {
+    return process.env.PAYBOND_COMPLETION_CATALOG_INTEGRITY?.trim().toLowerCase() === INTEGRITY_SKIP;
+}
+/** Verifies raw catalog bytes against the bundled SHA-256 digest. */
+export function verifyBundledCompletionCatalogIntegrity(raw) {
+    if (integrityCheckSkipped()) {
+        return;
+    }
+    const bytes = typeof raw === "string" ? Buffer.from(raw, "utf8") : raw;
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== BUNDLED_COMPLETION_CATALOG_SHA256_HEX) {
+        throw new Error(`completion preset catalog integrity check failed (sha256=${digest}, expected=${BUNDLED_COMPLETION_CATALOG_SHA256_HEX})`);
+    }
+}

package/dist/completion-catalog.d.ts

@@ -0,0 +1,49 @@
+export type CompletionPreset = {
+    preset_id: string;
+    title: string;
+    description: string;
+    harbor_template_id: string;
+    parameters: Record<string, unknown>;
+    evidence_schema: Record<string, unknown>;
+    sample_evidence: Record<string, unknown>;
+    sample_failing_evidence: Record<string, unknown>;
+    human_summary: string;
+    recommended_amount_cents?: number;
+    spend_hints?: {
+        approval_threshold_cents?: number;
+        per_tool_max_cents?: number;
+    };
+    kind?: "archetype" | "vendor_pack";
+    archetype_preset_id?: string;
+    evidence_field_map?: Record<string, string>;
+    vendor_evidence_schema?: Record<string, unknown>;
+    vendor_sample_evidence?: Record<string, unknown>;
+    scope?: "tool_completion" | "sandbox_smoke";
+    rail_hints?: string[];
+    forbidden_evidence_fields?: string[];
+    anti_patterns?: string[];
+    deprecated?: boolean;
+    superseded_by?: string;
+    vendor_contract?: {
+        provider: "stripe" | "x402" | "mcp" | "generic";
+        api_version: string;
+        contract_kind: "json_schema" | "openapi_fragment" | "mapper_version";
+        schema_digest_hex: string;
+        canonical_schema_digest_hex: string;
+        quality_fields: string[];
+        supersedes?: string;
+        migration_notes?: string;
+    };
+};
+export type CompletionPresetCatalog = {
+    version: number;
+    presets: CompletionPreset[];
+};
+export declare function loadCompletionCatalog(): CompletionPresetCatalog;
+export declare function listCompletionPresetIds(): string[];
+export declare function getCompletionPreset(presetId: string): CompletionPreset;
+export declare function getCompletionPresetByTemplateId(templateId: string): CompletionPreset | undefined;
+export declare function listCompletionPresetsByTemplateId(templateId: string): CompletionPreset[];
+export declare function jsonLiteral(value: unknown, indent?: number): string;
+export declare function catalogPathForTests(): string;
+export declare function catalogFileUrl(): string;

package/dist/completion-catalog.js

@@ -0,0 +1,62 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { verifyBundledCompletionCatalogIntegrity } from "./completion-catalog-integrity.js";
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+function catalogCandidatePaths() {
+    return [
+        join(MODULE_DIR, "../completion-presets/catalog.json"),
+        join(MODULE_DIR, "../../../kit/completion-presets/catalog.json"),
+        join(MODULE_DIR, "../../completion-presets/catalog.json"),
+    ];
+}
+let cachedCatalog;
+export function loadCompletionCatalog() {
+    if (cachedCatalog) {
+        return cachedCatalog;
+    }
+    let lastError;
+    for (const candidate of catalogCandidatePaths()) {
+        try {
+            const raw = readFileSync(candidate, "utf8");
+            verifyBundledCompletionCatalogIntegrity(raw);
+            cachedCatalog = JSON.parse(raw);
+            return cachedCatalog;
+        }
+        catch (err) {
+            lastError = err;
+        }
+    }
+    throw new Error(`completion preset catalog not found (${catalogCandidatePaths().join(", ")}): ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}
+export function listCompletionPresetIds() {
+    return loadCompletionCatalog().presets.map((preset) => preset.preset_id);
+}
+export function getCompletionPreset(presetId) {
+    const preset = loadCompletionCatalog().presets.find((entry) => entry.preset_id === presetId);
+    if (!preset) {
+        throw new Error(`unknown completion preset: ${presetId}`);
+    }
+    return preset;
+}
+export function getCompletionPresetByTemplateId(templateId) {
+    const matches = loadCompletionCatalog().presets.filter((entry) => entry.harbor_template_id === templateId);
+    if (matches.length === 0) {
+        return undefined;
+    }
+    return (matches.find((entry) => entry.kind !== "vendor_pack") ??
+        matches.find((entry) => entry.kind === "archetype") ??
+        matches[0]);
+}
+export function listCompletionPresetsByTemplateId(templateId) {
+    return loadCompletionCatalog().presets.filter((entry) => entry.harbor_template_id === templateId);
+}
+export function jsonLiteral(value, indent = 2) {
+    return JSON.stringify(value, null, indent);
+}
+export function catalogPathForTests() {
+    return join(MODULE_DIR, "../completion-presets/catalog.json");
+}
+export function catalogFileUrl() {
+    return pathToFileURL(catalogPathForTests()).href;
+}

package/dist/completion-contract-digest.d.ts

@@ -0,0 +1,37 @@
+/**
+ * BLAKE3 digests for completion preset vendor_contract schema pinning.
+ * Matches `paybond-evidence::json_value_digest` and Harbor signing digests.
+ */
+import type { CompletionPreset } from "./completion-catalog.js";
+export type VendorContract = {
+    provider: "stripe" | "x402" | "mcp" | "generic";
+    api_version: string;
+    contract_kind: "json_schema" | "openapi_fragment" | "mapper_version";
+    schema_digest_hex: string;
+    canonical_schema_digest_hex: string;
+    quality_fields: string[];
+    supersedes?: string;
+    migration_notes?: string;
+};
+export type VendorContractDigests = {
+    schema_digest_hex: string;
+    canonical_schema_digest_hex: string;
+};
+/** Hex-encode a 32-byte BLAKE3 digest. */
+export declare function digestToHex(digest: Uint8Array): string;
+/** BLAKE3 hex digest of JCS-canonical JSON for a completion evidence schema object. */
+export declare function completionSchemaDigestHex(schema: Record<string, unknown>): string;
+/** Compute vendor and canonical schema digests for a vendor_pack preset. */
+export declare function computeVendorContractDigests(preset: {
+    vendor_evidence_schema: Record<string, unknown>;
+    evidence_schema: Record<string, unknown>;
+}): VendorContractDigests;
+/**
+ * Assert catalog-declared vendor_contract digests and quality_fields match computed values.
+ * @throws when a vendor_pack contract is missing, stale, or references unknown quality fields.
+ */
+export declare function verifyVendorContract(preset: CompletionPreset): void;
+/** Verify all vendor_pack presets in a catalog document. */
+export declare function verifyCatalogVendorContracts(catalog: {
+    presets: CompletionPreset[];
+}): void;