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

package/dist/catalog/owned-plugin-cleanup.d.ts

@@ -0,0 +1,56 @@
+import { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { CatalogItemLock } from "./locks.js";
+/**
+ * The cleanup of a removed org-owned plugin: {@link run} disables and uninstalls its extension (an
+ * install of the item's name from the item's package) when no live catalog item uses it any more
+ * ({@link OwnedPluginCleanup.referenced}), then releases the extension name claim, in one transaction under the import's item name lock
+ * (pre-flight F10: the claim of an
+ * installed extension is released here, never at the removal). Idempotent: a live item (a
+ * transferred one), a platform item or nothing installed changes nothing but the claim. The
+ * extension's data, secrets and configs stay, as with every uninstall. {@link sweep} runs it daily
+ * for every removed org-owned item whose extension is still installed (a lost enqueue).
+ */
+export declare class OwnedPluginCleanup {
+    private readonly kdb;
+    private readonly ops;
+    /** The import's item name lock (M5: no uninstall racing a re-import of the package). */
+    private readonly itemLock;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, ops: ExtensionAdminOps, 
+    /** The import's item name lock (M5: no uninstall racing a re-import of the package). */
+    itemLock: CatalogItemLock, lockService: LockService, log: KernelLogger, txHost: TransactionHost);
+    private get db();
+    /** Takes out the extension of removed item `itemId` (see the class). */
+    run(itemId: string): Promise<void>;
+    /**
+     * {@link run}'s one transaction, under the catalog item name lock an import of that name takes
+     * to write its item: a re-import of the package either committed first (a live item: nothing
+     * is taken out) or waits until this commits, so a newly imported extension is never uninstalled.
+     */
+    private takeOut;
+    /**
+     * Daily: {@link run} for every removed org-owned item no live item {@link referenced} names
+     * whose extension is still installed, or whose name claim is still held (a lost enqueue, or a
+     * run that uninstalled and failed before releasing the claim).
+     */
+    sweep(): Promise<void>;
+    /**
+     * A live catalog item still uses the extension: one named like it (a plugin and its extension
+     * share one name) from the same package whose owner is the removed item's owner (a re-upload)
+     * or the platform (the super admin imported it over the install). Never any item of the package
+     * name alone: another org choosing the same package name keeps nothing installed (ruling P3-51).
+     */
+    private referenced;
+}
+/**
+ * {@link OwnedPluginCleanup}: imported only by `MaintenanceModule` (the job's dispatcher), which
+ * only the worker role imports, so the sweep runs on worker replicas only.
+ */
+export declare class OwnedPluginCleanupModule {
+}

package/dist/catalog/owned-plugin-cleanup.js

@@ -0,0 +1,194 @@
+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); }
+};
+// Taking out the extension of a removed org-owned plugin (plugin scope phase 3, spec §14, P3-20,
+// P3-21; pre-flight F9, F10): the one-off job `owned-plugin-cleanup-<itemId>` on
+// `cap-kernel-maintenance` (dispatched by `MaintenanceProcessor`) and its daily sweep. Worker-only:
+// `OwnedPluginCleanupModule` is imported only by `MaintenanceModule`, which only `WorkerModule`
+// imports.
+import { Inject, Injectable, Module } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import { ExtensionsModule } from "../extensions/extensions.module.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 { LockService } from "../infra/lock/lock.service.js";
+import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { CatalogImportModule } from "./catalog.module.js";
+import { OWNED_PLUGIN_CLEANUP_SWEEP_JOB } from "./job-ids.js";
+import { CatalogItemLock } from "./locks.js";
+import { releaseExtensionClaim } from "./ownership.js";
+/** Codes that mean another run (or the confirmation's own take-out) got there first. */
+const GONE = new Set(["extension.not_found", "extension.not_disabled"]);
+/**
+ * The cleanup of a removed org-owned plugin: {@link run} disables and uninstalls its extension (an
+ * install of the item's name from the item's package) when no live catalog item uses it any more
+ * ({@link OwnedPluginCleanup.referenced}), then releases the extension name claim, in one transaction under the import's item name lock
+ * (pre-flight F10: the claim of an
+ * installed extension is released here, never at the removal). Idempotent: a live item (a
+ * transferred one), a platform item or nothing installed changes nothing but the claim. The
+ * extension's data, secrets and configs stay, as with every uninstall. {@link sweep} runs it daily
+ * for every removed org-owned item whose extension is still installed (a lost enqueue).
+ */
+let OwnedPluginCleanup = class OwnedPluginCleanup {
+    kdb;
+    ops;
+    itemLock;
+    lockService;
+    log;
+    txHost;
+    constructor(kdb, ops, 
+    /** The import's item name lock (M5: no uninstall racing a re-import of the package). */
+    itemLock, lockService, log, txHost) {
+        this.kdb = kdb;
+        this.ops = ops;
+        this.itemLock = itemLock;
+        this.lockService = lockService;
+        this.log = log;
+        this.txHost = txHost;
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    /** Takes out the extension of removed item `itemId` (see the class). */
+    async run(itemId) {
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select(["name", "package_name", "deleted_at", "owner_org_id"])
+            .where("id", "=", itemId)
+            .executeTakeFirst();
+        if (!item || item.deleted_at === null || item.owner_org_id === null)
+            return;
+        if (item.package_name === null)
+            return;
+        await this.takeOut(itemId, item.name, item.package_name, item.owner_org_id);
+    }
+    /**
+     * {@link run}'s one transaction, under the catalog item name lock an import of that name takes
+     * to write its item: a re-import of the package either committed first (a live item: nothing
+     * is taken out) or waits until this commits, so a newly imported extension is never uninstalled.
+     */
+    async takeOut(itemId, name, pkg, ownerOrgId) {
+        await this.itemLock.lock(name);
+        if (await this.referenced(this.db, name, pkg, ownerOrgId))
+            return;
+        const install = await this.db
+            .selectFrom("extension_installs as x")
+            .innerJoin("extension_packages as p", "p.sha256", "x.sha256")
+            .select(["x.desired_state", "p.package_name"])
+            .where("x.name", "=", name)
+            .executeTakeFirst();
+        if (install !== undefined && install.package_name === pkg) {
+            try {
+                if (install.desired_state !== "disabled")
+                    await this.ops.disable(name, null);
+                await this.ops.uninstall(name, null);
+                this.log.info("extension of a removed org plugin uninstalled", { itemId, name });
+            }
+            catch (e) {
+                if (!(e instanceof ApiError && GONE.has(e.code)))
+                    throw e;
+            }
+        }
+        await releaseExtensionClaim(this.db, name, pkg);
+    }
+    /**
+     * Daily: {@link run} for every removed org-owned item no live item {@link referenced} names
+     * whose extension is still installed, or whose name claim is still held (a lost enqueue, or a
+     * run that uninstalled and failed before releasing the claim).
+     */
+    async sweep() {
+        const rows = await this.db
+            .selectFrom("catalog_items as ci")
+            .select("ci.id")
+            .where("ci.deleted_at", "is not", null)
+            .where("ci.owner_org_id", "is not", null)
+            .where("ci.package_name", "is not", null)
+            .where(({ and, or, not, exists, selectFrom }) => and([
+            not(exists(selectFrom("catalog_items as live")
+                .select("live.id")
+                .whereRef("live.name", "=", "ci.name")
+                .whereRef("live.package_name", "=", "ci.package_name")
+                .where("live.deleted_at", "is", null)
+                .where((eb) => eb.or([
+                eb("live.owner_org_id", "is", null),
+                eb("live.owner_org_id", "=", eb.ref("ci.owner_org_id")),
+            ])))),
+            or([
+                exists(selectFrom("extension_installs as x")
+                    .innerJoin("extension_packages as p", "p.sha256", "x.sha256")
+                    .select("x.name")
+                    .whereRef("x.name", "=", "ci.name")
+                    .whereRef("p.package_name", "=", "ci.package_name")),
+                exists(selectFrom("extension_name_owners as o")
+                    .select("o.name")
+                    .whereRef("o.name", "=", "ci.name")
+                    .whereRef("o.package_name", "=", "ci.package_name")),
+            ]),
+        ]))
+            .execute();
+        for (const r of rows) {
+            try {
+                await this.run(r.id);
+            }
+            catch (err) {
+                this.log.error("owned plugin cleanup failed", { itemId: r.id, err });
+            }
+        }
+    }
+    /**
+     * A live catalog item still uses the extension: one named like it (a plugin and its extension
+     * share one name) from the same package whose owner is the removed item's owner (a re-upload)
+     * or the platform (the super admin imported it over the install). Never any item of the package
+     * name alone: another org choosing the same package name keeps nothing installed (ruling P3-51).
+     */
+    async referenced(db, name, packageName, ownerOrgId) {
+        const live = await db
+            .selectFrom("catalog_items")
+            .select("id")
+            .where("name", "=", name)
+            .where("package_name", "=", packageName)
+            .where("deleted_at", "is", null)
+            .where((eb) => eb.or([eb("owner_org_id", "is", null), eb("owner_org_id", "=", ownerOrgId)]))
+            .executeTakeFirst();
+        return live !== undefined;
+    }
+};
+__decorate([
+    Transactional()
+], OwnedPluginCleanup.prototype, "takeOut", null);
+__decorate([
+    LockedCron("40 3 * * *", { name: OWNED_PLUGIN_CLEANUP_SWEEP_JOB })
+], OwnedPluginCleanup.prototype, "sweep", null);
+OwnedPluginCleanup = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(ExtensionAdminOps)),
+    __param(2, Inject(CatalogItemLock)),
+    __param(3, Inject(LockService)),
+    __param(4, Inject(KERNEL_LOGGER)),
+    __param(5, Inject(TransactionHost))
+], OwnedPluginCleanup);
+export { OwnedPluginCleanup };
+/**
+ * {@link OwnedPluginCleanup}: imported only by `MaintenanceModule` (the job's dispatcher), which
+ * only the worker role imports, so the sweep runs on worker replicas only.
+ */
+let OwnedPluginCleanupModule = class OwnedPluginCleanupModule {
+};
+OwnedPluginCleanupModule = __decorate([
+    Module({
+        imports: [ExtensionsModule, CatalogImportModule],
+        providers: [OwnedPluginCleanup],
+        exports: [OwnedPluginCleanup],
+    })
+], OwnedPluginCleanupModule);
+export { OwnedPluginCleanupModule };

package/dist/catalog/ownership.d.ts

@@ -0,0 +1,172 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { ApiError } from "../errors.js";
+import { type PluginScope } from "./scope.js";
+/** Who owns an item or component: the platform, or one org (by id and name, deleted orgs too). */
+export type Owner = {
+    kind: "platform";
+} | {
+    kind: "org";
+    orgId: string;
+    name: string;
+};
+export declare const PLATFORM_OWNER: Owner;
+/**
+ * The share gate (P3-1): a platform item, or an org-owned one its owner made shareable. Closed:
+ * the item is never shown, requestable or associable outside its owner (orgs already associated
+ * keep it).
+ */
+export declare function shareGate(row: {
+    owner_org_id: string | null;
+    shareable: boolean;
+}): boolean;
+/** 409 `catalog.not_shareable` unless the row passes the {@link shareGate} (P3-16). */
+export declare function assertShareable(row: {
+    owner_org_id: string | null;
+    shareable: boolean;
+    name: string;
+}): void;
+/**
+ * 409 `catalog.owner_required` when a `named` list after a change leaves out the item's owner org
+ * (P3-17: the owner stays on its own item's list).
+ */
+export declare function assertOwnerListed(row: {
+    owner_org_id: string | null;
+    name: string;
+}, target: {
+    scope: string;
+    orgs: readonly string[];
+}): void;
+/**
+ * A widening of the scope for a row that does not pass the share gate -> 409
+ * `catalog.not_shareable`: a broader scope (`named` < `optional` < `all`), or, `named` to `named`,
+ * an org not on the list before the change. Narrowing is always allowed (P3-16).
+ */
+export declare function assertShareableTarget(row: {
+    owner_org_id: string | null;
+    shareable: boolean;
+    name: string;
+}, from: {
+    scope: string;
+    orgs: readonly string[];
+}, target: {
+    scope: string;
+    orgs: readonly string[];
+}): void;
+/** The facts {@link isUsable} and {@link usableBy} read from a `catalog_items` row. */
+export interface UsableFacts {
+    scope: PluginScope;
+    builtin: boolean;
+    disabled: boolean;
+    deleted_at: Date | null;
+    awaiting_confirmation: boolean;
+    owner_org_id: string | null;
+    shareable: boolean;
+}
+/**
+ * Whether an item can serve anything at all (ruling P3-9, F12): confirmed (not a first upload
+ * still waiting for the super admin), not disabled and not deleted. The one predicate for the
+ * dependency check of org uploads (P3-13), the scope sync, org switches and installs.
+ */
+export declare function isUsable(item: Pick<UsableFacts, "disabled" | "deleted_at" | "awaiting_confirmation">): boolean;
+/**
+ * 409 `catalog.item_pending`: the item, or the version asked for, waits for the super admin's
+ * confirmation in 待确认 (ruling P3-9): no scope edit, switch, install or generic update.
+ */
+export declare function itemPendingError(name: string, version?: string): ApiError;
+/**
+ * 409 `catalog.item_removed`: the item was removed while a super admin confirmation of its upload
+ * was running (ruling P3-21).
+ */
+export declare function itemRemovedError(name: string): ApiError;
+/** 409 `catalog.item_pending` while the item's first version waits for the super admin (P3-9). */
+export declare function assertNotAwaiting(item: {
+    awaiting_confirmation: boolean;
+    name: string;
+}): void;
+/**
+ * The digest a super admin confirms an org upload's pending version with (rulings P3-10, P3-11):
+ * the extension's permission review digest bound to the exact package, so a pending version
+ * replaced by another upload is stale even when both ask for the same permissions.
+ */
+export declare function pendingDigest(sha256: string, reviewHash: string): string;
+/**
+ * Releases the extension name an org upload claimed (pre-flight F10), in the caller's
+ * transaction, when nothing is installed under it: a rejected or withdrawn upload, a pending first
+ * version replaced by one without an extension, a deleted org's pending upload. An installed
+ * extension keeps its claim (its removal is the cleanup job's).
+ */
+export declare function releaseExtensionClaim(db: KernelSchemaDb, name: string, packageName: string | null): Promise<void>;
+/**
+ * Whether `orgId` can use the item (P3-13): {@link isUsable}, and its owner, or listed by a `named`
+ * scope (an org already associated keeps it), or offered to every org (`all` / `optional`, builtin)
+ * through the {@link shareGate} (another org's item only while it is shared).
+ */
+export declare function usableBy(item: UsableFacts, orgId: string, listed: boolean): boolean;
+/**
+ * The owner of the live catalog item called `name` when it is not `owner` (null = the platform),
+ * else undefined: a plugin name is live for one owner only (ruling P3-14).
+ */
+export declare function otherNameOwner(db: KernelSchemaDb, name: string, owner: string | null): Promise<Owner | undefined>;
+/**
+ * 409 `plugin.name_taken` (details `[{ owner }]`) when the plugin name is live for another owner
+ * than `owner` (null = the platform): an org cannot upload a platform's or another org's name, and
+ * the super admin cannot import an org's (ruling P3-14). The same owner adds a version.
+ */
+export declare function assertNameFree(db: KernelSchemaDb, name: string, owner: string | null): Promise<void>;
+/**
+ * The owner other than `owner` (an org id) that already holds npm package `packageName`, else
+ * undefined (ruling P3-51: a package name is an identity only within one owner). Held = a catalog
+ * item of the package of another owner that is live, or removed while its extension is still
+ * installed or its name claimed (a cleanup not run yet); an install of the package whose catalog
+ * item is not one of `owner`'s (none = the platform: bootstrap or a direct install); a name claim
+ * of the package for which `owner` has no item of that name (an uninstalled platform extension
+ * keeps its claim).
+ */
+export declare function otherPackageOwner(db: KernelSchemaDb, packageName: string | null, owner: string): Promise<Owner | undefined>;
+/**
+ * 409 `plugin.name_taken` (details `[{ owner }]`) when an org upload's npm package is held by
+ * another owner ({@link otherPackageOwner}, ruling P3-51): an org never shares a package identity
+ * with another org or the platform, so no name claim, existing install or cleanup can mistake one
+ * owner's plugin for another's.
+ */
+export declare function assertPackageFree(db: KernelSchemaDb, packageName: string | null, owner: string): Promise<void>;
+/**
+ * The owner of extension `extensionName`, held by npm package `packageName` (package -> its live
+ * catalog item -> that item's owner; ruling P3-14). The item is the one named like the extension
+ * (a plugin and its extension share one name), else the oldest live item of the package; none ->
+ * the platform (an extension installed outside the catalog is the super admin's).
+ */
+export declare function packageOwner(db: KernelSchemaDb, packageName: string | null, extensionName: string): Promise<Owner>;
+/** The owners of `orgIds` by org id (deleted orgs included, by their name). */
+export declare function ownersOf(db: KernelSchemaDb, orgIds: readonly string[]): Promise<Map<string, Owner>>;
+/** The {@link Owner} of a row from {@link ownersOf}'s map (an org row gone: its id as the name). */
+export declare function ownerOf(ownerOrgId: string | null, owners: ReadonlyMap<string, Owner>): Owner;
+/** An owned item: a plugin, a skill or an agent template (the platform id once promoted). */
+export type OwnedRef = {
+    kind: "plugin" | "skill" | "agent_template";
+    id: string;
+};
+/**
+ * The live orgs an item is on in (ruling P3-18: listed and not switched off for `named`, switched
+ * on for `optional`, any live org for `all`; a component by {@link componentOn}), minus
+ * `except` (usually the owner), by name. One definition for the update notices and the
+ * "used by another org" check of deletes. An item that is gone or disabled is on nowhere.
+ */
+export declare function orgsUsing(db: KernelSchemaDb, ref: OwnedRef, opts?: {
+    except?: string | null;
+}): Promise<{
+    id: string;
+    name: string;
+}[]>;
+/**
+ * Who a scope change newly shows an org-owned item to (the `item_shared` notice, P3-22): the orgs
+ * added to a `named` list, or `all_orgs` when the scope gets broader (`named` < `optional` < `all`);
+ * nothing for a narrowing or a platform-owned item.
+ */
+export declare function newlySharedWith(from: {
+    scope: string;
+    orgs: readonly string[];
+}, to: {
+    scope: string;
+    orgs: readonly string[];
+}): string[] | "all_orgs";