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

package/dist/catalog/admin-catalog.controller.d.ts

@@ -1,20 +1,12 @@
 import type { FastifyReply } from "fastify";
 import { z } from "zod";
 import { type Principal } from "../identity/principal.js";
+import { CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogNpmImportBody as NpmBody, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody } from "./admin-catalog.schemas.js";
 import { type CatalogItemDetail, type CatalogItemView, CatalogService, type PermissionsMismatch } from "./catalog.service.js";
 import { CatalogScopeService, type ScopePreview } from "./catalog-scope.service.js";
 import { OrgCatalogService } from "./org-catalog.service.js";
 import { type PluginConfirmResult, PluginImport, type PluginReview } from "./plugin-import.js";
 import { PlatformPluginUpdater, type PlatformUpdatePreview, type PlatformUpdateResult } from "./plugin-upgrade.js";
-declare const NpmBody: z.ZodObject<{
-    package: z.ZodString;
-    version: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-declare const GitBody: z.ZodObject<{
-    url: z.ZodString;
-    ref: z.ZodOptional<z.ZodString>;
-    path: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
 declare const ConfirmBody: z.ZodObject<{
     reviewHash: z.ZodString;
     scope: z.ZodOptional<z.ZodEnum<{
@@ -25,44 +17,6 @@ declare const ConfirmBody: z.ZodObject<{
     orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     pinnedSuggestions: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
-/** `{ scope, orgs? }` (a scope change) or `{ disabled: true }` (a disable), not both. */
-declare const ScopePreviewBody: z.ZodObject<{
-    scope: z.ZodOptional<z.ZodEnum<{
-        all: "all";
-        named: "named";
-        optional: "optional";
-    }>>;
-    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    disabled: z.ZodOptional<z.ZodLiteral<true>>;
-}, z.core.$strict>;
-declare const ScopeBody: z.ZodObject<{
-    scope: z.ZodEnum<{
-        all: "all";
-        named: "named";
-        optional: "optional";
-    }>;
-    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    scopeHash: z.ZodString;
-}, z.core.$strict>;
-declare const DisabledBody: z.ZodObject<{
-    disabled: z.ZodBoolean;
-    scopeHash: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-declare const ShownBody: z.ZodObject<{
-    shownToOthers: z.ZodBoolean;
-}, z.core.$strict>;
-declare const ListQuery: z.ZodObject<{
-    includeDeleted: z.ZodOptional<z.ZodEnum<{
-        false: "false";
-        true: "true";
-    }>>;
-    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
-    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
-    pending: z.ZodOptional<z.ZodEnum<{
-        false: "false";
-        true: "true";
-    }>>;
-}, z.core.$strip>;
 declare const ConfirmPermissionsBody: z.ZodObject<{
     permissionsHash: z.ZodString;
 }, z.core.$strict>;
@@ -70,13 +24,6 @@ declare const ConfirmPermissionsBody: z.ZodObject<{
 declare const RejectBody: z.ZodObject<{
     reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
-declare const UpdatePreviewBody: z.ZodObject<{
-    version: z.ZodString;
-}, z.core.$strict>;
-declare const UpdateBody: z.ZodObject<{
-    version: z.ZodString;
-    diffHash: z.ZodString;
-}, z.core.$strict>;
 /**
  * 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
@@ -157,7 +104,7 @@ export declare class AdminCatalogController {
      * The item list (`includeDeleted=true` includes deleted items). Paging: `limit` (default 200, at
      * most 1000) and `offset`; `nextOffset` is the next page's offset, null when there is none.
      */
-    list(q: z.infer<typeof ListQuery>): Promise<{
+    list(q: z.infer<typeof CatalogItemsQuery>): Promise<{
         items: CatalogItemView[];
         nextOffset: number | null;
     }>;
@@ -226,7 +173,7 @@ export declare class AdminCatalogController {
      * `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: string, body: z.infer<typeof UpdatePreviewBody>): Promise<PlatformUpdatePreview>;
+    previewUpdate(id: string, body: z.infer<typeof CatalogUpdatePreviewBody>): Promise<PlatformUpdatePreview>;
     /**
      * 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
@@ -235,7 +182,7 @@ export declare class AdminCatalogController {
      * version waits) -> 409 `catalog.item_pending`: confirm it in 待确认 (pre-flight F8); the
      * preview answers the same.
      */
-    update(principal: Principal, id: string, body: z.infer<typeof UpdateBody>): Promise<PlatformUpdateResult>;
+    update(principal: Principal, id: string, body: z.infer<typeof CatalogUpdateBody>): Promise<PlatformUpdateResult>;
     /** 删除条目（软删除，已安装的组件不受影响）。 */
     remove(principal: Principal, id: string): Promise<void>;
 }

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

@@ -13,26 +13,13 @@ import { ApiError } from "../errors.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 { CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogHash as Hash, CatalogNpmImportBody as NpmBody, CatalogScopeOrgs as Orgs, CatalogScope as Scope, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody, } from "./admin-catalog.schemas.js";
+import { 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(),
-});
-const GitBody = z
-    .object({
-    url: z.string().min(1).max(2000),
-    ref: z.string().min(1).max(256).optional(),
-    path: z.string().min(1).max(512).optional(),
-})
-    .strict();
-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,
@@ -43,33 +30,9 @@ const ConfirmBody = z
     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 } : {};
@@ -78,7 +41,7 @@ class CatalogImportConfirmBody extends createZodDto(ConfirmBody, "CatalogImportC
 }
 class CatalogGitImportBody extends createZodDto(GitBody, "CatalogGitImportBody") {
 }
-class CatalogItemsQuery extends createZodDto(ListQuery, "CatalogItemsQuery") {
+class CatalogItemsQueryDto extends createZodDto(CatalogItemsQuery, "CatalogItemsQuery") {
 }
 class CatalogNpmImportBody extends createZodDto(NpmBody, "CatalogNpmImportBody") {
 }
@@ -94,9 +57,9 @@ class CatalogRejectBody extends createZodDto(RejectBody, "CatalogRejectBody") {
 }
 class CatalogDisabledBody extends createZodDto(DisabledBody, "CatalogDisabledBody") {
 }
-class CatalogUpdatePreviewBody extends createZodDto(UpdatePreviewBody, "CatalogUpdatePreviewBody") {
+class CatalogUpdatePreviewBodyDto extends createZodDto(CatalogUpdatePreviewBody, "CatalogUpdatePreviewBody") {
 }
-class CatalogUpdateBody extends createZodDto(UpdateBody, "CatalogUpdateBody") {
+class CatalogUpdateBodyDto extends createZodDto(CatalogUpdateBody, "CatalogUpdateBody") {
 }
 /**
  * The platform catalog (`/api/v1/admin/catalog/*`, super admins): plugin import (upload / npm
@@ -351,7 +314,7 @@ __decorate([
 ], AdminCatalogController.prototype, "confirm", null);
 __decorate([
     Get("items"),
-    __param(0, ZQuery(CatalogItemsQuery))
+    __param(0, ZQuery(CatalogItemsQueryDto))
 ], AdminCatalogController.prototype, "list", null);
 __decorate([
     Get("items/:id"),
@@ -404,13 +367,13 @@ __decorate([
     Post("items/:id/update/preview"),
     HttpCode(200),
     __param(0, Param("id")),
-    __param(1, ZBody(CatalogUpdatePreviewBody))
+    __param(1, ZBody(CatalogUpdatePreviewBodyDto))
 ], AdminCatalogController.prototype, "previewUpdate", null);
 __decorate([
     Put("items/:id/update"),
     __param(0, CurrentPrincipal()),
     __param(1, Param("id")),
-    __param(2, ZBody(CatalogUpdateBody))
+    __param(2, ZBody(CatalogUpdateBodyDto))
 ], AdminCatalogController.prototype, "update", null);
 __decorate([
     Delete("items/:id"),

package/dist/catalog/admin-catalog.schemas.d.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const CatalogHash: z.ZodString;
+export declare const CatalogItemsQuery: z.ZodObject<{
+    includeDeleted: z.ZodOptional<z.ZodEnum<{
+        false: "false";
+        true: "true";
+    }>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    pending: z.ZodOptional<z.ZodEnum<{
+        false: "false";
+        true: "true";
+    }>>;
+}, z.core.$strip>;
+export declare const CatalogUpdatePreviewBody: z.ZodObject<{
+    version: z.ZodString;
+}, z.core.$strict>;
+export declare const CatalogUpdateBody: z.ZodObject<{
+    version: z.ZodString;
+    diffHash: z.ZodString;
+}, z.core.$strict>;
+/** `:id` as the routes take it (`@Param`). */
+export declare const CatalogIdPathParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/** `:stagingId` of a staged import as the route takes it (`@Param`). */
+export declare const CatalogStagingPathParams: z.ZodObject<{
+    stagingId: z.ZodString;
+}, z.core.$strip>;
+export declare const CatalogNpmImportBody: z.ZodObject<{
+    package: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const CatalogGitImportBody: z.ZodObject<{
+    url: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const CatalogScope: z.ZodEnum<{
+    all: "all";
+    named: "named";
+    optional: "optional";
+}>;
+export declare const CatalogScopeOrgs: z.ZodArray<z.ZodString>;
+/** `{ scope, orgs? }` (a scope change) or `{ disabled: true }` (a disable), not both. */
+export declare const CatalogScopePreviewBody: z.ZodObject<{
+    scope: z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        named: "named";
+        optional: "optional";
+    }>>;
+    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disabled: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+export declare const CatalogScopeBody: z.ZodObject<{
+    scope: z.ZodEnum<{
+        all: "all";
+        named: "named";
+        optional: "optional";
+    }>;
+    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    scopeHash: z.ZodString;
+}, z.core.$strict>;
+export declare const CatalogDisabledBody: z.ZodObject<{
+    disabled: z.ZodBoolean;
+    scopeHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const CatalogShownBody: z.ZodObject<{
+    shownToOthers: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const ADMIN_CATALOG_ROUTES: readonly RouteSchemas[];

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

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { CATALOG_LIST_MAX_LIMIT } from "./catalog.service.js";
+export const CatalogHash = z.string().min(1).max(128);
+export const CatalogItemsQuery = 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 CatalogVersion = z.string().min(1).max(256);
+export const CatalogUpdatePreviewBody = z.object({ version: CatalogVersion }).strict();
+export const CatalogUpdateBody = z
+    .object({ version: CatalogVersion, diffHash: CatalogHash })
+    .strict();
+/** `:id` as the routes take it (`@Param`). */
+export const CatalogIdPathParams = z.object({ id: z.string().min(1) });
+/** `:stagingId` of a staged import as the route takes it (`@Param`). */
+export const CatalogStagingPathParams = z.object({ stagingId: z.string().min(1) });
+export const CatalogNpmImportBody = z.object({
+    package: z.string().min(1).max(214),
+    version: z.string().min(1).max(256).optional(),
+});
+export const CatalogGitImportBody = z
+    .object({
+    url: z.string().min(1).max(2000),
+    ref: z.string().min(1).max(256).optional(),
+    path: z.string().min(1).max(512).optional(),
+})
+    .strict();
+export const CatalogScope = z.enum(["all", "optional", "named"]);
+export const CatalogScopeOrgs = z.array(z.string().min(1).max(128)).max(1000);
+/** `{ scope, orgs? }` (a scope change) or `{ disabled: true }` (a disable), not both. */
+export const CatalogScopePreviewBody = z
+    .object({
+    scope: CatalogScope.optional(),
+    orgs: CatalogScopeOrgs.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"],
+});
+export const CatalogScopeBody = z
+    .object({ scope: CatalogScope, orgs: CatalogScopeOrgs.optional(), scopeHash: CatalogHash })
+    .strict();
+export const CatalogDisabledBody = z
+    .object({ disabled: z.boolean(), scopeHash: CatalogHash.optional() })
+    .strict();
+export const CatalogShownBody = z.object({ shownToOthers: z.boolean() }).strict();
+export const ADMIN_CATALOG_ROUTES = [
+    { route: "GET /api/v1/admin/catalog/items", query: CatalogItemsQuery },
+    { route: "GET /api/v1/admin/catalog/items/:id", params: CatalogIdPathParams },
+    {
+        route: "POST /api/v1/admin/catalog/items/:id/update/preview",
+        params: CatalogIdPathParams,
+        body: CatalogUpdatePreviewBody,
+    },
+    {
+        route: "PUT /api/v1/admin/catalog/items/:id/update",
+        params: CatalogIdPathParams,
+        body: CatalogUpdateBody,
+    },
+    { route: "POST /api/v1/admin/catalog/import/npm", body: CatalogNpmImportBody },
+    { route: "POST /api/v1/admin/catalog/import/git", body: CatalogGitImportBody },
+    { route: "GET /api/v1/admin/catalog/imports/:stagingId", params: CatalogStagingPathParams },
+    {
+        route: "POST /api/v1/admin/catalog/items/:id/scope/preview",
+        params: CatalogIdPathParams,
+        body: CatalogScopePreviewBody,
+    },
+    {
+        route: "PUT /api/v1/admin/catalog/items/:id/scope",
+        params: CatalogIdPathParams,
+        body: CatalogScopeBody,
+    },
+    {
+        route: "PUT /api/v1/admin/catalog/items/:id/disabled",
+        params: CatalogIdPathParams,
+        body: CatalogDisabledBody,
+    },
+    {
+        route: "PUT /api/v1/admin/catalog/items/:id/shown",
+        params: CatalogIdPathParams,
+        body: CatalogShownBody,
+    },
+    { route: "DELETE /api/v1/admin/catalog/items/:id", params: CatalogIdPathParams },
+];

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

@@ -1,6 +1,7 @@
 import { type AgentTemplate, type Connector, type ConnectorTemplateFile, type ConnectorTemplateSpec, type LocalizedName, type PluginManifest } from "@capybara-hq/plugin-sdk";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import type { ExtensionRegistry } from "../extensions/registry.js";
+import type { ExtensionUnavailableReason } from "../extensions/unavailable.js";
 import type { OrgLock } from "../orgs/org-lock.js";
 import { type OrgAction } from "../orgs/roles.js";
 import { checkSkillFiles, type SkillPackageFile } from "../skills/package.js";
@@ -10,6 +11,8 @@ import type { CatalogItemView } from "./catalog.service.js";
 import type { ConnectorInstallInput, PluginInstallInput, PluginInstallView } from "./plugin-install.js";
 import type { OrgPluginState, PluginScope } from "./scope.js";
 /** A catalog item from an organization's view (`GET /orgs/:orgId/catalog`). */
+/** Why an org's plugin is `unavailable` ({@link OrgCatalogItem.reason}). */
+export type PluginUnavailableReason = "plugin_disabled" | ExtensionUnavailableReason;
 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;
@@ -21,10 +24,17 @@ export interface OrgCatalogItem extends Omit<CatalogItemView, "installs" | "mark
     /**
      * 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).
+     * install needs inputs), `unavailable` (disabled by the super admin, members don't see it; or
+     * not installed here and its extension cannot run on the deployment, see `reason`) or
+     * `not_offered` (a `named` item shown to orgs outside its list: requestable, not usable).
      */
     state: OrgPluginState;
+    /**
+     * Only when `unavailable`: why (Platform tool spec §14.2 problem 1). `plugin_disabled`: the super
+     * admin disabled the item; otherwise its extension's {@link ExtensionUnavailableReason}, the same
+     * one the org's 扩展 page shows.
+     */
+    reason?: PluginUnavailableReason;
     /** 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. */

package/dist/catalog/catalog-scope.service.js

@@ -596,6 +596,7 @@ let CatalogScopeService = class CatalogScopeService {
                 ownerOrgId: item.owner_org_id,
                 removed: item.awaiting_confirmation,
                 ...(how.kind === "reject" && { reason: how.reason }),
+                ...opts.auditDetail,
             },
         });
     }
@@ -661,7 +662,7 @@ let CatalogScopeService = class CatalogScopeService {
             ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
             action: "catalog.shown_changed",
             target: itemId,
-            detail: { name: item.name, from: item.shown_to_others, to: shown },
+            detail: { name: item.name, from: item.shown_to_others, to: shown, ...opts.auditDetail },
         });
     }
     async writeScope(actor, itemId, target, hash, opts) {
@@ -710,6 +711,7 @@ let CatalogScopeService = class CatalogScopeService {
                 name: item.name,
                 from: { scope: item.scope, orgs: from },
                 to: { scope: t.scope, orgs: t.orgs },
+                ...opts.auditDetail,
             },
         });
         afterCommit(() => this.enqueue(itemId));
@@ -740,7 +742,11 @@ let CatalogScopeService = class CatalogScopeService {
             ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
             action: "catalog.scope_changed",
             target: itemId,
-            detail: { name: item.name, disabled: { from: item.disabled, to: disabled } },
+            detail: {
+                name: item.name,
+                disabled: { from: item.disabled, to: disabled },
+                ...opts.auditDetail,
+            },
         });
         afterCommit(() => this.enqueue(itemId));
     }

package/dist/catalog/catalog.service.d.ts

@@ -186,6 +186,8 @@ export interface CatalogItemDetail {
 /** Audits carry the PAT when a personal token made the call. */
 export interface ActorOpts {
     actorTokenId?: string;
+    /** Merged into the audit detail (a write made through the Platform tool: `via`, …). */
+    auditDetail?: Record<string, unknown>;
 }
 /**
  * The marketplace's permission summary differs from the keys computed from the package (a warning,

package/dist/catalog/catalog.service.js

@@ -164,6 +164,7 @@ let CatalogService = class CatalogService {
         }
         const prepareOpts = {
             ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            ...(opts.auditDetail !== undefined && { auditDetail: opts.auditDetail }),
             expect: {
                 marketplace: {
                     name: entry.name,
@@ -300,6 +301,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),
@@ -520,6 +522,7 @@ let CatalogService = class CatalogService {
                 name: row.name,
                 ...(row.owner_org_id !== null && { ownerOrgId: row.owner_org_id }),
                 ...(opts.reason !== undefined && { reason: opts.reason }),
+                ...opts.auditDetail,
             },
         });
         return { name: row.name };

package/dist/catalog/component-scope.controller.d.ts

@@ -1,70 +1,9 @@
-import { z } from "zod";
+import type { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
+import { ComponentParams, ComponentDisabledSchema as DisabledBody, ComponentIdSchema as IdParams, ComponentListQuery as ListQuery, OrgComponentListQuery, ComponentScopePreviewSchema as PreviewBody, ComponentScopeSchema as ScopeBody, ComponentShownSchema as ShownBody, ComponentSwitchBody as SwitchBody, ComponentTemplateVersionSchema as TemplateVersionBody } from "./component-scope.schemas.js";
 import { type ComponentScopePreview, ComponentScopeService, type ComponentVersionView, type ComponentView, type OrgComponentView, type OrgOfferedComponentView } from "./component-scope.service.js";
 import { PlatformComponents, type UploadedComponentVersion } from "./platform-components.js";
-declare const ComponentParams: z.ZodObject<{
-    kind: z.ZodEnum<{
-        agent_template: "agent_template";
-        connector_template: "connector_template";
-        skill: "skill";
-    }>;
-    id: z.ZodString;
-}, z.core.$strip>;
-declare const ListQuery: z.ZodObject<{
-    kind: z.ZodEnum<{
-        agent_template: "agent_template";
-        connector_template: "connector_template";
-        skill: "skill";
-    }>;
-}, z.core.$strict>;
-declare const OrgListQuery: z.ZodObject<{
-    kind: z.ZodOptional<z.ZodEnum<{
-        agent_template: "agent_template";
-        connector_template: "connector_template";
-        skill: "skill";
-    }>>;
-    itemId: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-/** `{ scope, orgs? }`, `{ disabled: true }` or `{ follow: true }`: exactly one. */
-declare const PreviewBody: z.ZodObject<{
-    scope: z.ZodOptional<z.ZodEnum<{
-        all: "all";
-        named: "named";
-        optional: "optional";
-    }>>;
-    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    disabled: z.ZodOptional<z.ZodLiteral<true>>;
-    follow: z.ZodOptional<z.ZodLiteral<true>>;
-}, z.core.$strict>;
-/** `{ scope, orgs?, scopeHash }` or `{ follow: true, scopeHash }`. */
-declare const ScopeBody: z.ZodObject<{
-    scope: z.ZodOptional<z.ZodEnum<{
-        all: "all";
-        named: "named";
-        optional: "optional";
-    }>>;
-    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    follow: z.ZodOptional<z.ZodLiteral<true>>;
-    scopeHash: z.ZodString;
-}, z.core.$strict>;
-declare const DisabledBody: z.ZodObject<{
-    disabled: z.ZodBoolean;
-    scopeHash: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-declare const ShownBody: z.ZodObject<{
-    shownToOthers: z.ZodBoolean;
-}, z.core.$strict>;
-declare const SwitchBody: z.ZodObject<{
-    enabled: z.ZodBoolean;
-    confirm: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-declare const IdParams: z.ZodObject<{
-    id: z.ZodString;
-}, z.core.$strip>;
-declare const TemplateVersionBody: z.ZodObject<{
-    content: z.ZodString;
-}, z.core.$strict>;
 /**
  * Platform components (`/api/v1/admin/components/*`, super admins; plugin scope phase 2, Task 6):
  * the global list of skills, agent templates and connector templates, and each one's own scope,
@@ -132,7 +71,7 @@ export declare class OrgComponentsController {
      * with its state in the org (`on`, `locked` for `all`, the org's `switch`) and whether an org
      * admin may switch it. Members read it (the workspace pages are read-only for them).
      */
-    list(org: OrgContext, q: z.infer<typeof OrgListQuery>): Promise<{
+    list(org: OrgContext, q: z.infer<typeof OrgComponentListQuery>): Promise<{
         components: OrgOfferedComponentView[];
     }>;
     setSwitch(principal: Principal, org: OrgContext, p: z.infer<typeof ComponentParams>, body: z.infer<typeof SwitchBody>): Promise<{
@@ -149,4 +88,3 @@ export declare class OrgComponentsController {
         confirm: string;
     }>;
 }
-export {};

package/dist/catalog/component-scope.controller.js

@@ -8,67 +8,14 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Get, HttpCode, Inject, Post, Put, Req } from "@nestjs/common";
-import { z } from "zod";
 import { ApiError } from "../errors.js";
 import { CurrentPrincipal, patTokenId, requireUser, SuperAdmin, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZParam, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { ComponentParams, ComponentDisabledSchema as DisabledBody, ComponentIdSchema as IdParams, ComponentListQuery as ListQuery, OrgComponentListQuery, ComponentScopePreviewSchema as PreviewBody, ComponentScopeSchema as ScopeBody, ComponentShownSchema as ShownBody, ComponentSwitchBody as SwitchBody, ComponentTemplateVersionSchema as TemplateVersionBody, } from "./component-scope.schemas.js";
 import { ComponentScopeService, } from "./component-scope.service.js";
-import { COMPONENT_KINDS } from "./component-state.js";
 import { PlatformComponents } from "./platform-components.js";
-const Kind = z.enum(COMPONENT_KINDS);
-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 ComponentParams = z.object({ kind: Kind, id: z.string().min(1).max(128) });
-const ListQuery = z.object({ kind: Kind }).strict();
-const OrgListQuery = z
-    .object({ kind: Kind.optional(), itemId: z.string().uuid().optional() })
-    .strict();
-/** `{ scope, orgs? }`, `{ disabled: true }` or `{ follow: true }`: exactly one. */
-const PreviewBody = z
-    .object({
-    scope: Scope.optional(),
-    orgs: Orgs.optional(),
-    disabled: z.literal(true).optional(),
-    follow: z.literal(true).optional(),
-})
-    .strict()
-    .refine((b) => [b.scope !== undefined, b.disabled === true, b.follow === true].filter(Boolean).length === 1, { message: "send exactly one of scope (with orgs for named), disabled: true or follow: true" })
-    .refine((b) => b.scope !== undefined || b.orgs === undefined, {
-    message: "orgs: only allowed with scope named",
-    path: ["orgs"],
-});
-/** `{ scope, orgs?, scopeHash }` or `{ follow: true, scopeHash }`. */
-const ScopeBody = z
-    .object({
-    scope: Scope.optional(),
-    orgs: Orgs.optional(),
-    follow: z.literal(true).optional(),
-    scopeHash: Hash,
-})
-    .strict()
-    .refine((b) => (b.scope !== undefined) !== (b.follow === true), {
-    message: "send either scope (with orgs for named) or follow: true",
-})
-    .refine((b) => b.scope !== undefined || b.orgs === undefined, {
-    message: "orgs: only allowed with scope named",
-    path: ["orgs"],
-});
-const DisabledBody = z.object({ disabled: z.boolean(), scopeHash: Hash.optional() }).strict();
-const ShownBody = z.object({ shownToOthers: z.boolean() }).strict();
-const SwitchBody = z
-    .object({
-    enabled: z.boolean(),
-    confirm: z
-        .string()
-        .regex(/^[0-9a-f]{64}$/)
-        .optional(),
-})
-    .strict();
-const IdParams = z.object({ id: z.string().min(1).max(128) });
-const TemplateVersionBody = z.object({ content: z.string().min(1).max(400_000) }).strict();
 class ComponentIdParams extends createZodDto(IdParams, "ComponentIdParams") {
 }
 class TemplateVersionDto extends createZodDto(TemplateVersionBody, "TemplateVersionBody") {
@@ -77,7 +24,7 @@ class ComponentParamsDto extends createZodDto(ComponentParams, "ComponentParams"
 }
 class ComponentListQuery extends createZodDto(ListQuery, "ComponentListQuery") {
 }
-class OrgComponentListQuery extends createZodDto(OrgListQuery, "OrgComponentListQuery") {
+class OrgComponentListQueryDto extends createZodDto(OrgComponentListQuery, "OrgComponentListQuery") {
 }
 class ComponentScopePreviewBody extends createZodDto(PreviewBody, "ComponentScopePreviewBody") {
 }
@@ -270,7 +217,7 @@ __decorate([
     Get(),
     OrgAction("catalog.read"),
     __param(0, CurrentOrg()),
-    __param(1, ZQuery(OrgComponentListQuery))
+    __param(1, ZQuery(OrgComponentListQueryDto))
 ], OrgComponentsController.prototype, "list", null);
 __decorate([
     Put(":kind/:id/switch"),