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

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

@@ -9,38 +9,35 @@ 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 { ClientBuilds } from "../client/client-builds.service.js";
 import { ApiError } from "../errors.js";
-import { CurrentPrincipal, EnterpriseAdmin, patTokenId, requireUser, } from "../identity/principal.js";
+import { PluginGuides } from "../extensions/plugin-guides.js";
+import { PluginIcons } from "../extensions/plugin-icons.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 { AdminCatalogGuideQuery, 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 { AppearanceApplyBody } from "./appearance.schemas.js";
+import { AppearanceService, suggestedAppearanceOf, } from "./appearance.service.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";
-const NpmBody = z.object({
-    package: z.string().min(1).max(214),
-    version: z.string().min(1).max(256).optional(),
-});
-const GitBody = z
+import { PlatformPluginUpdater, } from "./plugin-upgrade.js";
+const ConfirmBody = 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 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(),
+    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(),
-});
-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(),
-});
+})
+    .strict();
+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 actorOpts = (actor) => {
     const tokenId = patTokenId(actor);
     return tokenId !== undefined ? { actorTokenId: tokenId } : {};
@@ -49,28 +46,56 @@ class CatalogImportConfirmBody extends createZodDto(ConfirmBody, "CatalogImportC
 }
 class CatalogGitImportBody extends createZodDto(GitBody, "CatalogGitImportBody") {
 }
-class CatalogDeploymentInstallBody extends createZodDto(InstallBody, "CatalogDeploymentInstallBody") {
+class AdminCatalogGuideQueryDto extends createZodDto(AdminCatalogGuideQuery, "AdminCatalogGuideQuery") {
 }
-class CatalogItemsQuery extends createZodDto(ListQuery, "CatalogItemsQuery") {
+class CatalogItemsQueryDto extends createZodDto(CatalogItemsQuery, "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 CatalogUpdatePreviewBodyDto extends createZodDto(CatalogUpdatePreviewBody, "CatalogUpdatePreviewBody") {
+}
+class CatalogUpdateBodyDto extends createZodDto(CatalogUpdateBody, "CatalogUpdateBody") {
+}
+class AppearanceApplyBodyDto extends createZodDto(AppearanceApplyBody, "AppearanceApplyBody") {
 }
 /**
- * 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;
+    icons;
+    appearance;
+    clientBuilds;
+    guides;
+    constructor(catalog, pluginImport, orgCatalog, scope, updater, icons, appearance, clientBuilds, guides) {
         this.catalog = catalog;
         this.pluginImport = pluginImport;
         this.orgCatalog = orgCatalog;
+        this.scope = scope;
+        this.updater = updater;
+        this.icons = icons;
+        this.appearance = appearance;
+        this.clientBuilds = clientBuilds;
+        this.guides = guides;
     }
     /**
      * Prepares the import of an uploaded plugin (an npm-pack tgz as the raw body,
@@ -126,11 +151,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,27 +166,65 @@ 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
      * most 1000) and `offset`; `nextOffset` is the next page's offset, null when there is none.
      */
-    list(q) {
-        return this.catalog.page({
+    async list(q) {
+        const page = await this.catalog.page({
             includeDeleted: q.includeDeleted === "true",
+            ...(q.pending === "true" && { pending: true }),
             ...(q.limit !== undefined && { limit: q.limit }),
             ...(q.offset !== undefined && { offset: q.offset }),
         });
+        // Each item's icon (admin route; a deleted item has none)
+        const icons = await this.icons.ofItems(page.items.map((i) => i.id), { kind: "admin" });
+        return { ...page, items: page.items.map((i) => ({ ...i, icon: icons.get(i.id) ?? null })) };
     }
     /**
-     * 条目详情与各版本，另给出 `hasIcon`（最新版本有图标，`GET items/:id/icon` 可取）；不存在 → 404
-     * `catalog.item_not_found`。
+     * The item with its versions, plus `hasIcon` (the latest version has an icon, served by `GET
+     * items/:id/icon`) and `suggestedAppearance` (the platform version's, null without one: the page
+     * offers 应用此插件的外观 when set). Each version carries `client`: its extension package's
+     * client build (files with sizes, total, client API version; null without one), what the
+     * permission confirmation of an org's upload shows in its 客户端代码 group (client extensions spec
+     * §5.4). Unknown -> 404 `catalog.item_not_found`.
      */
     async get(id) {
         const detail = await this.catalog.get(id);
-        return { ...detail, hasIcon: await this.orgCatalog.hasIcon(id) };
+        const platform = detail.versions.find((v) => v.version === detail.item.platformVersion);
+        const [hasIcon, builds] = await Promise.all([
+            this.orgCatalog.hasIcon(id),
+            this.clientBuilds.summaries(detail.versions.flatMap((v) => (v.extensionSha256 === null ? [] : [v.extensionSha256]))),
+        ]);
+        return {
+            ...detail,
+            versions: detail.versions.map((v) => ({
+                ...v,
+                client: v.extensionSha256 === null ? null : (builds.get(v.extensionSha256) ?? null),
+            })),
+            hasIcon,
+            suggestedAppearance: suggestedAppearanceOf(platform?.manifest),
+        };
+    }
+    /**
+     * 应用此插件的外观 (client extensions spec §6.5): sets the plugin's suggested theme as the platform
+     * default theme and each suggested replacement as the platform arrangement's `use` of its slot, in
+     * one transaction. `dryRun: true` answers the same changes and writes nothing. A theme that cannot
+     * be the platform default -> 400 `theme.not_available` (nothing written); a replacement not
+     * available on the platform is skipped. No such item, or no suggestion -> 404
+     * `catalog.item_not_found`.
+     */
+    applyAppearance(principal, id, body) {
+        const actor = requireUser(principal);
+        const tokenId = patTokenId(actor);
+        return this.appearance.apply({ platform: true }, id, { accountId: actor.account.id, ...(tokenId !== undefined && { tokenId }) }, body.dryRun === true);
     }
     /**
      * The item's icon (disabled items included; same response headers as the org side, see
@@ -168,24 +233,113 @@ 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) {
+    /**
+     * A setup guide of the item as the platform sees it (spec 2026-11-09-setup-guides-v2-design.md
+     * §9.3; the admin console's connector template page): any live item, the admin audience, no org
+     * (`orgName` unresolved, reason `no_org`), no target, no checks run. Unknown item -> 404
+     * `catalog.item_not_found`, unknown guide -> 404 `catalog.guide_not_found`.
+     */
+    async guide(itemId, guideId, q) {
+        return { guide: await this.guides.renderForPlatform(itemId, guideId, q) };
+    }
+    /**
+     * 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.catalog.installToDeployment(actor.account.id, id, body.version, actorOpts(actor));
+        return this.updater.update(actor.account.id, id, body, actorOpts(actor));
+    }
+    /** 删除条目（软删除，已安装的组件不受影响）。 */
+    async remove(principal, id) {
+        const actor = requireUser(principal);
+        await this.catalog.remove(actor.account.id, id, actorOpts(actor));
     }
 };
 __decorate([
@@ -219,41 +373,97 @@ __decorate([
 ], AdminCatalogController.prototype, "confirm", null);
 __decorate([
     Get("items"),
-    __param(0, ZQuery(CatalogItemsQuery))
+    __param(0, ZQuery(CatalogItemsQueryDto))
 ], AdminCatalogController.prototype, "list", null);
 __decorate([
     Get("items/:id"),
     __param(0, Param("id"))
 ], AdminCatalogController.prototype, "get", null);
+__decorate([
+    Post("items/:id/appearance"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("id")),
+    __param(2, ZBody(AppearanceApplyBodyDto))
+], AdminCatalogController.prototype, "applyAppearance", null);
 __decorate([
     Get("items/:id/icon"),
     __param(0, Param("id")),
     __param(1, Res())
 ], AdminCatalogController.prototype, "icon", null);
 __decorate([
-    Put("items/:id/policy"),
+    Get(":itemId/guides/:guideId"),
+    __param(0, Param("itemId")),
+    __param(1, Param("guideId")),
+    __param(2, ZQuery(AdminCatalogGuideQueryDto))
+], AdminCatalogController.prototype, "guide", null);
+__decorate([
+    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(CatalogUpdatePreviewBodyDto))
+], 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(CatalogUpdateBodyDto))
+], 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)),
+    __param(5, Inject(PluginIcons)),
+    __param(6, Inject(AppearanceService)),
+    __param(7, Inject(ClientBuilds)),
+    __param(8, Inject(PluginGuides))
 ], AdminCatalogController);
 export { AdminCatalogController };

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

@@ -0,0 +1,82 @@
+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>;
+/**
+ * `GET :itemId/guides/:guideId`, the super admin's preview of a setup guide (spec
+ * 2026-11-09-setup-guides-v2-design.md §9.3): only the document language; no org, no target.
+ */
+export declare const AdminCatalogGuideQuery: z.ZodObject<{
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$strict>;
+export declare const ADMIN_CATALOG_ROUTES: readonly RouteSchemas[];

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

@@ -0,0 +1,99 @@
+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();
+/**
+ * `GET :itemId/guides/:guideId`, the super admin's preview of a setup guide (spec
+ * 2026-11-09-setup-guides-v2-design.md §9.3): only the document language; no org, no target.
+ */
+export const AdminCatalogGuideQuery = z
+    .object({ locale: z.enum(["en", "zh"]).optional() })
+    .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/appearance.schemas.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/**
+ * The body of both "apply this plugin's appearance" routes (client extensions spec §6.5):
+ * `dryRun: true` answers what would change and writes nothing (the confirm dialog's preview).
+ */
+export declare const AppearanceApplyBody: z.ZodObject<{
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const APPEARANCE_ROUTES: readonly RouteSchemas[];