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

package/dist/extensions/bootstrap.js

@@ -0,0 +1,441 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { bootstrapFileName, parseBootstrapManifest, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
+import { sql } from "kysely";
+import pg from "pg";
+import semver from "semver";
+import { catalogPackageError } from "../catalog/plugin-import.js";
+import { PluginPackageError, readPluginPackage } from "../catalog/plugin-package.js";
+import { pgConnectOptions } from "../db/pool.js";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { writeSnapshot } from "./approvals.js";
+import { ExtensionPackageError, permissionSetOfPackage, readExtensionPackage } from "./package.js";
+import { diffPermissions } from "./permission-set.js";
+/**
+ * The bootstrap step (package ecosystem spec §7): installs the plugins pinned by the bootstrap
+ * manifest (`packages/kernel/bootstrap.json`) from the tgz files baked into the image. It replaced
+ * the builtin extensions.
+ *
+ * - Every file (`<dir>/<name>-<version>.tgz`) is checked against the entry's sha512 before anything
+ *   is read or written; a missing file is `bootstrap.missing_file`, a mismatch
+ *   `bootstrap.integrity_mismatch` (both name the plugin), and then nothing is written. It never
+ *   touches the network.
+ * - The whole run holds the session advisory lock `capybara.bootstrap` on a connection of its own
+ *   (taken with `pg_try_advisory_lock` in a backoff loop that observes the signal, and closed
+ *   afterwards, so the lock never outlives the run): when several replicas start together only one
+ *   runs it; the others wait, then find it done. "Done" is a `bootstrap_runs` row for the
+ *   manifest's sha256 (written with the audit `bootstrap.completed` only when every entry
+ *   succeeded; otherwise the next start runs it again, which is idempotent). A lock connection
+ *   that drops mid-run is not detected (its errors are swallowed) and the run goes on without the
+ *   lock, so a second replica could run concurrently: accepted, since a concurrent import or
+ *   install degrades to `catalog.version_exists` and a deploy from the package store.
+ * - Only entries new to the manifest are installed (Ruling 5): an optional entry that the last
+ *   completed run already handled and that is not installed now (an enterprise admin uninstalled
+ *   it) stays uninstalled -> `kept`. A required entry is always installed.
+ * - Per entry, by the installed state of its extension:
+ *   - not installed (and new, or required): imported into the catalog (source `bootstrap`, ref
+ *     `bootstrap:<name>@<version>`, like a marketplace import), installed, approved (snapshot
+ *     source `bootstrap`, audited `extension.permissions_approved` with `source: "bootstrap"`)
+ *     and enabled -> `installed`;
+ *   - installed from `bootstrap` at a lower version: upgraded the same way (core's release vouched
+ *     for the version, so new permissions are pre-approved and audited), keeping the desired state
+ *     an enterprise admin chose (a disabled optional plugin stays disabled) -> `upgraded`;
+ *   - installed at a higher version, or from another source (an enterprise admin upgraded it), or
+ *     the name is config-declared (`declared`: config wins, no install record is created):
+ *     untouched, never downgraded -> `kept`;
+ *   - a declarative plugin (no extension): imported into the catalog only -> `imported` (`kept`
+ *     when that version is already there, or when the entry is not new).
+ *   Every extension entry gets `extension_installs.required` from the manifest, and a required one
+ *   is enabled on the deployment.
+ * - Package bytes are content-addressed: when the very same tgz was ingested before with another
+ *   source (e.g. imported from a marketplace), its `extension_packages` row keeps that source and
+ *   so does the install record, which is then not a bootstrap install and never upgraded by a
+ *   later manifest (`kept`, like a plugin the admin installed).
+ * - An install record still `required` whose entry left the manifest is not uninstalled; it only
+ *   loses `required` -> `required_cleared`.
+ * A failed entry does not stop the others; the run then throws {@link BootstrapFailedError} naming
+ * them. The packages are kept in PG (`blob_store = 'pg'`), so installing an extension never needs
+ * the object store (object-store-s3 is itself a bootstrap plugin); a declarative plugin's catalog
+ * files do.
+ */
+/** The bootstrap manifest that ships with the kernel package. */
+export const BOOTSTRAP_MANIFEST_FILE = fileURLToPath(new URL("../../bootstrap.json", import.meta.url));
+/** Some entries failed (the others were done); the run is not recorded as done. */
+export class BootstrapFailedError extends Error {
+    failures;
+    results;
+    /**
+     * @param results what the entries that did not fail did (pass them as `carry` to a later run in
+     * the same start, so its record keeps `installed` instead of `kept`).
+     */
+    constructor(failures, results = []) {
+        super(`bootstrap failed for ${failures.map((f) => `${f.name}${f.required ? " (required)" : ""}: ${f.message}`).join("; ")}`);
+        this.failures = failures;
+        this.results = results;
+        this.name = "BootstrapFailedError";
+    }
+    /** A required entry failed: the kernel must not serve without it. */
+    get requiredFailed() {
+        return this.failures.some((f) => f.required);
+    }
+}
+/** sha256 (hex) of a manifest: of its JSON text as parsed (key order kept). */
+export function bootstrapManifestSha256(manifest) {
+    return createHash("sha256").update(JSON.stringify(manifest)).digest("hex");
+}
+/** Reads and parses a bootstrap manifest file; an invalid one throws with its problems. */
+export async function readBootstrapManifest(file = BOOTSTRAP_MANIFEST_FILE) {
+    const parsed = parseBootstrapManifest(JSON.parse(await readFile(file, "utf8")));
+    if ("errors" in parsed) {
+        throw new Error(`invalid bootstrap manifest ${file}: ${parsed.errors.join("; ")}`);
+    }
+    return parsed;
+}
+const integrityOf = (bytes) => `sha512-${createHash("sha512").update(bytes).digest("base64")}`;
+/** The advisory lock around a whole run. */
+const LOCK_KEY = "capybara.bootstrap";
+export class BootstrapService {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    /** Whether the bootstrap step completed for the manifest with this sha256. */
+    async isDone(manifestSha256) {
+        const row = await this.d.db
+            .selectFrom("bootstrap_runs")
+            .select("manifest_sha256")
+            .where("manifest_sha256", "=", manifestSha256)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+    /**
+     * Runs the bootstrap step (see the file header); when it is already done for this manifest
+     * (also when another replica finished it while this one waited for the lock) returns the
+     * recorded result without doing anything. `carry`: the results of an earlier, failed run in the
+     * same start ({@link BootstrapFailedError.results}); an entry it installed, upgraded or imported
+     * keeps that action instead of `kept` in this run's record.
+     */
+    async run(o) {
+        const manifestSha256 = bootstrapManifestSha256(o.manifest);
+        const files = await this.verifyFiles(o.manifest, o.dir);
+        return this.locked(o.signal, async () => {
+            const done = await this.d.db
+                .selectFrom("bootstrap_runs")
+                .select("results")
+                .where("manifest_sha256", "=", manifestSha256)
+                .executeTakeFirst();
+            if (done) {
+                return { manifestSha256, results: done.results };
+            }
+            const handled = await this.lastRunNames();
+            const results = [];
+            const failures = [];
+            for (const e of o.manifest.plugins) {
+                o.signal?.throwIfAborted();
+                try {
+                    const r = await this.entry(e, files.get(e.name), handled);
+                    results.push(carried(r, o.carry));
+                }
+                catch (err) {
+                    this.d.log.error("bootstrap: a plugin could not be installed", {
+                        plugin: e.name,
+                        version: e.version,
+                        required: e.required,
+                        err,
+                    });
+                    failures.push({
+                        name: e.name,
+                        required: e.required,
+                        code: err instanceof ApiError ? err.code : "internal",
+                        message: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            results.push(...(await this.clearRemoved(o.manifest)));
+            if (failures.length > 0)
+                throw new BootstrapFailedError(failures, results);
+            await this.d.db.transaction().execute(async (trx) => {
+                await trx
+                    .insertInto("bootstrap_runs")
+                    .values({
+                    manifest_sha256: manifestSha256,
+                    completed_at: sql `now()`,
+                    results: JSON.stringify(results),
+                })
+                    .execute();
+                await audit(trx, {
+                    action: "bootstrap.completed",
+                    target: manifestSha256,
+                    detail: { manifestSha256, results },
+                });
+            });
+            this.d.log.info("bootstrap completed", { manifestSha256, results });
+            return { manifestSha256, results };
+        });
+    }
+    /**
+     * Runs `fn` holding the session advisory lock on a connection of its own: `pg_try_advisory_lock`
+     * retried with a backoff (100 ms doubling to 1 s) that stops when `signal` aborts. The connection
+     * is closed afterwards in every case, which releases the lock even when the unlock failed.
+     */
+    async locked(signal, fn) {
+        const client = new pg.Client({
+            connectionString: this.d.dbUrl,
+            ...pgConnectOptions({ connectTimeoutMs: this.d.connectTimeoutMs }),
+        });
+        client.on("error", () => { });
+        try {
+            await client.connect();
+            for (let wait = 100;; wait = Math.min(wait * 2, 1_000)) {
+                signal?.throwIfAborted();
+                const r = await client.query("SELECT pg_try_advisory_lock(hashtext($1)) AS ok", [LOCK_KEY]);
+                if (r.rows[0]?.ok === true)
+                    break;
+                await sleep(wait, signal);
+            }
+            try {
+                return await fn();
+            }
+            finally {
+                await client
+                    .query("SELECT pg_advisory_unlock(hashtext($1))", [LOCK_KEY])
+                    .catch((err) => this.d.log.warn("bootstrap: cannot release the advisory lock; closing its connection", {
+                    err,
+                }));
+            }
+        }
+        finally {
+            await client.end().catch(() => { });
+        }
+    }
+    /** The entry names the last completed run handled (undefined before any run completed). */
+    async lastRunNames() {
+        const row = await this.d.db
+            .selectFrom("bootstrap_runs")
+            .select("results")
+            .orderBy("completed_at", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        if (!row)
+            return undefined;
+        return new Set(row.results
+            .filter((r) => r.action !== "required_cleared")
+            .map((r) => r.name));
+    }
+    /** Reads every entry's file and checks its sha512 (before the lock: nothing is written yet). */
+    async verifyFiles(manifest, dir) {
+        const out = new Map();
+        for (const e of manifest.plugins) {
+            const file = join(dir, bootstrapFileName(e));
+            let bytes;
+            try {
+                bytes = new Uint8Array(await readFile(file));
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    throw err;
+                throw new ApiError("bootstrap.missing_file", `Bootstrap plugin ${e.name} ${e.version}: ${file} is missing; the image must carry every package bootstrap.json pins`);
+            }
+            const actual = integrityOf(bytes);
+            if (actual !== e.integrity) {
+                throw new ApiError("bootstrap.integrity_mismatch", `Bootstrap plugin ${e.name} ${e.version}: ${file} does not match its pinned sha512 (expected ${e.integrity.slice(0, 19)}…, got ${actual.slice(0, 19)}…); refusing to install anything`);
+            }
+            out.set(e.name, bytes);
+        }
+        return out;
+    }
+    async entry(e, bytes, handled) {
+        const pkg = await readPluginPackage(bytes, {
+            maxBytes: this.d.config().packages.maxBytes,
+            hostSdkVersion: SDK_VERSION,
+        }).catch((err) => {
+            throw err instanceof PluginPackageError ? catalogPackageError(err) : err;
+        });
+        if (pkg.manifest.name !== e.name || pkg.manifest.version !== e.version) {
+            throw new ApiError("catalog.invalid_manifest", `The package for bootstrap entry ${e.name} ${e.version} contains plugin ${pkg.manifest.name} ${pkg.manifest.version}`);
+        }
+        const ref = `bootstrap:${e.name}@${e.version}`;
+        // Not new to the manifest: an optional entry left out on purpose stays out (Ruling 5)
+        const isNew = handled === undefined || !handled.has(e.name);
+        if (!pkg.manifest.extension) {
+            if (!isNew)
+                return { name: e.name, action: "kept", version: e.version };
+            const imported = await this.importOnly(e, bytes, ref);
+            return { name: e.name, action: imported ? "imported" : "kept", version: e.version };
+        }
+        if (this.d.declared?.().has(e.name)) {
+            this.d.log.warn("bootstrap: the plugin is declared in the extensions config list; the config plugin is used", { plugin: e.name });
+            return { name: e.name, action: "kept", version: e.version };
+        }
+        const row = await this.d.db
+            .selectFrom("extension_installs")
+            .select(["version", "source", "required", "desired_state", "sha256"])
+            .where("name", "=", e.name)
+            .executeTakeFirst();
+        if (!row && !isNew && !e.required) {
+            this.d.log.info("bootstrap: an optional plugin that is not installed stays uninstalled", {
+                plugin: e.name,
+            });
+            return { name: e.name, action: "kept", version: e.version };
+        }
+        let result;
+        if (!row) {
+            await this.deploy(e, bytes, ref, true);
+            result = { name: e.name, action: "installed", version: e.version };
+        }
+        else if (row.source === "bootstrap" && isLower(row.version, e.version)) {
+            // The desired state the admin chose is kept; a required plugin is enabled below anyway
+            await this.deploy(e, bytes, ref, row.desired_state === "enabled");
+            result = { name: e.name, action: "upgraded", version: e.version };
+        }
+        else {
+            if (row.source === "bootstrap" &&
+                row.version === e.version &&
+                row.sha256 !== createHash("sha256").update(bytes).digest("hex")) {
+                // The pin changed bytes without a version bump (an image built from main between
+                // releases): the installed package stays, so say so instead of keeping it silently
+                this.d.log.warn("bootstrap: the image's package differs from the installed one at the same version; the installed package is kept (bump the version to roll it out)", { plugin: e.name, version: e.version });
+            }
+            result = { name: e.name, action: "kept", version: row.version };
+        }
+        if (row?.required !== e.required) {
+            await this.d.db
+                .updateTable("extension_installs")
+                .set({ required: e.required })
+                .where("name", "=", e.name)
+                .execute();
+        }
+        // A required install must run on the deployment (an org cannot use it otherwise)
+        if (e.required && row?.desired_state === "disabled") {
+            await this.d.ops.enable(e.name, null);
+        }
+        return result;
+    }
+    /** A declarative plugin: catalog only. Returns false when that version is already imported. */
+    async importOnly(e, bytes, ref) {
+        try {
+            const { stagingId, review } = await this.d.imports.prepare(null, bytes, {
+                kind: "bootstrap",
+                ref,
+                integrity: e.integrity,
+            });
+            await this.d.imports.confirm(null, stagingId, {
+                reviewHash: review.reviewHash,
+                deployExtension: false,
+            });
+            return true;
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.code === "catalog.version_exists")
+                return false;
+            throw err;
+        }
+    }
+    /**
+     * Imports, approves, installs and enables (one review, confirmed with `deployExtension`). When
+     * the catalog already has this version (an earlier run stopped after importing, or the same
+     * package came from a marketplace), the extension is deployed from the package store instead.
+     */
+    async deploy(e, bytes, ref, enable) {
+        let staged;
+        try {
+            staged = await this.d.imports.prepare(null, bytes, {
+                kind: "bootstrap",
+                ref,
+                integrity: e.integrity,
+            });
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.code === "catalog.version_exists") {
+                await this.deployFromStore(e, bytes, ref, enable);
+                return;
+            }
+            throw err;
+        }
+        const r = await this.d.imports.confirm(null, staged.stagingId, {
+            reviewHash: staged.review.reviewHash,
+            deployExtension: true,
+            enable,
+        });
+        if (r.deploy?.result === "failed") {
+            throw new ApiError((r.deploy.code ?? "internal"), r.deploy.message ?? `installing extension ${e.name} failed`);
+        }
+    }
+    /** The extension of a catalog version already imported: ingest, approve, install (, enable). */
+    async deployFromStore(e, bytes, ref, enable) {
+        const review = await this.d.installs.ingest(null, bytes, { source: "bootstrap", ref }, { store: "pg" });
+        let set;
+        try {
+            set = permissionSetOfPackage(await readExtensionPackage(bytes, {
+                maxBytes: this.d.config().packages.maxBytes,
+                hostSdkVersion: SDK_VERSION,
+            }));
+        }
+        catch (err) {
+            throw err instanceof ExtensionPackageError ? catalogPackageError(err) : err;
+        }
+        await this.d.db.transaction().execute(async (trx) => {
+            await sql `SELECT pg_advisory_xact_lock(hashtext(${`capybara.plugin-approve:${e.name}`}))`.execute(trx);
+            const snap = await trx
+                .selectFrom("extension_permission_snapshots")
+                .select("permissions")
+                .where("plugin", "=", e.name)
+                .forUpdate()
+                .executeTakeFirst();
+            const { added, removed } = diffPermissions(snap?.permissions, set);
+            await writeSnapshot(trx, e.name, e.version, set, {
+                source: "bootstrap",
+                audit: { added, removed, sha256: review.sha256 },
+            });
+        });
+        const item = await this.d.db
+            .selectFrom("catalog_items")
+            .select("id")
+            .where("name", "=", e.name)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        await this.d.ops.install(e.name, review.sha256, null, undefined, item ? { catalogItemId: item.id } : {});
+        if (enable)
+            await this.d.ops.enable(e.name, null);
+    }
+    /** Install records still `required` whose entry left the manifest lose `required`. */
+    async clearRemoved(manifest) {
+        const names = manifest.plugins.map((p) => p.name);
+        let q = this.d.db
+            .updateTable("extension_installs")
+            .set({ required: false })
+            .where("required", "=", true);
+        if (names.length > 0)
+            q = q.where("name", "not in", names);
+        const rows = await q.returning(["name", "version"]).execute();
+        return rows.map((r) => ({ name: r.name, action: "required_cleared", version: r.version }));
+    }
+}
+/** A `kept` result whose entry an earlier pass of the same start installed / upgraded / imported. */
+function carried(r, carry) {
+    if (r.action !== "kept")
+        return r;
+    const before = carry?.find((c) => c.name === r.name && c.version === r.version);
+    return before !== undefined && before.action !== "kept" && before.action !== "required_cleared"
+        ? before
+        : r;
+}
+/** Resolves after `ms`; rejects with the abort reason when `signal` aborts first. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** `installed` is below `pinned` (a version that is not semver is never upgraded). */
+const isLower = (installed, pinned) => semver.valid(installed) !== null && semver.valid(pinned) !== null && semver.lt(installed, pinned);

package/dist/extensions/cli.d.ts

@@ -0,0 +1,61 @@
+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 { 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;
+    /** 配置声明的插件（导入、按依赖排序，不 setup）。 */
+    inspected: InspectedExtension[];
+    /**
+     * 配置声明插件的部署配置问题（启动配置与 PG 里保存的合并后按 schema 校验；只有路径与说明，不含值）：
+     * 有问题的插件内核不加载（待配置）。没有问题的不在这里。
+     */
+    configIssues: ReadonlyMap<string, ConfigIssue[]>;
+    /** The valid merged deployment config (secrets decrypted) of the declared extensions that have one. */
+    deploymentConfigs: ReadonlyMap<string, unknown>;
+    /**
+     * The deployment config of any extension (an install record too) validated against `schema`: the
+     * startup config completed by the fields stored in PG, as the kernel merges it. No schema = `{}`.
+     */
+    deploymentConfigOf(name: string, schema: z.ZodTypeAny | undefined): Promise<{
+        ok: true;
+        value: unknown;
+    } | {
+        ok: false;
+        issues: ConfigIssue[];
+    }>;
+    installs: ExtensionInstalls;
+    admin: ExtensionAdmin;
+    ops: ExtensionAdminOps;
+    approvals: ExtensionApprovals;
+    /** CLI 本次刚导入的包字节（降级判断等读包时优先用它：包可能存在 CLI 读不到的对象存储里）。 */
+    remember(sha256: string, bytes: Uint8Array): void;
+    /** 安装记录包的权限集合（与后台审阅相同）；包在对象存储里时 CLI 读不到，抛错。 */
+    packageSet(sha256: string): Promise<PermissionSet>;
+    /** The bytes of a stored package (this process's imports first, then the package store in PG). */
+    readPackage(sha256: string): Promise<Uint8Array>;
+    /** 写完 PG 后经 Redis 发布 `kernel.plugins.changed`（C18）；失败只告警，返回是否发布成功。 */
+    publishChanged(plugin: string): Promise<boolean>;
+    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).
+ */
+export declare function openExtensionCli(config: KernelConfig, log: KernelLogger, opts?: {
+    resolveFrom?: string;
+}): Promise<ExtensionCli>;

package/dist/extensions/cli.js

@@ -0,0 +1,165 @@
+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 { 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 { ExtensionHost } from "./host.js";
+import { ExtensionInstalls } from "./installs.js";
+import { PLUGINS_CHANGED_TOPIC } from "./lifecycle.js";
+import { toIssues } from "./org-config.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).
+ */
+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 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]));
+    // 部署配置 = 启动配置补上后台保存在 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, {
+            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) };
+    };
+    const configIssues = new Map();
+    const deploymentConfigs = new Map();
+    try {
+        for (const p of inspected) {
+            const schema = p.manifest.config?.deployment;
+            if (!schema)
+                continue;
+            const r = await deploymentConfigOf(p.manifest.name, schema);
+            if (r.ok)
+                deploymentConfigs.set(p.manifest.name, r.value);
+            else
+                configIssues.set(p.manifest.name, r.issues);
+        }
+    }
+    catch (e) {
+        await raw.destroy().catch(() => { });
+        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,
+    });
+    return {
+        config,
+        db,
+        inspected,
+        configIssues,
+        deploymentConfigs,
+        deploymentConfigOf,
+        installs,
+        admin,
+        ops,
+        approvals: new ExtensionApprovals(db),
+        remember: (sha256, bytes) => {
+            local.set(sha256, bytes);
+        },
+        readPackage: (sha256) => blobs.get(sha256),
+        async packageSet(sha256) {
+            // a stored package in the pre-0.1.0 format -> extension.legacy_format
+            const pkg = await readExtensionPackage(await blobs.get(sha256), {
+                maxBytes: config.packages.maxBytes,
+                hostSdkVersion: SDK_VERSION,
+            }).catch((e) => {
+                throw e instanceof ExtensionPackageError ? extensionPackageApiError(e) : e;
+            });
+            return permissionSetOfPackage(pkg);
+        },
+        async publishChanged(plugin) {
+            try {
+                await publisher.publish(PLUGINS_CHANGED_TOPIC, { plugin });
+                return true;
+            }
+            catch (err) {
+                log.warn("cannot publish plugins.changed; running replicas pick the change up on their next periodic reconcile", { plugin, err });
+                return false;
+            }
+        },
+        async close() {
+            redis?.disconnect();
+            await raw.destroy().catch(() => { });
+        },
+    };
+}

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

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export type JsonSchema = Record<string, unknown>;
+/**
+ * 把插件配置 schema 转成 JSON Schema（供界面渲染表单）：
+ * - `secret()` 字段带 `"x-secret": true`（去掉 zod 附带的 `secret` 元数据键）；
+ * - 无法表达的类型为 `{ "x-unsupported": true }`，不抛错；
+ * - 以输入侧形态输出（含 default），不带 `$schema`。
+ */
+export declare function configToJsonSchema(schema: z.ZodType): JsonSchema;