@paybond/kit 0.9.7 → 0.10.0

package/dist/cli/config.js

@@ -0,0 +1,96 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { redactConfigValue } from "./redact.js";
+import { CliError } from "./types.js";
+export function configFilePath() {
+    const home = process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || "";
+    const base = process.env.XDG_CONFIG_HOME?.trim() || (home ? `${home}/.config` : ".config");
+    return `${base.replace(/\/+$/, "")}/paybond/config.json`;
+}
+export async function loadConfigFile() {
+    try {
+        const raw = await readFile(configFilePath(), "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+            return {};
+        }
+        throw new CliError(`unable to read CLI config: ${err instanceof Error ? err.message : String(err)}`, {
+            category: "environment",
+            code: "cli.environment.config_read_failed",
+        });
+    }
+}
+export async function saveConfigFile(config) {
+    const configPath = configFilePath();
+    const dir = configPath.replace(/\/[^/]+$/, "");
+    await mkdir(dir, { recursive: true });
+    await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+}
+export async function resolveConfigValue(key, profile) {
+    const config = await loadConfigFile();
+    if (profile) {
+        const profileValues = config.profiles?.[profile];
+        if (profileValues && key in profileValues) {
+            const value = profileValues[key];
+            return typeof value === "string" ? value : undefined;
+        }
+    }
+    return config.values?.[key];
+}
+export async function setConfigValue(key, value, profile) {
+    const config = await loadConfigFile();
+    if (profile) {
+        config.profiles ??= {};
+        config.profiles[profile] ??= {};
+        config.profiles[profile][key] = value;
+    }
+    else {
+        config.values ??= {};
+        config.values[key] = value;
+    }
+    await saveConfigFile(config);
+}
+export async function unsetConfigValue(key, profile) {
+    const config = await loadConfigFile();
+    if (profile) {
+        const profileValues = config.profiles?.[profile];
+        if (!profileValues || !(key in profileValues)) {
+            return false;
+        }
+        delete profileValues[key];
+        await saveConfigFile(config);
+        return true;
+    }
+    if (!config.values || !(key in config.values)) {
+        return false;
+    }
+    delete config.values[key];
+    await saveConfigFile(config);
+    return true;
+}
+export async function listConfigEntries(profile) {
+    const config = await loadConfigFile();
+    const entries = {};
+    if (profile) {
+        const profileValues = config.profiles?.[profile] ?? {};
+        for (const [key, value] of Object.entries(profileValues)) {
+            if (typeof value === "string") {
+                entries[key] = redactConfigValue(key, value);
+            }
+        }
+        return entries;
+    }
+    for (const [key, value] of Object.entries(config.values ?? {})) {
+        entries[key] = redactConfigValue(key, value);
+    }
+    for (const [profileName, profileValues] of Object.entries(config.profiles ?? {})) {
+        for (const [key, value] of Object.entries(profileValues ?? {})) {
+            if (typeof value === "string") {
+                entries[`profiles.${profileName}.${key}`] = redactConfigValue(key, value);
+            }
+        }
+    }
+    return entries;
+}

package/dist/cli/context.d.ts

@@ -0,0 +1,22 @@
+import { type CliDependencies, type CommandResult, type GlobalOptions, type Writable } from "./types.js";
+export type GatewayJson = Record<string, unknown>;
+export type GatewayClient = {
+    getJson(path: string): Promise<GatewayJson>;
+    postJson(path: string, body?: GatewayJson): Promise<GatewayJson>;
+    deleteJson(path: string): Promise<GatewayJson>;
+};
+export declare function gatewayUrl(base: string, path: string): string;
+export declare function createGatewayClient(globals: GlobalOptions, apiKey: string, fetchFn: typeof fetch, extraHeaders?: Record<string, string>): GatewayClient;
+export type CliContext = {
+    globals: GlobalOptions;
+    cwd: string;
+    stdout: Writable;
+    stderr: Writable;
+    fetch: typeof fetch;
+    deps: CliDependencies;
+    gateway?: GatewayClient;
+};
+export declare function withGateway(ctx: CliContext, handler: (gateway: GatewayClient, apiKey: string) => Promise<CommandResult>, extraHeaders?: Record<string, string>): Promise<CommandResult>;
+export declare function requireConfirmation(globals: GlobalOptions, action: string): void;
+export declare function commandPath(parts: string[]): string;
+export declare function createContext(globals: GlobalOptions, deps?: CliDependencies): CliContext;

package/dist/cli/context.js

@@ -0,0 +1,109 @@
+import { resolveApiKeyWithMeta } from "./credentials.js";
+import { CliError, exitCodeForHttpStatus, } from "./types.js";
+export function gatewayUrl(base, path) {
+    return `${base.trim().replace(/\/+$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
+}
+function parseGatewayErrorBody(body, status) {
+    const nested = body.error;
+    const gatewayCode = nested && typeof nested === "object" && !Array.isArray(nested)
+        ? String(nested.code ?? "")
+        : String(body.code ?? "");
+    const gatewayMessage = nested && typeof nested === "object" && !Array.isArray(nested)
+        ? String(nested.message ?? "")
+        : String(body.message ?? body.error_description ?? "gateway request failed");
+    const mapped = exitCodeForHttpStatus(status);
+    return new CliError(gatewayMessage || `Gateway HTTP ${status}`, {
+        category: mapped.category,
+        code: gatewayCode || `cli.gateway.http_${status}`,
+        exitCode: mapped.exitCode,
+        details: {
+            gateway_status: status,
+            gateway_code: gatewayCode || undefined,
+        },
+    });
+}
+async function parseJsonResponse(response) {
+    const text = await response.text();
+    if (!text.trim()) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // fall through
+    }
+    throw new CliError(`Gateway returned non-JSON response (${response.status}).`, {
+        category: "gateway",
+        code: "cli.gateway.non_json",
+        exitCode: 5,
+        details: { gateway_status: response.status },
+    });
+}
+export function createGatewayClient(globals, apiKey, fetchFn, extraHeaders = {}) {
+    const headers = {
+        authorization: `Bearer ${apiKey}`,
+        "content-type": "application/json",
+        "x-request-id": globals.requestId,
+        ...extraHeaders,
+    };
+    async function request(method, path, body) {
+        let response;
+        try {
+            response = await fetchFn(gatewayUrl(globals.gateway, path), {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (err) {
+            throw new CliError(err instanceof Error ? err.message : String(err), {
+                category: "network",
+                code: "cli.network.request_failed",
+                exitCode: 5,
+            });
+        }
+        const parsed = await parseJsonResponse(response);
+        if (!response.ok) {
+            throw parseGatewayErrorBody(parsed, response.status);
+        }
+        return parsed;
+    }
+    return {
+        getJson: (path) => request("GET", path),
+        postJson: (path, body) => request("POST", path, body),
+        deleteJson: (path) => request("DELETE", path),
+    };
+}
+export async function withGateway(ctx, handler, extraHeaders = {}) {
+    const resolved = await resolveApiKeyWithMeta(ctx.globals, ctx.cwd);
+    const gateway = createGatewayClient(ctx.globals, resolved.apiKey, ctx.fetch, extraHeaders);
+    const result = await handler(gateway, resolved.apiKey);
+    const warnings = [...(result.warnings ?? []), ...resolved.warnings];
+    return warnings.length ? { ...result, warnings } : result;
+}
+export function requireConfirmation(globals, action) {
+    if (!globals.yes) {
+        throw new CliError(`confirmation required; re-run with --yes to ${action}`, {
+            category: "confirmation_required",
+            code: "cli.confirmation.required",
+            exitCode: 4,
+        });
+    }
+}
+export function commandPath(parts) {
+    return parts.join(" ");
+}
+export function createContext(globals, deps = {}) {
+    return {
+        globals,
+        cwd: deps.cwd ?? process.cwd(),
+        stdout: deps.stdout ?? process.stdout,
+        stderr: deps.stderr ?? process.stderr,
+        fetch: deps.fetch ?? fetch,
+        deps,
+    };
+}

package/dist/cli/credentials.d.ts

@@ -0,0 +1,21 @@
+import { type GlobalOptions } from "./types.js";
+export declare function readEnvFileValue(body: string, key: string): string | undefined;
+export declare function loadEnvFile(envFile: string, cwd: string): Promise<string | undefined>;
+export type ResolvedApiKey = {
+    apiKey: string;
+    warnings: string[];
+};
+export declare function resolveApiKeyWithMeta(globals: GlobalOptions, cwd: string): Promise<ResolvedApiKey>;
+export declare function resolveApiKey(globals: GlobalOptions, cwd: string): Promise<string>;
+export type CredentialSourceDescription = {
+    source: "process_env" | "env_file" | "missing";
+    env_file?: string;
+    profile?: string;
+    key_masked?: string;
+};
+export declare function describeCredentialSource(globals: GlobalOptions, cwd: string): Promise<CredentialSourceDescription>;
+export declare function assertApiKeyShape(apiKey: string): void;
+export declare function resolvedDefaultsForDoctor(globals: GlobalOptions): {
+    gateway: string;
+    envFile: string;
+};

package/dist/cli/credentials.js

@@ -0,0 +1,141 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveConfigValue } from "./config.js";
+import { CLI_WARN_ENV_FALLBACK, formatWarning } from "./automation.js";
+import { DEFAULT_ENV_FILE, DEFAULT_GATEWAY } from "./globals.js";
+import { CliError } from "./types.js";
+function resolvePath(cwd, envFile) {
+    return path.isAbsolute(envFile) ? path.resolve(envFile) : path.resolve(cwd, envFile);
+}
+function quoteTrim(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+export function readEnvFileValue(body, key) {
+    const prefix = `${key}=`;
+    const exportPrefix = `export ${key}=`;
+    for (const rawLine of body.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        let value = "";
+        if (line.startsWith(exportPrefix)) {
+            value = line.slice(exportPrefix.length).trim();
+        }
+        else if (line.startsWith(prefix)) {
+            value = line.slice(prefix.length).trim();
+        }
+        else {
+            continue;
+        }
+        const unquoted = quoteTrim(value);
+        return unquoted || undefined;
+    }
+    return undefined;
+}
+export async function loadEnvFile(envFile, cwd) {
+    const envPath = resolvePath(cwd, envFile);
+    try {
+        const body = await readFile(envPath, "utf8");
+        return readEnvFileValue(body, "PAYBOND_API_KEY");
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+            return undefined;
+        }
+        throw new CliError(`unable to read env file ${envPath}`, {
+            category: "environment",
+            code: "cli.environment.env_file_read_failed",
+            details: { env_file: envPath },
+        });
+    }
+}
+export async function resolveApiKeyWithMeta(globals, cwd) {
+    const warnings = [];
+    const fromProcess = process.env.PAYBOND_API_KEY?.trim();
+    if (fromProcess) {
+        warnings.push(formatWarning(CLI_WARN_ENV_FALLBACK, "using PAYBOND_API_KEY from process environment"));
+        return { apiKey: fromProcess, warnings };
+    }
+    let envFile = globals.envFile;
+    let gateway = globals.gateway;
+    if (globals.profile) {
+        const profileEnvFile = await resolveConfigValue("env_file", globals.profile);
+        const profileGateway = await resolveConfigValue("gateway", globals.profile);
+        if (profileEnvFile) {
+            envFile = profileEnvFile;
+            warnings.push(formatWarning(CLI_WARN_ENV_FALLBACK, `using profile ${globals.profile} env_file`));
+        }
+        if (profileGateway) {
+            gateway = profileGateway;
+            warnings.push(formatWarning(CLI_WARN_ENV_FALLBACK, `using profile ${globals.profile} gateway`));
+        }
+    }
+    globals.envFile = envFile;
+    globals.gateway = gateway;
+    const fromFile = await loadEnvFile(envFile, cwd);
+    if (fromFile) {
+        return { apiKey: fromFile, warnings };
+    }
+    throw new CliError("missing PAYBOND_API_KEY; run paybond login or set PAYBOND_API_KEY", {
+        category: "auth",
+        code: "cli.auth.missing_api_key",
+        exitCode: 2,
+        details: { env_file: resolvePath(cwd, envFile) },
+    });
+}
+export async function resolveApiKey(globals, cwd) {
+    const resolved = await resolveApiKeyWithMeta(globals, cwd);
+    return resolved.apiKey;
+}
+export async function describeCredentialSource(globals, cwd) {
+    const { maskApiKey } = await import("./redact.js");
+    const fromProcess = process.env.PAYBOND_API_KEY?.trim();
+    if (fromProcess) {
+        return { source: "process_env", key_masked: maskApiKey(fromProcess) };
+    }
+    let envFile = globals.envFile;
+    const profile = globals.profile;
+    if (globals.profile) {
+        const profileEnvFile = await resolveConfigValue("env_file", globals.profile);
+        if (profileEnvFile) {
+            envFile = profileEnvFile;
+        }
+    }
+    const envPath = resolvePath(cwd, envFile);
+    try {
+        const fromFile = await loadEnvFile(envFile, cwd);
+        if (fromFile) {
+            return {
+                source: "env_file",
+                env_file: envPath,
+                profile: profile ?? undefined,
+                key_masked: maskApiKey(fromFile),
+            };
+        }
+    }
+    catch {
+        // fall through to missing
+    }
+    return {
+        source: "missing",
+        env_file: envPath,
+        profile: profile ?? undefined,
+    };
+}
+export function assertApiKeyShape(apiKey) {
+    if (!apiKey.startsWith("paybond_sk_")) {
+        throw new CliError("PAYBOND_API_KEY has an unexpected shape", {
+            category: "auth",
+            code: "cli.auth.invalid_api_key_shape",
+            exitCode: 2,
+        });
+    }
+}
+export function resolvedDefaultsForDoctor(globals) {
+    return {
+        gateway: globals.gateway || DEFAULT_GATEWAY,
+        envFile: globals.envFile || DEFAULT_ENV_FILE,
+    };
+}

package/dist/cli/doctor-agent.d.ts

@@ -0,0 +1,15 @@
+export type DoctorCheck = {
+    name: string;
+    ok: boolean;
+    message: string;
+    details?: Record<string, unknown>;
+};
+export declare function packageVersion(): string;
+export declare function encodeMcpMessage(payload: Record<string, unknown>): Buffer;
+export declare function runAgentMcpChecks(input: {
+    envFile: string;
+    cwd: string;
+    host?: string;
+    serverCommand?: string[];
+    timeoutMs?: number;
+}): Promise<DoctorCheck[]>;