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

package/dist/catalog/catalog.service.js

@@ -11,21 +11,24 @@ import { isSafePackagePath, marketplaceEntryVersion, } from "@capybara-hq/plugin
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
-import { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import { ExtensionAdmin } from "../extensions/admin-view.js";
 import { ExtensionInstalls } from "../extensions/installs.js";
+import { PluginInstallLock } from "../extensions/locks.js";
 import { audit } from "../identity/audit.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-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 { sameRepository } from "../packages/provenance.js";
-import { countInstalls, itemView, marketplaceLatest } from "./catalog-items.js";
+import { assertNotPlatformDefault } from "../themes/theme-usage.js";
+import { countInstalls, inAuthorOrder, itemConfirmations, itemScopeFacts, itemView, marketplaceLatest, versionUsable, } from "./catalog-items.js";
 import { expandGitUrl, GitSourceError, gitErrorDetails, normalGitPath, readGitTreeAndOids, resolveGitCommit, } from "./git-source.js";
 import { fetchMarketplaceArchive, marketplaceNetPolicy, marketplaceUrlProblem, } from "./marketplace-fetch.js";
-import { entryCompatible, entrySourceHost, HOST_VERSIONS, hostAllowed, loadMarketplaceEntry, MarketplacesService, pluginNameFrom, } from "./marketplaces.service.js";
+import { assertEntryNotDeprecated, entryCompatible, entrySourceHost, HOST_VERSIONS, hostAllowed, loadMarketplaceEntry, MarketplacesService, pluginNameFrom, } from "./marketplaces.service.js";
+import { releaseExtensionClaim } from "./ownership.js";
 import { PluginImport } from "./plugin-import.js";
-import { cancelPendingRequests } from "./requests.service.js";
+import { cancelPendingRequests } from "./request-rules.js";
 import { newestFirst } from "./versions.js";
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const notFound = () => new ApiError("catalog.item_not_found", "Catalog item not found");
@@ -77,34 +80,41 @@ function gitSource(loc, read, pinned) {
 export const CATALOG_LIST_DEFAULT_LIMIT = 200;
 export const CATALOG_LIST_MAX_LIMIT = 1000;
 /**
- * Enterprise catalog items (D9 / C21 / C22, `/api/v1/admin/catalog/*`, enterprise admins only). One
+ * Platform catalog items (D9 / C21 / C22, `/api/v1/admin/catalog/*`, super admins only). One
  * kind: every item is a plugin (spec §4), imported through {@link PluginImport} (prepare -> confirm,
- * one review); this service lists and shows items, changes policy, deletes, installs an item's
- * extension on the deployment, and prepares marketplace imports. Stateless, shared by every replica.
+ * one review, whose confirm installs the plugin's extension); this service lists and shows items,
+ * deletes, and prepares marketplace imports (scope and disable: `CatalogScopeService`). Stateless,
+ * shared by every replica.
  */
 let CatalogService = class CatalogService {
     kdb;
     adminLock;
     config;
     installs;
-    ops;
+    admin;
     pluginImport;
     marketplaces;
+    installLock;
     txHost;
     constructor(kdb, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the caller's transaction. */
-    adminLock, config, installs, ops, 
+    /** The super admin lock (identity/super-admin.ts): joins the caller's transaction. */
+    adminLock, config, installs, 
+    /** The deployment's extensions with their approvals (what is pending confirmation). */
+    admin, 
     /** Plugin import (a marketplace entry goes through its prepare). */
     pluginImport, 
-    /** The token of an enterprise marketplace (sent only to its URL's origin). */
-    marketplaces, txHost) {
+    /** The token of a custom marketplace (sent only to its URL's origin). */
+    marketplaces, 
+    /** Serializes a claim release with an install of that name still committing (F10). */
+    installLock, txHost) {
         this.kdb = kdb;
         this.adminLock = adminLock;
         this.config = config;
         this.installs = installs;
-        this.ops = ops;
+        this.admin = admin;
         this.pluginImport = pluginImport;
         this.marketplaces = marketplaces;
+        this.installLock = installLock;
         this.txHost = txHost;
     }
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
@@ -124,7 +134,8 @@ let CatalogService = class CatalogService {
     /**
      * Prepares the import of one marketplace entry (C25 / C26, spec §5.2): `version` defaults to the
      * newest compatible version the marketplace lists for `name`; the entry must be compatible with
-     * the host (`marketplace.incompatible`); an npm source is downloaded from the configured registry
+     * the host (`marketplace.incompatible`) and not deprecated (`marketplace.entry_deprecated`, 409; the
+     * confirm does not read the marketplace again); an npm source is downloaded from the configured registry
      * and an archive source from its URL, both always verified against the marketplace's integrity
      * (`marketplace.integrity_mismatch`, nothing written). A `path` source is read from the git
      * marketplace's repository at its last refreshed commit (an http marketplace has none:
@@ -146,6 +157,7 @@ let CatalogService = class CatalogService {
         if (!entryCompatible(entry)) {
             throw new ApiError("marketplace.incompatible", `${entry.name}${version !== null ? `@${version}` : ""} needs kernel >= ${entry.minKernel}; this deployment runs kernel ${HOST_VERSIONS.kernel}`);
         }
+        assertEntryNotDeprecated(entry);
         const src = entry.source;
         const host = entrySourceHost(entry);
         if (host !== undefined && !hostAllowed(host, config)) {
@@ -153,6 +165,7 @@ let CatalogService = class CatalogService {
         }
         const prepareOpts = {
             ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            ...(opts.auditDetail !== undefined && { auditDetail: opts.auditDetail }),
             expect: {
                 marketplace: {
                     name: entry.name,
@@ -289,6 +302,7 @@ let CatalogService = class CatalogService {
             : where.detail.path.split("/").pop();
         const r = await this.pluginImport.prepareGit(actor, read.files, { kind: "git", ref: where.ref, detail: where.detail }, {
             ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            ...(opts.auditDetail !== undefined && { auditDetail: opts.auditDetail }),
             fallback: {
                 name: pluginNameFrom(segment),
                 version: gitFallbackVersion(read.commit),
@@ -327,6 +341,25 @@ let CatalogService = class CatalogService {
     }
     /** Same as {@link list}, plus the offset of the next page (null when there is none). */
     async page(q = {}) {
+        // `pending`: every item waiting for a confirmation (one list, not paged: the pending set is small)
+        if (q.pending === true) {
+            const all = await this.page({
+                ...(q.includeDeleted && { includeDeleted: true }),
+                limit: CATALOG_LIST_MAX_LIMIT,
+            });
+            const items = [...all.items];
+            let next = all.nextOffset;
+            while (next !== null) {
+                const more = await this.page({
+                    ...(q.includeDeleted && { includeDeleted: true }),
+                    limit: CATALOG_LIST_MAX_LIMIT,
+                    offset: next,
+                });
+                items.push(...more.items);
+                next = more.nextOffset;
+            }
+            return { items: items.filter((i) => i.pending), nextOffset: null };
+        }
         const limit = Math.min(Math.max(1, q.limit ?? CATALOG_LIST_DEFAULT_LIMIT), CATALOG_LIST_MAX_LIMIT);
         const offset = Math.max(0, q.offset ?? 0);
         let query = this.db
@@ -354,19 +387,29 @@ let CatalogService = class CatalogService {
             "integrity",
             "source_detail",
             "imported_at",
+            "manifest",
+            "source_format",
+            "applied_at",
+            "rejected_at",
         ])
             .where("item_id", "in", items.map((i) => i.id))
             .execute();
+        const platformOwned = new Set(items.filter((i) => i.owner_org_id === null).map((i) => i.id));
         const byItem = new Map();
         for (const v of versions) {
+            // a platform item offers only versions it may use (a transferred org item's rejected or
+            // never-applied uploads stay out, ruling P3-52); an org item's pending ones show in 待确认
+            if (platformOwned.has(v.item_id) && !versionUsable(v))
+                continue;
             const list = byItem.get(v.item_id) ?? [];
             list.push(v);
             byItem.set(v.item_id, list);
         }
         const installs = await countInstalls(this.db, items, byItem);
         const latest = await marketplaceLatest(this.db, this.config.get(), items, byItem);
+        const facts = await itemScopeFacts(this.db, items, await itemConfirmations(this.admin, items, byItem));
         return {
-            items: items.map((i) => itemView(i, byItem.get(i.id) ?? [], installs.get(i.id) ?? 0, latest.get(i.id))),
+            items: items.map((i) => itemView(i, byItem.get(i.id) ?? [], installs.get(i.id) ?? 0, latest.get(i.id), facts.get(i.id))),
             nextOffset,
         };
     }
@@ -381,20 +424,22 @@ let CatalogService = class CatalogService {
             .executeTakeFirst();
         if (!item)
             throw notFound();
-        const rows = await this.db
+        const rows = (await this.db
             .selectFrom("catalog_item_versions")
             .selectAll()
             .where("item_id", "=", itemId)
-            .execute();
+            .execute()).filter((v) => item.owner_org_id !== null || versionUsable(v));
         rows.sort((a, b) => newestFirst({ version: a.version, importedAt: a.imported_at }, { version: b.version, importedAt: b.imported_at }));
         const byItem = new Map([[item.id, rows]]);
         const installs = await countInstalls(this.db, [item], byItem);
         const latest = await marketplaceLatest(this.db, this.config.get(), [item], byItem);
+        const facts = await itemScopeFacts(this.db, [item], await itemConfirmations(this.admin, [item], byItem));
         return {
             item: {
-                ...itemView(item, rows, installs.get(item.id) ?? 0, latest.get(item.id)),
+                ...itemView(item, rows, installs.get(item.id) ?? 0, latest.get(item.id), facts.get(item.id)),
                 packageName: item.package_name,
                 deletedAt: item.deleted_at?.toISOString() ?? null,
+                platformVersion: item.platform_synced_version ?? item.latest_version,
             },
             versions: rows.map((v) => ({
                 version: v.version,
@@ -403,7 +448,7 @@ let CatalogService = class CatalogService {
                 integrity: v.integrity,
                 contentDigest: v.content_digest,
                 sourceDetail: v.source_detail ?? null,
-                manifest: v.manifest,
+                manifest: inAuthorOrder(v.manifest, v.appearance_order),
                 files: v.files,
                 size: Number(v.size),
                 extensionSha256: v.extension_sha256,
@@ -417,132 +462,159 @@ let CatalogService = class CatalogService {
         };
     }
     /**
-     * Changes the policy (audit `catalog.policy_changed`, not written when unchanged). Deleted /
-     * missing -> `catalog.item_not_found`.
+     * Deletes the item (soft delete, audit `catalog.removed`; requests still pending are cancelled in
+     * the same transaction): versions and stored files are kept (installed components still refer to
+     * them), its themes are soft-deleted (nothing refers to their rows), organizations no longer see
+     * it; the same name can later be imported again as a new item. Deleted / missing -> `catalog.item_not_found`. A platform plugin whose extension is
+     * still enabled on the deployment -> 409 `catalog.extension_enabled` (details
+     * `[{ extension, displayName }]`): disable it on the Extensions page first, as an uninstall
+     * requires. A disabled extension keeps its install record (the super admin uninstalls it on the
+     * Extensions page); an org-owned item's extension is taken out by `OwnedPluginCleanup`.
      */
-    async setPolicy(actor, itemId, policy, opts = {}) {
+    async remove(actor, itemId, opts = {}) {
         if (!UUID_RE.test(itemId))
             throw notFound();
-        await this.writePolicy(actor, itemId, policy, opts);
-        return this.view(itemId);
+        await this.writeRemove(actor, itemId, opts);
     }
-    async writePolicy(actor, itemId, policy, opts) {
-        const t = this.db;
+    /**
+     * The precheck of {@link remove} (the Platform tool's `plugins.delete`): throws what the delete
+     * would throw for an enabled extension; read-only, no locks.
+     */
+    async assertRemovable(itemId) {
+        if (!UUID_RE.test(itemId))
+            throw notFound();
+        await this.assertExtensionDisabled(this.kdb.db, itemId);
+    }
+    async writeRemove(actor, itemId, opts) {
         await this.adminLock.lockAndAuthorize(actor);
-        const row = await t
+        // The item row before the install lock the check below takes (the global lock order: the
+        // item, then the install lock, ruling P3-50; also the item before its theme rows in removeIn)
+        await this.db
             .selectFrom("catalog_items")
-            .select(["name", "policy"])
+            .select("id")
             .where("id", "=", itemId)
-            .where("deleted_at", "is", null)
             .forUpdate()
-            .executeTakeFirst();
-        if (!row)
-            throw notFound();
-        if (row.policy === policy)
-            return;
-        await t
-            .updateTable("catalog_items")
-            .set({ policy, updated_at: sql `now()` })
-            .where("id", "=", itemId)
             .execute();
-        await audit(t, {
-            actorAccountId: actor,
-            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
-            action: "catalog.policy_changed",
-            target: itemId,
-            detail: { name: row.name, from: row.policy, to: policy },
-        });
+        await this.assertExtensionDisabled(this.db, itemId, true);
+        if ((await this.removeIn(actor, itemId, opts)) === null)
+            throw notFound();
     }
     /**
-     * Deletes the item (soft delete, audit `catalog.removed`; requests still pending are cancelled in
-     * the same transaction): versions and stored files are kept (installed components still refer to
-     * them), organizations no longer see it; the same name can later be imported again as a new
-     * item. Deleted / missing -> `catalog.item_not_found`.
+     * A live platform item whose extension (the install of the item's name from its package) is
+     * enabled -> 409 `catalog.extension_enabled`. With `lock`, under the per-name install lock an
+     * enable takes too (the caller's transaction), so no enable slips in between.
      */
-    async remove(actor, itemId, opts = {}) {
-        if (!UUID_RE.test(itemId))
-            throw notFound();
-        await this.writeRemove(actor, itemId, opts);
+    async assertExtensionDisabled(db, itemId, lock = false) {
+        const item = await db
+            .selectFrom("catalog_items")
+            .select(["name", "package_name", "owner_org_id", "display_name"])
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!item || item.owner_org_id !== null)
+            return;
+        if (lock)
+            await this.installLock.lock(item.name);
+        const install = await 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", "=", item.name)
+            .executeTakeFirst();
+        if (install === undefined || install.desired_state !== "enabled")
+            return;
+        if (item.package_name !== null && install.package_name !== item.package_name)
+            return;
+        throw new ApiError("catalog.extension_enabled", `The extension "${item.name}" of this plugin is enabled on the deployment; disable it on the Extensions page first, then delete the plugin`, [{ extension: item.name, displayName: item.display_name ?? null }]);
     }
-    async writeRemove(actor, itemId, opts) {
+    /**
+     * The soft delete of {@link remove} in the caller's transaction, without its super admin check
+     * (pre-flight F14: the super admin's remove and an owner's delete or an org deletion,
+     * `OwnedItems.transferOrRemove`, share it): `deleted_at` set, a pending version cleared, the
+     * extension name claim of a first upload still waiting released (ruling P3-37, F10), its themes
+     * soft-deleted (refused with 409 `theme.platform_default` while one is the platform default),
+     * pending requests cancelled, audit `catalog.removed` (`actor` null: the kernel). Returns the
+     * removed item's name, or null when it is gone already.
+     */
+    async removeIn(actor, itemId, opts = {}) {
         const t = this.db;
-        await this.adminLock.lockAndAuthorize(actor);
+        const now = sql `now()`;
+        // Its themes go with it: refused while one is the platform default (themes spec §7), before
+        // anything is written
+        // (the theme rows FOR UPDATE first: the theme lock order is item, theme row, `uiTheme`)
+        const themes = await t
+            .selectFrom("platform_themes")
+            .select("id")
+            .where("catalog_item_id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .forUpdate()
+            .execute();
+        await assertNotPlatformDefault(t, themes.map((r) => r.id), () => "gone");
         const row = await t
             .updateTable("catalog_items")
             .set({
-            deleted_at: sql `now()`,
-            updated_at: sql `now()`,
+            deleted_at: now,
+            updated_at: now,
+            pending_version: null,
+            pending_by: null,
+            pending_at: null,
         })
             .where("id", "=", itemId)
             .where("deleted_at", "is", null)
-            .returning(["name"])
+            .returning(["name", "awaiting_confirmation", "package_name", "owner_org_id"])
             .executeTakeFirst();
         if (!row)
-            throw notFound();
+            return null;
+        // An org upload still waiting: free the name when nothing is installed under its claim
+        // (ruling P3-37, pre-flight F10). Under the install lock, so an install a running confirmation
+        // is committing is seen: that claim stays for its take-out or the cleanup job
+        if (row.awaiting_confirmation && row.package_name !== null) {
+            await this.installLock.lock(row.name);
+            await releaseExtensionClaim(t, row.name, row.package_name);
+        }
+        // Its themes go with it (themes spec §6): nothing refers to a theme row (a theme picked by an
+        // org or a person is an id that falls back once no live theme has it)
+        await t
+            .updateTable("platform_themes")
+            .set({ deleted_at: now, updated_at: now })
+            .where("catalog_item_id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .execute();
         // Pending requests for a deleted item are pointless: cancel them in the same transaction
         await cancelPendingRequests(t, { itemId }, actor, "item_removed", opts);
         await audit(t, {
             actorAccountId: actor,
             ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            // an org-owned item's removal shows in its owner org's audit log too
+            ...(row.owner_org_id !== null && { orgId: row.owner_org_id }),
             action: "catalog.removed",
             target: itemId,
-            detail: { name: row.name },
-        });
-    }
-    /**
-     * Installs the extension of one version of an item on the deployment
-     * (`ExtensionAdminOps.install`: a new install is disabled, a version change keeps the desired
-     * state; audit `extension.installed`), with the install record linked to the item (F-AA). The
-     * returned status may be `pending_approval` when the version's permissions are not approved yet.
-     * A version without an extension -> `catalog.no_extension`; item or version missing ->
-     * `catalog.item_not_found`.
-     */
-    async installToDeployment(actor, itemId, version, opts = {}) {
-        if (!UUID_RE.test(itemId))
-            throw notFound();
-        const item = await this.db
-            .selectFrom("catalog_items")
-            .select(["id", "name"])
-            .where("id", "=", itemId)
-            .where("deleted_at", "is", null)
-            .executeTakeFirst();
-        if (!item)
-            throw notFound();
-        const v = await this.db
-            .selectFrom("catalog_item_versions")
-            .select("extension_sha256")
-            .where("item_id", "=", itemId)
-            .where("version", "=", version)
-            .executeTakeFirst();
-        if (!v) {
-            throw new ApiError("catalog.item_not_found", `Version ${version} of this item not found`);
-        }
-        if (v.extension_sha256 === null) {
-            throw new ApiError("catalog.no_extension", `Plugin ${item.name} ${version} has no extension; there is nothing to install on the deployment`);
-        }
-        return this.ops.install(item.name, v.extension_sha256, actor, opts.actorTokenId, {
-            catalogItemId: itemId,
+            detail: {
+                name: row.name,
+                ...(row.owner_org_id !== null && { ownerOrgId: row.owner_org_id }),
+                ...(opts.reason !== undefined && { reason: opts.reason }),
+                ...opts.auditDetail,
+            },
         });
-    }
-    async view(itemId) {
-        return (await this.get(itemId)).item;
+        return { name: row.name };
     }
 };
-__decorate([
-    Transactional()
-], CatalogService.prototype, "writePolicy", null);
 __decorate([
     Transactional()
 ], CatalogService.prototype, "writeRemove", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], CatalogService.prototype, "removeIn", null);
 CatalogService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
-    __param(1, Inject(EnterpriseAdminLock)),
+    __param(1, Inject(SuperAdminLock)),
     __param(2, Inject(KernelConfigService)),
     __param(3, Inject(ExtensionInstalls)),
-    __param(4, Inject(ExtensionAdminOps)),
+    __param(4, Inject(ExtensionAdmin)),
     __param(5, Inject(PluginImport)),
     __param(6, Inject(MarketplacesService)),
-    __param(7, Inject(TransactionHost))
+    __param(7, Inject(PluginInstallLock)),
+    __param(8, Inject(TransactionHost))
 ], CatalogService);
 export { CatalogService };

package/dist/catalog/claude/agents.js

@@ -13,16 +13,21 @@ import { item } from "./report.js";
 export const GENERATED_AGENTS_DIR = ".capybara-generated/agents";
 /** Claude Code tool names -> Capybara tool keys (spec §16.4; anything else is dropped). */
 const TOOL_MAP = {
-    Bash: "sandbox_bash",
-    Read: "sandbox_read",
-    Write: "sandbox_write",
-    Edit: "sandbox_edit",
-    MultiEdit: "sandbox_edit",
-    Glob: "sandbox_glob",
-    Grep: "sandbox_grep",
-    Skill: "skill_load",
-    TodoWrite: "todo__write",
-    ToolSearch: "tool_search",
+    Bash: "Bash",
+    Read: "Read",
+    Write: "Write",
+    Edit: "Edit",
+    MultiEdit: "Edit",
+    Glob: "Glob",
+    Grep: "Grep",
+    Skill: "Skill",
+    AskUserQuestion: "AskUserQuestion",
+    ToolSearch: "ToolSearch",
+    Agent: "Agent",
+    Task: "Agent",
+    TodoWrite: "plugin__todo__write",
+    WebFetch: "WebFetch",
+    WebSearch: "WebSearch",
 };
 /** Claude ignores these for plugin agents: `not_applicable`. */
 const NOT_APPLICABLE = new Set(["permissionMode", "hooks", "mcpServers"]);

package/dist/catalog/claude/translate.js

@@ -836,6 +836,9 @@ export function translateClaudePlugin(files, o) {
         // the raw Claude agents/*.md the tree still holds and parse them as Capybara templates
         // (batch 12 review I1); normalizedManifest drops an empty list, so digests are unchanged
         agents: agents.agents.map((a) => ({ path: `./${a.path}` })),
+        // always empty, for the same reason: a Claude Code plugin's themes/*.json are not Capybara
+        // themes (themes spec §4); normalizedManifest drops the empty list
+        themes: [],
     };
     const checked = parsePluginManifest(manifest);
     if ("errors" in checked) {

package/dist/catalog/cli.d.ts

@@ -4,11 +4,21 @@ import { type ExtensionCli } from "../extensions/cli.js";
 import type { KernelLogger } from "../log.js";
 import { CatalogService } from "./catalog.service.js";
 import { PluginImport } from "./plugin-import.js";
+import type { PluginScope } from "./scope.js";
 /** {@link openCatalogCli}'s result: the extension CLI context plus the catalog services. */
 export interface CatalogCli extends ExtensionCli {
     catalog: CatalogService;
     /** Plugin import (prepare / confirm). The CLI acts without an account (actor `null`). */
     imports: PluginImport;
+    /**
+     * After an import's confirm: enqueues the item's plugin scope sync, as the admin console's
+     * confirm does, when its scope turns it on by itself (`all` or `named`). A failure only warns
+     * (the next worker start enqueues every item); returns whether it was enqueued.
+     */
+    enqueueScopeSync(item: {
+        id: string;
+        scope: PluginScope;
+    }): Promise<boolean>;
 }
 /** What the CLI can do with the deployment's object store, and why not when it cannot. */
 export type CliObjectStore = {
@@ -35,7 +45,7 @@ export declare function loadCliObjectStore(cli: Pick<ExtensionCli, "inspected" |
  * The CLI's plugin catalog context (`capybara plugins *`): {@link openExtensionCli} with the
  * catalog's {@link CatalogImportModule}, so {@link PluginImport} and {@link CatalogService} are the
  * kernel's providers. Imports run with actor `null` (the operator of the
- * deployment, like `capybara extensions install`: no enterprise-admin re-check, audits without an
+ * deployment, like `capybara extensions install`: no super-admin re-check, audits without an
  * actor, permission snapshots written with source `cli`). Files of the plugin (skills, connector
  * templates, icons) go to the deployment's object store, set up in-process from the declared or
  * installed object-store extension (see {@link loadCliObjectStore}; an installed package is synced

package/dist/catalog/cli.js

@@ -2,17 +2,22 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { OBJECT_STORE_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
+import { ClientBuilds } from "../client/client-builds.service.js";
 import { ApiError } from "../errors.js";
 import { planApprovals, snapshotCovers } from "../extensions/approvals.js";
 import { openExtensionCli } from "../extensions/cli.js";
 import { assertSecretsReachable } from "../extensions/host.js";
 import { importExtensionModule, matchesSection } from "../extensions/instance.js";
 import { packageRootOf, syncPackage } from "../extensions/sync.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { addJobOnce } from "../infra/queue/add-job-once.js";
+import { REDIS } from "../infra/tokens.js";
 import { packagePath } from "../packages/tgz.js";
 import { PrefixedStorage } from "../storage/storage.service.js";
 import { CatalogImportModule } from "./catalog.module.js";
 import { CatalogService } from "./catalog.service.js";
 import { PluginImport } from "./plugin-import.js";
+import { PLUGIN_SCOPE_QUEUE, scopeItemJob } from "./scope-sync.js";
 /**
  * Sets up the deployment's object-store extension inside the CLI process. The CLI hosts no
  * extensions, so this runs only the provider's `setup` with a context that offers `config` and
@@ -148,7 +153,7 @@ class CliStorage extends PrefixedStorage {
  * The CLI's plugin catalog context (`capybara plugins *`): {@link openExtensionCli} with the
  * catalog's {@link CatalogImportModule}, so {@link PluginImport} and {@link CatalogService} are the
  * kernel's providers. Imports run with actor `null` (the operator of the
- * deployment, like `capybara extensions install`: no enterprise-admin re-check, audits without an
+ * deployment, like `capybara extensions install`: no super-admin re-check, audits without an
  * actor, permission snapshots written with source `cli`). Files of the plugin (skills, connector
  * templates, icons) go to the deployment's object store, set up in-process from the declared or
  * installed object-store extension (see {@link loadCliObjectStore}; an installed package is synced
@@ -174,11 +179,34 @@ export async function openCatalogCli(config, log, opts = {}) {
         // inspection (the registry), marketplace imports are not offered by the CLI.
         const imports = cli.app.get(PluginImport);
         imports.useCliStorage(storage);
+        // and so do the client files of a package with client code (stored with the package)
+        cli.app.get(ClientBuilds).useCliStorage(storage);
         const catalog = cli.app.get(CatalogService);
+        const db = cli.app.get(KernelDb);
+        const redis = cli.app.get(REDIS);
         return {
             ...cli,
             catalog,
             imports,
+            async enqueueScopeSync(item) {
+                if (item.scope === "optional")
+                    return false;
+                try {
+                    const row = await db.db
+                        .selectFrom("catalog_items")
+                        .select("scope_version")
+                        .where("id", "=", item.id)
+                        .executeTakeFirst();
+                    if (!row)
+                        return false;
+                    await addJobOnce(redis, PLUGIN_SCOPE_QUEUE, scopeItemJob(item.id, row.scope_version));
+                    return true;
+                }
+                catch (err) {
+                    log.warn("cannot enqueue the plugin scope sync; the next worker start converges the orgs", { itemId: item.id, err });
+                    return false;
+                }
+            },
             async close() {
                 await cli.close();
                 await removeSyncDir();