@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/config/docs.js

@@ -0,0 +1,85 @@
+import { configFields, describeSchema } from "./fields.js";
+/** `db.poolMax` -> `CAPYBARA_DB__POOL_MAX` (the inverse of the envOverrides mapping)。 */
+export function envName(path) {
+    const seg = path.split(".").map((s) => s.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase());
+    return `CAPYBARA_${seg.join("__")}`;
+}
+const cell = (s) => s.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+const code = (s) => `\`${cell(s)}\``;
+/** Default column: no default -> "required" ("optional" for optional fields); secret -> never printed (—). */
+function defaultCell(secret, d) {
+    if (!d.hasDefault)
+        return d.optional ? "optional" : "required";
+    if (secret)
+        return "—";
+    const v = typeof d.defaultValue === "function" ? d.defaultValue() : d.defaultValue;
+    return code(JSON.stringify(v) ?? "undefined");
+}
+/**
+ * Renders the config schema as a deterministic Markdown table: dotted path, env var, type, default,
+ * hot-reloadable, secret, description. The default of a secret field is always printed as "—" and
+ * never reaches the document.
+ */
+export function renderConfigDocs(schema) {
+    const rows = configFields(schema).map((f) => {
+        const d = describeSchema(f.schema);
+        const secret = f.meta?.secret === true;
+        return `| ${[
+            code(f.path),
+            code(envName(f.path)),
+            code(d.type),
+            defaultCell(secret, d),
+            f.meta?.hot === true ? "yes" : "no",
+            secret ? "yes" : "no",
+            cell(f.meta?.description ?? ""),
+        ].join(" | ")} |`;
+    });
+    return [
+        "# Configuration reference",
+        "",
+        "<!-- Generated by `pnpm gen:config-docs`; do not edit by hand. -->",
+        "",
+        "The config source is chosen by `CAPYBARA_CONFIG_SOURCE` (`file` or `nacos`); environment variables win.",
+        "Nested keys use double underscores, e.g. `CAPYBARA_DB__URL` maps to `db.url`.",
+        "The defaults of secret fields do not appear in this document.",
+        "",
+        "| Key | Env var | Type | Default | Hot | Secret | Description |",
+        "| --- | --- | --- | --- | --- | --- | --- |",
+        ...rows,
+        "",
+        "## Nacos config source",
+        "",
+        "With `CAPYBARA_CONFIG_SOURCE=nacos`, Nacos is specified by the following environment variables (they are not config keys and cannot be written in the config file):",
+        "",
+        "| Env var | Description |",
+        "| --- | --- |",
+        "| `CAPYBARA_NACOS_SERVER` | Nacos address (e.g. `nacos:8848`; the protocol defaults to http). Required |",
+        "| `CAPYBARA_NACOS_NAMESPACE` | Namespace ID. Required |",
+        "| `CAPYBARA_NACOS_DATA_ID` | The config's dataId (YAML). Required; the group is fixed to `DEFAULT_GROUP` |",
+        "| `CAPYBARA_NACOS_USERNAME` / `CAPYBARA_NACOS_PASSWORD` | Username and password when Nacos has authentication on: the kernel logs in to obtain an accessToken and logs in again after 80% of `tokenTtl` or on a 403; set both or neither |",
+        "| `CAPYBARA_NACOS_ACCESS_TOKEN` | An accessToken used as is (the login endpoint is not called); cannot be set together with the username and password |",
+        "",
+        // The web tier's env vars and defaults are owned by apps/web/src/lib/kernel-proxy.ts (kernel address,
+        // body and package upload limits), apps/web/server.mjs (PORT / CAPYBARA_WEB_HOST) and
+        // apps/web/src/dev/catalog/routes.tsx (CAPYBARA_DEV_UI); change this text together with them.
+        // CAPYBARA_WEB_TRUST_PROXY: apps/web/src/lib/peer.ts; CAPYBARA_WEB_SHUTDOWN_GRACE_MS: apps/web/server.mjs.
+        // CAPYBARA_WEB_OBJECT_STORE_*: apps/web/src/lib/object-store-proxy.ts.
+        "## Web tier (apps/web) environment variables",
+        "",
+        "The web tier is a separate process (started through `apps/web/server.mjs`); it does not read the kernel config and only honors the following environment variables:",
+        "",
+        "| Env var | Description |",
+        "| --- | --- |",
+        "| `CAPYBARA_KERNEL_URL` | The kernel address that the `/api/*` proxy forwards to; default `http://localhost:8080` |",
+        "| `PORT` / `CAPYBARA_WEB_HOST` | The web tier's listen port (default 3000) and address |",
+        "| `CAPYBARA_WEB_TRUST_PROXY` | Proxies in front of the web tier (TLS proxy, load balancer) trusted to report the client address in `X-Forwarded-For`: a hop count (`1` = the nearest proxy) or a list of IPs / CIDRs, comma-separated or a JSON array, in the grammar of `http.trustProxy` (dotted netmasks, `loopback` / `linklocal` / `uniquelocal`; a range that trusts every address such as `/0` is refused; no `true` / `false`). Unset (default) trusts nothing: the socket peer is the client, so behind a proxy every user shares the proxy's address for login rate limiting. A hop count is only safe when the web tier is reachable solely through exactly that many proxies. Either way the kernel receives one sanitized client address; a malformed value stops the web tier at startup |",
+        "| `CAPYBARA_WEB_SHUTDOWN_GRACE_MS` | Production only: after SIGTERM / SIGINT, how long in-flight requests (including SSE streams) may run before the process exits; default 5000 |",
+        "| `CAPYBARA_WEB_MAX_BODY_BYTES` | Request body limit of the `/api/*` proxy, default 1 MiB (matches the kernel's bodyLimit) |",
+        "| `CAPYBARA_WEB_MAX_PACKAGE_BYTES` | Request body limit for extension package and plugin uploads (`/api/v1/admin/extensions/packages/file`, `/api/v1/admin/catalog/import/file`), default 50 MiB, forwarded while being read. This is the web tier's limit; the kernel additionally rejects by `packages.maxBytes`. Raise both together, otherwise a large package uploaded through the web is first rejected by the web tier with a 413 |",
+        "| `CAPYBARA_WEB_OBJECT_STORE_URL` | Object storage on the web origin: the object store's address as web reaches it (e.g. `http://seaweedfs-s3:8333`). When set, web proxies `/<bucket>/**` (and `/<bucket>` itself for POST only) there, so browsers upload attachments (presigned POST) and download attachments and artifacts (presigned GET) through web; set the object-store extension's `publicEndpoint` to the web origin with `forcePathStyle: true`. Only GET, HEAD and POST; the path is forwarded unchanged; cookies and authorization are not forwarded; responses carry `X-Content-Type-Options: nosniff` and `Content-Security-Policy: sandbox`; uploads are capped at `CAPYBARA_WEB_MAX_PACKAGE_BYTES`. Unset (default): off |",
+        "| `CAPYBARA_WEB_OBJECT_STORE_BUCKET` | With `CAPYBARA_WEB_OBJECT_STORE_URL`: the bucket, equal to the object-store extension's `bucket` (it is the first path segment web proxies) |",
+        "| `CAPYBARA_WEB_OBJECT_STORE_PUBLIC_HOST` | With `CAPYBARA_WEB_OBJECT_STORE_URL`: the host of the extension's `publicEndpoint` (a host such as `capybara.example.com`, or that URL). Sent upstream as `Host` instead of the incoming one, because presigned URLs sign the host they were issued for and front proxies rewrite it |",
+        "| `CAPYBARA_DEV_UI` | When set to `1`, production builds also serve the `/dev/ui` component catalog page (off by default) |",
+        "",
+    ].join("\n");
+}

package/dist/config/env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 把 `CAPYBARA_A__B_C=x` 形式的环境变量转成嵌套对象 `{ a: { bC: x } }`。
+ * Under `extensionConfig` the second segment is the extension name, converted snake -> kebab.
+ * 同时存在 `CAPYBARA_X`（标量）与 `CAPYBARA_X__Y`（嵌套）时抛 ConfigError。
+ */
+export declare function envOverrides(env: NodeJS.ProcessEnv): Record<string, unknown>;

package/dist/config/env.js

@@ -0,0 +1,73 @@
+import { ConfigError } from "./types.js";
+const PREFIX = "CAPYBARA_";
+const IGNORED = ["CAPYBARA_CONFIG_", "CAPYBARA_NACOS_"];
+function snakeToCamel(segment) {
+    return segment.toLowerCase().replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function parseValue(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+    if (typeof parsed === "number")
+        return String(parsed) === raw ? parsed : raw;
+    if (typeof parsed === "string")
+        return raw;
+    return parsed;
+}
+/** Extension name segment: `EXAMPLE_COUNTER` -> `example-counter` (extension names contain no `_`, so the mapping is unambiguous). */
+function snakeToKebab(segment) {
+    return segment.toLowerCase().replaceAll("_", "-");
+}
+function toPath(key) {
+    const segs = key.slice(PREFIX.length).split("__");
+    const path = segs.map(snakeToCamel);
+    if (path[0] === "extensionConfig" && segs.length > 1)
+        path[1] = snakeToKebab(segs[1]);
+    return path;
+}
+/**
+ * 把 `CAPYBARA_A__B_C=x` 形式的环境变量转成嵌套对象 `{ a: { bC: x } }`。
+ * Under `extensionConfig` the second segment is the extension name, converted snake -> kebab.
+ * 同时存在 `CAPYBARA_X`（标量）与 `CAPYBARA_X__Y`（嵌套）时抛 ConfigError。
+ */
+export function envOverrides(env) {
+    const entries = [];
+    for (const [key, raw] of Object.entries(env)) {
+        if (raw === undefined || !key.startsWith(PREFIX))
+            continue;
+        if (IGNORED.some((p) => key.startsWith(p)))
+            continue;
+        const path = toPath(key);
+        if (path.some((s) => s === ""))
+            continue;
+        entries.push({ key, path, raw });
+    }
+    for (const a of entries) {
+        for (const b of entries) {
+            if (a.path.length < b.path.length && a.path.every((s, i) => s === b.path[i])) {
+                throw new ConfigError(`conflicting environment variables: ${a.key} sets a scalar but ${b.key} sets a nested value under it`);
+            }
+        }
+    }
+    const out = {};
+    for (const { path, raw } of entries) {
+        let node = out;
+        for (const seg of path.slice(0, -1)) {
+            const next = node[seg];
+            if (typeof next === "object" && next !== null && !Array.isArray(next)) {
+                node = next;
+            }
+            else {
+                const created = {};
+                node[seg] = created;
+                node = created;
+            }
+        }
+        node[path[path.length - 1]] = parseValue(raw);
+    }
+    return out;
+}

package/dist/config/fields.d.ts

@@ -0,0 +1,42 @@
+import { type core } from "zod";
+import type { FieldMeta } from "./schema.js";
+/** 一个配置叶子字段：点路径与其元信息。 */
+export interface ConfigField {
+    path: string;
+    meta: FieldMeta | undefined;
+    /** 该叶子的原始 schema（含 default / optional 等包装），供生成文档读取类型与默认值。 */
+    schema: core.$ZodType;
+}
+/**
+ * 剥掉包装后的内层 schema 类型与默认值（无 default 时 hasDefault 为 false）；
+ * `optional` 表示包装链上有 optional（可以不填，且没有默认值时值为 undefined）。
+ */
+export declare function describeSchema(schema: core.$ZodType): {
+    type: string;
+    hasDefault: boolean;
+    defaultValue: unknown;
+    optional: boolean;
+};
+/** 列出 schema 的所有叶子字段（对象递归展开；数组、record 等视作叶子）。 */
+export declare function configFields(schema: core.$ZodType, prefix?: string, inheritedSecret?: boolean): ConfigField[];
+/** 按点路径取值。 */
+export declare function getPath(obj: unknown, path: string): unknown;
+/** 按点路径设值（就地修改，中间对象必须已存在）。 */
+export declare function setPath(obj: Record<string, unknown>, path: string, value: unknown): void;
+/** 比较两份已校验配置，返回值发生变化的叶子点路径。 */
+export declare function changedPaths(schema: core.$ZodType, a: unknown, b: unknown): string[];
+/**
+ * 把一个密钥值展开成需要打码的字符串：字符串原样；数字、bigint 转成字符串；布尔不收集
+ * （`true` / `false` 不携带秘密，登记只会误伤普通文本）；数组与对象（secret 叶子可能是 record / 数组 / 对象）
+ * 递归展开所有标量。最短长度由 logger 把关。
+ */
+export declare function secretScalars(value: unknown, out?: string[]): string[];
+/** 收集标记为 secret 的字段的值（嵌套的数组 / 对象展开为其中所有标量，数字转成字符串，布尔跳过），供 logger 打码。 */
+export declare function secretValues(schema: core.$ZodType, config: unknown): string[];
+/**
+ * 找出 `configFields` 拆不出来的 secret 标记：secret 只能标在「从根经对象字段（及 default / optional 等包装）
+ * 可达」的节点上。标在 union / intersection / pipe（含 transform）/ lazy / array 元素 / record 值 /
+ * tuple / map / set 等内部的 secret，内核既无法单独加密存储也无法打码，返回其描述路径
+ * （如 `auth<union#1>.token`）。对象路径上的 secret 若未让对应叶子被视为 secret（被外层 meta 遮蔽）同样返回。
+ */
+export declare function unreachableSecrets(schema: core.$ZodType): string[];

package/dist/config/fields.js

@@ -0,0 +1,214 @@
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+/**
+ * 剥掉包装后的内层 schema 类型与默认值（无 default 时 hasDefault 为 false）；
+ * `optional` 表示包装链上有 optional（可以不填，且没有默认值时值为 undefined）。
+ */
+export function describeSchema(schema) {
+    let node = schema;
+    let hasDefault = false;
+    let optional = false;
+    let defaultValue;
+    for (;;) {
+        const def = node._zod.def;
+        if (def.type === "default" || def.type === "prefault") {
+            if (!hasDefault) {
+                hasDefault = true;
+                defaultValue = def.defaultValue;
+            }
+        }
+        if (def.type === "optional")
+            optional = true;
+        if (!WRAPPERS.has(def.type) || !def.innerType)
+            break;
+        node = def.innerType;
+    }
+    const def = node._zod.def;
+    // z.preprocess(fn, T) is a pipe from a transform into T: document T.
+    if (def.type === "pipe" && def.in?._zod.def.type === "transform" && def.out) {
+        return { ...describeSchema(def.out), hasDefault, defaultValue, optional };
+    }
+    // T.transform(fn) is a pipe from T into a transform: document T (what the config is written as).
+    if (def.type === "pipe" && def.out?._zod.def.type === "transform" && def.in) {
+        return { ...describeSchema(def.in), hasDefault, defaultValue, optional };
+    }
+    let type = def.type;
+    if (type === "array" && def.element)
+        type = `array<${describeSchema(def.element).type}>`;
+    else if (type === "union" && def.options) {
+        type = def.options.map((o) => describeSchema(o).type).join(" | ");
+    }
+    else if (type === "enum" && def.entries) {
+        type = Object.values(def.entries)
+            .map((v) => JSON.stringify(v))
+            .join(" | ");
+    }
+    return { type, hasDefault, defaultValue, optional };
+}
+const WRAPPERS = new Set(["default", "prefault", "optional", "nullable", "readonly", "catch"]);
+/** 剥掉 default / optional 等包装，返回内层 schema 与沿途遇到的第一个（最外层）元信息。 */
+function unwrap(schema) {
+    let node = schema;
+    let found = z.globalRegistry.get(node);
+    while (WRAPPERS.has(node._zod.def.type)) {
+        node = node._zod.def.innerType;
+        found ??= z.globalRegistry.get(node);
+    }
+    return { inner: node, meta: found };
+}
+/** 列出 schema 的所有叶子字段（对象递归展开；数组、record 等视作叶子）。 */
+export function configFields(schema, prefix = "", inheritedSecret = false) {
+    const { inner, meta: own } = unwrap(schema);
+    const secret = inheritedSecret || own?.secret === true;
+    // 对象节点上标的 secret 对所有后代叶子生效，否则嵌套字段的默认值会被文档/日志漏出。
+    const meta = secret && own?.secret !== true
+        ? { ...own, secret: true, description: own?.description ?? "" }
+        : own;
+    if (inner._zod.def.type === "object") {
+        const shape = inner._zod.def.shape;
+        return Object.entries(shape).flatMap(([k, v]) => configFields(v, prefix ? `${prefix}.${k}` : k, secret));
+    }
+    return [{ path: prefix, meta, schema }];
+}
+/** 按点路径取值。 */
+export function getPath(obj, path) {
+    let node = obj;
+    for (const seg of path.split(".")) {
+        if (typeof node !== "object" || node === null)
+            return undefined;
+        node = node[seg];
+    }
+    return node;
+}
+/** 按点路径设值（就地修改，中间对象必须已存在）。 */
+export function setPath(obj, path, value) {
+    const segs = path.split(".");
+    let node = obj;
+    for (const seg of segs.slice(0, -1))
+        node = node[seg];
+    node[segs[segs.length - 1]] = value;
+}
+/** 比较两份已校验配置，返回值发生变化的叶子点路径。 */
+export function changedPaths(schema, a, b) {
+    return configFields(schema)
+        .map((f) => f.path)
+        .filter((p) => !isDeepStrictEqual(getPath(a, p), getPath(b, p)));
+}
+/**
+ * 把一个密钥值展开成需要打码的字符串：字符串原样；数字、bigint 转成字符串；布尔不收集
+ * （`true` / `false` 不携带秘密，登记只会误伤普通文本）；数组与对象（secret 叶子可能是 record / 数组 / 对象）
+ * 递归展开所有标量。最短长度由 logger 把关。
+ */
+export function secretScalars(value, out = []) {
+    if (typeof value === "string")
+        out.push(value);
+    else if (typeof value === "number" || typeof value === "bigint") {
+        out.push(String(value));
+    }
+    else if (Array.isArray(value)) {
+        for (const v of value)
+            secretScalars(v, out);
+    }
+    else if (typeof value === "object" && value !== null) {
+        for (const v of Object.values(value))
+            secretScalars(v, out);
+    }
+    return out;
+}
+/** 收集标记为 secret 的字段的值（嵌套的数组 / 对象展开为其中所有标量，数字转成字符串，布尔跳过），供 logger 打码。 */
+export function secretValues(schema, config) {
+    const out = [];
+    for (const f of configFields(schema)) {
+        if (f.meta?.secret)
+            secretScalars(getPath(config, f.path), out);
+    }
+    return out;
+}
+const isSecretNode = (node) => z.globalRegistry.get(node)?.secret === true;
+/**
+ * 找出 `configFields` 拆不出来的 secret 标记：secret 只能标在「从根经对象字段（及 default / optional 等包装）
+ * 可达」的节点上。标在 union / intersection / pipe（含 transform）/ lazy / array 元素 / record 值 /
+ * tuple / map / set 等内部的 secret，内核既无法单独加密存储也无法打码，返回其描述路径
+ * （如 `auth<union#1>.token`）。对象路径上的 secret 若未让对应叶子被视为 secret（被外层 meta 遮蔽）同样返回。
+ */
+export function unreachableSecrets(schema) {
+    const covered = configFields(schema)
+        .filter((f) => f.meta?.secret)
+        .map((f) => f.path);
+    const isCovered = (p) => covered.some((c) => p === "" || c === p || c.startsWith(`${p}.`));
+    const out = [];
+    // 只防 lazy 自引用造成的环：同一 schema 实例可能复用在多个位置，每个位置都要检查
+    const stack = new Set();
+    const join = (prefix, seg) => (prefix ? `${prefix}.${seg}` : seg);
+    const t = (v) => v;
+    const walk = (node, label, onPath) => {
+        if (stack.has(node))
+            return;
+        stack.add(node);
+        try {
+            visit(node, label, onPath);
+        }
+        finally {
+            stack.delete(node);
+        }
+    };
+    const visit = (node, label, onPath) => {
+        if (isSecretNode(node)) {
+            if (onPath && isCovered(label))
+                return; // 整棵子树都按 secret 处理
+            out.push(label || "<root>");
+            return;
+        }
+        const def = node._zod.def;
+        switch (def.type) {
+            case "object":
+                for (const [k, v] of Object.entries(def.shape)) {
+                    walk(v, join(label, k), onPath);
+                }
+                if (def.catchall)
+                    walk(t(def.catchall), `${label}<catchall>`, false);
+                return;
+            case "union":
+                def.options.forEach((o, i) => {
+                    walk(o, `${label}<union#${i}>`, false);
+                });
+                return;
+            case "intersection":
+                walk(t(def.left), `${label}<intersection:left>`, false);
+                walk(t(def.right), `${label}<intersection:right>`, false);
+                return;
+            case "pipe":
+                walk(t(def.in), `${label}<pipe:in>`, false);
+                walk(t(def.out), `${label}<pipe:out>`, false);
+                return;
+            case "lazy":
+                walk(def.getter(), `${label}<lazy>`, false);
+                return;
+            case "array":
+                walk(t(def.element), `${label}[]`, false);
+                return;
+            case "set":
+                walk(t(def.valueType), `${label}<set>`, false);
+                return;
+            case "record":
+            case "map":
+                walk(t(def.keyType), `${label}<${def.type}:key>`, false);
+                walk(t(def.valueType), `${label}<${def.type}:value>`, false);
+                return;
+            case "tuple":
+                def.items.forEach((o, i) => {
+                    walk(o, `${label}[${i}]`, false);
+                });
+                if (def.rest)
+                    walk(t(def.rest), `${label}[...]`, false);
+                return;
+            default:
+                // default / optional 等包装沿用 configFields 的对象路径；其余带 innerType 的包装（nonoptional、
+                // promise 等）configFields 视作叶子，其内部的 secret 不可达。
+                if (def.innerType)
+                    walk(t(def.innerType), label, onPath && WRAPPERS.has(def.type));
+        }
+    };
+    walk(schema, "", true);
+    return out;
+}

package/dist/config/file-source.d.ts

@@ -0,0 +1,3 @@
+import { type ConfigSource } from "./types.js";
+/** 从 YAML 文件读取配置；未指定路径时返回空对象（纯环境变量配置）。错误信息不含文件内容。 */
+export declare function fileSource(path: string | undefined): ConfigSource;

package/dist/config/file-source.js

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+import { parse, YAMLParseError } from "yaml";
+import { ConfigError } from "./types.js";
+/** 从 YAML 文件读取配置；未指定路径时返回空对象（纯环境变量配置）。错误信息不含文件内容。 */
+export function fileSource(path) {
+    return {
+        async load() {
+            if (!path)
+                return {};
+            let text;
+            try {
+                text = await readFile(path, "utf8");
+            }
+            catch (e) {
+                const code = e.code ?? "unknown error";
+                throw new ConfigError(`cannot read config file '${path}': ${code}`);
+            }
+            try {
+                return parse(text) ?? {};
+            }
+            catch (e) {
+                if (e instanceof YAMLParseError) {
+                    const pos = e.linePos?.[0];
+                    const at = pos ? ` at line ${pos.line}, column ${pos.col}` : "";
+                    throw new ConfigError(`invalid YAML in config file '${path}'${at}`);
+                }
+                throw new ConfigError(`invalid YAML in config file '${path}'`);
+            }
+        },
+    };
+}

package/dist/config/load.d.ts

@@ -0,0 +1,20 @@
+import { type KernelConfig } from "./schema.js";
+import { type ConfigSourceKind } from "./sources.js";
+import { ConfigError, type ConfigSource } from "./types.js";
+export { ConfigError, type ConfigSource };
+/** 按 `CAPYBARA_CONFIG_SOURCE` 选择配置来源，默认 `file`。 */
+export declare function selectConfigSource(env: NodeJS.ProcessEnv): ConfigSource;
+/** 深合并：对象递归合并，其余（含数组）由 override 整体替换。 */
+export declare function deepMerge(base: unknown, override: unknown): unknown;
+/** 原始配置深合并环境变量覆盖（优先级最高）后校验；热更新与启动共用。错误只列路径不列值。 */
+export declare function resolveConfig(raw: unknown, env: NodeJS.ProcessEnv): KernelConfig;
+/** 选来源 → 深合并环境变量覆盖（优先级最高）→ 校验。 */
+export declare function loadConfig(env: NodeJS.ProcessEnv): Promise<KernelConfig>;
+/**
+ * 与 {@link loadConfig} 相同，另给出各插件部署配置字段的来源（文件 / Nacos / 环境变量，见
+ * {@link extensionConfigSources}）：传给 `createKernel` 的 `extensionConfigSources`，后台据此把这些字段标为只读（D8）。
+ */
+export declare function loadConfigWithSources(env: NodeJS.ProcessEnv): Promise<{
+    config: KernelConfig;
+    extensionConfigSources: Record<string, Record<string, ConfigSourceKind>>;
+}>;

package/dist/config/load.js

@@ -0,0 +1,98 @@
+import { webhookBaseUrlProblem } from "../channels/webhook-url.js";
+import { envOverrides } from "./env.js";
+import { fileSource } from "./file-source.js";
+import { createNacosSource } from "./nacos-source.js";
+import { KernelConfigSchema } from "./schema.js";
+import { configSourceKind, extensionConfigSources } from "./sources.js";
+import { ConfigError } from "./types.js";
+export { ConfigError };
+/**
+ * Nacos 鉴权凭据：`CAPYBARA_NACOS_ACCESS_TOKEN`（静态令牌），或 `CAPYBARA_NACOS_USERNAME` +
+ * `CAPYBARA_NACOS_PASSWORD`（登录换取令牌）；都不设则不鉴权。令牌与用户名不能同时设置，用户名与密码必须成对。
+ */
+function nacosAuth(env) {
+    const token = env.CAPYBARA_NACOS_ACCESS_TOKEN;
+    const username = env.CAPYBARA_NACOS_USERNAME;
+    const password = env.CAPYBARA_NACOS_PASSWORD;
+    if (token) {
+        if (username || password) {
+            throw new ConfigError("set either CAPYBARA_NACOS_ACCESS_TOKEN or CAPYBARA_NACOS_USERNAME / CAPYBARA_NACOS_PASSWORD, not both");
+        }
+        return { auth: { accessToken: token } };
+    }
+    if (!username && !password)
+        return {};
+    if (!username)
+        throw new ConfigError("CAPYBARA_NACOS_USERNAME is required when CAPYBARA_NACOS_PASSWORD is set");
+    if (!password)
+        throw new ConfigError("CAPYBARA_NACOS_PASSWORD is required when CAPYBARA_NACOS_USERNAME is set");
+    return { auth: { username, password } };
+}
+/** 按 `CAPYBARA_CONFIG_SOURCE` 选择配置来源，默认 `file`。 */
+export function selectConfigSource(env) {
+    const kind = env.CAPYBARA_CONFIG_SOURCE || "file";
+    switch (kind) {
+        case "file":
+            return fileSource(env.CAPYBARA_CONFIG_FILE);
+        case "nacos": {
+            const need = (name) => {
+                const v = env[name];
+                if (!v)
+                    throw new ConfigError(`${name} is required when CAPYBARA_CONFIG_SOURCE=nacos`);
+                return v;
+            };
+            const server = need("CAPYBARA_NACOS_SERVER");
+            const namespace = need("CAPYBARA_NACOS_NAMESPACE");
+            const dataId = need("CAPYBARA_NACOS_DATA_ID");
+            return createNacosSource({ server, namespace, dataId, ...nacosAuth(env) });
+        }
+        default:
+            throw new ConfigError(`unknown config source '${kind}' (expected 'file' or 'nacos')`);
+    }
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** 深合并：对象递归合并，其余（含数组）由 override 整体替换。 */
+export function deepMerge(base, override) {
+    if (!isPlainObject(base) || !isPlainObject(override))
+        return override;
+    const out = { ...base };
+    for (const [k, v] of Object.entries(override)) {
+        out[k] = k in out ? deepMerge(out[k], v) : v;
+    }
+    return out;
+}
+/** 原始配置深合并环境变量覆盖（优先级最高）后校验；热更新与启动共用。错误只列路径不列值。 */
+export function resolveConfig(raw, env) {
+    if (!isPlainObject(raw))
+        throw new ConfigError("config file root must be a mapping");
+    const merged = deepMerge(raw, envOverrides(env));
+    const result = KernelConfigSchema.safeParse(merged);
+    if (!result.success) {
+        const lines = result.error.issues.map((i) => `  - ${i.path.map(String).join(".") || "(root)"}: ${i.message}`);
+        throw new ConfigError(`invalid configuration:\n${lines.join("\n")}`);
+    }
+    // Cross-section rule (the loopback exception lives under `tools`)
+    const webhookProblem = webhookBaseUrlProblem(result.data);
+    if (webhookProblem !== null) {
+        throw new ConfigError(`invalid configuration:\n  - channels.webhookBaseUrl: ${webhookProblem}`);
+    }
+    return result.data;
+}
+/** 选来源 → 深合并环境变量覆盖（优先级最高）→ 校验。 */
+export async function loadConfig(env) {
+    return resolveConfig(await selectConfigSource(env).load(), env);
+}
+/**
+ * 与 {@link loadConfig} 相同，另给出各插件部署配置字段的来源（文件 / Nacos / 环境变量，见
+ * {@link extensionConfigSources}）：传给 `createKernel` 的 `extensionConfigSources`，后台据此把这些字段标为只读（D8）。
+ */
+export async function loadConfigWithSources(env) {
+    const raw = await selectConfigSource(env).load();
+    const config = resolveConfig(raw, env);
+    return {
+        config,
+        extensionConfigSources: extensionConfigSources(raw, env, configSourceKind(env)),
+    };
+}

package/dist/config/nacos-source.d.ts

@@ -0,0 +1,31 @@
+import { type ConfigSource } from "./types.js";
+/** Nacos 配置来源的参数。 */
+export interface NacosSourceOptions {
+    server: string;
+    namespace: string;
+    dataId: string;
+    /** 默认 `DEFAULT_GROUP`。 */
+    group?: string;
+    fetch?: typeof fetch;
+    /** 单次读取配置的超时，默认 10000ms；超时抛 ConfigError（启动快速失败）。 */
+    timeoutMs?: number;
+    /** watch 出错后的退避间隔，默认 1000ms。 */
+    backoffMs?: number;
+    /**
+     * Nacos 开启鉴权时的凭据：
+     * - 用户名密码：先 `POST /nacos/v1/auth/login` 换取 accessToken，用到 `tokenTtl` 的 80% 后（或请求收到 403 时）重新登录；
+     * - accessToken：直接使用，不调用登录接口（收到 403 即报错）。
+     * 令牌以 `accessToken` 查询参数随每个配置 / 监听请求发送。
+     */
+    auth?: {
+        username: string;
+        password: string;
+    } | {
+        accessToken: string;
+    };
+}
+/**
+ * 从 Nacos 读取 YAML 配置并可长轮询监听变更。错误信息含 server 与 dataId，但不含响应体、YAML 内容或凭据。
+ * 鉴权见 `NacosSourceOptions.auth`：令牌按需续期（每次请求前检查是否到了续期时刻），不起定时器。
+ */
+export declare function createNacosSource(opts: NacosSourceOptions): ConfigSource;