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

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 {
@@ -18,14 +19,15 @@ export interface PermissionSnapshot {
  * reason: new = no snapshot (first seen); added = more permissions than the snapshot;
  * dependency = needs no approval itself, but an extension point it `requires` is provided only by
  * extensions pending approval (or not loaded because of that); the same when it declares
- * `permissions.storage` and `object-store@1` has no provider that will load (providers may be empty).
+ * `permissions.storage` and `object-store@1` has no provider that will load (providers may be empty);
+ * conflict = see {@link PendingExtension.conflicts}.
  */
 export interface PendingExtension {
     plugin: string;
     version: string;
     added: string[];
     removed: string[];
-    reason: "new" | "added" | "dependency";
+    reason: "new" | "added" | "dependency" | "conflict";
     /**
      * When reason is dependency: the extension points blocking it and their providers (only providers
      * that are not loading; empty when there is no provider at all).
@@ -34,6 +36,15 @@ export interface PendingExtension {
         extensionPoint: string;
         providers: string[];
     }[];
+    /**
+     * When reason is conflict (an installed extension, not an approval matter): the single-provider
+     * extension points it provides that other extensions already provide, and those providers. It
+     * loads once they are disabled or uninstalled.
+     */
+    conflicts?: {
+        extensionPoint: string;
+        providers: string[];
+    }[];
 }
 /** {@link planApprovals} 对单个插件的结论。 */
 export type ApprovalDecision = {
@@ -70,11 +81,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 +100,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}. */

package/dist/extensions/blobs.js

@@ -1,4 +1,19 @@
+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 { createHash } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+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 { StorageService } from "../storage/storage.service.js";
 /**
  * Content-addressed extension package store (C13): one copy per sha256 of the whole tgz.
  * - With object storage: `deployment/plugins/blobs/<sha256>.tgz` (`blob_store = object`);
@@ -17,10 +32,46 @@ export class ExtensionBlobIntegrityError extends Error {
 /** 对象存储里的键（相对 `deployment/`）。 */
 export const blobKey = (sha256) => `plugins/blobs/${sha256}.tgz`;
 const SHA256_RE = /^[0-9a-f]{64}$/;
-export class ExtensionBlobs {
-    d;
-    constructor(d) {
-        this.d = d;
+/** How many packages {@link ExtensionBlobs.remember} keeps; the oldest is dropped beyond it. */
+const REMEMBERED_MAX = 8;
+let ExtensionBlobs = class ExtensionBlobs {
+    db;
+    txHost;
+    storage;
+    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.
+     */
+    local = new Map();
+    constructor(db, txHost, 
+    /** Without an object-store extension (the CLI) packages go to PG. */
+    storage, config) {
+        this.db = db;
+        this.txHost = txHost;
+        this.storage = storage;
+        this.config = config;
+    }
+    /** `packages.maxBytes` (read at every call). */
+    maxBytes() {
+        return this.config.get().packages.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, bytes) {
+        if (createHash("sha256").update(bytes).digest("hex") !== sha256) {
+            throw new ExtensionBlobIntegrityError(sha256);
+        }
+        this.local.delete(sha256);
+        this.local.set(sha256, bytes);
+        while (this.local.size > REMEMBERED_MAX) {
+            const oldest = this.local.keys().next().value;
+            this.local.delete(oldest);
+        }
     }
     /**
      * Stores a validated package (the result of {@link readExtensionPackage}) and its bytes, and writes
@@ -28,13 +79,13 @@ export class ExtensionBlobs {
      * (content-addressed, idempotent; replicas writing the same package concurrently is harmless).
      */
     async put(p, bytes, src) {
-        if (bytes.byteLength > this.d.maxBytes()) {
-            throw new Error(`the package is larger than ${this.d.maxBytes()} bytes`);
+        if (bytes.byteLength > this.maxBytes()) {
+            throw new Error(`the package is larger than ${this.maxBytes()} bytes`);
         }
         if (createHash("sha256").update(bytes).digest("hex") !== p.sha256) {
             throw new ExtensionBlobIntegrityError(p.sha256);
         }
-        const existing = await this.d.db
+        const existing = await this.db
             .selectFrom("extension_packages")
             .select("blob_store")
             .where("sha256", "=", p.sha256)
@@ -44,58 +95,60 @@ export class ExtensionBlobs {
             await this.repair(p.sha256, existing.blob_store, bytes);
             return;
         }
-        const store = src.store ?? (this.d.storage?.available ? "object" : "pg");
+        const store = src.store ?? (this.storage.available ? "object" : "pg");
         if (store === "object") {
-            if (!this.d.storage)
+            if (!this.storage.available)
                 throw new Error("object storage is not available");
-            await this.d.storage.deployment().put(blobKey(p.sha256), bytes, {
+            await this.storage.deployment().put(blobKey(p.sha256), bytes, {
                 contentType: "application/gzip",
                 size: bytes.byteLength,
             });
         }
-        const m = p.section.manifest;
         // the row stores the plugin's extension section as reviewed (without the name / version copy)
         const { name: _name, version: _version, ...section } = p.section;
-        await this.d.db.transaction().execute(async (trx) => {
-            const inserted = await trx
-                .insertInto("extension_packages")
-                .values({
-                sha256: p.sha256,
-                name: m.name,
-                package_name: String(p.packageJson.name),
-                version: m.version,
-                size: p.size,
-                section: JSON.stringify(section),
-                blob_store: store,
-                source: src.source,
-                source_ref: src.ref,
-                uploaded_by: src.actor,
-            })
+        await this.record(p, section, bytes, src, store);
+    }
+    async record(p, section, bytes, src, store) {
+        const m = p.section.manifest;
+        const inserted = await this.db
+            .insertInto("extension_packages")
+            .values({
+            sha256: p.sha256,
+            name: m.name,
+            package_name: String(p.packageJson.name),
+            version: m.version,
+            size: p.size,
+            section: JSON.stringify(section),
+            blob_store: store,
+            source: src.source,
+            source_ref: src.ref,
+            uploaded_by: src.actor,
+            display_name: p.displayName === undefined ? null : JSON.stringify(p.displayName),
+        })
+            .onConflict((oc) => oc.column("sha256").doNothing())
+            .returning("sha256")
+            .executeTakeFirst();
+        if (inserted && store === "pg") {
+            await this.db
+                .insertInto("extension_blobs")
+                .values({ sha256: p.sha256, bytes: Buffer.from(bytes) })
                 .onConflict((oc) => oc.column("sha256").doNothing())
-                .returning("sha256")
-                .executeTakeFirst();
-            if (inserted && store === "pg") {
-                await trx
-                    .insertInto("extension_blobs")
-                    .values({ sha256: p.sha256, bytes: Buffer.from(bytes) })
-                    .onConflict((oc) => oc.column("sha256").doNothing())
-                    .execute();
-            }
-        });
+                .execute();
+        }
     }
     /** 已有记录的包：按记录的存放位置检查字节在不在，不在就写回（调用方已校验 sha256）。 */
     async repair(sha256, store, bytes) {
         if (store === "pg") {
-            await this.d.db
+            await this.db
                 .insertInto("extension_blobs")
                 .values({ sha256, bytes: Buffer.from(bytes) })
                 .onConflict((oc) => oc.column("sha256").doNothing())
                 .execute();
             return;
         }
-        if (!this.d.storage?.available)
+        if (!this.storage.available)
             return;
-        const d = this.d.storage.deployment();
+        const d = this.storage.deployment();
         if ((await d.head(blobKey(sha256))) === null) {
             await d.put(blobKey(sha256), bytes, {
                 contentType: "application/gzip",
@@ -107,7 +160,10 @@ export class ExtensionBlobs {
     async get(sha256) {
         if (!SHA256_RE.test(sha256))
             throw new Error(`invalid package sha256 "${sha256}"`);
-        const row = await this.d.db
+        const local = this.local.get(sha256);
+        if (local)
+            return local;
+        const row = await this.db
             .selectFrom("extension_packages")
             .select("blob_store")
             .where("sha256", "=", sha256)
@@ -116,7 +172,7 @@ export class ExtensionBlobs {
             throw new Error(`plugin package ${sha256} is not in the package store`);
         let bytes;
         if (row.blob_store === "pg") {
-            const b = await this.d.db
+            const b = await this.db
                 .selectFrom("extension_blobs")
                 .select("bytes")
                 .where("sha256", "=", sha256)
@@ -126,21 +182,32 @@ export class ExtensionBlobs {
             bytes = b.bytes;
         }
         else {
-            if (!this.d.storage)
+            if (!this.storage.available)
                 throw new Error("object storage is not available");
-            const got = await this.d.storage.deployment().get(blobKey(sha256));
+            const got = await this.storage.deployment().get(blobKey(sha256));
             if (!got) {
                 // 常见原因：对象存储换了桶 / 地址，旧桶里的包没有带过来
                 throw new Error(`plugin package ${sha256} is recorded in object storage, but deployment/${blobKey(sha256)} is missing there; if the object store's bucket or endpoint was changed, copy the deployment/ prefix from the old bucket, or upload the same package again to restore it`);
             }
-            bytes = await readCapped(got.body, this.d.maxBytes());
+            bytes = await readCapped(got.body, this.maxBytes());
         }
         if (createHash("sha256").update(bytes).digest("hex") !== sha256) {
             throw new ExtensionBlobIntegrityError(sha256);
         }
         return bytes;
     }
-}
+};
+__decorate([
+    Transactional()
+], ExtensionBlobs.prototype, "record", null);
+ExtensionBlobs = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(StorageService)),
+    __param(3, Inject(KernelConfigService))
+], ExtensionBlobs);
+export { ExtensionBlobs };
 async function readCapped(body, max) {
     const reader = body.getReader();
     const chunks = [];