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

package/dist/extensions/migrate-lock.d.ts

@@ -0,0 +1,51 @@
+import { type Transaction } from "kysely";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+/** 插件迁移完成（kernel bus 主题，频道 `cap:kernel:plugins.migrated`，payload `{ plugin, sha256 }`）。 */
+export declare const PLUGINS_MIGRATED_TOPIC = "plugins.migrated";
+/** 插件迁移咨询锁的键前缀（`hashtext(<前缀><插件名>)`）。 */
+export declare const MIGRATE_LOCK_PREFIX = "capybara.plugin-migrate:";
+/** {@link ensureMigrated} 的依赖。 */
+export interface MigrateLockDeps {
+    db: KernelDb;
+    /** 迁移用独立连接（不走连接池）。 */
+    dbUrl: string;
+    connectTimeoutMs?: number | undefined;
+    /** 发布 `plugins.migrated`（kernel bus）。 */
+    bus: {
+        publish(topic: string, payload: unknown): Promise<void>;
+    };
+    log?: {
+        warn(msg: string, fields?: Record<string, unknown>): void;
+    };
+    /** 中止进行中的迁移（宿主关闭）。 */
+    signal?: AbortSignal | undefined;
+    /**
+     * 迁移的总时限（毫秒，`extensionHost.migrationTimeoutSeconds`）：到时终止迁移会话并抛错（调用方记 migration_failed），
+     * 咨询锁随会话结束释放；迁移会话另设同值的 `statement_timeout` 与不超过 {@link MIGRATION_LOCK_TIMEOUT_MS} 的
+     * `lock_timeout`。不给不限时。
+     */
+    timeoutMs?: number | undefined;
+}
+/** 插件迁移等锁（表锁、按 schema 的咨询锁）的上限：排在它后面的业务查询不被长时间堵住。 */
+export declare const MIGRATION_LOCK_TIMEOUT_MS = 30000;
+/**
+ * 某插件某个包的迁移由一个副本持锁执行（C16，F-P）：
+ * 1. 独立 `pg.Client`（不走连接池）上 `pg_try_advisory_lock(hashtext('capybara.plugin-migrate:' || name))`，
+ *    拿不到 → `busy`（别的副本正在迁移；调用方记 `pending_migration`，等 `plugins.migrated` 或下一个周期）；
+ * 2. 拿到后复核安装记录：已换成别的包 → `busy`（不迁移过期目标，下一轮按新目标处理）；`migrated_sha` 已是它 → `migrated`；
+ * 3. 执行迁移（迁移器另开会话，持按 schema 的锁；只做扩展，见 .agents/skills/writing-migrations；`timeoutMs` 限时），
+ *    写 `migrated_sha`；
+ * 4. 结束会话（锁随之释放，进程崩溃时同样释放），发布 `plugins.migrated {plugin, sha256}`（失败只告警）。
+ * `dir` 为迁移目录的绝对路径（只取审阅过的 `capybara.migrations`）；没有迁移时直接记下 `migrated_sha`。
+ * 迁移出错时抛出（不写 `migrated_sha`）。
+ */
+export declare function ensureMigrated(d: MigrateLockDeps, name: string, sha256: string, dir: string | undefined): Promise<"migrated" | "busy">;
+/**
+ * 目标包里尚未执行过的迁移文件（降级判断，C16：降级仅当目标版本的迁移文件都已执行过）：
+ * 按插件 schema 的 `_migrations` 表比对文件名与 checksum（与迁移器相同的 sha256）；改过内容的也算未执行。
+ * 插件从没迁移过时返回全部文件。
+ */
+export declare function unrunMigrations(db: KernelDb | Transaction<KernelDatabase>, name: string, files: {
+    file: string;
+    sql: string;
+}[]): Promise<string[]>;

package/dist/extensions/migrate-lock.js

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import { sql } from "kysely";
+import pg from "pg";
+import { pluginSchemaName } from "../ctx/create-ctx.js";
+import { migrate } from "../db/migrator.js";
+import { pgConnectOptions } from "../db/pool.js";
+/** 插件迁移完成（kernel bus 主题，频道 `cap:kernel:plugins.migrated`，payload `{ plugin, sha256 }`）。 */
+export const PLUGINS_MIGRATED_TOPIC = "plugins.migrated";
+/** 插件迁移咨询锁的键前缀（`hashtext(<前缀><插件名>)`）。 */
+export const MIGRATE_LOCK_PREFIX = "capybara.plugin-migrate:";
+/** 插件迁移等锁（表锁、按 schema 的咨询锁）的上限：排在它后面的业务查询不被长时间堵住。 */
+export const MIGRATION_LOCK_TIMEOUT_MS = 30_000;
+/**
+ * 某插件某个包的迁移由一个副本持锁执行（C16，F-P）：
+ * 1. 独立 `pg.Client`（不走连接池）上 `pg_try_advisory_lock(hashtext('capybara.plugin-migrate:' || name))`，
+ *    拿不到 → `busy`（别的副本正在迁移；调用方记 `pending_migration`，等 `plugins.migrated` 或下一个周期）；
+ * 2. 拿到后复核安装记录：已换成别的包 → `busy`（不迁移过期目标，下一轮按新目标处理）；`migrated_sha` 已是它 → `migrated`；
+ * 3. 执行迁移（迁移器另开会话，持按 schema 的锁；只做扩展，见 .agents/skills/writing-migrations；`timeoutMs` 限时），
+ *    写 `migrated_sha`；
+ * 4. 结束会话（锁随之释放，进程崩溃时同样释放），发布 `plugins.migrated {plugin, sha256}`（失败只告警）。
+ * `dir` 为迁移目录的绝对路径（只取审阅过的 `capybara.migrations`）；没有迁移时直接记下 `migrated_sha`。
+ * 迁移出错时抛出（不写 `migrated_sha`）。
+ */
+export async function ensureMigrated(d, name, sha256, dir) {
+    const client = new pg.Client({
+        connectionString: d.dbUrl,
+        ...pgConnectOptions({ connectTimeoutMs: d.connectTimeoutMs }),
+    });
+    client.on("error", () => { });
+    let ran = false;
+    try {
+        await client.connect();
+        const lock = await client.query("SELECT pg_try_advisory_lock(hashtext($1)) AS ok", [`${MIGRATE_LOCK_PREFIX}${name}`]);
+        if (lock.rows[0]?.ok !== true)
+            return "busy";
+        const row = (await client.query("SELECT sha256, migrated_sha FROM capybara.extension_installs WHERE name = $1", [name])).rows[0];
+        if (row?.sha256 !== sha256)
+            return "busy";
+        if (row.migrated_sha === sha256)
+            return "migrated";
+        if (dir !== undefined) {
+            const timeout = d.timeoutMs === undefined ? undefined : AbortSignal.timeout(d.timeoutMs);
+            const signals = [d.signal, timeout].filter((x) => x !== undefined);
+            try {
+                await migrate(d.dbUrl, { schema: pluginSchemaName(name), dir }, {
+                    connectTimeoutMs: d.connectTimeoutMs,
+                    signal: signals.length > 0 ? AbortSignal.any(signals) : undefined,
+                    ...(d.timeoutMs !== undefined && {
+                        statementTimeoutMs: d.timeoutMs,
+                        lockTimeoutMs: Math.min(d.timeoutMs, MIGRATION_LOCK_TIMEOUT_MS),
+                    }),
+                });
+            }
+            catch (e) {
+                if (timeout?.aborted && !d.signal?.aborted) {
+                    throw new Error(`plugin ${name}: migrations did not finish within ${Math.round(d.timeoutMs / 1000)}s (extensionHost.migrationTimeoutSeconds); the migration session was terminated`, { cause: e });
+                }
+                throw e;
+            }
+        }
+        await client.query("UPDATE capybara.extension_installs SET migrated_sha = $2 WHERE name = $1 AND sha256 = $2", [name, sha256]);
+        ran = true;
+    }
+    finally {
+        // 会话结束即释放咨询锁（不把持锁连接还给任何池）
+        await client.end().catch(() => { });
+    }
+    if (ran) {
+        try {
+            await d.bus.publish(PLUGINS_MIGRATED_TOPIC, { plugin: name, sha256 });
+        }
+        catch (err) {
+            d.log?.warn("cannot publish plugins.migrated; other replicas pick it up on the next reconcile", {
+                plugin: name,
+                err,
+            });
+        }
+    }
+    return "migrated";
+}
+/**
+ * 目标包里尚未执行过的迁移文件（降级判断，C16：降级仅当目标版本的迁移文件都已执行过）：
+ * 按插件 schema 的 `_migrations` 表比对文件名与 checksum（与迁移器相同的 sha256）；改过内容的也算未执行。
+ * 插件从没迁移过时返回全部文件。
+ */
+export async function unrunMigrations(db, name, files) {
+    if (files.length === 0)
+        return [];
+    const schema = pluginSchemaName(name);
+    const exists = await sql `SELECT to_regclass(${`"${schema}"._migrations`})::text AS t`.execute(db);
+    const done = new Map();
+    if (exists.rows[0]?.t) {
+        const rows = await sql `SELECT name, checksum FROM ${sql.table(`${schema}._migrations`)}`.execute(db);
+        for (const r of rows.rows)
+            done.set(r.name, r.checksum);
+    }
+    return files
+        .filter((f) => done.get(f.file) !== createHash("sha256").update(f.sql).digest("hex"))
+        .map((f) => f.file);
+}

package/dist/extensions/org-config.controller.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { OrgExtensionConfigs, OrgExtensionView } from "./org-config.js";
+declare const PutBody: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    force: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/**
+ * Org-level extension enablement and config (`/api/v1/orgs/:orgId/extensions`); responses echo only
+ * non-secret config and whether each secret is set.
+ */
+export declare class OrgExtensionConfigsController {
+    private readonly configs;
+    constructor(configs: OrgExtensionConfigs);
+    list(org: OrgContext): Promise<{
+        extensions: OrgExtensionView[];
+    }>;
+    put(principal: Principal, org: OrgContext, extension: string, body: z.infer<typeof PutBody>): Promise<{
+        extension: OrgExtensionView;
+    }>;
+}
+export {};

package/dist/extensions/org-config.controller.js

@@ -0,0 +1,59 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Body, Controller, Get, Inject, Param, Put } from "@nestjs/common";
+import { z } from "zod";
+import { ORG_EXTENSION_CONFIGS } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+const PutBody = z
+    .object({
+    enabled: z.boolean().optional(),
+    config: z.record(z.string(), z.unknown()).optional(),
+    force: z.boolean().optional(),
+})
+    .strict();
+/**
+ * Org-level extension enablement and config (`/api/v1/orgs/:orgId/extensions`); responses echo only
+ * non-secret config and whether each secret is set.
+ */
+let OrgExtensionConfigsController = class OrgExtensionConfigsController {
+    configs;
+    constructor(configs) {
+        this.configs = configs;
+    }
+    async list(org) {
+        return { extensions: await this.configs.list(org.orgId) };
+    }
+    async put(principal, org, extension, body) {
+        const p = requireUser(principal);
+        return {
+            extension: await this.configs.put(org.orgId, extension, body, p.account.id, patTokenId(p)),
+        };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentOrg())
+], OrgExtensionConfigsController.prototype, "list", null);
+__decorate([
+    Put(":extension"),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("extension")),
+    __param(3, Body(new ZodPipe(PutBody)))
+], OrgExtensionConfigsController.prototype, "put", null);
+OrgExtensionConfigsController = __decorate([
+    Controller("api/v1/orgs/:orgId/extensions"),
+    __param(0, Inject(ORG_EXTENSION_CONFIGS))
+], OrgExtensionConfigsController);
+export { OrgExtensionConfigsController };

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

@@ -0,0 +1,169 @@
+import type { Transaction } from "kysely";
+import type { z } from "zod";
+import { type Keyring } from "../ctx/secrets.js";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import { type JsonSchema } from "./config-json-schema.js";
+import type { ExtensionHost } from "./host.js";
+import { type PermissionGroup } from "./permission-view.js";
+type Trx = Transaction<KernelDatabase>;
+/** 组织视角下一个已加载插件的状态；`config` 永远不含密钥字段，密钥只回显「是否已设置」。 */
+export interface OrgExtensionView {
+    plugin: string;
+    version: string;
+    enabled: boolean;
+    /** 插件是否声明了 `config.org`。 */
+    configurable: boolean;
+    /** 已存的非密钥配置；未配置或不可配置时为 null。 */
+    config: Record<string, unknown> | null;
+    secrets: {
+        path: string;
+        set: boolean;
+    }[];
+    /** 插件要用的权限，按类别分组并标出敏感项（密钥、公开路由、工具、hook）。 */
+    permissions: PermissionGroup[];
+    /** `config.org` 的 JSON Schema（密钥字段带 `x-secret`）；不可配置时为 null。 */
+    orgConfigSchema: JsonSchema | null;
+    /**
+     * 插件此刻在部署上可用（已加载）。false：已安装但在部署上停用（或尚未加载），组织页显示「不可用」，
+     * 组织的启用开关保留不变（不能修改），其余字段为空。
+     */
+    available: boolean;
+    /**
+     * A required bootstrap plugin: enabled in every org (`enabled` is always true) and cannot be
+     * disabled here (`extension.required`); its org config, when it has one, can still be set.
+     */
+    required: boolean;
+}
+/** `put` 的输入：`config` 中的密钥字段缺省 = 保留原值、`null` = 清除、其他值 = 新值。 */
+export interface OrgExtensionInput {
+    enabled?: boolean | undefined;
+    config?: Record<string, unknown> | undefined;
+    /** Disable even when enabled dependents remain (default `extension.has_dependents`). */
+    force?: boolean | undefined;
+}
+/** `put` 的内部选项（不来自 HTTP）。 */
+export interface OrgExtensionPutOptions {
+    /**
+     * Enable through this enterprise catalog item (the extension's own item, or an app item: plugins
+     * in an app follow the app item's policy, C22). When omitted, judged by every source item in
+     * `extension_catalog_sources` (the strictest wins); an extension not installed through the catalog
+     * is not bound by catalog policy.
+     */
+    viaItem?: string;
+    /**
+     * With `viaItem`: the item whose policy approves the enabling (a dependency's extension: the
+     * plugin the org is installing; default `viaItem`).
+     */
+    approvedBy?: string;
+    /**
+     * 应用安装用：在组织行锁内读到该插件已启用时什么都不写（不改配置、不审计），并把 `skipped` 置为 true——
+     * 「之前就启用」与「本次启用」在锁内判定，不会与并发的启用竞争。
+     */
+    ifDisabled?: {
+        skipped: boolean;
+    };
+    /**
+     * 在同一个事务（组织行锁内）里最后执行，`skipped` 同 {@link ifDisabled}：应用安装在这里记组件，启用与记录之间
+     * 插不进并发的卸载。
+     */
+    inTransaction?: (t: Trx, skipped: boolean) => Promise<void>;
+}
+/** 校验失败的单条原因：只含路径与按 issue 类型生成的说明，不回显字段值。 */
+export interface ConfigIssue {
+    path: string;
+    message: string;
+}
+export declare function toIssues(error: z.ZodError): ConfigIssue[];
+/**
+ * Org-level extension config: enablement and the `config.org` config stored per org.
+ * The non-secret part is stored in `capybara.extension_org_configs.config`; each secret field is
+ * encrypted separately in `capybara.secrets` (namespace `kernel`, key `plugin-config:<plugin>:<path>`),
+ * written in the same transaction as the config row.
+ * No in-process state: every call reads PG, safe with multiple replicas.
+ */
+export declare class OrgExtensionConfigs {
+    private readonly db;
+    private readonly keyring;
+    private readonly host;
+    private readonly hooks;
+    constructor(db: KernelDb, keyring: Keyring, host: ExtensionHost, hooks?: {
+        /**
+         * 经手（写入或解密读出）的密钥值，含嵌套字段；只在事务提交后调用（回滚的写入不上报）。
+         * 内核传 `log.addOrgSecrets` 使其在日志中打码。
+         */
+        onSecrets?: (values: string[]) => void;
+        /**
+         * 写入提交之后调用（`enabled` 为写入后的启用状态）。内核传：停用时给该组织该插件的渠道连接广播
+         * `channel.changed`，持有长连接的副本立即断开。
+         */
+        afterPut?: (orgId: string, plugin: string, enabled: boolean) => Promise<void>;
+        /** 部署上的安装记录（任何期望状态）：没加载的列为不可用（T14）。 */
+        installed?: () => Promise<{
+            name: string;
+            version: string;
+        }[]>;
+        /** 仅供测试：在读完配置行之后、读密钥之前插入确定性的交错点。 */
+        afterConfigRowRead?: () => Promise<void>;
+    });
+    /** 把一份组织配置里的密钥值交给 onSecrets（无回调或无密钥时无操作）；调用方须在事务提交后调用。 */
+    private reportSecrets;
+    /** `REPEATABLE READ` 只读事务：配置行与密钥来自同一个快照，不会读到跨两次提交的混合状态。 */
+    private snapshot;
+    /**
+     * 列出所有已加载插件在该组织下的状态（按加载顺序）；无记录时 enabled=false、config=null。
+     * 之后是已安装但此刻没加载的插件（部署上停用等），`available: false`，按名字排序。
+     */
+    list(orgId: string): Promise<OrgExtensionView[]>;
+    /**
+     * Writes enablement and / or config. The actor's role is re-read under the org row lock (needs
+     * `org.extensions.manage`).
+     * - Extension not loaded -> `extension.not_found`; `config` given but the extension has no
+     *   `config.org` -> `extension.no_org_config`; `enabled: false` for a required bootstrap plugin
+     *   -> `extension.required` (it stays enabled in every org; its config can still be written).
+     * - Non-secret fields are replaced as a whole by the given value; secret fields keep the old value
+     *   when omitted, `null` clears, any other value is the new value.
+     * - The merged full config (or, without `config`, the existing config when the result is enabled)
+     *   does not satisfy the schema -> `extension.config_invalid`.
+     */
+    put(orgId: string, plugin: string, input: OrgExtensionInput, actorAccountId: string, actorTokenId?: string, opts?: OrgExtensionPutOptions): Promise<OrgExtensionView>;
+    /**
+     * 读取并解密某插件在该组织下的完整配置（供运行时按组织构造插件实例）。
+     * A required bootstrap plugin is enabled without a row (its stored config, or `{}`, is validated).
+     * 无记录 → undefined；插件无 `config.org` 或已停用（`enabled=false`，不校验、不读密钥）时 `config` 为 null。
+     * 配置行与密钥在同一个 `REPEATABLE READ` 只读事务里读取。
+     * 已存配置不再满足 schema（如插件升级后）→ 抛 Error，信息含插件名、组织 ID 与出错路径（不含值）。
+     */
+    get(orgId: string, plugin: string): Promise<{
+        enabled: boolean;
+        config: unknown;
+    } | undefined>;
+    private decode;
+    /**
+     * 该组织里已启用、且所 requires 的按组织启用的能力只剩这个插件提供的插件（停用它会让它们失去依赖）。
+     * 在调用方事务里读（应用卸载 / 回滚前判断是否保留）。
+     */
+    enabledDependents(t: Trx, orgId: string, plugin: string): Promise<string[]>;
+    /**
+     * 在调用方事务里停用（应用安装的回滚与卸载用；调用方已锁组织行并复核角色）：不检查依赖方，配置保留，
+     * 审计 `org.plugin_config.updated`（带 reason）。提交后调用方须再调 {@link afterDisable}。
+     */
+    disableIn(t: Trx, orgId: string, plugin: string, actorAccountId: string, reason: string): Promise<boolean>;
+    /** {@link disableIn} 的事务提交之后：通知停用（断开该插件的渠道连接等）。 */
+    afterDisable(orgId: string, plugin: string): Promise<void>;
+    /** 该组织已启用的插件名（只含当前已加载的插件；待批准的不算；必需的引导插件始终算启用）。 */
+    private enabledSet;
+    /** 引用是否为按组织启用的能力。 */
+    private isOrgScoped;
+    /** 该组织内（已启用、已加载、非 `except`）提供完整引用（含主版本）的插件。 */
+    private enabledProviders;
+    /** 启用前：A `requires` 的每个 orgScoped 能力（按主版本），该组织须至少有一个已启用的提供方。 */
+    private assertDependenciesEnabled;
+    /** 停用前：若停用后某个已启用的插件所 requires 的 orgScoped 能力（按主版本）再无已启用的提供方，拒绝。 */
+    private assertNoEnabledDependents;
+    private manifest;
+    private permissionsOf;
+    private view;
+    /** 该组织在 `kernel` 命名空间下已设置的插件配置密钥键（不解密）。 */
+    private setSecretKeys;
+}
+export {};