@paybond/kit 0.10.0 → 0.11.0

package/dist/cli/mcp-policy.js

@@ -1,9 +1,19 @@
 export const MCP_TOOL_POLICY_ENV = "PAYBOND_MCP_TOOL_POLICY";
 export const MCP_TOOL_ALLOWLIST_ENV = "PAYBOND_MCP_TOOL_ALLOWLIST";
+export const DEFAULT_MCP_TOOL_POLICY = "spend-write";
 export const LIVE_MONEY_TOOL_NAMES = new Set([
     "paybond_fund_intent",
     "paybond_confirm_settlement",
 ]);
+export function defaultMcpToolPolicyConfig() {
+    return { policy: DEFAULT_MCP_TOOL_POLICY, allowlist: [] };
+}
+export function resolveMcpToolPolicy(config) {
+    if (config.policy !== null) {
+        return config;
+    }
+    return defaultMcpToolPolicyConfig();
+}
 export function parseMcpToolPolicy(raw) {
     const value = (raw ?? "").trim().toLowerCase();
     if (!value) {
@@ -38,14 +48,12 @@ export function mergeMcpToolPolicy(policy, allowlist) {
     return { policy: policy.policy, allowlist: [...mergedAllowlist] };
 }
 export function mcpToolPolicyEnv(config) {
-    if (config.policy === null) {
-        return {};
-    }
+    const resolved = resolveMcpToolPolicy(config);
     const env = {
-        [MCP_TOOL_POLICY_ENV]: config.policy,
+        [MCP_TOOL_POLICY_ENV]: resolved.policy ?? DEFAULT_MCP_TOOL_POLICY,
     };
-    if (config.policy === "allowlist") {
-        env[MCP_TOOL_ALLOWLIST_ENV] = config.allowlist.join(",");
+    if (resolved.policy === "allowlist") {
+        env[MCP_TOOL_ALLOWLIST_ENV] = resolved.allowlist.join(",");
     }
     return env;
 }
@@ -56,18 +64,16 @@ export function toolAnnotationsFlags(annotations) {
     };
 }
 export function toolAllowedByPolicy(name, annotations, config) {
-    if (config.policy === null) {
-        return true;
-    }
+    const resolved = resolveMcpToolPolicy(config);
     const { readOnly, destructive } = toolAnnotationsFlags(annotations);
-    if (config.policy === "readonly") {
+    if (resolved.policy === "readonly") {
         return readOnly;
     }
-    if (config.policy === "spend-write") {
+    if (resolved.policy === "spend-write") {
         return !isLiveMoneyTool(name, annotations);
     }
-    if (config.policy === "allowlist") {
-        return new Set(config.allowlist).has(name);
+    if (resolved.policy === "allowlist") {
+        return new Set(resolved.allowlist).has(name);
     }
     return true;
 }

package/dist/cli/mcp-verify-config.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { defaultMcpServerCommand, planMcpInstall, } from "./mcp-install.js";
-import { MCP_TOOL_ALLOWLIST_ENV, MCP_TOOL_POLICY_ENV, mergeMcpToolPolicy, parseMcpToolAllowlist, parseMcpToolPolicy, } from "./mcp-policy.js";
+import { MCP_TOOL_ALLOWLIST_ENV, MCP_TOOL_POLICY_ENV, mergeMcpToolPolicy, parseMcpToolAllowlist, parseMcpToolPolicy, resolveMcpToolPolicy, } from "./mcp-policy.js";
 function validationMessage(ok, issues) {
     if (ok) {
         return "MCP host config is valid";
@@ -99,16 +99,14 @@ function validateEntry(entry, cwd, expectedEnvFile) {
     let toolPolicy;
     const rawPolicy = entry.env[MCP_TOOL_POLICY_ENV]?.trim() ?? "";
     const rawAllowlist = entry.env[MCP_TOOL_ALLOWLIST_ENV]?.trim() ?? "";
-    if (rawPolicy || rawAllowlist) {
-        try {
-            toolPolicy = mergeMcpToolPolicy(parseMcpToolPolicy(rawPolicy || undefined), parseMcpToolAllowlist(rawAllowlist || undefined));
-        }
-        catch (err) {
-            issues.push({
-                field: "tool_policy",
-                message: err instanceof Error ? err.message : String(err),
-            });
-        }
+    try {
+        toolPolicy = resolveMcpToolPolicy(mergeMcpToolPolicy(parseMcpToolPolicy(rawPolicy || undefined), parseMcpToolAllowlist(rawAllowlist || undefined)));
+    }
+    catch (err) {
+        issues.push({
+            field: "tool_policy",
+            message: err instanceof Error ? err.message : String(err),
+        });
     }
     return { issues, toolPolicy };
 }

package/dist/cli/redact.js

@@ -1,3 +1,20 @@
+const SENSITIVE_SEED_EXACT_FIELDS = new Set(["payee_signing_seed", "agent_recognition_signing_seed"]);
+function isSensitiveSeedKey(key) {
+    const lowered = key.toLowerCase();
+    if (SENSITIVE_SEED_EXACT_FIELDS.has(lowered)) {
+        return true;
+    }
+    return lowered.endsWith("_seed") || lowered.endsWith("_seed_hex");
+}
+function hasRedactableScalarContent(value) {
+    if (typeof value === "string") {
+        return value.trim().length > 0;
+    }
+    if (value instanceof Uint8Array) {
+        return value.length > 0;
+    }
+    return false;
+}
 export function maskApiKey(rawKey) {
     const trimmed = rawKey.trim();
     const parts = trimmed.split("_");
@@ -16,23 +33,27 @@ export function redactSensitiveFields(value) {
     if (value && typeof value === "object") {
         const out = {};
         for (const [key, child] of Object.entries(value)) {
-            if (child && typeof child === "object") {
-                out[key] = redactSensitiveFields(child);
-                continue;
-            }
             const lowered = key.toLowerCase();
             if (lowered === "capability_token" ||
                 lowered === "access_token" ||
                 lowered === "refresh_token" ||
                 (lowered.endsWith("_token") && lowered !== "token_type")) {
-                out[key] = typeof child === "string" && child.trim() ? "[redacted]" : child;
+                out[key] = hasRedactableScalarContent(child) ? "[redacted]" : child;
+                continue;
             }
-            else if (lowered === "api_key" || lowered.endsWith("_api_key")) {
+            if (lowered === "api_key" || lowered.endsWith("_api_key")) {
                 out[key] = typeof child === "string" ? maskApiKey(child) : child;
+                continue;
             }
-            else {
-                out[key] = child;
+            if (isSensitiveSeedKey(key)) {
+                out[key] = hasRedactableScalarContent(child) ? "[redacted]" : child;
+                continue;
+            }
+            if (child && typeof child === "object") {
+                out[key] = redactSensitiveFields(child);
+                continue;
             }
+            out[key] = child;
         }
         return out;
     }

package/dist/cli/router.js

@@ -1,6 +1,9 @@
 import { commandPath, createContext } from "./context.js";
 import { handleA2a, handleAuditExports, handleMandates, handleReceipts, handleSignal, } from "./commands/discovery.js";
-import { handleConfig, handleDoctor, handleDiagnose, handleInitGuardrail, handleLogin, handleMcpInstall, handleMcpServe, handleMcpTools, handleMcpVerifyConfig, handleVersion, handleWhoami, } from "./commands/setup.js";
+import { handleConfig, handleDoctor, handleDiagnose, handleInitCompletion, handleInitAgentMiddleware, handleInitGuardrail, handleInitWizard, handleLogin, handleMcpInstall, handleMcpServe, handleMcpTools, handleMcpVerifyConfig, handleVersion, handleWhoami, } from "./commands/setup.js";
+import { handlePolicyExtend, handlePolicyImportMcpReceipt, handlePolicyImportX402Receipt, handlePolicyInit, handlePolicyInitOrg, handlePolicyPresetsList, handlePolicyPresetsShow, handlePolicyPreview, handlePolicyTemplates, handlePolicyValidateEvidence, handlePolicyValidateTools, } from "./commands/policy.js";
+import { handleAgent } from "./commands/agent.js";
+import { handleDev } from "./commands/dev.js";
 import { handleGuardrails, handleIntents, handleKeys, handleSpendAuthorize, } from "./commands/workflows.js";
 import { failureEnvelope, prepareCommandOutput, successEnvelope, writeEnvelope, writeTableLines } from "./envelope.js";
 import { defaultGlobalOptions, parseCliArgv } from "./globals.js";
@@ -147,6 +150,18 @@ export async function runCli(argv, deps = {}) {
             canonical = "init guardrail";
             result = await handleInitGuardrail(ctx, command.slice(2));
         }
+        else if (head === "init" && second === "agent-middleware") {
+            canonical = "init agent-middleware";
+            result = await handleInitAgentMiddleware(ctx, command.slice(2));
+        }
+        else if (head === "init" && second === "completion") {
+            canonical = "init completion";
+            result = await handleInitCompletion(ctx, command.slice(2));
+        }
+        else if (head === "init") {
+            canonical = "init";
+            result = await handleInitWizard(ctx, command.slice(1));
+        }
         else if (head === "mcp" && second === "serve") {
             canonical = "mcp serve";
             result = await handleMcpServe(ctx, command.slice(2));
@@ -167,6 +182,10 @@ export async function runCli(argv, deps = {}) {
             canonical = "doctor";
             result = await handleDoctor(ctx, command.slice(1));
         }
+        else if (head === "dev" && second) {
+            canonical = commandPath(["dev", second]);
+            result = await handleDev(ctx, second, tail);
+        }
         else if (head === "version") {
             canonical = "version";
             result = await handleVersion(ctx, command.slice(1));
@@ -219,6 +238,54 @@ export async function runCli(argv, deps = {}) {
             canonical = commandPath(["audit", "exports", third]);
             result = await handleAuditExports(ctx, third, command.slice(3));
         }
+        else if (head === "policy" && second === "presets" && third === "list") {
+            canonical = "policy presets list";
+            result = await handlePolicyPresetsList(ctx, command.slice(3));
+        }
+        else if (head === "policy" && second === "presets" && third === "show") {
+            canonical = "policy presets show";
+            result = await handlePolicyPresetsShow(ctx, command.slice(3));
+        }
+        else if (head === "policy" && second === "templates") {
+            canonical = "policy templates";
+            result = await handlePolicyTemplates(ctx, command.slice(2));
+        }
+        else if (head === "policy" && second === "preview") {
+            canonical = "policy preview";
+            result = await handlePolicyPreview(ctx, command.slice(2));
+        }
+        else if (head === "policy" && second === "import-mcp-receipt") {
+            canonical = "policy import-mcp-receipt";
+            result = await handlePolicyImportMcpReceipt(ctx, command.slice(2));
+        }
+        else if (head === "policy" && second === "import-x402-receipt") {
+            canonical = "policy import-x402-receipt";
+            result = await handlePolicyImportX402Receipt(ctx, command.slice(2));
+        }
+        else if (head === "policy" && second === "validate-evidence") {
+            canonical = "policy validate-evidence";
+            result = await handlePolicyValidateEvidence(ctx, command.slice(2));
+        }
+        else if (head === "policy" && second === "init-org") {
+            canonical = "policy init-org";
+            result = await handlePolicyInitOrg(ctx, command.slice(2));
+        }
+        else if (head === "policy" && second === "extend") {
+            canonical = "policy extend";
+            result = await handlePolicyExtend(ctx, command.slice(2));
+        }
+        else if (head === "policy" && second === "init") {
+            canonical = "policy init";
+            result = await handlePolicyInit(ctx, command.slice(2));
+        }
+        else if (head === "policy" && second === "validate-tools") {
+            canonical = "policy validate-tools";
+            result = await handlePolicyValidateTools(ctx, command.slice(2));
+        }
+        else if (head === "agent" && second && third) {
+            canonical = commandPath(["agent", second, third]);
+            result = await handleAgent(ctx, second, third, command.slice(3));
+        }
         else {
             throw new CliError(formatUnknownCommandMessage(command.join(" ")), {
                 category: "usage",
@@ -252,7 +319,43 @@ export async function runCli(argv, deps = {}) {
                 ctx.stdout.write(`${line}\n`);
             }
         }
-        else if (canonical !== "login" && canonical !== "mcp serve") {
+        else if (canonical === "agent sandbox smoke" && Array.isArray(result.data.checklist_lines)) {
+            writeTableLines(ctx.stdout, result.data.checklist_lines);
+            if (output.warnings.length) {
+                for (const warning of output.warnings) {
+                    ctx.stderr.write(`${warning}\n`);
+                }
+            }
+        }
+        else if ((canonical === "dev smoke" || canonical === "dev loop") &&
+            Array.isArray(result.data.checklist_lines)) {
+            if (canonical === "dev loop" && Array.isArray(result.data.banner_lines)) {
+                writeTableLines(ctx.stdout, result.data.banner_lines);
+            }
+            writeTableLines(ctx.stdout, result.data.checklist_lines);
+            if (output.warnings.length) {
+                for (const warning of output.warnings) {
+                    ctx.stderr.write(`${warning}\n`);
+                }
+            }
+        }
+        else if (canonical === "agent run trace" && Array.isArray(result.data.trace_lines)) {
+            writeTableLines(ctx.stdout, result.data.trace_lines);
+            if (output.warnings.length) {
+                for (const warning of output.warnings) {
+                    ctx.stderr.write(`${warning}\n`);
+                }
+            }
+        }
+        else if (canonical === "policy presets show" && Array.isArray(result.data.yaml_lines)) {
+            writeTableLines(ctx.stdout, result.data.yaml_lines);
+            if (output.warnings.length) {
+                for (const warning of output.warnings) {
+                    ctx.stderr.write(`${warning}\n`);
+                }
+            }
+        }
+        else if (canonical !== "login" && canonical !== "mcp serve" && canonical !== "dev trace") {
             writeTableLines(ctx.stdout, renderTable(canonical, result, globals));
         }
         return EXIT_SUCCESS;

package/dist/cli/smoke-deep-links.d.ts

@@ -0,0 +1,15 @@
+import type { GlobalOptions } from "./types.js";
+/** Deep links returned by `paybond agent sandbox smoke` for local trace and hosted replay. */
+export type AgentSandboxSmokeDeepLinks = Readonly<{
+    trace_url: string;
+    console_url?: string;
+    agent_trace_url?: string;
+}>;
+/**
+ * Builds trace, console dossier, and hosted agent-trace replay URLs for sandbox smoke JSON.
+ */
+export declare function buildAgentSandboxSmokeDeepLinks(input: {
+    bind: Record<string, unknown>;
+}): AgentSandboxSmokeDeepLinks;
+/** Inserts trace/console/replay checklist lines before the trailing Success row. */
+export declare function appendSmokeDeepLinkChecklistLines(checklistLines: ReadonlyArray<string>, deepLinks: AgentSandboxSmokeDeepLinks, globals: GlobalOptions): string[];

package/dist/cli/smoke-deep-links.js

@@ -0,0 +1,63 @@
+import { devTraceUrl } from "../dev/trace-buffer.js";
+import { colorize, shouldUseColor } from "./color.js";
+const HARBOR_INTENT_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const DEFAULT_LOCAL_PUBLIC_ORIGIN = "http://127.0.0.1:3000";
+function stripTrailingSlashes(value) {
+    return value.replace(/\/+$/, "");
+}
+function resolvePublicOrigin() {
+    const configured = process.env.PAYBOND_PUBLIC_BASE_URL?.trim() ||
+        process.env.PAYBOND_CONSOLE_BASE_URL?.trim();
+    return stripTrailingSlashes(configured && configured.length > 0 ? configured : DEFAULT_LOCAL_PUBLIC_ORIGIN);
+}
+function resolveConsoleOrigin() {
+    const configured = process.env.PAYBOND_CONSOLE_BASE_URL?.trim() ||
+        process.env.PAYBOND_PUBLIC_BASE_URL?.trim();
+    return stripTrailingSlashes(configured && configured.length > 0 ? configured : DEFAULT_LOCAL_PUBLIC_ORIGIN);
+}
+function harborIntentId(bind) {
+    const raw = bind.intent_id;
+    if (typeof raw !== "string") {
+        return undefined;
+    }
+    const trimmed = raw.trim();
+    return HARBOR_INTENT_UUID.test(trimmed) ? trimmed : undefined;
+}
+/**
+ * Builds trace, console dossier, and hosted agent-trace replay URLs for sandbox smoke JSON.
+ */
+export function buildAgentSandboxSmokeDeepLinks(input) {
+    const runId = String(input.bind.run_id ?? "smoke-1");
+    const links = {
+        trace_url: devTraceUrl(undefined, runId),
+    };
+    const intentId = harborIntentId(input.bind);
+    if (!intentId) {
+        return links;
+    }
+    const consoleOrigin = resolveConsoleOrigin();
+    const publicOrigin = resolvePublicOrigin();
+    return {
+        ...links,
+        console_url: `${consoleOrigin}/console/operations/intents/${encodeURIComponent(intentId)}`,
+        agent_trace_url: `${publicOrigin}/demo/agent-trace?intent=${encodeURIComponent(intentId)}`,
+    };
+}
+/** Inserts trace/console/replay checklist lines before the trailing Success row. */
+export function appendSmokeDeepLinkChecklistLines(checklistLines, deepLinks, globals) {
+    const useColor = shouldUseColor(globals);
+    const mark = (line) => colorize(line, "green", useColor);
+    const linkLines = [
+        mark(`✓ Trace → ${deepLinks.trace_url}`),
+        ...(deepLinks.console_url ? [mark(`✓ Console → ${deepLinks.console_url}`)] : []),
+        ...(deepLinks.agent_trace_url ? [mark(`✓ Replay → ${deepLinks.agent_trace_url}`)] : []),
+    ];
+    if (checklistLines.length === 0) {
+        return linkLines;
+    }
+    const last = checklistLines.at(-1);
+    if (last === "Success" || last === mark("Success")) {
+        return [...checklistLines.slice(0, -1), ...linkLines, last];
+    }
+    return [...checklistLines, ...linkLines];
+}

package/dist/cli/telemetry.d.ts

@@ -0,0 +1,17 @@
+import type { CliContext } from "./context.js";
+export type CliTelemetryCommand = "dev loop" | "dev smoke";
+export declare function hashCliInstallId(installId: string): string;
+export declare function resolveCliInstallId(): Promise<string>;
+export declare function cliTelemetryEnabled(gateway: string): Promise<boolean>;
+/**
+ * Fire-and-forget adoption telemetry for successful local dev commands.
+ * Failures are swallowed so CLI workflows never depend on analytics.
+ */
+export declare function reportCliCommandSuccess(ctx: CliContext, input: Readonly<{
+    commandPath: CliTelemetryCommand;
+    offline: boolean;
+}>): Promise<void>;
+export declare function scheduleCliCommandTelemetry(ctx: CliContext, input: Readonly<{
+    commandPath: CliTelemetryCommand;
+    offline: boolean;
+}>): void;

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/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;
+}