@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/extensions/cli.d.ts

@@ -1,18 +1,23 @@
+import type { DynamicModule, INestApplicationContext, Type } from "@nestjs/common";
 import type { z } from "zod";
 import type { KernelConfig } from "../config/schema.js";
-import { type KernelDb } from "../db/kernel-schema.js";
 import type { KernelLogger } from "../log.js";
 import { ExtensionAdminOps } from "./admin-ops.js";
 import { ExtensionAdmin } from "./admin-view.js";
 import { ExtensionApprovals } from "./approvals.js";
-import { type ConfigIssue } from "./deployment-config.js";
+import { BootstrapService } from "./bootstrap.js";
+import { type ConfigIssue } from "./config-issues.js";
 import { type InspectedExtension } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import type { PermissionSet } from "./permission-set.js";
 /** {@link openExtensionCli} 的结果：CLI 的 `capybara extensions *` 共用。 */
 export interface ExtensionCli {
     config: KernelConfig;
-    db: KernelDb;
+    /**
+     * The command's Nest application context: the extension providers, the database
+     * and the CLI's Redis. Closed by {@link close}.
+     */
+    app: INestApplicationContext;
     /** 配置声明的插件（导入、按依赖排序，不 setup）。 */
     inspected: InspectedExtension[];
     /**
@@ -37,6 +42,8 @@ export interface ExtensionCli {
     admin: ExtensionAdmin;
     ops: ExtensionAdminOps;
     approvals: ExtensionApprovals;
+    /** The bootstrap step (`capybara bootstrap`), under the same `lock:bootstrap` as the kernel. */
+    bootstrap: BootstrapService;
     /** CLI 本次刚导入的包字节（降级判断等读包时优先用它：包可能存在 CLI 读不到的对象存储里）。 */
     remember(sha256: string, bytes: Uint8Array): void;
     /** 安装记录包的权限集合（与后台审阅相同）；包在对象存储里时 CLI 读不到，抛错。 */
@@ -48,14 +55,29 @@ export interface ExtensionCli {
     close(): Promise<void>;
 }
 /**
- * The CLI's extension management context (C18, F-Q): connects only to PG (and Redis for publishing),
- * starts no extension host and runs no extension's `setup` (a catalog import sets up the declared
- * object-store extension itself, see `openCatalogCli`). Packages the CLI imports are always
- * stored in PG (`blob_store = 'pg'`); replicas read by `blob_store`. Install / enable / disable /
- * uninstall share {@link ExtensionAdminOps} with the admin console (actor null, audits without an
- * actor); after writing PG it publishes `kernel.plugins.changed` and running replicas reconcile; a
- * failed publish only warns (the periodic reconcile catches up).
+ * The effective deployment config (the startup config `fileValue` completed by the `stored` PG
+ * fields) parsed as the host's load gate does: overridable fields may stay empty (spec A §5.4a),
+ * hidden and read-only ones must be complete.
+ */
+export declare function parseDeploymentConfig(schema: z.ZodTypeAny, stored: Record<string, unknown>, fileValue: unknown): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    issues: ConfigIssue[];
+};
+/**
+ * The CLI's extension management context (C18, F-Q): a Nest application context with
+ * the extensions module over the database and a lazy Redis connection used only for publishing
+ * and the bootstrap lock. It loads no extension and runs no extension's `setup` (a catalog import
+ * sets up the declared object-store extension itself, see `openCatalogCli`). Packages the CLI
+ * imports are always stored in PG (`blob_store = 'pg'`); replicas read by `blob_store`. Install /
+ * enable / disable / uninstall share {@link ExtensionAdminOps} with the admin console (actor null,
+ * audits without an actor); after writing PG it publishes `kernel.plugins.changed` and running
+ * replicas reconcile; a failed publish only warns (the periodic reconcile catches up).
  */
 export declare function openExtensionCli(config: KernelConfig, log: KernelLogger, opts?: {
     resolveFrom?: string;
+    /** More domain modules for the context (the catalog CLI adds its import module). */
+    modules?: (Type | DynamicModule)[];
 }): Promise<ExtensionCli>;

package/dist/extensions/cli.js

@@ -1,54 +1,60 @@
 import { SDK_VERSION } from "@capybara-hq/plugin-sdk";
-import { Redis } from "ioredis";
-import { createBus } from "../ctx/bus.js";
-import { createKeyring } from "../ctx/secrets.js";
-import { kernelDb } from "../db/kernel-schema.js";
-import { createDb } from "../db/pool.js";
+import { openKernelCli } from "../infra/cli/kernel-cli.module.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KERNEL_BUS, KEYRING } from "../infra/tokens.js";
 import { ExtensionAdminOps } from "./admin-ops.js";
 import { ExtensionAdmin } from "./admin-view.js";
 import { ExtensionApprovals } from "./approvals.js";
 import { ExtensionBlobs } from "./blobs.js";
-import { mergeDeploymentConfig, readStoredDeploymentConfig, schemaFields, secretPathsOf, } from "./deployment-config.js";
+import { BootstrapService } from "./bootstrap.js";
+import { toIssues } from "./config-issues.js";
+import { mergeDeploymentConfig, readStoredDeploymentConfig, schemaFields, secretPathsOf, } from "./deployment-config-store.js";
+import { ExtensionsModule } from "./extensions.module.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
-import { PLUGINS_CHANGED_TOPIC } from "./lifecycle.js";
-import { toIssues } from "./org-config.js";
+import { PLUGINS_CHANGED_TOPIC } from "./lifecycle-topics.js";
+import { parseLoadGate } from "./org-levels.js";
 import { ExtensionPackageError, extensionPackageApiError, permissionSetOfPackage, readExtensionPackage, } from "./package.js";
-/** CLI 发布 bus 消息时连 Redis 的时限（连不上只告警）。 */
-const CLI_REDIS_CONNECT_TIMEOUT_MS = 3_000;
 /**
- * The CLI's extension management context (C18, F-Q): connects only to PG (and Redis for publishing),
- * starts no extension host and runs no extension's `setup` (a catalog import sets up the declared
- * object-store extension itself, see `openCatalogCli`). Packages the CLI imports are always
- * stored in PG (`blob_store = 'pg'`); replicas read by `blob_store`. Install / enable / disable /
- * uninstall share {@link ExtensionAdminOps} with the admin console (actor null, audits without an
- * actor); after writing PG it publishes `kernel.plugins.changed` and running replicas reconcile; a
- * failed publish only warns (the periodic reconcile catches up).
+ * The effective deployment config (the startup config `fileValue` completed by the `stored` PG
+ * fields) parsed as the host's load gate does: overridable fields may stay empty (spec A §5.4a),
+ * hidden and read-only ones must be complete.
+ */
+export function parseDeploymentConfig(schema, stored, fileValue) {
+    const r = parseLoadGate(schema, mergeDeploymentConfig(stored, fileValue, schemaFields(schema).map((f) => f.path)));
+    return r.success ? { ok: true, value: r.data } : { ok: false, issues: toIssues(r.error) };
+}
+/**
+ * The CLI's extension management context (C18, F-Q): a Nest application context with
+ * the extensions module over the database and a lazy Redis connection used only for publishing
+ * and the bootstrap lock. It loads no extension and runs no extension's `setup` (a catalog import
+ * sets up the declared object-store extension itself, see `openCatalogCli`). Packages the CLI
+ * imports are always stored in PG (`blob_store = 'pg'`); replicas read by `blob_store`. Install /
+ * enable / disable / uninstall share {@link ExtensionAdminOps} with the admin console (actor null,
+ * audits without an actor); after writing PG it publishes `kernel.plugins.changed` and running
+ * replicas reconcile; a failed publish only warns (the periodic reconcile catches up).
  */
 export async function openExtensionCli(config, log, opts = {}) {
     const inspected = await ExtensionHost.inspect(config.extensions, {
         ...(opts.resolveFrom !== undefined && { resolveFrom: opts.resolveFrom }),
     });
-    const raw = createDb(config.db.url, 2, (err) => log.error("pg idle client error", { err }), {
-        connectTimeoutMs: config.db.connectTimeoutMs,
+    const app = await openKernelCli(config, {
+        logger: log,
+        ...(opts.resolveFrom !== undefined && { resolveFrom: opts.resolveFrom }),
+        modules: [ExtensionsModule, ...(opts.modules ?? [])],
     });
-    const db = kernelDb(raw);
-    const local = new Map();
-    const stored = new ExtensionBlobs({ db, maxBytes: () => config.packages.maxBytes });
-    const blobs = {
-        get: async (sha256) => local.get(sha256) ?? stored.get(sha256),
-    };
-    const declared = new Map(inspected.map((p) => [p.manifest.name, p.source]));
+    const close = () => app.close().catch(() => { });
+    const db = app.get(KernelDb);
+    const keyring = app.get(KEYRING);
+    const blobs = app.get(ExtensionBlobs);
     // 部署配置 = 启动配置补上后台保存在 PG 的字段（C10）；不合法的插件内核不加载（待配置）
-    const keyring = createKeyring(Buffer.from(config.masterKey, "base64"), config.masterKeyPrevious.map((k) => Buffer.from(k, "base64")));
     const deploymentConfigOf = async (name, schema) => {
         if (!schema)
             return { ok: true, value: {} };
-        const stored = await readStoredDeploymentConfig(db, keyring, name, {
+        const stored = await readStoredDeploymentConfig(db.db, keyring, name, {
             secretPaths: secretPathsOf(schemaFields(schema)),
         });
-        const r = schema.safeParse(mergeDeploymentConfig(stored, config.extensionConfig[name], schemaFields(schema).map((f) => f.path)));
-        return r.success ? { ok: true, value: r.data } : { ok: false, issues: toIssues(r.error) };
+        return parseDeploymentConfig(schema, stored, config.extensionConfig[name]);
     };
     const configIssues = new Map();
     const deploymentConfigs = new Map();
@@ -65,77 +71,28 @@ export async function openExtensionCli(config, log, opts = {}) {
         }
     }
     catch (e) {
-        await raw.destroy().catch(() => { });
+        await close();
         throw e;
     }
-    const declaredInfo = inspected.map((p) => ({
-        name: p.manifest.name,
-        source: p.source,
-        version: p.manifest.version,
-        permissions: p.permissions,
-        configurable: p.manifest.config?.deployment !== undefined,
-        configValid: !configIssues.has(p.manifest.name),
-    }));
-    let redis;
-    const publisher = {
-        async publish(topic, payload) {
-            if (!redis) {
-                redis = new Redis(config.redis.url, {
-                    lazyConnect: true,
-                    enableOfflineQueue: false,
-                    maxRetriesPerRequest: 0,
-                    connectTimeout: CLI_REDIS_CONNECT_TIMEOUT_MS,
-                    retryStrategy: () => null,
-                });
-                redis.on("error", () => { });
-            }
-            if (redis.status !== "ready")
-                await redis.connect();
-            // 与内核 bus 同一个频道命名（cap:kernel:<topic>）；CLI 只发布，不订阅
-            const bus = createBus(redis, {
-                subscribe: () => Promise.reject(new Error("the CLI does not subscribe")),
-            }, "kernel", log);
-            await bus.publish(topic, payload);
-        },
-    };
-    const installs = new ExtensionInstalls({
-        db,
-        blobs: stored,
-        config: () => config,
-        declared: () => declared,
-    });
-    const admin = new ExtensionAdmin({
-        db,
-        blobs,
-        installs,
-        config: () => config,
-        host: { declaredPlugins: () => declaredInfo },
-        bus: publisher,
-        log,
-    });
-    const ops = new ExtensionAdminOps({
-        db,
-        view: (name) => admin.get(name, { allowUnreadable: true }),
-        declared: () => declared,
-        blobs,
-        config: () => config,
-        bus: publisher,
-        log,
-    });
+    // The admin view, the operations and the bootstrap step see the declared extensions as a
+    // replica would (the CLI checked their deployment config above)
+    app
+        .get(ExtensionHost)
+        .noteInspected(inspected, new Map(inspected.map((p) => [p.manifest.name, !configIssues.has(p.manifest.name)])));
+    const bus = app.get(KERNEL_BUS);
     return {
         config,
-        db,
+        app,
         inspected,
         configIssues,
         deploymentConfigs,
         deploymentConfigOf,
-        installs,
-        admin,
-        ops,
-        approvals: new ExtensionApprovals(db),
-        remember: (sha256, bytes) => {
-            local.set(sha256, bytes);
-        },
+        installs: app.get(ExtensionInstalls),
+        admin: app.get(ExtensionAdmin),
+        ops: app.get(ExtensionAdminOps),
+        approvals: app.get(ExtensionApprovals),
+        bootstrap: app.get(BootstrapService),
+        remember: (sha256, bytes) => blobs.remember(sha256, bytes),
         readPackage: (sha256) => blobs.get(sha256),
         async packageSet(sha256) {
             // a stored package in the pre-0.1.0 format -> extension.legacy_format
@@ -149,7 +106,7 @@ export async function openExtensionCli(config, log, opts = {}) {
         },
         async publishChanged(plugin) {
             try {
-                await publisher.publish(PLUGINS_CHANGED_TOPIC, { plugin });
+                await bus.publish(PLUGINS_CHANGED_TOPIC, { plugin });
                 return true;
             }
             catch (err) {
@@ -157,9 +114,6 @@ export async function openExtensionCli(config, log, opts = {}) {
                 return false;
             }
         },
-        async close() {
-            redis?.disconnect();
-            await raw.destroy().catch(() => { });
-        },
+        close,
     };
 }

package/dist/extensions/config-hash.d.ts

@@ -0,0 +1,10 @@
+import type { core } from "zod";
+/**
+ * 插件部署配置（校验后）中非密钥部分的摘要：先把 schema 里所有 secret 叶子（`configFields` 可达路径，
+ * 加载时 `assertSecretsReachable` 已保证密钥都在这些路径上）换成固定占位值，再取 sha256(键排序 JSON) 前 16 位十六进制。
+ * 给需要「配置变了就失效」的缓存键用（如模型列表）。密钥不参与摘要：不加盐的短摘要写进 Redis 键名后，
+ * 低熵密钥可被离线猜测、泄露的密钥可被确认；代价是轮换密钥不会让缓存失效（缓存内容本来就不该依赖密钥）。
+ * 没有部署配置 schema 时无从得知哪些是密钥，摘要不按配置区分。同一份配置在各副本上得到同一摘要。
+ * 函数自己按 schema 遮蔽，调用方不必（也不能忘记）先打码。
+ */
+export declare function deploymentConfigHash(schema: core.$ZodType | undefined, config: unknown): string;

package/dist/extensions/config-hash.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { configFields, getPath, setPath } from "../config/fields.js";
+/** 键排序后的 JSON（对象键顺序不影响结果）；undefined 字段与 JSON.stringify 一样省略。 */
+const canonicalJson = (v) => {
+    if (Array.isArray(v))
+        return `[${v.map((x) => (x === undefined ? "null" : canonicalJson(x))).join(",")}]`;
+    if (v !== null && typeof v === "object") {
+        const entries = Object.entries(v)
+            .filter(([, x]) => x !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, x]) => `${JSON.stringify(k)}:${canonicalJson(x)}`).join(",")}}`;
+    }
+    return JSON.stringify(v) ?? "null";
+};
+/** 遮蔽 secret 字段后参与摘要的固定占位值。 */
+const SECRET_PLACEHOLDER = "<secret>";
+/**
+ * 插件部署配置（校验后）中非密钥部分的摘要：先把 schema 里所有 secret 叶子（`configFields` 可达路径，
+ * 加载时 `assertSecretsReachable` 已保证密钥都在这些路径上）换成固定占位值，再取 sha256(键排序 JSON) 前 16 位十六进制。
+ * 给需要「配置变了就失效」的缓存键用（如模型列表）。密钥不参与摘要：不加盐的短摘要写进 Redis 键名后，
+ * 低熵密钥可被离线猜测、泄露的密钥可被确认；代价是轮换密钥不会让缓存失效（缓存内容本来就不该依赖密钥）。
+ * 没有部署配置 schema 时无从得知哪些是密钥，摘要不按配置区分。同一份配置在各副本上得到同一摘要。
+ * 函数自己按 schema 遮蔽，调用方不必（也不能忘记）先打码。
+ */
+export function deploymentConfigHash(schema, config) {
+    let redacted = null;
+    if (schema) {
+        redacted = structuredClone(config);
+        if (redacted !== null && typeof redacted === "object") {
+            for (const f of configFields(schema)) {
+                if (f.meta?.secret && getPath(redacted, f.path) !== undefined) {
+                    setPath(redacted, f.path, SECRET_PLACEHOLDER);
+                }
+            }
+        }
+    }
+    return createHash("sha256").update(canonicalJson(redacted)).digest("hex").slice(0, 16);
+}

package/dist/extensions/config-issues.d.ts

@@ -0,0 +1,19 @@
+import type { z } from "zod";
+/** 校验失败的单条原因：只含路径与按 issue 类型生成的说明，不回显字段值。 */
+export interface ConfigIssue {
+    /** The path joined with dots (`""` = the root); ambiguous when a key contains a dot. */
+    path: string;
+    /** The zod path unjoined (record keys such as endpoint names may contain dots). */
+    segments: (string | number)[];
+    message: string;
+    /**
+     * A custom issue whose `params.ui` names a key of the schema's root `x-ui.messages`: the form
+     * shows that localized message (spec §4.4). Never zod's own custom text.
+     */
+    messageKey?: string;
+}
+/**
+ * The issues of a failed config parse. `messages` is the root `x-ui.messages` of the schema's
+ * form JSON Schema (`configMessages`): custom issues naming one of its keys get `messageKey`.
+ */
+export declare function toIssues(error: z.ZodError, messages?: Record<string, unknown>): ConfigIssue[];

package/dist/extensions/config-issues.js

@@ -0,0 +1,48 @@
+/** 由 issue 类型与结构字段生成说明；不用 zod 的 message（自定义消息可能拼入输入值）。 */
+function issueMessage(i) {
+    switch (i.code) {
+        case "invalid_type":
+            return `expected ${i.expected}`;
+        case "too_small":
+            return `too small (minimum ${String(i.minimum)})`;
+        case "too_big":
+            return `too big (maximum ${String(i.maximum)})`;
+        case "invalid_format":
+            return `invalid ${i.format}`;
+        case "not_multiple_of":
+            return `not a multiple of ${String(i.divisor)}`;
+        case "unrecognized_keys":
+            return "unrecognized keys";
+        case "invalid_union":
+            return "no union member matched";
+        case "invalid_key":
+            return "invalid key";
+        case "invalid_element":
+            return "invalid element";
+        default:
+            return "invalid value";
+    }
+}
+/** The `params.ui` of a custom issue when it names one of `messages` (own keys only). */
+function messageKeyOf(i, messages) {
+    if (i.code !== "custom" || messages === undefined)
+        return undefined;
+    const key = i.params?.ui;
+    return typeof key === "string" && Object.hasOwn(messages, key) ? key : undefined;
+}
+/**
+ * The issues of a failed config parse. `messages` is the root `x-ui.messages` of the schema's
+ * form JSON Schema (`configMessages`): custom issues naming one of its keys get `messageKey`.
+ */
+export function toIssues(error, messages) {
+    return error.issues.map((i) => {
+        const segments = i.path.map((s) => (typeof s === "number" ? s : String(s)));
+        const messageKey = messageKeyOf(i, messages);
+        return {
+            path: segments.join("."),
+            segments,
+            message: issueMessage(i),
+            ...(messageKey !== undefined && { messageKey }),
+        };
+    });
+}

package/dist/extensions/config-json-schema.d.ts

@@ -1,9 +1,45 @@
-import { z } from "zod";
-export type JsonSchema = Record<string, unknown>;
 /**
- * 把插件配置 schema 转成 JSON Schema（供界面渲染表单）：
- * - `secret()` 字段带 `"x-secret": true`（去掉 zod 附带的 `secret` 元数据键）；
- * - 无法表达的类型为 `{ "x-unsupported": true }`，不抛错；
- * - 以输入侧形态输出（含 default），不带 `$schema`。
+ * Config schema → JSON Schema for forms. The conversion (and the secret scrub) lives in the SDK
+ * (`configJsonSchema`, extension config forms spec §4.1) so the packer, the checks and the kernel
+ * share one implementation; the kernel keeps no copy.
  */
-export declare function configToJsonSchema(schema: z.ZodType): JsonSchema;
+import { type ConfigUiProblem, type JsonSchema } from "@capybara-hq/plugin-sdk";
+import type { z } from "zod";
+export { configJsonSchema as configToJsonSchema, type JsonSchema } from "@capybara-hq/plugin-sdk";
+/** The config level a schema belongs to (which hints `validateConfigUi` allows). */
+export type ConfigLevel = "deployment" | "org" | "connection";
+/** A config schema as served to forms, with the problems of its hints (empty = kept). */
+export interface ConfigFormSchema {
+    /** Shared by every caller: clone it before handing it out or changing it. */
+    readonly schema: JsonSchema;
+    readonly problems: ConfigUiProblem[];
+}
+/**
+ * Removes every `x-ui` from a JSON Schema in place (a property named `x-ui` is kept, and so are
+ * values: `default`, `const`, `enum` and `examples` are left as they are).
+ */
+export declare function stripConfigUi(node: unknown): void;
+/**
+ * Validates the hints of a JSON Schema at a level and strips every `x-ui` when there is any
+ * problem (in place): invalid hints never reach a form, and never fail a load (spec §4.1).
+ */
+export declare function checkConfigUi(schema: JsonSchema, level: ConfigLevel): ConfigUiProblem[];
+/** A config schema's form JSON Schema ({@link checkConfigUi} applied), cached per schema object. */
+export declare function configFormSchema(schema: z.ZodTypeAny, level: ConfigLevel): ConfigFormSchema;
+/**
+ * {@link configFormSchema} that never throws, for every caller that serves a form schema or reads
+ * its messages (deployment, org, connection, issues). A hint conversion that throws (a hand-made
+ * package, e.g. hints that won't serialize as JSON) drops the hints: the plain schema with every
+ * `x-ui` stripped, else `null` when even the plain conversion fails. `onFallback` runs once per
+ * schema object and level on this replica (the caller's one warning); later calls reuse the result.
+ */
+export declare function safeConfigFormSchema(schema: z.ZodTypeAny, level: ConfigLevel, onFallback: (err: unknown, fallback: "plain" | "none") => void): ConfigFormSchema | null;
+/**
+ * The secret record paths some `x-ui.secrets[].path` of a form schema names (spec §4.3), anywhere in
+ * the schema. Read from a checked schema: one whose hints were invalid was stripped and names none.
+ */
+export declare function hintedSecretPaths(node: unknown, out?: Set<string>): Set<string>;
+/** The root `x-ui.messages` of a form schema (the localized texts of custom issues), if any. */
+export declare function configMessages(schema: JsonSchema | null | undefined): Record<string, unknown> | undefined;
+/** A short text of hint problems for a status detail or a log (the first few). */
+export declare function describeConfigUiProblems(level: ConfigLevel, problems: ConfigUiProblem[]): string;

package/dist/extensions/config-json-schema.js

@@ -1,73 +1,139 @@
-import { z } from "zod";
-/** JSON Schema 无法表达的 zod 类型：降级为 `{}` 并标注 `x-unsupported`。 */
-const UNSUPPORTED = new Set([
-    "bigint",
-    "date",
-    "symbol",
-    "undefined",
-    "void",
-    "nan",
-    "map",
-    "set",
-    "function",
-    "promise",
-    "custom",
-    "file",
-]);
 /**
- * 把插件配置 schema 转成 JSON Schema（供界面渲染表单）：
- * - `secret()` 字段带 `"x-secret": true`（去掉 zod 附带的 `secret` 元数据键）；
- * - 无法表达的类型为 `{ "x-unsupported": true }`，不抛错；
- * - 以输入侧形态输出（含 default），不带 `$schema`。
+ * Config schema → JSON Schema for forms. The conversion (and the secret scrub) lives in the SDK
+ * (`configJsonSchema`, extension config forms spec §4.1) so the packer, the checks and the kernel
+ * share one implementation; the kernel keeps no copy.
  */
-export function configToJsonSchema(schema) {
-    const out = z.toJSONSchema(schema, {
-        io: "input",
-        unrepresentable: "any",
-        override: (ctx) => {
-            const js = ctx.jsonSchema;
-            const def = ctx.zodSchema._zod.def;
-            if (js.secret === true) {
-                delete js.secret;
-                js["x-secret"] = true;
-            }
-            if (UNSUPPORTED.has(def.type))
-                js["x-unsupported"] = true;
-        },
-    });
-    delete out.$schema;
-    scrubSecrets(out);
-    return out;
-}
-/** 会泄露取值的关键字：密钥字段一律不输出。 */
-const VALUE_KEYWORDS = ["default", "examples", "const", "enum"];
-/** 值为「名字 -> 子 schema」映射的关键字：其键是用户字段名，不是关键字。 */
+import { configJsonSchema, validateConfigUi, } from "@capybara-hq/plugin-sdk";
+export { configJsonSchema as configToJsonSchema } from "@capybara-hq/plugin-sdk";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Keywords whose value maps names to sub-schemas: their keys are field names, not keywords. */
 const SCHEMA_MAPS = new Set(["properties", "patternProperties", "$defs", "definitions"]);
+/** Keywords whose value is data, not a schema: never recursed into. */
+const VALUE_KEYWORDS = new Set(["default", "const", "enum", "examples"]);
 /**
- * 递归清掉密钥节点及其所有后代上会暴露取值的关键字（`inSecret` 随递归下传）；无环（输出为纯 JSON 树）。
- * 只有 schema 关键字 default / examples / const / enum 的值被当作数据跳过；
- * `properties` 等映射里的键是字段名，名为 default / enum 的字段照常遍历。
+ * Removes every `x-ui` from a JSON Schema in place (a property named `x-ui` is kept, and so are
+ * values: `default`, `const`, `enum` and `examples` are left as they are).
  */
-function scrubSecrets(node, inSecret = false) {
+export function stripConfigUi(node) {
     if (Array.isArray(node)) {
         for (const n of node)
-            scrubSecrets(n, inSecret);
+            stripConfigUi(n);
         return;
     }
-    if (typeof node !== "object" || node === null)
+    if (!isObj(node))
         return;
-    const o = node;
-    const secret = inSecret || o["x-secret"] === true;
-    if (secret)
-        for (const k of VALUE_KEYWORDS)
-            delete o[k];
-    for (const [k, v] of Object.entries(o)) {
-        if (SCHEMA_MAPS.has(k) && typeof v === "object" && v !== null) {
+    delete node["x-ui"];
+    for (const [k, v] of Object.entries(node)) {
+        if (VALUE_KEYWORDS.has(k))
+            continue;
+        if (SCHEMA_MAPS.has(k) && isObj(v))
             for (const child of Object.values(v))
-                scrubSecrets(child, secret);
+                stripConfigUi(child);
+        else
+            stripConfigUi(v);
+    }
+}
+/**
+ * Validates the hints of a JSON Schema at a level and strips every `x-ui` when there is any
+ * problem (in place): invalid hints never reach a form, and never fail a load (spec §4.1).
+ */
+export function checkConfigUi(schema, level) {
+    const problems = validateConfigUi(schema, level);
+    if (problems.length > 0)
+        stripConfigUi(schema);
+    return problems;
+}
+/** Manifests are immutable: one conversion per zod schema object and level (read-only, per replica). */
+const caches = {
+    deployment: new WeakMap(),
+    org: new WeakMap(),
+    connection: new WeakMap(),
+};
+/** A config schema's form JSON Schema ({@link checkConfigUi} applied), cached per schema object. */
+export function configFormSchema(schema, level) {
+    const cache = caches[level];
+    let r = cache.get(schema);
+    if (!r) {
+        const js = configJsonSchema(schema);
+        r = { schema: js, problems: checkConfigUi(js, level) };
+        cache.set(schema, r);
+    }
+    return r;
+}
+/** The schemas whose hinted conversion threw: their fallback (plain schema, or null). */
+const fallbacks = {
+    deployment: new WeakMap(),
+    org: new WeakMap(),
+    connection: new WeakMap(),
+};
+/**
+ * {@link configFormSchema} that never throws, for every caller that serves a form schema or reads
+ * its messages (deployment, org, connection, issues). A hint conversion that throws (a hand-made
+ * package, e.g. hints that won't serialize as JSON) drops the hints: the plain schema with every
+ * `x-ui` stripped, else `null` when even the plain conversion fails. `onFallback` runs once per
+ * schema object and level on this replica (the caller's one warning); later calls reuse the result.
+ */
+export function safeConfigFormSchema(schema, level, onFallback) {
+    const failed = fallbacks[level].get(schema);
+    if (failed !== undefined)
+        return failed;
+    try {
+        return configFormSchema(schema, level);
+    }
+    catch (err) {
+        let r = null;
+        try {
+            const plain = configJsonSchema(schema);
+            stripConfigUi(plain);
+            r = { schema: plain, problems: [] };
+        }
+        catch {
+            r = null;
         }
-        else if (!VALUE_KEYWORDS.includes(k)) {
-            scrubSecrets(v, secret);
+        fallbacks[level].set(schema, r);
+        onFallback(err, r ? "plain" : "none");
+        return r;
+    }
+}
+/**
+ * The secret record paths some `x-ui.secrets[].path` of a form schema names (spec §4.3), anywhere in
+ * the schema. Read from a checked schema: one whose hints were invalid was stripped and names none.
+ */
+export function hintedSecretPaths(node, out = new Set()) {
+    if (Array.isArray(node)) {
+        for (const n of node)
+            hintedSecretPaths(n, out);
+        return out;
+    }
+    if (!isObj(node))
+        return out;
+    const hints = node["x-ui"];
+    if (isObj(hints) && Array.isArray(hints.secrets)) {
+        for (const s of hints.secrets) {
+            if (isObj(s) && typeof s.path === "string")
+                out.add(s.path);
         }
     }
+    for (const [k, v] of Object.entries(node)) {
+        if (k === "x-ui" || VALUE_KEYWORDS.has(k))
+            continue;
+        if (SCHEMA_MAPS.has(k) && isObj(v)) {
+            for (const child of Object.values(v))
+                hintedSecretPaths(child, out);
+        }
+        else
+            hintedSecretPaths(v, out);
+    }
+    return out;
+}
+/** The root `x-ui.messages` of a form schema (the localized texts of custom issues), if any. */
+export function configMessages(schema) {
+    const hints = schema?.["x-ui"];
+    return isObj(hints) && isObj(hints.messages) ? hints.messages : undefined;
+}
+/** A short text of hint problems for a status detail or a log (the first few). */
+export function describeConfigUiProblems(level, problems) {
+    const shown = problems.slice(0, 5).map((p) => `${p.path || "<root>"}: ${p.message}`);
+    const more = problems.length > shown.length ? `; and ${problems.length - shown.length} more` : "";
+    return `${level} config UI hints ignored (${shown.join("; ")}${more})`;
 }