@capybara-hq/kernel 0.1.0-rc.6 → 0.1.0-rc.7

package/dist/platform/ops/plugins.ops.d.ts

@@ -4,14 +4,16 @@ import { OrgCatalogService } from "../../catalog/org-catalog.service.js";
 import { PluginInstaller } from "../../catalog/plugin-install.js";
 import { PlatformPluginUpdater } from "../../catalog/plugin-upgrade.js";
 import { OrgExtensionConfigs } from "../../extensions/org-config.js";
+import { ExtensionAvailability } from "../../extensions/unavailable.js";
 import { KernelDb } from "../../infra/database/kernel-db.js";
 import { PlatformOperations } from "../registry.js";
-export declare const OTHER_ORG = "This plugin belongs to another org; use the admin console.";
+export { OTHER_ORG } from "./other-orgs.js";
 export declare const NEEDS_INPUT = "This plugin needs configuration a person must enter; ask them to enable it on the \u63D2\u4EF6 page.";
 /**
  * Plugin operations of the `Platform` tool (spec §7): the org's view (list, get, switch on or off)
  * and the super admin's platform view (list, get, update with its preview). Every platform result
- * goes through {@link redactOrgs}: other orgs only as counts (spec §6.1).
+ * shows the admin console's data in full for platform items and the org's own (spec §14.5 item 1);
+ * plugins other orgs own are only counted, and reading or updating one is refused.
  */
 export declare class PluginsOperations implements OnModuleInit {
     private readonly registry;
@@ -21,13 +23,13 @@ export declare class PluginsOperations implements OnModuleInit {
     private readonly installer;
     private readonly extensions;
     private readonly kdb;
-    constructor(registry: PlatformOperations, orgCatalog: OrgCatalogService, catalog: CatalogService, updater: PlatformPluginUpdater, installer: PluginInstaller, extensions: OrgExtensionConfigs, kdb: KernelDb);
+    private readonly availability;
+    constructor(registry: PlatformOperations, orgCatalog: OrgCatalogService, catalog: CatalogService, updater: PlatformPluginUpdater, installer: PluginInstaller, extensions: OrgExtensionConfigs, kdb: KernelDb, availability: ExtensionAvailability);
     /**
-     * Refuses a super-admin operation on an item another org owns: its results would describe that
-     * org's private plugin in this org's log (spec §6.1). Platform items and the org's own pass.
+     * Installed (or builtin) plugins whose extension stopped loading: the reason, keyed by plugin
+     * name. Their state stays (`on` / `needs_config`) so an org admin can still switch them off;
+     * the reason and next step tell why the plugin does nothing now.
      */
-    private assertNotOtherOrgs;
-    /** How many live catalog items other orgs own (left out of the platform list). */
-    private otherOrgItems;
+    private stopped;
     onModuleInit(): void;
 }

package/dist/platform/ops/plugins.ops.js

@@ -10,37 +10,56 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { z } from "zod";
+import { CatalogIdPathParams, CatalogUpdateBody } from "../../catalog/admin-catalog.schemas.js";
 import { CatalogService } from "../../catalog/catalog.service.js";
+import { CatalogItemPathParams } from "../../catalog/org-catalog.schemas.js";
 import { OrgCatalogService } from "../../catalog/org-catalog.service.js";
 import { PluginInstaller, uninstallPreviewHash } from "../../catalog/plugin-install.js";
 import { PlatformPluginUpdater } from "../../catalog/plugin-upgrade.js";
 import { OrgExtensionConfigs } from "../../extensions/org-config.js";
+import { ExtensionAvailability } from "../../extensions/unavailable.js";
 import { KernelDb } from "../../infra/database/kernel-db.js";
 import { defineOperation } from "../operation.js";
-import { redactOrgs } from "../redact-orgs.js";
 import { PlatformOperations } from "../registry.js";
-import { asToolError, viaAgent } from "./errors.js";
+import { viaAgent } from "./errors.js";
+import { assertNotOtherOrgs, otherOrgItems } from "./other-orgs.js";
 import { Cursor, pageOf, startOf } from "./paging.js";
 import { localized } from "./summary.js";
-const Id = z.string().min(1).max(100);
-const Version = z.string().min(1).max(100);
-const Hash = z.string().min(1).max(200);
+import { roleFor, unavailableFields, unavailableMessage, unavailableNext } from "./unavailable.js";
+/** An org catalog item id (`:itemId` of the org routes). */
+const ItemId = CatalogItemPathParams.shape.itemId.max(100);
+/** A platform catalog item id (`:id` of the admin routes), named `itemId` like the org's. */
+const PlatformItemId = CatalogIdPathParams.shape.id.max(100);
+const Version = CatalogUpdateBody.shape.version.max(100);
+/** The switch-off confirm: the uninstall preview's hash, or `nothing-installed`. */
+const Confirm = z.string().min(1).max(200);
 /** Entries per page of the paged lists (the tool caps a bare list at 50). */
 const PAGE = 50;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-export const OTHER_ORG = "This plugin belongs to another org; use the admin console.";
+export { OTHER_ORG } from "./other-orgs.js";
 const LOCKED = "This plugin is on for every org (or shipped with the platform) and cannot be switched off in one org.";
 /** The confirm value of switching off a plugin with nothing installed in the org. */
 const NOTHING_INSTALLED = "nothing-installed";
 export const NEEDS_INPUT = "This plugin needs configuration a person must enter; ask them to enable it on the 插件 page.";
-/** An org's view of a plugin, as the list shows it. */
-const brief = (i) => ({
+/** The English name of a plugin as next steps and messages name it. */
+const enName = (i) => localized(i.displayName, i.name).en;
+/** The item with the reason its extension stopped loading (state unchanged), when it has one. */
+const withStopped = (i, stopped) => {
+    const reason = i.reason ?? stopped.get(i.name);
+    return reason === undefined ? i : { ...i, reason };
+};
+/**
+ * An org's view of a plugin (`plugins.get`): the state, and when unavailable the reason and the
+ * actor's next step (spec §14.2 problem 4: one call decides it).
+ */
+const brief = (i, role) => ({
     id: i.id,
     name: i.name,
     displayName: i.displayName,
     description: i.description,
     scope: i.scope,
     state: i.state,
+    ...unavailableFields(i.reason, enName(i), role),
     switchable: i.switchable,
     builtin: i.builtin,
     notDeployed: i.notDeployed,
@@ -50,6 +69,16 @@ const brief = (i) => ({
     owner: i.owner,
     request: i.request,
 });
+/** A plugin as `plugins.list` shows it: a compact row; the rest comes from `plugins.get`. */
+const row = (i, role) => ({
+    id: i.id,
+    name: i.name,
+    state: i.state,
+    ...unavailableFields(i.reason, enName(i), role),
+    displayName: i.displayName,
+    switchable: i.switchable,
+    request: i.request,
+});
 const hasConfigFields = (schema) => {
     const props = schema?.properties;
     return typeof props === "object" && props !== null && Object.keys(props).length > 0;
@@ -74,7 +103,8 @@ function needsInput(item, extensions) {
 /**
  * Plugin operations of the `Platform` tool (spec §7): the org's view (list, get, switch on or off)
  * and the super admin's platform view (list, get, update with its preview). Every platform result
- * goes through {@link redactOrgs}: other orgs only as counts (spec §6.1).
+ * shows the admin console's data in full for platform items and the org's own (spec §14.5 item 1);
+ * plugins other orgs own are only counted, and reading or updating one is refused.
  */
 let PluginsOperations = class PluginsOperations {
     registry;
@@ -84,7 +114,8 @@ let PluginsOperations = class PluginsOperations {
     installer;
     extensions;
     kdb;
-    constructor(registry, orgCatalog, catalog, updater, installer, extensions, kdb) {
+    availability;
+    constructor(registry, orgCatalog, catalog, updater, installer, extensions, kdb, availability) {
         this.registry = registry;
         this.orgCatalog = orgCatalog;
         this.catalog = catalog;
@@ -92,52 +123,49 @@ let PluginsOperations = class PluginsOperations {
         this.installer = installer;
         this.extensions = extensions;
         this.kdb = kdb;
+        this.availability = availability;
     }
     /**
-     * Refuses a super-admin operation on an item another org owns: its results would describe that
-     * org's private plugin in this org's log (spec §6.1). Platform items and the org's own pass.
+     * Installed (or builtin) plugins whose extension stopped loading: the reason, keyed by plugin
+     * name. Their state stays (`on` / `needs_config`) so an org admin can still switch them off;
+     * the reason and next step tell why the plugin does nothing now.
      */
-    async assertNotOtherOrgs(itemId, orgId) {
-        if (!UUID_RE.test(itemId))
-            return;
-        const row = await this.kdb.db
-            .selectFrom("catalog_items")
-            .select("owner_org_id")
-            .where("id", "=", itemId)
-            .executeTakeFirst();
-        if (row?.owner_org_id != null && row.owner_org_id !== orgId)
-            throw new ToolError(OTHER_ORG);
-    }
-    /** How many live catalog items other orgs own (left out of the platform list). */
-    async otherOrgItems(orgId) {
-        const r = await this.kdb.db
-            .selectFrom("catalog_items")
-            .select((eb) => eb.fn.countAll().as("n"))
-            .where("deleted_at", "is", null)
-            .where("owner_org_id", "is not", null)
-            .where("owner_org_id", "!=", orgId)
-            .executeTakeFirstOrThrow();
-        return Number(r.n);
+    async stopped(items) {
+        const names = items
+            .filter((i) => i.reason === undefined &&
+            i.componentCounts.extension > 0 &&
+            (i.installed !== null || i.builtin))
+            // a plugin's extension carries the plugin's name
+            .map((i) => i.name);
+        const out = new Map();
+        for (const [name, u] of await this.availability.unavailable(names))
+            out.set(name, u.reason);
+        return out;
     }
     onModuleInit() {
         this.registry.register([
             defineOperation({
                 id: "plugins.list",
-                description: "List the plugins this org can see, with their state here (on, off, needs_config, unavailable, not_offered), whether an org admin can switch them, and the org's pending request. Pages by 50: pass the returned next as params.cursor.",
+                description: "List the plugins this org can see, one compact row each: the state here (on, off, needs_config, unavailable, not_offered), why an unavailable one cannot be used (reason) and your next step (next; an installed plugin whose extension stopped running keeps its state and carries them too), whether an org admin can switch it, and the org's pending request. Details come from plugins.get. Pages by 50: pass the returned next as params.cursor.",
                 input: z.object({ cursor: Cursor.optional() }).strict(),
                 example: {},
                 authz: { orgAction: "catalog.read" },
                 mirrors: ["GET /api/v1/orgs/:orgId/catalog"],
+                extras: ["cursor"],
                 confirm: "read",
                 run: async (input, ctx) => {
-                    const all = await this.orgCatalog.list(ctx.orgId, ctx.actorAccountId);
-                    return pageOf(all.map(brief), startOf(input.cursor), PAGE);
+                    const [all, role] = await Promise.all([
+                        this.orgCatalog.list(ctx.orgId, ctx.actorAccountId),
+                        roleFor(this.kdb.db, ctx),
+                    ]);
+                    const stopped = await this.stopped(all);
+                    return pageOf(all.map((i) => row(withStopped(i, stopped), role)), startOf(input.cursor), PAGE);
                 },
             }),
             defineOperation({
                 id: "plugins.get",
-                description: "Read one plugin as this org sees it: its state, extension, connector templates (presets only, never credentials), dependencies, skills and agent templates.",
-                input: z.object({ itemId: Id }).strict(),
+                description: "Read one plugin as this org sees it: its state (with the reason and your next step when it is unavailable, or installed but its extension stopped running), extension, connector templates (presets only, never credentials), dependencies, skills and agent templates.",
+                input: z.object({ itemId: ItemId }).strict(),
                 example: { itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c" },
                 authz: { orgAction: "catalog.read" },
                 mirrors: ["GET /api/v1/orgs/:orgId/catalog/:itemId"],
@@ -145,15 +173,18 @@ let PluginsOperations = class PluginsOperations {
                 errors: [
                     { code: "catalog.item_not_found", next: "Check the plugin id with plugins.list." },
                 ],
-                run: async (input, ctx) => asToolError(async () => {
-                    const d = await this.orgCatalog.detail(ctx.orgId, ctx.actorAccountId, input.itemId);
-                    return { ...d, item: brief(d.item) };
-                }),
+                run: async (input, ctx) => {
+                    const [d, role] = await Promise.all([
+                        this.orgCatalog.detail(ctx.orgId, ctx.actorAccountId, input.itemId),
+                        roleFor(this.kdb.db, ctx),
+                    ]);
+                    return { ...d, item: brief(withStopped(d.item, await this.stopped([d.item])), role) };
+                },
             }),
             defineOperation({
                 id: "plugins.disable-preview",
                 description: "Preview switching a plugin off in this org (org admins): what it would remove and which agents use it, and the confirm value plugins.set-enabled needs to switch it off. Show the preview to the person before switching off.",
-                input: z.object({ itemId: Id }).strict(),
+                input: z.object({ itemId: ItemId }).strict(),
                 example: { itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c" },
                 // the web previews through the switch route itself (no confirm); writes nothing here
                 authz: { orgAction: "org.extensions.manage" },
@@ -162,7 +193,7 @@ let PluginsOperations = class PluginsOperations {
                 errors: [
                     { code: "catalog.item_not_found", next: "Check the plugin id with plugins.list." },
                 ],
-                run: async (input, ctx) => asToolError(async () => {
+                run: async (input, ctx) => {
                     const d = await this.orgCatalog.detail(ctx.orgId, ctx.actorAccountId, input.itemId);
                     if (!d.item.switchable)
                         throw new ToolError(LOCKED);
@@ -176,14 +207,14 @@ let PluginsOperations = class PluginsOperations {
                     }
                     const preview = await this.installer.previewUninstall(ctx.orgId, live.pluginInstallId);
                     return { preview, confirm: uninstallPreviewHash(preview) };
-                }),
+                },
             }),
             defineOperation({
                 id: "plugins.set-enabled",
                 description: "Switch a plugin on or off in this org. Switching on installs it; a plugin whose enabling needs configuration a person enters (connector credentials, extension config) is refused, so point the person to the 插件 page. Switching off removes what the plugin brought and needs confirm: the value plugins.disable-preview returned with the preview the person saw.",
                 input: z.discriminatedUnion("enabled", [
-                    z.object({ itemId: Id, enabled: z.literal(true) }).strict(),
-                    z.object({ itemId: Id, enabled: z.literal(false), confirm: Hash }).strict(),
+                    z.object({ itemId: ItemId, enabled: z.literal(true) }).strict(),
+                    z.object({ itemId: ItemId, enabled: z.literal(false), confirm: Confirm }).strict(),
                 ]),
                 example: { itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c", enabled: true },
                 // the route needs catalog.read; setSwitch requires an org admin (any of skills.manage,
@@ -191,6 +222,11 @@ let PluginsOperations = class PluginsOperations {
                 authz: { orgAction: "org.extensions.manage" },
                 authzNote: "service-enforced",
                 mirrors: ["PUT /api/v1/orgs/:orgId/catalog/:itemId/switch"],
+                // install inputs a person enters on the web (a plugin that needs them is refused)
+                omits: ["inputs"],
+                loosens: {
+                    confirm: "also takes `nothing-installed` (plugins.disable-preview's value when nothing is installed), which the route's hash pattern rejects; the service checks confirm only when something is installed",
+                },
                 confirm: "org",
                 errors: [
                     {
@@ -203,17 +239,64 @@ let PluginsOperations = class PluginsOperations {
                     },
                     {
                         code: "plugin.disabled",
-                        next: "The super admin stopped this plugin on the platform; ask them.",
+                        next: {
+                            superAdmin: "The plugin is stopped on the platform: turn it back on in the admin console under Plugins, then call again.",
+                            orgAdmin: "The super admin stopped this plugin on the platform; ask them.",
+                            member: "The super admin stopped this plugin on the platform; tell your org admin, who can ask the super admin.",
+                        },
+                    },
+                    {
+                        code: "catalog.item_not_found",
+                        next: "Check the plugin id with plugins.list.",
+                    },
+                    {
+                        code: "plugin.needs_input",
+                        next: "Ask the person to enable it on the 插件 page, where they enter its configuration.",
                     },
                     {
                         code: "catalog.approval_required",
                         next: "The plugin is not offered to this org: create an access request with requests.create.",
                     },
+                    {
+                        code: "catalog.not_deployed",
+                        next: {
+                            superAdmin: "Open the admin console → Extensions → the plugin's extension to see why it is not running (deployment config, permission approval, disabled, or failed to load); fix it, then call again.",
+                            orgAdmin: "Only the super admin can make the plugin's extension run; plugins.get shows the reason. There is no request operation for this (requests.create covers enabling and access only), so tell the super admin directly.",
+                            member: "Ask an org admin: the super admin must set up the plugin's extension on the platform first.",
+                        },
+                    },
                     {
                         code: "plugin.skill_conflict",
                         next: "An org skill has the name of one of the plugin's skills; the person resolves it on the web.",
                     },
                 ],
+                // what is known to fail before the card: an unknown plugin, switching off a locked one,
+                // switching on one whose extension cannot run (with the role's next step naming it) or
+                // that needs a person's input
+                precheck: async (i, ctx) => {
+                    const [item] = UUID_RE.test(i.itemId)
+                        ? await this.orgCatalog.list(ctx.orgId, ctx.actorAccountId, i.itemId)
+                        : [];
+                    if (item === undefined) {
+                        return { ok: false, code: "catalog.item_not_found", message: "Catalog item not found" };
+                    }
+                    if (!i.enabled && !item.switchable) {
+                        return { ok: false, code: "plugin.scope_locked", message: LOCKED };
+                    }
+                    if (i.enabled && item.state === "unavailable" && item.reason !== undefined) {
+                        const name = enName(item);
+                        return {
+                            ok: false,
+                            code: item.reason === "plugin_disabled" ? "plugin.disabled" : "catalog.not_deployed",
+                            message: unavailableMessage(item.reason, name),
+                            next: unavailableNext(item.reason, name),
+                        };
+                    }
+                    if (i.enabled && needsInput(item, await this.extensions.list(ctx.orgId))) {
+                        return { ok: false, code: "plugin.needs_input", message: NEEDS_INPUT };
+                    }
+                    return { ok: true };
+                },
                 summary: async (i, ctx) => {
                     const [item] = await this.orgCatalog.list(ctx.orgId, ctx.actorAccountId, i.itemId);
                     if (item === undefined)
@@ -236,7 +319,7 @@ let PluginsOperations = class PluginsOperations {
                         en: `Disable plugin "${n.en}" in the org: removes ${p.components.length} components; ${p.agents.length} agents use it`,
                     };
                 },
-                run: async (input, ctx) => asToolError(async () => {
+                run: async (input, ctx) => {
                     if (input.enabled) {
                         const [item] = await this.orgCatalog.list(ctx.orgId, ctx.actorAccountId, input.itemId);
                         if (item && needsInput(item, await this.extensions.list(ctx.orgId))) {
@@ -244,36 +327,43 @@ let PluginsOperations = class PluginsOperations {
                         }
                     }
                     const r = await this.orgCatalog.setSwitch(ctx.orgId, ctx.actorAccountId, input.itemId, input.enabled ? { enabled: true } : { enabled: false, confirm: input.confirm }, undefined, viaAgent("plugins.set-enabled", ctx));
-                    if (r.kind === "done")
-                        return { item: brief(r.item) };
+                    if (r.kind === "done") {
+                        return {
+                            item: brief(r.item, await roleFor(this.kdb.db, ctx)),
+                        };
+                    }
                     // unreachable: confirm is required when switching off
                     return { preview: r.preview, confirm: r.confirm };
-                }),
+                },
             }),
             defineOperation({
                 id: "plugins.platform-list",
-                description: "List the platform's plugins and this org's own (super admin): scope, disabled, versions, pending confirmation and how many orgs use it. Plugins other orgs own are only counted (otherOrgItems); orgs are given as counts. Pages by 50: pass the returned next as params.cursor.",
+                description: "List the platform's plugins and this org's own (super admin): scope, disabled, versions, pending confirmation and how many orgs use it. Plugins other orgs own are only counted (otherOrgItems). Pages by 50: pass the returned next as params.cursor.",
                 input: z.object({ cursor: Cursor.optional() }).strict(),
                 example: {},
                 authz: { superAdmin: true },
                 mirrors: ["GET /api/v1/admin/catalog/items"],
+                // paged by cursor; deleted items and the pending filter are the admin console's
+                omits: ["includeDeleted", "limit", "offset", "pending"],
+                extras: ["cursor"],
                 confirm: "read",
                 run: async (input, ctx) => {
                     const p = await this.catalog.page({ limit: PAGE, offset: startOf(input.cursor) });
-                    return redactOrgs({
+                    return {
                         items: p.items.filter((i) => i.owner.kind !== "org" || i.owner.orgId === ctx.orgId),
-                        otherOrgItems: await this.otherOrgItems(ctx.orgId),
+                        otherOrgItems: await otherOrgItems(this.kdb.db, ctx.orgId),
                         next: p.nextOffset === null ? null : String(p.nextOffset),
-                    });
+                    };
                 },
             }),
             defineOperation({
                 id: "plugins.platform-get",
-                description: "Read one platform catalog plugin (super admin): the item, its platform version and every version with its source. Orgs are given as counts only.",
-                input: z.object({ itemId: Id }).strict(),
+                description: "Read one platform catalog plugin (super admin): the item, its platform version and every version with its source, and the orgs it is offered to. Another org's own plugin is refused.",
+                input: z.object({ itemId: PlatformItemId }).strict(),
                 example: { itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c" },
                 authz: { superAdmin: true },
                 mirrors: ["GET /api/v1/admin/catalog/items/:id"],
+                renames: { itemId: "id" },
                 confirm: "read",
                 errors: [
                     {
@@ -281,10 +371,10 @@ let PluginsOperations = class PluginsOperations {
                         next: "Check the plugin id with plugins.platform-list.",
                     },
                 ],
-                run: async (input, ctx) => asToolError(async () => {
-                    await this.assertNotOtherOrgs(input.itemId, ctx.orgId);
+                run: async (input, ctx) => {
+                    await assertNotOtherOrgs(this.kdb.db, input.itemId, ctx.orgId);
                     const d = await this.catalog.get(input.itemId);
-                    return redactOrgs({
+                    return {
                         item: d.item,
                         versions: d.versions.map((v) => ({
                             version: v.version,
@@ -294,16 +384,17 @@ let PluginsOperations = class PluginsOperations {
                             importedAt: v.importedAt,
                             ...(v.version === d.item.platformVersion && { manifest: v.manifest }),
                         })),
-                    });
-                }),
+                    };
+                },
             }),
             defineOperation({
                 id: "plugins.update-preview",
-                description: "Preview updating a platform plugin to another imported version (super admin): every component's change, the extension step and the org connectors it touches, with the diffHash plugins.update takes. Orgs are given as counts only; the admin console shows which.",
-                input: z.object({ itemId: Id, version: Version }).strict(),
+                description: "Preview updating a platform plugin to another imported version (super admin): every component's change, the extension step and the org connectors it touches, with the diffHash plugins.update takes. Another org's own plugin is refused.",
+                input: z.object({ itemId: PlatformItemId, version: Version }).strict(),
                 example: { itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c", version: "1.2.0" },
                 authz: { superAdmin: true },
                 mirrors: ["POST /api/v1/admin/catalog/items/:id/update/preview"],
+                renames: { itemId: "id" },
                 confirm: "read",
                 errors: [
                     {
@@ -311,15 +402,21 @@ let PluginsOperations = class PluginsOperations {
                         next: "Check the plugin id and its versions with plugins.platform-get.",
                     },
                 ],
-                run: async (input, ctx) => asToolError(async () => {
-                    await this.assertNotOtherOrgs(input.itemId, ctx.orgId);
-                    return redactOrgs(await this.updater.preview(input.itemId, input.version));
-                }),
+                run: async (input, ctx) => {
+                    await assertNotOtherOrgs(this.kdb.db, input.itemId, ctx.orgId);
+                    return this.updater.preview(input.itemId, input.version);
+                },
             }),
             defineOperation({
                 id: "plugins.update",
                 description: "Update a platform plugin to the version previewed (super admin), for every org at once: pass the version and the diffHash plugins.update-preview returned. A preview that is out of date is refused; preview again.",
-                input: z.object({ itemId: Id, version: Version, diffHash: Hash }).strict(),
+                input: z
+                    .object({
+                    itemId: PlatformItemId,
+                    version: Version,
+                    diffHash: CatalogUpdateBody.shape.diffHash,
+                })
+                    .strict(),
                 example: {
                     itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c",
                     version: "1.2.0",
@@ -327,6 +424,7 @@ let PluginsOperations = class PluginsOperations {
                 },
                 authz: { superAdmin: true },
                 mirrors: ["PUT /api/v1/admin/catalog/items/:id/update"],
+                renames: { itemId: "id" },
                 confirm: "platform",
                 errors: [
                     {
@@ -339,7 +437,7 @@ let PluginsOperations = class PluginsOperations {
                     },
                 ],
                 summary: async (i, ctx) => {
-                    await this.assertNotOtherOrgs(i.itemId, ctx.orgId);
+                    await assertNotOtherOrgs(this.kdb.db, i.itemId, ctx.orgId);
                     const [{ item }, p] = await Promise.all([
                         this.catalog.get(i.itemId),
                         this.updater.preview(i.itemId, i.version),
@@ -349,17 +447,17 @@ let PluginsOperations = class PluginsOperations {
                     const changed = count("upgrade", "downgrade");
                     const added = count("added");
                     const removed = count("removed");
-                    // one version for every org: the orgs it is on in, as a count (spec §6.1)
+                    // one version for every org: how many orgs it is on in
                     const orgs = item.enabledOrgs;
                     return {
                         zh: `把平台插件「${n.zh}」从 ${p.from ?? "无"} 更新到 ${p.to}：组件 ${changed} 个更新、${added} 个新增、${removed} 个移除，影响 ${orgs} 个组织`,
                         en: `Update platform plugin "${n.en}" from ${p.from ?? "none"} to ${p.to}: components ${changed} updated, ${added} added, ${removed} removed; ${orgs} orgs affected`,
                     };
                 },
-                run: async (input, ctx) => asToolError(async () => {
-                    await this.assertNotOtherOrgs(input.itemId, ctx.orgId);
-                    return redactOrgs(await this.updater.update(ctx.actorAccountId, input.itemId, { version: input.version, diffHash: input.diffHash }, { auditDetail: viaAgent("plugins.update", ctx) }));
-                }),
+                run: async (input, ctx) => {
+                    await assertNotOtherOrgs(this.kdb.db, input.itemId, ctx.orgId);
+                    return this.updater.update(ctx.actorAccountId, input.itemId, { version: input.version, diffHash: input.diffHash }, { auditDetail: viaAgent("plugins.update", ctx) });
+                },
             }),
         ]);
     }
@@ -372,6 +470,7 @@ PluginsOperations = __decorate([
     __param(3, Inject(PlatformPluginUpdater)),
     __param(4, Inject(PluginInstaller)),
     __param(5, Inject(OrgExtensionConfigs)),
-    __param(6, Inject(KernelDb))
+    __param(6, Inject(KernelDb)),
+    __param(7, Inject(ExtensionAvailability))
 ], PluginsOperations);
 export { PluginsOperations };

package/dist/platform/ops/previewers.ops.d.ts

@@ -0,0 +1,14 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { PreviewerRegistry } from "../../files/previewers.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * File previewer operations (the `extensions` domain): the org's order of the previewers its
+ * extensions provide and which are off (org admins, `org.extensions.manage`). Rendering a preview
+ * is the web's (`transport`).
+ */
+export declare class PreviewersOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly previewers;
+    constructor(registry: PlatformOperations, previewers: PreviewerRegistry);
+    onModuleInit(): void;
+}