@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/catalog/admin-catalog.controller.js

@@ -10,13 +10,15 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Put, Req, Res, } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
-import { CurrentPrincipal, EnterpriseAdmin, patTokenId, requireUser, } from "../identity/principal.js";
+import { CurrentPrincipal, patTokenId, requireUser, SuperAdmin, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
 import { CATALOG_LIST_MAX_LIMIT, CatalogService, } from "./catalog.service.js";
+import { CatalogScopeService } from "./catalog-scope.service.js";
 import { sendCatalogIcon } from "./org-catalog.controller.js";
 import { OrgCatalogService } from "./org-catalog.service.js";
 import { PluginImport } from "./plugin-import.js";
+import { PlatformPluginUpdater, } from "./plugin-upgrade.js";
 const NpmBody = z.object({
     package: z.string().min(1).max(214),
     version: z.string().min(1).max(256).optional(),
@@ -28,19 +30,46 @@ const GitBody = z
     path: z.string().min(1).max(512).optional(),
 })
     .strict();
-const PolicyBody = z.object({ policy: z.enum(["allow", "needs_approval", "disabled"]) });
-const InstallBody = z.object({ version: z.string().min(1).max(256) });
-const ConfirmBody = z.object({
-    reviewHash: z.string().min(1).max(128),
-    deployExtension: z.boolean(),
+const Scope = z.enum(["all", "optional", "named"]);
+const Orgs = z.array(z.string().min(1).max(128)).max(1000);
+const Hash = z.string().min(1).max(128);
+const ConfirmBody = z
+    .object({
+    reviewHash: Hash,
+    /** The new item's scope (default `optional`); `orgs` only with `named`. */
+    scope: Scope.optional(),
+    orgs: Orgs.optional(),
     /** Skill names suggested as pinned (spec §9.1); omitted keeps the plugin's flags. */
     pinnedSuggestions: z.array(z.string().min(1).max(64)).max(50).optional(),
+})
+    .strict();
+/** `{ scope, orgs? }` (a scope change) or `{ disabled: true }` (a disable), not both. */
+const ScopePreviewBody = z
+    .object({ scope: Scope.optional(), orgs: Orgs.optional(), disabled: z.literal(true).optional() })
+    .strict()
+    .refine((b) => (b.disabled === true) !== (b.scope !== undefined), {
+    message: "send either scope (with orgs for named) or disabled: true",
+})
+    .refine((b) => b.disabled === undefined || b.orgs === undefined, {
+    message: "orgs: only allowed with scope named",
+    path: ["orgs"],
 });
+const ScopeBody = z.object({ scope: Scope, orgs: Orgs.optional(), scopeHash: Hash }).strict();
+const DisabledBody = z.object({ disabled: z.boolean(), scopeHash: Hash.optional() }).strict();
+const ShownBody = z.object({ shownToOthers: z.boolean() }).strict();
 const ListQuery = z.object({
     includeDeleted: z.enum(["true", "false"]).optional(),
     limit: z.coerce.number().int().min(1).max(CATALOG_LIST_MAX_LIMIT).optional(),
     offset: z.coerce.number().int().min(0).max(1_000_000).optional(),
+    /** `true`: only the items waiting for a permission confirmation (not paged). */
+    pending: z.enum(["true", "false"]).optional(),
 });
+const ConfirmPermissionsBody = z.object({ permissionsHash: Hash }).strict();
+/** The reason shown to the owner org in its `upload_rejected` notice (optional). */
+const RejectBody = z.object({ reason: z.string().trim().min(1).max(1000).optional() }).strict();
+const Version = z.string().min(1).max(256);
+const UpdatePreviewBody = z.object({ version: Version }).strict();
+const UpdateBody = z.object({ version: Version, diffHash: Hash }).strict();
 const actorOpts = (actor) => {
     const tokenId = patTokenId(actor);
     return tokenId !== undefined ? { actorTokenId: tokenId } : {};
@@ -49,28 +78,44 @@ class CatalogImportConfirmBody extends createZodDto(ConfirmBody, "CatalogImportC
 }
 class CatalogGitImportBody extends createZodDto(GitBody, "CatalogGitImportBody") {
 }
-class CatalogDeploymentInstallBody extends createZodDto(InstallBody, "CatalogDeploymentInstallBody") {
-}
 class CatalogItemsQuery extends createZodDto(ListQuery, "CatalogItemsQuery") {
 }
 class CatalogNpmImportBody extends createZodDto(NpmBody, "CatalogNpmImportBody") {
 }
-class CatalogPolicyBody extends createZodDto(PolicyBody, "CatalogPolicyBody") {
+class CatalogScopePreviewBody extends createZodDto(ScopePreviewBody, "CatalogScopePreviewBody") {
+}
+class CatalogScopeBody extends createZodDto(ScopeBody, "CatalogScopeBody") {
+}
+class CatalogConfirmPermissionsBody extends createZodDto(ConfirmPermissionsBody, "CatalogConfirmPermissionsBody") {
+}
+class CatalogShownBody extends createZodDto(ShownBody, "CatalogShownBody") {
+}
+class CatalogRejectBody extends createZodDto(RejectBody, "CatalogRejectBody") {
+}
+class CatalogDisabledBody extends createZodDto(DisabledBody, "CatalogDisabledBody") {
+}
+class CatalogUpdatePreviewBody extends createZodDto(UpdatePreviewBody, "CatalogUpdatePreviewBody") {
+}
+class CatalogUpdateBody extends createZodDto(UpdateBody, "CatalogUpdateBody") {
 }
 /**
- * The enterprise catalog (`/api/v1/admin/catalog/*`, enterprise admins): plugin import (upload / npm
- * prepare, then confirm), the item list and detail, policy, delete, and installing an item's
- * extension on the deployment. Writes re-check the enterprise admin inside the service's lock and are
+ * The platform catalog (`/api/v1/admin/catalog/*`, super admins): plugin import (upload / npm
+ * prepare, then confirm, which installs the plugin's extension), the item list and detail, scope and
+ * disable (previewed, then confirmed with `scopeHash`), delete. Writes re-check the super admin inside the service's lock and are
  * audited.
  */
 let AdminCatalogController = class AdminCatalogController {
     catalog;
     pluginImport;
     orgCatalog;
-    constructor(catalog, pluginImport, orgCatalog) {
+    scope;
+    updater;
+    constructor(catalog, pluginImport, orgCatalog, scope, updater) {
         this.catalog = catalog;
         this.pluginImport = pluginImport;
         this.orgCatalog = orgCatalog;
+        this.scope = scope;
+        this.updater = updater;
     }
     /**
      * Prepares the import of an uploaded plugin (an npm-pack tgz as the raw body,
@@ -126,11 +171,13 @@ let AdminCatalogController = class AdminCatalogController {
         return this.pluginImport.staged(stagingId);
     }
     /**
-     * Confirms a staged import: approves the plugin's extension when this import installs it (writes
-     * its snapshot) and creates the item or adds the version; with `deployExtension` it installs and
-     * enables the plugin's own extension after the commit and returns `{ item, deploy }`, where
-     * `deploy` says enabled / failed (+ code); a failed deploy does not make the committed import fail
-     * (retry from the extension admin by sha256). A foreseeable failure (a downgrade to a version with
+     * Confirms a staged import: approves the plugin's extension when this import installs or upgrades
+     * it (writes its snapshot), creates the item (with `scope`, default `optional`; `orgs` only with
+     * `named`, each an existing org, else 400 `validation_failed`) or adds the version, installs and
+     * enables the plugin's own extension after the commit and enqueues the item's scope sync; returns
+     * `{ item, deploy }`, where `deploy` says enabled / failed (+ code), null without an extension to
+     * deploy; a failed deploy does not make the committed import fail (retry from the extension admin
+     * by sha256). An unknown field (the removed `deployExtension`) -> 400 `validation_failed`. A foreseeable failure (a downgrade to a version with
      * unrun migrations) is a 409 `extension.downgrade_unsupported` before anything is written.
      * Staging missing or expired -> 404 `plugin.staging_not_found`; `reviewHash` differs or the
      * extension on the deployment changed -> 409 `plugin.review_stale`. `pinnedSuggestions` (skill
@@ -139,8 +186,12 @@ let AdminCatalogController = class AdminCatalogController {
      */
     confirm(principal, stagingId, body) {
         const actor = requireUser(principal);
-        const { pinnedSuggestions, ...rest } = body;
-        return this.pluginImport.confirm(actor.account.id, stagingId, { ...rest, ...(pinnedSuggestions !== undefined && { pinnedSuggestions }) }, actorOpts(actor));
+        return this.scope.confirmImport(actor.account.id, stagingId, {
+            reviewHash: body.reviewHash,
+            ...(body.scope !== undefined && { scope: body.scope }),
+            ...(body.orgs !== undefined && { orgs: body.orgs }),
+            ...(body.pinnedSuggestions !== undefined && { pinnedSuggestions: body.pinnedSuggestions }),
+        }, actorOpts(actor));
     }
     /**
      * The item list (`includeDeleted=true` includes deleted items). Paging: `limit` (default 200, at
@@ -149,6 +200,7 @@ let AdminCatalogController = class AdminCatalogController {
     list(q) {
         return this.catalog.page({
             includeDeleted: q.includeDeleted === "true",
+            ...(q.pending === "true" && { pending: true }),
             ...(q.limit !== undefined && { limit: q.limit }),
             ...(q.offset !== undefined && { offset: q.offset }),
         });
@@ -168,24 +220,104 @@ let AdminCatalogController = class AdminCatalogController {
     async icon(id, reply) {
         await sendCatalogIcon(reply, await this.orgCatalog.icon(id, true));
     }
-    /** 改策略（allow / needs_approval / disabled）。 */
-    setPolicy(principal, id, body) {
+    /**
+     * What a scope change (`{ scope, orgs? }`, `orgs` only with `named`) or a disable
+     * (`{ disabled: true }`) would take away: `{ affected: [{ orgId, orgName, agents,
+     * connectorsKept }], needsConfig, scopeHash }` (spec §5 rule 8; nothing written; the connectors
+     * stay as the orgs' own). A builtin item -> 409 `plugin.builtin`; unknown
+     * orgs -> 400 `validation_failed`.
+     */
+    previewScope(id, body) {
+        return this.scope.preview(id, body.scope === undefined
+            ? { disabled: true }
+            : { scope: body.scope, ...(body.orgs !== undefined && { orgs: body.orgs }) });
+    }
+    /**
+     * Changes the scope, confirmed with the preview's `scopeHash` (recomputed under the item row lock;
+     * a difference -> 409 `plugin.scope_stale`); bumps the scope version, audits
+     * `catalog.scope_changed` and enqueues the scope sync. Builtin -> 409 `plugin.builtin`.
+     */
+    setScope(principal, id, body) {
         const actor = requireUser(principal);
-        return this.catalog.setPolicy(actor.account.id, id, body.policy, actorOpts(actor));
+        return this.scope.setScope(actor.account.id, id, {
+            scope: body.scope,
+            scopeHash: body.scopeHash,
+            ...(body.orgs !== undefined && { orgs: body.orgs }),
+        }, actorOpts(actor));
     }
-    /** 删除条目（软删除，已安装的组件不受影响）。 */
-    async remove(principal, id) {
+    /**
+     * Disables the plugin on the whole deployment (`scopeHash` of the `{ disabled: true }` preview
+     * required; the scope sync then uninstalls it everywhere, its scope and the org switches are kept)
+     * or enables it again (no hash; the sync reinstalls where it is wanted). Builtin -> 409
+     * `plugin.builtin`; a stale hash -> 409 `plugin.scope_stale`.
+     */
+    setDisabled(principal, id, body) {
         const actor = requireUser(principal);
-        await this.catalog.remove(actor.account.id, id, actorOpts(actor));
+        return this.scope.setDisabled(actor.account.id, id, {
+            disabled: body.disabled,
+            ...(body.scopeHash !== undefined && { scopeHash: body.scopeHash }),
+        }, actorOpts(actor));
+    }
+    /**
+     * Confirms the item's extension permissions (the admin's 待确认; body `{ permissionsHash }` from
+     * the item view): approves the current permission set (snapshot source `web`) and installs and
+     * enables an extension that was never deployed. A changed set -> 409 `extension.approval_stale`;
+     * nothing to confirm -> 409 `extension.not_pending`. Returns the item. An org's upload
+     * (`owner.kind` org, ruling P3-10): the digest of its pending version's package; a first version
+     * is installed, approved, enabled and synced, a new version applied by the platform update
+     * (the item removed meanwhile -> 409 `catalog.item_removed`, P3-21).
+     */
+    confirmPermissions(principal, id, body) {
+        const actor = requireUser(principal);
+        return this.scope.confirmPermissions(actor.account.id, id, body.permissionsHash, actorOpts(actor));
+    }
+    /**
+     * Rejects an org upload's pending version (ruling P3-10; body `{ reason? }`, told to the owner
+     * org in `upload_rejected`): a first version is removed (its name free again), a new version's
+     * pending state cleared. Nothing pending, or a platform item (pre-flight F11) -> 409
+     * `extension.not_pending`. 204.
+     */
+    async reject(principal, id, body) {
+        const actor = requireUser(principal);
+        await this.scope.reject(actor.account.id, id, body.reason ?? null, actorOpts(actor));
+    }
+    /**
+     * Whether orgs outside a `named` item's list see it as requestable (spec §5.1 rule 1). Hiding it
+     * keeps pending requests as they are; new requests from unlisted orgs are then 404. Never makes
+     * anything usable, so no preview and no scope sync. Audits `catalog.shown_changed`.
+     */
+    setShown(principal, id, body) {
+        const actor = requireUser(principal);
+        return this.scope.setShown(actor.account.id, id, body.shownToOthers, actorOpts(actor));
+    }
+    /**
+     * What updating the platform plugin to `version` would do (spec §7.1, `PlatformPluginUpdater`):
+     * `{ itemId, name, from, to, components: [{ kind, id, name, change: added | removed | upgrade |
+     * downgrade | same, from, to, updatedOnOwn, ownScope, pinnedOrgs, kept? }], extension,
+     * connectorOrgs: [{ orgId, connectors, needsConfig }], diffHash }`. Nothing written. The same
+     * version, a target the deployment's extension or a dependent plugin cannot take -> 409
+     * `plugin.upgrade_target_invalid`; an added skill named like one in use where the plugin is on
+     * -> 409 `plugin.skill_conflict`; disabled -> 403 `catalog.item_disabled`.
+     */
+    previewUpdate(id, body) {
+        return this.updater.preview(id, body.version);
     }
     /**
-     * Installs the extension of a version of an item on the deployment (a new install starts disabled;
-     * unapproved permissions still need approval). A version without an extension -> 409
-     * `catalog.no_extension`.
+     * Updates the platform plugin, confirmed with the preview's `diffHash` (recomputed under the item
+     * lock; a difference -> 409 `plugin.upgrade_stale`; another update running -> 409
+     * `plugin.install_in_progress`). A failure undoes everything -> 502 `plugin.upgrade_failed`.
+     * Audits `plugin.platform_updated`. A version an org upload waits with (or an item whose first
+     * version waits) -> 409 `catalog.item_pending`: confirm it in 待确认 (pre-flight F8); the
+     * preview answers the same.
      */
-    installToDeployment(principal, id, body) {
+    update(principal, id, body) {
+        const actor = requireUser(principal);
+        return this.updater.update(actor.account.id, id, body, actorOpts(actor));
+    }
+    /** 删除条目（软删除，已安装的组件不受影响）。 */
+    async remove(principal, id) {
         const actor = requireUser(principal);
-        return this.catalog.installToDeployment(actor.account.id, id, body.version, actorOpts(actor));
+        await this.catalog.remove(actor.account.id, id, actorOpts(actor));
     }
 };
 __decorate([
@@ -231,29 +363,68 @@ __decorate([
     __param(1, Res())
 ], AdminCatalogController.prototype, "icon", null);
 __decorate([
-    Put("items/:id/policy"),
+    Post("items/:id/scope/preview"),
+    HttpCode(200),
+    __param(0, Param("id")),
+    __param(1, ZBody(CatalogScopePreviewBody))
+], AdminCatalogController.prototype, "previewScope", null);
+__decorate([
+    Put("items/:id/scope"),
     __param(0, CurrentPrincipal()),
     __param(1, Param("id")),
-    __param(2, ZBody(CatalogPolicyBody))
-], AdminCatalogController.prototype, "setPolicy", null);
+    __param(2, ZBody(CatalogScopeBody))
+], AdminCatalogController.prototype, "setScope", null);
 __decorate([
-    Delete("items/:id"),
+    Put("items/:id/disabled"),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("id")),
+    __param(2, ZBody(CatalogDisabledBody))
+], AdminCatalogController.prototype, "setDisabled", null);
+__decorate([
+    Post("items/:id/confirm"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("id")),
+    __param(2, ZBody(CatalogConfirmPermissionsBody))
+], AdminCatalogController.prototype, "confirmPermissions", null);
+__decorate([
+    Post("items/:id/reject"),
     HttpCode(204),
     __param(0, CurrentPrincipal()),
-    __param(1, Param("id"))
-], AdminCatalogController.prototype, "remove", null);
+    __param(1, Param("id")),
+    __param(2, ZBody(CatalogRejectBody))
+], AdminCatalogController.prototype, "reject", null);
+__decorate([
+    Put("items/:id/shown"),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("id")),
+    __param(2, ZBody(CatalogShownBody))
+], AdminCatalogController.prototype, "setShown", null);
 __decorate([
-    Post("items/:id/install-deployment"),
+    Post("items/:id/update/preview"),
     HttpCode(200),
+    __param(0, Param("id")),
+    __param(1, ZBody(CatalogUpdatePreviewBody))
+], AdminCatalogController.prototype, "previewUpdate", null);
+__decorate([
+    Put("items/:id/update"),
     __param(0, CurrentPrincipal()),
     __param(1, Param("id")),
-    __param(2, ZBody(CatalogDeploymentInstallBody))
-], AdminCatalogController.prototype, "installToDeployment", null);
+    __param(2, ZBody(CatalogUpdateBody))
+], AdminCatalogController.prototype, "update", null);
+__decorate([
+    Delete("items/:id"),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("id"))
+], AdminCatalogController.prototype, "remove", null);
 AdminCatalogController = __decorate([
     Controller("api/v1/admin/catalog"),
-    EnterpriseAdmin(),
+    SuperAdmin(),
     __param(0, Inject(CatalogService)),
     __param(1, Inject(PluginImport)),
-    __param(2, Inject(OrgCatalogService))
+    __param(2, Inject(OrgCatalogService)),
+    __param(3, Inject(CatalogScopeService)),
+    __param(4, Inject(PlatformPluginUpdater))
 ], AdminCatalogController);
 export { AdminCatalogController };

package/dist/catalog/catalog-content.d.ts

@@ -8,29 +8,42 @@ import type { StorageService } from "../storage/storage.service.js";
 import type { ConnectorTemplateRef, CreateConnectorInput } from "../tools/connectors.service.js";
 import type { CatalogItemView } from "./catalog.service.js";
 import type { ConnectorInstallInput, PluginInstallInput, PluginInstallView } from "./plugin-install.js";
-import type { CatalogRequestView } from "./requests.service.js";
+import type { OrgPluginState, PluginScope } from "./scope.js";
 /** A catalog item from an organization's view (`GET /orgs/:orgId/catalog`). */
-export interface OrgCatalogItem extends Omit<CatalogItemView, "installs" | "marketplaceId" | "latestMarketplaceVersion" | "newerInMarketplace"> {
+export interface OrgCatalogItem extends Omit<CatalogItemView, "installs" | "marketplaceId" | "latestMarketplaceVersion" | "newerInMarketplace" | "scopeOrgs" | "enabledOrgs" | "offCount" | "pending" | "shownToOthers" | "awaitingConfirmation" | "pendingVersion"> {
+    /** The owner org only (absent for other orgs): its upload waits for the super admin (P3-9). */
+    awaitingConfirmation?: boolean;
+    /** The owner org only (absent for other orgs): the version waiting for that confirmation. */
+    pendingVersion?: string | null;
+    scope: PluginScope;
+    /** Shipped with the deployment (a required bootstrap plugin): on in every org, never switchable. */
+    builtin: boolean;
     /**
-     * `yes` installable now; `needs_approval` needs enterprise admin approval (install returns 202 and
-     * creates a request); `granted` approved for this org; `disabled` disabled by the enterprise admin
-     * (members don't see it); `not_deployed` the plugin's extension is not on the deployment.
+     * The effective state in this org: `on`, `off`, `needs_config` (installed with an on connector
+     * template that has no connector here, ruling P2-10; or wanted but not installed, and the
+     * install needs inputs), `unavailable` (disabled by the super admin; members don't see it)
+     * or `not_offered` (a `named` item shown to orgs outside its list: requestable, not usable).
      */
-    installable: "yes" | "needs_approval" | "granted" | "disabled" | "not_deployed";
+    state: OrgPluginState;
+    /** The org admin may switch it (never for `all` and builtin items). */
+    switchable: boolean;
+    /** The plugin's extension (or a template's connector extension) is not on the deployment. */
+    notDeployed: boolean;
     /**
      * This org's live plugin install of the item (installing, installed or upgrading);
-     * `upgradeAvailable` is the version it can be upgraded to now (spec §10), null when none.
+     * `upgradeAvailable` is always null since plugin scope phase 2 (no per-org upgrade, ruling F2;
+     * kept for the web until its upgrade dialog goes).
      */
     installed: {
         pluginInstallId: string;
         version: string;
         upgradeAvailable: string | null;
     } | null;
-    /** This org's latest request for the item. */
+    /** This org's pending request for the item (spec §5.1), null when none. */
     request: {
         id: string;
-        stage: "org" | "deployment";
-        status: string;
+        kind: "access" | "enable";
+        createdAt: string;
     } | null;
 }
 /**
@@ -57,15 +70,25 @@ export interface OrgCatalogDetail {
     /** The plugin's extension (its name), null without one. */
     extension: string | null;
     templates: OrgCatalogTemplate[];
-    /** The plugin's dependencies (name and range). */
+    /**
+     * The plugin's dependencies (name and range); `implied` ones are the connector extensions its
+     * templates use that the org has off: the install switches them on first.
+     */
     dependencies: {
         name: string;
         range: string;
+        implied?: true;
     }[];
     /** The skill directories. */
     skills: string[];
     /** The agent template files (`agents/<name>.md`, sub-agents spec §16). */
     agents: string[];
+    /**
+     * An installed plugin whose connector templates on in the org miss a connector there
+     * (`needs_config`, ruling P2-10): those templates, for `POST …/catalog/:itemId/connectors`;
+     * empty otherwise (Task 10).
+     */
+    missingTemplates: OrgCatalogTemplate[];
 }
 /**
  * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
@@ -76,7 +99,6 @@ export declare function orgTemplateView(id: string, file: ConnectorTemplateFile)
 export interface CatalogIcon {
     data: Uint8Array;
     contentType: "image/svg+xml" | "image/png";
-    policy: "allow" | "needs_approval" | "disabled";
 }
 /** The parts of a catalog version row an org install reads. */
 export interface CatalogVersionFiles {
@@ -88,6 +110,16 @@ export interface CatalogVersionFiles {
         sha256: string;
     }[];
 }
+/**
+ * The digest of a skill's files (paths relative to the skill directory): equal digests = the same
+ * content. Shared by the org upgrade diff and the platform components.
+ */
+export declare function skillFilesDigest(files: {
+    path: string;
+    sha256: string;
+}[]): string;
+/** The digest of the files under `dir/` of a catalog version (paths relative to it). */
+export declare function dirDigest(row: CatalogVersionFiles, dir: string): string;
 /** Whether the item's latest version has an icon; unreadable counts as none. */
 export declare function catalogHasIcon(db: KernelSchemaDb, itemId: string): Promise<boolean>;
 /**
@@ -99,12 +131,13 @@ export declare function catalogHasIcon(db: KernelSchemaDb, itemId: string): Prom
  */
 export declare function readCatalogIcon(db: KernelSchemaDb, storage: StorageService, itemId: string, includeDisabled: boolean): Promise<CatalogIcon>;
 export type { ConnectorInstallInput };
-/** The input of `POST /orgs/:orgId/catalog/:itemId/install` (default version: the latest). */
-export interface OrgInstallInput extends PluginInstallInput {
-    version?: string;
-}
-/** Install result: 201 installed; 202 needs enterprise admin approval, a request was created (or escalated). */
-export type OrgInstallResult = {
+/**
+ * The input of `POST /orgs/:orgId/catalog/:itemId/install`: the platform version is installed
+ * (ruling P2-17), so there is no version.
+ */
+export type OrgInstallInput = PluginInstallInput;
+/** Install result: 201 installed. */
+export interface OrgInstallResult {
     status: 201;
     installed: {
         itemId: string;
@@ -113,26 +146,19 @@ export type OrgInstallResult = {
     };
     /** The install view (its components, dependency installs included). */
     install: PluginInstallView;
-} | {
-    status: 202;
-    request: CatalogRequestView;
-};
-/** Upgrade result: 200 upgraded (the install view); 202 needs enterprise admin approval, a request was created. */
-export type OrgUpgradeResult = {
-    status: 200;
-    install: PluginInstallView;
-} | {
-    status: 202;
-    request: CatalogRequestView;
-};
+}
 /**
  * The org actions installing / uninstalling a plugin needs: the union over its components (an
  * extension -> `org.extensions.manage`, skills -> `skills.manage`, connector templates ->
  * `connectors.manage`, agent templates -> `agents.manage`), re-checked inside the org row lock.
  */
 export declare function requiredActions(m: PluginManifest): OrgAction[];
-/** Locks the org row in the caller's transaction (`orgLock` joins it) and re-checks the actor can do every action (else `forbidden`). */
-export declare function lockOrgForActions(orgLock: Pick<OrgLock, "lockAndAuthorize">, orgId: string, actor: string, actions: OrgAction[]): Promise<void>;
+/**
+ * Locks the org row in the caller's transaction (`orgLock` joins it) and re-checks the actor can do
+ * every action (else `forbidden`). `actor` null is the kernel itself (the plugin scope sync): the
+ * lock only.
+ */
+export declare function lockOrgForActions(orgLock: Pick<OrgLock, "lock" | "lockAndAuthorize">, orgId: string, actor: string | null, actions: OrgAction[]): Promise<void>;
 /** The value at a dot path of `v` (own keys only), undefined when absent. */
 export declare function getPath(v: unknown, path: string): unknown;
 /** Sets the value at a dot path of `obj`, creating the objects on the way. */

package/dist/catalog/catalog-content.js

@@ -1,5 +1,5 @@
 // Reading a catalog version's stored content (templates, skills, agent templates, icons) and the
-// org install helpers (no providers), shared by PluginInstaller, PluginUpgrader and
+// org install helpers (no providers), shared by PluginInstaller, PlatformPluginUpdater and
 // OrgCatalogService: kept out of org-catalog.service.ts so the installer's module never imports a
 // module whose provider injects PluginInstaller (an ESM import cycle would run decorators early).
 import { createHash } from "node:crypto";
@@ -31,6 +31,25 @@ export function orgTemplateView(id, file) {
     };
 }
 const iconNotFound = () => new ApiError("catalog.icon_not_found", "This catalog item has no icon");
+/**
+ * The digest of a skill's files (paths relative to the skill directory): equal digests = the same
+ * content. Shared by the org upgrade diff and the platform components.
+ */
+export function skillFilesDigest(files) {
+    return createHash("sha256")
+        .update(files
+        .map((f) => `${f.path}\0${f.sha256}\n`)
+        .sort()
+        .join(""))
+        .digest("hex");
+}
+/** The digest of the files under `dir/` of a catalog version (paths relative to it). */
+export function dirDigest(row, dir) {
+    const prefix = `${dir}/`;
+    return skillFilesDigest(row.files
+        .filter((f) => f.path.startsWith(prefix))
+        .map((f) => ({ path: f.path.slice(prefix.length), sha256: f.sha256 })));
+}
 /**
  * The item's latest version row; item missing, deleted or (when `includeDisabled` is false)
  * disabled -> `catalog.item_not_found`.
@@ -40,13 +59,13 @@ async function latestVersionRow(db, itemId, includeDisabled) {
         throw itemNotFound();
     const item = await db
         .selectFrom("catalog_items")
-        .select(["latest_version", "policy"])
+        .select(["latest_version", "disabled"])
         .where("id", "=", itemId)
         .where("deleted_at", "is", null)
         .executeTakeFirst();
     // An item the caller cannot see is "not found" before any version / storage is read, so "no icon"
     // never reveals that it exists
-    if (!item || (!includeDisabled && item.policy === "disabled"))
+    if (!item || (!includeDisabled && item.disabled))
         throw itemNotFound();
     const v = await db
         .selectFrom("catalog_item_versions")
@@ -82,7 +101,7 @@ export async function catalogHasIcon(db, itemId) {
  * (checked at import, this guards against tampered storage) -> `internal`.
  */
 export async function readCatalogIcon(db, storage, itemId, includeDisabled) {
-    const { item, v } = await latestVersionRow(db, itemId, includeDisabled);
+    const { v } = await latestVersionRow(db, itemId, includeDisabled);
     const path = iconPath(v);
     const f = path === undefined ? undefined : v.files.find((x) => x.path === path);
     if (path === undefined || !f)
@@ -96,7 +115,6 @@ export async function readCatalogIcon(db, storage, itemId, includeDisabled) {
     return {
         data: file.data,
         contentType: /\.svg$/i.test(path) ? "image/svg+xml" : "image/png",
-        policy: item.policy,
     };
 }
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -119,8 +137,16 @@ export function requiredActions(m) {
         out.push("agents.manage");
     return out.length > 0 ? out : ["org.extensions.manage"];
 }
-/** Locks the org row in the caller's transaction (`orgLock` joins it) and re-checks the actor can do every action (else `forbidden`). */
+/**
+ * Locks the org row in the caller's transaction (`orgLock` joins it) and re-checks the actor can do
+ * every action (else `forbidden`). `actor` null is the kernel itself (the plugin scope sync): the
+ * lock only.
+ */
 export async function lockOrgForActions(orgLock, orgId, actor, actions) {
+    if (actor === null) {
+        await orgLock.lock(orgId);
+        return;
+    }
     const [first, ...rest] = actions;
     const { role } = await orgLock.lockAndAuthorize(orgId, actor, first);
     for (const a of rest) {
@@ -175,12 +201,12 @@ export function findConnectorIn(registry, plugin, kind) {
  */
 export function templatePluginProblem(d, template) {
     if (!d.findConnector(template.plugin, template.connector)) {
-        return `Connector extension ${template.plugin} providing "${template.connector}" is not deployed; ask the enterprise admin to install and enable it`;
+        return `Connector extension ${template.plugin} providing "${template.connector}" is not deployed; ask the super admin to install and enable it`;
     }
     const range = template.pluginVersion;
     const version = d.pluginVersion(template.plugin);
     if (range !== undefined && version !== undefined && !satisfiesRange(version, range)) {
-        return `Connector extension ${template.plugin} is deployed at version ${version}, but the template needs ${range}; ask the enterprise admin to upgrade it`;
+        return `Connector extension ${template.plugin} is deployed at version ${version}, but the template needs ${range}; ask the super admin to upgrade it`;
     }
     return undefined;
 }

package/dist/catalog/catalog-import.module.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The platform side of the catalog: marketplaces, the one import review (prepare -> confirm), the
+ * items and their platform components. The CLI's `capybara plugins *` and `capybara bootstrap` run on this
+ * part alone.
+ */
+export declare class CatalogImportModule {
+}