@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.2

package/dist/extensions/admin-view.js

@@ -1,9 +1,28 @@
+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 { SDK_VERSION } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
-import { lockEnterpriseAdminsAndAuthorize } from "../identity/enterprise-admin.js";
+import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { ExtensionApprovals, snapshotCovers, writeSnapshot, } from "./approvals.js";
-import { PLUGINS_CHANGED_TOPIC, STALE_RECONCILE_PERIODS } from "./lifecycle.js";
+import { ExtensionBlobs } from "./blobs.js";
+import { ExtensionHost } from "./host.js";
+import { ExtensionInstalls } from "./installs.js";
+import { ExtensionLifecycle, PLUGINS_CHANGED_TOPIC, STALE_RECONCILE_PERIODS } from "./lifecycle.js";
+import { PluginApproveLock } from "./locks.js";
 import { ExtensionPackageError, permissionSetOfPackage, readExtensionPackage } from "./package.js";
 import { buildPermissionSet, diffPermissions } from "./permission-set.js";
 import { deriveExtensionStatus, migrationWarnings, permissionGroups, permissionKeyItems, reviewHash, } from "./permission-view.js";
@@ -31,11 +50,42 @@ function assertReadable(s) {
  * 部署级插件后台（企业管理员）：列表 / 详情与网页批准权限（D8）。无状态，多副本共用；
  * 状态由 PG（安装记录、快照、各副本状态行）与本副本宿主（配置声明插件的清单）推出。
  */
-export class ExtensionAdmin {
-    d;
+let ExtensionAdmin = class ExtensionAdmin {
+    kdb;
+    txHost;
+    adminLock;
+    approveLock;
+    blobs;
+    installs;
+    approvals;
+    host;
+    lifecycle;
+    config;
+    bus;
+    log;
     packageSets = new Map();
-    constructor(d) {
-        this.d = d;
+    constructor(kdb, txHost, 
+    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
+    adminLock, approveLock, blobs, installs, approvals, 
+    /** The config-declared extensions (this replica's host; the CLI fills it from its inspection). */
+    host, 
+    /** This replica's reconcile after an approval (a no-op where the lifecycle never started: the CLI). */
+    lifecycle, config, bus, log) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.adminLock = adminLock;
+        this.approveLock = approveLock;
+        this.blobs = blobs;
+        this.installs = installs;
+        this.approvals = approvals;
+        this.host = host;
+        this.lifecycle = lifecycle;
+        this.config = config;
+        this.bus = bus;
+        this.log = log;
+    }
+    get db() {
+        return this.kdb.db;
     }
     /** 全部插件（配置声明 → 安装记录，各自按名字）。 */
     async list() {
@@ -84,62 +134,64 @@ export class ExtensionAdmin {
             throw stale();
         if (body.reviewHash !== reviewHash(s.set, s.warnings))
             throw stale();
-        await this.d.db.transaction().execute(async (trx) => {
-            await lockEnterpriseAdminsAndAuthorize(trx, actor);
-            await sql `SELECT pg_advisory_xact_lock(hashtext(${`capybara.plugin-approve:${name}`}))`.execute(trx);
-            if (s.install !== null) {
-                // 审阅之后安装记录可能已换包（T14 升级）：锁行复核
-                const row = await trx
-                    .selectFrom("extension_installs")
-                    .select("sha256")
-                    .where("name", "=", name)
-                    .forUpdate()
-                    .executeTakeFirst();
-                if (row?.sha256 !== s.install.sha256)
-                    throw stale();
-            }
-            const snapRow = await trx
-                .selectFrom("extension_permission_snapshots")
-                .select(["version", "permissions"])
-                .where("plugin", "=", name)
-                .forUpdate()
-                .executeTakeFirst();
-            const snap = snapRow && {
-                version: snapRow.version,
-                permissions: snapRow.permissions,
-            };
-            if (snapshotCovers(snap, s.set)) {
-                throw new ApiError("extension.not_pending", `Extension ${name} ${s.version} has no new permissions awaiting approval`);
-            }
-            const { added, removed } = diffPermissions(snap?.permissions, s.set);
-            await writeSnapshot(trx, name, s.version, s.set, {
-                source: "web",
-                approvedBy: actor,
-                ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
-                audit: { added, removed, sha256: s.install?.sha256 ?? null },
-            });
-        });
+        await this.writeApproval(actor, name, s, opts.actorTokenId, stale);
         try {
-            await this.d.bus.publish(PLUGINS_CHANGED_TOPIC, { plugin: name });
+            await this.bus.publish(PLUGINS_CHANGED_TOPIC, { plugin: name });
         }
         catch (err) {
             // 快照已写入；其他副本由周期 reconcile（T14）兜底
-            this.d.log.warn("cannot publish plugins.changed after approval", { plugin: name, err });
+            this.log.warn("cannot publish plugins.changed after approval", { plugin: name, err });
         }
         try {
-            await this.d.reconcile?.(`approved:${name}`);
+            await this.lifecycle.reconcile(`approved:${name}`);
         }
         catch (err) {
-            this.d.log.error("loading approved plugins on this replica failed", { plugin: name, err });
+            this.log.error("loading approved plugins on this replica failed", { plugin: name, err });
         }
         return this.get(name);
     }
+    async writeApproval(actor, name, s, actorTokenId, stale) {
+        const db = this.db;
+        await this.adminLock.lockAndAuthorize(actor);
+        await this.approveLock.lock(name);
+        if (s.install !== null) {
+            // 审阅之后安装记录可能已换包（T14 升级）：锁行复核
+            const row = await db
+                .selectFrom("extension_installs")
+                .select("sha256")
+                .where("name", "=", name)
+                .forUpdate()
+                .executeTakeFirst();
+            if (row?.sha256 !== s.install.sha256)
+                throw stale();
+        }
+        const snapRow = await db
+            .selectFrom("extension_permission_snapshots")
+            .select(["version", "permissions"])
+            .where("plugin", "=", name)
+            .forUpdate()
+            .executeTakeFirst();
+        const snap = snapRow && {
+            version: snapRow.version,
+            permissions: snapRow.permissions,
+        };
+        if (snapshotCovers(snap, s.set)) {
+            throw new ApiError("extension.not_pending", `Extension ${name} ${s.version} has no new permissions awaiting approval`);
+        }
+        const { added, removed } = diffPermissions(snap?.permissions, s.set);
+        await writeSnapshot(db, name, s.version, s.set, {
+            source: "web",
+            approvedBy: actor,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            audit: { added, removed, sha256: s.install?.sha256 ?? null },
+        });
+    }
     /** 配置声明 → 安装记录（与配置声明重名的安装记录不生效，不单列）。`only` 给出时只取这一个。 */
     async subjects(only) {
-        const declared = this.d.host
+        const declared = this.host
             .declaredPlugins()
             .filter((p) => only === undefined || p.name === only);
-        const taken = new Set(this.d.host.declaredPlugins().map((p) => p.name));
+        const taken = new Set(this.host.declaredPlugins().map((p) => p.name));
         const out = [...declared]
             .sort((a, b) => a.name.localeCompare(b.name))
             .map((p) => ({
@@ -154,7 +206,7 @@ export class ExtensionAdmin {
         }));
         if (only !== undefined && out.length > 0)
             return out;
-        const rows = (await this.d.installs.list()).filter((r) => !taken.has(r.name) && (only === undefined || r.name === only));
+        const rows = (await this.installs.list()).filter((r) => !taken.has(r.name) && (only === undefined || r.name === only));
         for (const r of rows) {
             let info;
             try {
@@ -168,7 +220,7 @@ export class ExtensionAdmin {
                     ? err.message
                     : `package ${r.name} ${r.version} (${r.sha256}) cannot be read: ${err instanceof Error ? err.message : String(err)}`;
                 // A pre-0.1.0 package is an expected state (repack needed), logged without a stack trace.
-                this.d.log.warn("plugin package unreadable for the admin view", {
+                this.log.warn("plugin package unreadable for the admin view", {
                     plugin: r.name,
                     sha256: r.sha256,
                     ...(legacy ? { reason: detail } : { err }),
@@ -207,8 +259,8 @@ export class ExtensionAdmin {
     async packageInfo(sha256) {
         let cached = this.packageSets.get(sha256);
         if (!cached) {
-            const pkg = await readExtensionPackage(await this.d.blobs.get(sha256), {
-                maxBytes: this.d.config().packages.maxBytes,
+            const pkg = await readExtensionPackage(await this.blobs.get(sha256), {
+                maxBytes: this.config.get().packages.maxBytes,
                 hostSdkVersion: SDK_VERSION,
             });
             cached = {
@@ -225,9 +277,9 @@ export class ExtensionAdmin {
         if (subjects.length === 0)
             return [];
         const names = subjects.map((s) => s.name);
-        const snapshots = await new ExtensionApprovals(this.d.db).all();
-        const staleSeconds = STALE_RECONCILE_PERIODS * this.d.config().extensionHost.reconcileIntervalSeconds;
-        const rows = await this.d.db
+        const snapshots = await this.approvals.all();
+        const staleSeconds = STALE_RECONCILE_PERIODS * this.config.get().extensionHost.reconcileIntervalSeconds;
+        const rows = await this.db
             .selectFrom("extension_replica_status")
             .selectAll()
             .where("plugin", "in", names)
@@ -307,7 +359,26 @@ export class ExtensionAdmin {
             };
         });
     }
-}
+};
+__decorate([
+    Transactional()
+], ExtensionAdmin.prototype, "writeApproval", null);
+ExtensionAdmin = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(EnterpriseAdminLock)),
+    __param(3, Inject(PluginApproveLock)),
+    __param(4, Inject(ExtensionBlobs)),
+    __param(5, Inject(ExtensionInstalls)),
+    __param(6, Inject(ExtensionApprovals)),
+    __param(7, Inject(ExtensionHost)),
+    __param(8, Inject(ExtensionLifecycle)),
+    __param(9, Inject(KernelConfigService)),
+    __param(10, Inject(KERNEL_BUS)),
+    __param(11, Inject(KERNEL_LOGGER))
+], ExtensionAdmin);
+export { ExtensionAdmin };
 const replicaView = (r) => ({
     replicaId: r.replica_id,
     version: r.version,

package/dist/extensions/approvals.d.ts

@@ -1,6 +1,7 @@
 import { type ExtensionManifest } from "@capybara-hq/plugin-sdk";
-import { type Transaction } from "kysely";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
 import { type PermissionSet } from "./permission-set.js";
 /** An approved permission snapshot (one row of `capybara.extension_permission_snapshots`). */
 export interface PermissionSnapshot {
@@ -70,11 +71,11 @@ export declare function withPreApproved(snapshots: Map<string, PermissionSnapsho
 /** 快照是否已覆盖该权限集合（没有需要批准的新增；F-N：「待批准」只看这一条，与期望状态无关）。 */
 export declare function snapshotCovers(snap: Pick<PermissionSnapshot, "permissions"> | undefined, set: PermissionSet): boolean;
 /**
- * Writes (adds or overwrites) a snapshot in the caller's transaction; with `audit`, the
- * `extension.permissions_approved` audit is written in the same transaction (actor is `approvedBy`,
+ * Writes (adds or overwrites) a snapshot on `db` (the caller's transaction); with `audit`, the
+ * `extension.permissions_approved` audit is written on the same handle (actor is `approvedBy`,
  * empty for the CLI).
  */
-export declare function writeSnapshot(trx: Transaction<KernelDatabase>, plugin: string, version: string, permissions: PermissionSet, opts: {
+export declare function writeSnapshot(db: KernelSchemaDb, plugin: string, version: string, permissions: PermissionSet, opts: {
     source: PermissionSnapshot["source"];
     approvedBy?: string | null;
     actorTokenId?: string;
@@ -89,11 +90,14 @@ export declare function writeSnapshot(trx: Transaction<KernelDatabase>, plugin:
         };
     };
 }): Promise<void>;
-/** 读写权限快照（直连 PG；内核启动与 CLI 共用）。 */
+/** Every approved snapshot, by extension name (a query on `db`; the CLI's migrate runs it on its own pool). */
+export declare function readSnapshots(db: KernelSchemaDb): Promise<Map<string, PermissionSnapshot>>;
+/** The permission snapshots (PG; the kernel and the CLI share them). */
 export declare class ExtensionApprovals {
     private readonly db;
-    constructor(db: KernelDb);
-    /** 全部快照，按插件名索引。 */
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, txHost: TransactionHost);
+    /** Every snapshot, by extension name. */
     all(): Promise<Map<string, PermissionSnapshot>>;
     /**
      * Approves (adds or overwrites) a snapshot: writes the current permission set and version,

package/dist/extensions/approvals.js

@@ -1,7 +1,20 @@
+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 { OBJECT_STORE_EXTENSION_POINT } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import semver from "semver";
 import { audit } from "../identity/audit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
 import { blockingKeys, diffPermissions, permissionKeys, } from "./permission-set.js";
 /**
  * 按依赖拓扑序（`ordered`）比对快照，决定每个插件加载还是待批准：
@@ -107,11 +120,11 @@ export function snapshotCovers(snap, set) {
     return (snap !== undefined && blockingKeys(diffPermissions(snap.permissions, set).added).length === 0);
 }
 /**
- * Writes (adds or overwrites) a snapshot in the caller's transaction; with `audit`, the
- * `extension.permissions_approved` audit is written in the same transaction (actor is `approvedBy`,
+ * Writes (adds or overwrites) a snapshot on `db` (the caller's transaction); with `audit`, the
+ * `extension.permissions_approved` audit is written on the same handle (actor is `approvedBy`,
  * empty for the CLI).
  */
-export async function writeSnapshot(trx, plugin, version, permissions, opts) {
+export async function writeSnapshot(db, plugin, version, permissions, opts) {
     const values = {
         plugin,
         version,
@@ -120,7 +133,7 @@ export async function writeSnapshot(trx, plugin, version, permissions, opts) {
         approved_at: sql `now()`,
         source: opts.source,
     };
-    await trx
+    await db
         .insertInto("extension_permission_snapshots")
         .values(values)
         .onConflict((oc) => oc.column("plugin").doUpdateSet({
@@ -132,7 +145,7 @@ export async function writeSnapshot(trx, plugin, version, permissions, opts) {
     }))
         .execute();
     if (opts.audit) {
-        await audit(trx, {
+        await audit(db, {
             ...(opts.approvedBy && { actorAccountId: opts.approvedBy }),
             ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
             action: "extension.permissions_approved",
@@ -143,26 +156,32 @@ export async function writeSnapshot(trx, plugin, version, permissions, opts) {
 }
 /** `version` 是否比 `than` 旧（任一方不是合法 semver 时视为不旧）。 */
 const isOlder = (version, than) => semver.valid(version) !== null && semver.valid(than) !== null && semver.lt(version, than);
-/** 读写权限快照（直连 PG；内核启动与 CLI 共用）。 */
-export class ExtensionApprovals {
+/** Every approved snapshot, by extension name (a query on `db`; the CLI's migrate runs it on its own pool). */
+export async function readSnapshots(db) {
+    const rows = await db.selectFrom("extension_permission_snapshots").selectAll().execute();
+    return new Map(rows.map((r) => [
+        r.plugin,
+        {
+            plugin: r.plugin,
+            version: r.version,
+            permissions: r.permissions,
+            approvedBy: r.approved_by,
+            approvedAt: r.approved_at,
+            source: r.source,
+        },
+    ]));
+}
+/** The permission snapshots (PG; the kernel and the CLI share them). */
+let ExtensionApprovals = class ExtensionApprovals {
     db;
-    constructor(db) {
+    txHost;
+    constructor(db, txHost) {
         this.db = db;
+        this.txHost = txHost;
     }
-    /** 全部快照，按插件名索引。 */
-    async all() {
-        const rows = await this.db.selectFrom("extension_permission_snapshots").selectAll().execute();
-        return new Map(rows.map((r) => [
-            r.plugin,
-            {
-                plugin: r.plugin,
-                version: r.version,
-                permissions: r.permissions,
-                approvedBy: r.approved_by,
-                approvedAt: r.approved_at,
-                source: r.source,
-            },
-        ]));
+    /** Every snapshot, by extension name. */
+    all() {
+        return readSnapshots(this.db.db);
     }
     /**
      * Approves (adds or overwrites) a snapshot: writes the current permission set and version,
@@ -170,9 +189,7 @@ export class ExtensionApprovals {
      * same transaction (actor is `approvedBy`, empty for the CLI).
      */
     async approve(plugin, version, permissions, opts) {
-        await this.db
-            .transaction()
-            .execute((trx) => writeSnapshot(trx, plugin, version, permissions, opts));
+        await writeSnapshot(this.db.db, plugin, version, permissions, opts);
     }
     /**
      * 权限变少、不变或只多出 `ui.view:*`（不卡加载）时更新快照的权限集合与版本；批准人、批准时间与来源保持不变，
@@ -181,25 +198,35 @@ export class ExtensionApprovals {
      * 或当前集合相对快照有需要批准的新增时不更新。返回是否更新。
      */
     async refresh(plugin, version, permissions) {
-        return this.db.transaction().execute(async (trx) => {
-            const row = await trx
-                .selectFrom("extension_permission_snapshots")
-                .select(["version", "permissions"])
-                .where("plugin", "=", plugin)
-                .forUpdate()
-                .executeTakeFirst();
-            if (!row || isOlder(version, row.version))
-                return false;
-            const { added } = diffPermissions(row.permissions, permissions);
-            if (blockingKeys(added).length > 0) {
-                return false;
-            }
-            await trx
-                .updateTable("extension_permission_snapshots")
-                .set({ version, permissions: JSON.stringify(permissions) })
-                .where("plugin", "=", plugin)
-                .execute();
-            return true;
-        });
+        const row = await this.db
+            .selectFrom("extension_permission_snapshots")
+            .select(["version", "permissions"])
+            .where("plugin", "=", plugin)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!row || isOlder(version, row.version))
+            return false;
+        const { added } = diffPermissions(row.permissions, permissions);
+        if (blockingKeys(added).length > 0) {
+            return false;
+        }
+        await this.db
+            .updateTable("extension_permission_snapshots")
+            .set({ version, permissions: JSON.stringify(permissions) })
+            .where("plugin", "=", plugin)
+            .execute();
+        return true;
     }
-}
+};
+__decorate([
+    Transactional()
+], ExtensionApprovals.prototype, "approve", null);
+__decorate([
+    Transactional()
+], ExtensionApprovals.prototype, "refresh", null);
+ExtensionApprovals = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost))
+], ExtensionApprovals);
+export { ExtensionApprovals };

package/dist/extensions/blobs.d.ts

@@ -1,5 +1,7 @@
-import type { KernelDb } from "../db/kernel-schema.js";
-import type { StorageService } from "../storage/storage.service.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { StorageService } from "../storage/storage.service.js";
 import type { ExtensionPackage } from "./package.js";
 /**
  * Content-addressed extension package store (C13): one copy per sha256 of the whole tgz.
@@ -24,20 +26,35 @@ export interface ExtensionBlobSource {
     store?: "object" | "pg";
 }
 export declare class ExtensionBlobs {
-    private readonly d;
-    constructor(d: {
-        db: KernelDb;
-        /** 没有时一律存 PG（如 CLI）。 */
-        storage?: StorageService;
-        /** `packages.maxBytes`（每次调用时读）。 */
-        maxBytes: () => number;
-    });
+    private readonly db;
+    readonly txHost: TransactionHost;
+    /** Without an object-store extension (the CLI) packages go to PG. */
+    private readonly storage;
+    private readonly config;
+    /**
+     * CLI only: packages the CLI process imported itself and reads back before the store, since such
+     * a package may be recorded in an object store the CLI cannot read. Each entry's sha256 was
+     * checked by {@link remember}; content-addressed and immutable, so it is never stale. Bounded
+     * ({@link REMEMBERED_MAX}, oldest dropped); a kernel replica never fills it.
+     */
+    private readonly local;
+    constructor(db: KernelDb, txHost: TransactionHost, 
+    /** Without an object-store extension (the CLI) packages go to PG. */
+    storage: StorageService, config: KernelConfigService);
+    /** `packages.maxBytes` (read at every call). */
+    private maxBytes;
+    /**
+     * CLI only: keeps `bytes` for {@link get} in this process (see {@link local}). Bytes whose sha256
+     * is not `sha256` throw {@link ExtensionBlobIntegrityError} and are not kept.
+     */
+    remember(sha256: string, bytes: Uint8Array): void;
     /**
      * Stores a validated package (the result of {@link readExtensionPackage}) and its bytes, and writes
      * the `extension_packages` row. Does nothing when a package with the same sha256 exists
      * (content-addressed, idempotent; replicas writing the same package concurrently is harmless).
      */
     put(p: ExtensionPackage, bytes: Uint8Array, src: ExtensionBlobSource): Promise<void>;
+    private record;
     /** 已有记录的包：按记录的存放位置检查字节在不在，不在就写回（调用方已校验 sha256）。 */
     private repair;
     /** Reads the package from its recorded location and checks its sha256; a mismatch throws {@link ExtensionBlobIntegrityError}. */