@paybond/kit 0.9.8 → 0.10.0

package/dist/cli/audit-export.d.ts

@@ -0,0 +1,7 @@
+export declare const MANIFEST_CORE_FIELD_ORDER: readonly ["schema_version", "kind", "tenant_realm_id", "job_id", "generated_at_rfc3339", "gateway_build_version", "score_model_version", "disclosure_tier", "redaction_profile", "checkpoint_last_ledger_seq", "export_filter", "artifacts"];
+export declare function buildManifestCore(manifest: Record<string, unknown>): Record<string, unknown>;
+export declare function manifestCoreBytes(manifest: Record<string, unknown>): Uint8Array;
+export declare function verifyAuditManifest(manifest: Record<string, unknown>): boolean;
+export declare function auditVerifyResult(manifest: Record<string, unknown>, path: string): Record<string, unknown>;
+export declare function readManifestFromBundle(bundlePath: string, cwd: string): Promise<string>;
+export declare function verifyAuditBundleLocal(path: string, cwd: string): Promise<Record<string, unknown>>;

package/dist/cli/audit-export.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { verify as ed25519Verify } from "@noble/ed25519";
+import { ensureEd25519Sha512Sync } from "../ed25519-sync.js";
+import { CliError } from "./types.js";
+export const MANIFEST_CORE_FIELD_ORDER = [
+    "schema_version",
+    "kind",
+    "tenant_realm_id",
+    "job_id",
+    "generated_at_rfc3339",
+    "gateway_build_version",
+    "score_model_version",
+    "disclosure_tier",
+    "redaction_profile",
+    "checkpoint_last_ledger_seq",
+    "export_filter",
+    "artifacts",
+];
+export function buildManifestCore(manifest) {
+    const core = {};
+    for (const key of MANIFEST_CORE_FIELD_ORDER) {
+        if (key === "checkpoint_last_ledger_seq") {
+            if (!(key in manifest)) {
+                continue;
+            }
+            const value = manifest[key];
+            if (value === 0 || value === null) {
+                continue;
+            }
+            core[key] = value;
+            continue;
+        }
+        if (key in manifest) {
+            core[key] = manifest[key];
+        }
+    }
+    return core;
+}
+export function manifestCoreBytes(manifest) {
+    const core = buildManifestCore(manifest);
+    return new TextEncoder().encode(JSON.stringify(core));
+}
+function hexToBytes(hex) {
+    const normalized = hex.trim();
+    const out = new Uint8Array(normalized.length / 2);
+    for (let i = 0; i < out.length; i += 1) {
+        out[i] = Number.parseInt(normalized.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes)
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+export function verifyAuditManifest(manifest) {
+    const coreBytes = manifestCoreBytes(manifest);
+    const digest = createHash("sha256").update(coreBytes).digest();
+    const expected = String(manifest.signed_payload_sha256_hex ?? "").trim().toLowerCase();
+    if (bytesToHex(new Uint8Array(digest)) !== expected) {
+        return false;
+    }
+    const signatureHex = String(manifest.ed25519_signature_hex ?? "").trim();
+    const publicKeyHex = String(manifest.signing_public_key_ed25519_hex ?? "").trim();
+    if (!signatureHex || !publicKeyHex) {
+        return false;
+    }
+    ensureEd25519Sha512Sync();
+    return ed25519Verify(hexToBytes(signatureHex), digest, hexToBytes(publicKeyHex));
+}
+export function auditVerifyResult(manifest, path) {
+    return {
+        verified: verifyAuditManifest(manifest),
+        manifest_kind: String(manifest.kind ?? ""),
+        tenant_realm_id: String(manifest.tenant_realm_id ?? ""),
+        job_id: String(manifest.job_id ?? ""),
+        path,
+    };
+}
+export async function readManifestFromBundle(bundlePath, cwd) {
+    if (bundlePath.endsWith(".zip")) {
+        const result = await new Promise((resolvePromise) => {
+            const child = spawn("unzip", ["-p", bundlePath, "manifest.json"], { cwd });
+            let stdout = "";
+            let stderr = "";
+            child.stdout.on("data", (chunk) => {
+                stdout += String(chunk);
+            });
+            child.stderr.on("data", (chunk) => {
+                stderr += String(chunk);
+            });
+            child.on("close", (code) => resolvePromise({ code, stdout, stderr }));
+            child.on("error", () => resolvePromise({ code: 127, stdout: "", stderr: "unzip not found" }));
+        });
+        if (result.code !== 0 || !result.stdout.trim()) {
+            throw new CliError(result.stderr.trim() || "unable to read manifest.json from ZIP bundle", {
+                category: "validation",
+                code: "cli.audit.bundle_read_failed",
+            });
+        }
+        return result.stdout;
+    }
+    const manifestPath = bundlePath.endsWith("manifest.json")
+        ? bundlePath
+        : `${bundlePath.replace(/\/+$/, "")}/manifest.json`;
+    return readFile(manifestPath, "utf8");
+}
+export async function verifyAuditBundleLocal(path, cwd) {
+    const manifestRaw = await readManifestFromBundle(path, cwd);
+    const manifest = JSON.parse(manifestRaw);
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+        throw new CliError("manifest.json must be a JSON object", {
+            category: "validation",
+            code: "cli.audit.invalid_manifest",
+        });
+    }
+    return auditVerifyResult(manifest, path);
+}

package/dist/cli/automation.d.ts

@@ -0,0 +1,25 @@
+/** Stable machine-readable warning codes for automation consumers. */
+export declare const CLI_WARN_PARTIAL_RESULTS = "cli.warn.partial_results";
+export declare const CLI_WARN_GATEWAY_RETRY = "cli.warn.gateway_retry";
+export declare const CLI_WARN_DEPRECATED_ALIAS = "cli.warn.deprecated_alias";
+export declare const CLI_WARN_ENV_FALLBACK = "cli.warn.env_fallback";
+export declare function formatWarning(code: string, detail?: string): string;
+export declare function deprecatedAliasWarning(argv0: string | undefined): string | undefined;
+export declare function parseJsonFields(raw: string): string[];
+export declare function selectJsonFields(rows: Record<string, unknown>[], fields: string[]): Record<string, unknown>[];
+export declare function extractListArray(data: Record<string, unknown>): Record<string, unknown>[] | null;
+export declare function applyJsonFieldSelection(command: string, data: Record<string, unknown>, fields: string[]): Record<string, unknown> | Record<string, unknown>[];
+export declare function applyJqFilter(data: unknown, expr: string): unknown;
+export declare function supportsAutomationOutput(command: string): boolean;
+export declare function applyAutomationTransforms(command: string, data: Record<string, unknown>, options: {
+    jsonFields?: string;
+    jqExpr?: string;
+}): unknown;
+export declare function extractNextCursor(body: Record<string, unknown>): string | undefined;
+export declare function partialResultsWarning(nextCursor: string | undefined): string | undefined;
+export declare function buildListQueryParams(limit: string | undefined, cursor: string | undefined, defaults?: {
+    limit?: string;
+}): URLSearchParams;
+export declare function readJsonBody(source: string, stdin?: NodeJS.ReadableStream): Promise<Record<string, unknown>>;
+export declare function writeAtomicFile(path: string, content: string | Uint8Array, mode?: number): void;
+export declare function writeAtomicFileAsync(path: string, content: string | Uint8Array, mode?: number): Promise<void>;

package/dist/cli/automation.js

@@ -0,0 +1,297 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, renameSync, rmSync, writeFileSync, chmodSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { CliError } from "./types.js";
+/** Stable machine-readable warning codes for automation consumers. */
+export const CLI_WARN_PARTIAL_RESULTS = "cli.warn.partial_results";
+export const CLI_WARN_GATEWAY_RETRY = "cli.warn.gateway_retry";
+export const CLI_WARN_DEPRECATED_ALIAS = "cli.warn.deprecated_alias";
+export const CLI_WARN_ENV_FALLBACK = "cli.warn.env_fallback";
+export function formatWarning(code, detail) {
+    return detail ? `${code}: ${detail}` : code;
+}
+const LEGACY_INVOCATION_ALIASES = {
+    "paybond-kit-login": "paybond login",
+    "paybond-init": "paybond init guardrail",
+    "paybond-kit-init": "paybond init guardrail",
+    "paybond-mcp-server": "paybond mcp serve",
+};
+export function deprecatedAliasWarning(argv0) {
+    const base = (argv0 ?? "").split(/[/\\]/).pop() ?? "";
+    const canonical = LEGACY_INVOCATION_ALIASES[base];
+    if (!canonical) {
+        return undefined;
+    }
+    return formatWarning(CLI_WARN_DEPRECATED_ALIAS, `use ${canonical} instead of ${base}`);
+}
+export function parseJsonFields(raw) {
+    const fields = raw
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (fields.length === 0) {
+        throw new CliError("invalid --json (expected comma-separated field names)", {
+            category: "usage",
+            code: "cli.usage.invalid_json_fields",
+        });
+    }
+    return fields;
+}
+function readNestedField(row, field) {
+    const parts = field.split(".").filter(Boolean);
+    let current = row;
+    for (const part of parts) {
+        if (!current || typeof current !== "object" || Array.isArray(current)) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+export function selectJsonFields(rows, fields) {
+    return rows.map((row) => {
+        const selected = {};
+        for (const field of fields) {
+            const value = field.includes(".") ? readNestedField(row, field) : row[field];
+            if (field.includes(".")) {
+                selected[field] = value;
+            }
+            else {
+                selected[field] = value;
+            }
+        }
+        return selected;
+    });
+}
+const LIST_ARRAY_KEYS = ["items", "keys", "exports", "intents", "tools", "entries", "contracts", "jobs"];
+export function extractListArray(data) {
+    for (const key of LIST_ARRAY_KEYS) {
+        const value = data[key];
+        if (Array.isArray(value)) {
+            return value.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item));
+        }
+    }
+    return null;
+}
+export function applyJsonFieldSelection(command, data, fields) {
+    const rows = extractListArray(data);
+    if (rows) {
+        return selectJsonFields(rows, fields);
+    }
+    return selectJsonFields([data], fields)[0] ?? {};
+}
+function trySimpleJqPath(data, expr) {
+    const trimmed = expr.trim();
+    if (!trimmed || trimmed === ".") {
+        return data;
+    }
+    const pipeParts = trimmed.split("|").map((part) => part.trim());
+    let current = data;
+    for (const part of pipeParts) {
+        if (part === ".") {
+            continue;
+        }
+        if (part === ".[]") {
+            if (!Array.isArray(current)) {
+                return undefined;
+            }
+            current = current;
+            continue;
+        }
+        if (part.endsWith("[]")) {
+            const key = part.slice(0, -2);
+            if (key === ".") {
+                if (!Array.isArray(current)) {
+                    return undefined;
+                }
+                continue;
+            }
+            if (!key.startsWith(".") || !current || typeof current !== "object" || Array.isArray(current)) {
+                return undefined;
+            }
+            const field = key.slice(1);
+            const nested = current[field];
+            if (!Array.isArray(nested)) {
+                return undefined;
+            }
+            current = nested;
+            continue;
+        }
+        if (part.startsWith(".")) {
+            const arraySubfield = part.match(/^\.([^.[]+)(\[\])(?:\.(.+))?$/);
+            if (arraySubfield) {
+                const [, field, , subfield] = arraySubfield;
+                if (!current || typeof current !== "object" || Array.isArray(current)) {
+                    return undefined;
+                }
+                const nested = current[field];
+                if (!Array.isArray(nested)) {
+                    return undefined;
+                }
+                if (!subfield) {
+                    current = nested;
+                    continue;
+                }
+                current = nested.map((item) => item && typeof item === "object" && !Array.isArray(item)
+                    ? item[subfield]
+                    : undefined);
+                continue;
+            }
+            const pathParts = part.slice(1).split(".").filter(Boolean);
+            for (const segment of pathParts) {
+                if (!current || typeof current !== "object" || Array.isArray(current)) {
+                    return undefined;
+                }
+                current = current[segment];
+            }
+            continue;
+        }
+        return undefined;
+    }
+    return current;
+}
+function runJqBinary(data, expr) {
+    try {
+        const result = spawnSync("jq", ["-c", expr], {
+            input: JSON.stringify(data),
+            encoding: "utf8",
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        if (result.status !== 0 || result.error) {
+            return undefined;
+        }
+        const output = result.stdout.trim();
+        if (!output) {
+            return null;
+        }
+        return JSON.parse(output);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function applyJqFilter(data, expr) {
+    const trimmed = expr.trim();
+    if (!trimmed || trimmed === ".") {
+        return data;
+    }
+    const simple = trySimpleJqPath(data, trimmed);
+    if (simple !== undefined) {
+        return simple;
+    }
+    const fromBinary = runJqBinary(data, trimmed);
+    if (fromBinary !== undefined) {
+        return fromBinary;
+    }
+    throw new CliError(`invalid --jq expression: ${expr}`, {
+        category: "usage",
+        code: "cli.usage.invalid_jq",
+    });
+}
+export function supportsAutomationOutput(command) {
+    return (command.endsWith(" list") ||
+        command.endsWith(" get") ||
+        command === "whoami" ||
+        command === "mcp tools" ||
+        command === "a2a contracts" ||
+        command === "a2a card");
+}
+export function applyAutomationTransforms(command, data, options) {
+    if (!supportsAutomationOutput(command)) {
+        if (options.jsonFields || options.jqExpr) {
+            throw new CliError(`--json/--jq are not supported for ${command}`, {
+                category: "usage",
+                code: "cli.usage.automation_unsupported",
+            });
+        }
+        return data;
+    }
+    let current = data;
+    if (options.jsonFields) {
+        current = applyJsonFieldSelection(command, data, parseJsonFields(options.jsonFields));
+    }
+    if (options.jqExpr) {
+        current = applyJqFilter(current, options.jqExpr);
+    }
+    return current;
+}
+export function extractNextCursor(body) {
+    const raw = body.next_cursor ?? body.nextCursor ?? body.cursor_next;
+    if (typeof raw === "string" && raw.trim()) {
+        return raw.trim();
+    }
+    return undefined;
+}
+export function partialResultsWarning(nextCursor) {
+    if (!nextCursor) {
+        return undefined;
+    }
+    return formatWarning(CLI_WARN_PARTIAL_RESULTS, "more items available; pass --cursor");
+}
+export function buildListQueryParams(limit, cursor, defaults = {}) {
+    const params = new URLSearchParams({ limit: limit?.trim() || defaults.limit || "20" });
+    if (cursor?.trim()) {
+        params.set("cursor", cursor.trim());
+    }
+    return params;
+}
+export async function readJsonBody(source, stdin) {
+    const normalized = source.trim();
+    let raw;
+    if (normalized === "-" || normalized === "stdin") {
+        if (!stdin) {
+            throw new CliError("JSON body requires --body - with stdin piped in", {
+                category: "usage",
+                code: "cli.usage.missing_stdin",
+            });
+        }
+        const chunks = [];
+        for await (const chunk of stdin) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+        }
+        raw = Buffer.concat(chunks).toString("utf8");
+    }
+    else {
+        raw = await readFile(normalized, "utf8");
+    }
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError("JSON body must be an object", { category: "validation", code: "cli.validation.invalid_json_body" });
+    }
+    return parsed;
+}
+export function writeAtomicFile(path, content, mode = 0o600) {
+    const dir = dirname(path);
+    const prefix = join(dir, ".paybond-write-");
+    const tempDir = mkdtempSync(prefix);
+    const tempFile = join(tempDir, "payload");
+    try {
+        writeFileSync(tempFile, content);
+        chmodSync(tempFile, mode);
+        renameSync(tempFile, path);
+        rmSync(tempDir, { recursive: true, force: true });
+    }
+    catch (err) {
+        rmSync(tempDir, { recursive: true, force: true });
+        throw err;
+    }
+}
+export async function writeAtomicFileAsync(path, content, mode = 0o600) {
+    const { mkdir, writeFile, chmod, rename, rm } = await import("node:fs/promises");
+    const dir = dirname(path);
+    await mkdir(dir, { recursive: true });
+    const tempDir = await import("node:fs/promises").then((mod) => mod.mkdtemp(join(tmpdir(), "paybond-write-")));
+    const tempFile = join(tempDir, "payload");
+    try {
+        await writeFile(tempFile, content);
+        await chmod(tempFile, mode);
+        await rename(tempFile, path);
+        await rm(tempDir, { recursive: true, force: true });
+    }
+    catch (err) {
+        await rm(tempDir, { recursive: true, force: true });
+        throw err;
+    }
+}

package/dist/cli/body.d.ts

@@ -0,0 +1,7 @@
+export declare function resolveJsonBody(argv: string[], options?: {
+    required?: boolean;
+    missingMessage?: string;
+}): Promise<{
+    payload: Record<string, unknown>;
+    rest: string[];
+}>;

package/dist/cli/body.js

@@ -0,0 +1,22 @@
+import { consumeBooleanFlag, consumeFlag } from "./globals.js";
+import { readJsonBody } from "./automation.js";
+import { CliError } from "./types.js";
+export async function resolveJsonBody(argv, options) {
+    const required = options?.required ?? true;
+    const missingMessage = options?.missingMessage ?? "missing JSON body; pass --body <json-file> or --stdin";
+    const stdinFlag = consumeBooleanFlag(argv, "--stdin");
+    if (stdinFlag.present) {
+        return { payload: await readJsonBody("-", process.stdin), rest: stdinFlag.rest };
+    }
+    const bodyFlag = consumeFlag(stdinFlag.rest, "--body");
+    if (!bodyFlag.value) {
+        if (!required) {
+            return { payload: {}, rest: bodyFlag.rest };
+        }
+        throw new CliError(missingMessage, {
+            category: "usage",
+            code: "cli.usage.missing_body",
+        });
+    }
+    return { payload: await readJsonBody(bodyFlag.value, process.stdin), rest: bodyFlag.rest };
+}

package/dist/cli/color.d.ts

@@ -0,0 +1,15 @@
+import type { ColorMode, GlobalOptions } from "./types.js";
+declare const ANSI: {
+    readonly reset: "\u001B[0m";
+    readonly bold: "\u001B[1m";
+    readonly dim: "\u001B[2m";
+    readonly green: "\u001B[32m";
+    readonly yellow: "\u001B[33m";
+    readonly cyan: "\u001B[36m";
+};
+export type AnsiStyle = keyof typeof ANSI;
+export declare function resolveColorModeFromEnv(env?: NodeJS.ProcessEnv): ColorMode;
+export declare function parseColorMode(raw: string): ColorMode;
+export declare function shouldUseColor(globals: GlobalOptions, isTTY?: boolean): boolean;
+export declare function colorize(text: string, style: AnsiStyle, enabled: boolean): string;
+export {};

package/dist/cli/color.js

@@ -0,0 +1,39 @@
+const ANSI = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+};
+export function resolveColorModeFromEnv(env = process.env) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR.trim() !== "") {
+        return "never";
+    }
+    return "auto";
+}
+export function parseColorMode(raw) {
+    const value = raw.trim().toLowerCase();
+    if (value === "auto" || value === "always" || value === "never") {
+        return value;
+    }
+    throw new Error("invalid --color (expected auto|always|never)");
+}
+export function shouldUseColor(globals, isTTY = process.stdout.isTTY === true) {
+    if (globals.format === "json") {
+        return false;
+    }
+    if (globals.color === "never") {
+        return false;
+    }
+    if (globals.color === "always") {
+        return true;
+    }
+    return isTTY;
+}
+export function colorize(text, style, enabled) {
+    if (!enabled) {
+        return text;
+    }
+    return `${ANSI[style]}${text}${ANSI.reset}`;
+}

package/dist/cli/command-spec.d.ts

@@ -0,0 +1,12 @@
+export declare const COMMAND_PATHS: string[];
+export declare const GLOBAL_FLAG_NAMES: string[];
+export declare const COMMAND_EXAMPLES: Record<string, string[]>;
+export declare const COMPLETIONS: Record<string, string[]>;
+export declare const WORKFLOWS: Array<{
+    title: string;
+    description?: string;
+    examples: string[];
+    next?: string;
+}>;
+export declare const DOCS_BASE_URL = "https://docs.paybond.ai/kit";
+export declare const COMPLETION_SCRIPTS: Record<"bash" | "zsh" | "fish", string>;