@capybara-hq/kernel 0.1.0-rc.10 → 0.1.0-rc.12

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

@@ -1,4 +1,5 @@
 import type { z } from "zod";
+import { PluginIcons } from "../extensions/plugin-icons.js";
 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";
@@ -13,7 +14,8 @@ import { PlatformComponents, type UploadedComponentVersion } from "./platform-co
 export declare class AdminComponentsController {
     private readonly scope;
     private readonly components;
-    constructor(scope: ComponentScopeService, components: PlatformComponents);
+    private readonly icons;
+    constructor(scope: ComponentScopeService, components: PlatformComponents, icons: PluginIcons);
     /**
      * Updates a platform skill on its own (spec §7.2): the skill package (zip) as the raw body
      * (`application/octet-stream`, at most `packages.maxBytes`). The package keeps the skill's name
@@ -26,9 +28,14 @@ export declare class AdminComponentsController {
     }): Promise<UploadedComponentVersion>;
     /** Updates a platform agent template on its own: `{ content }` is the template markdown file. */
     uploadAgentTemplateVersion(principal: Principal, p: z.infer<typeof IdParams>, body: z.infer<typeof TemplateVersionBody>): Promise<UploadedComponentVersion>;
-    /** `GET ?kind=`: every platform component of the kind (plugin, owner, scope, version, orgs on). */
+    /**
+     * `GET ?kind=`: every platform component of the kind (plugin, owner, scope, version, orgs on),
+     * each with its display name and its plugin's icon (`icon`, the admin route; null without one).
+     */
     list(q: z.infer<typeof ListQuery>): Promise<{
-        components: ComponentView[];
+        components: (ComponentView & {
+            icon: string | null;
+        })[];
     }>;
     /**
      * A component's versions, newest first: `{ versions: [{ version, catalogVersion, updatedOnOwn,
@@ -65,14 +72,19 @@ export declare class AdminComponentsController {
  */
 export declare class OrgComponentsController {
     private readonly scope;
-    constructor(scope: ComponentScopeService);
+    private readonly icons;
+    constructor(scope: ComponentScopeService, icons: PluginIcons);
     /**
      * The platform components offered to the org (`?kind=`, `?itemId=`: only those; Task 10): each
      * 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).
+     * admin may switch it. Members read it (the workspace pages are read-only for them). Each has
+     * its display name and `icon`, its plugin's icon on the org's catalog route (null without one,
+     * or when the org's catalog does not show the plugin to the reader: the share gate holds).
      */
     list(org: OrgContext, q: z.infer<typeof OrgComponentListQuery>): Promise<{
-        components: OrgOfferedComponentView[];
+        components: (OrgOfferedComponentView & {
+            icon: string | null;
+        })[];
     }>;
     setSwitch(principal: Principal, org: OrgContext, p: z.infer<typeof ComponentParams>, body: z.infer<typeof SwitchBody>): Promise<{
         component: OrgComponentView;

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

@@ -9,6 +9,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { Controller, Get, HttpCode, Inject, Post, Put, Req } from "@nestjs/common";
 import { ApiError } from "../errors.js";
+import { orgIconScope, 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, ZParam, ZQuery } from "../infra/validation/zod-params.js";
@@ -36,6 +37,16 @@ class ComponentShownBody extends createZodDto(ShownBody, "ComponentShownBody") {
 }
 class ComponentSwitchBody extends createZodDto(SwitchBody, "ComponentSwitchBody") {
 }
+/**
+ * Each component with `icon`: its plugin's icon URL on the reader's route (null without one, for
+ * a component without a plugin, or when the reader may not see the plugin; maintainer decision
+ * 2026-11-09: a connector template without an icon of its own shows its plugin's).
+ */
+async function withIcons(icons, rows, scope) {
+    const ids = rows.flatMap((r) => (r.itemId === null ? [] : [r.itemId]));
+    const urls = await icons.ofItems(ids, scope);
+    return rows.map((r) => ({ ...r, icon: r.itemId === null ? null : (urls.get(r.itemId) ?? null) }));
+}
 const actorOpts = (actor) => {
     const tokenId = patTokenId(actor);
     return tokenId !== undefined ? { actorTokenId: tokenId } : {};
@@ -49,9 +60,11 @@ const actorOpts = (actor) => {
 let AdminComponentsController = class AdminComponentsController {
     scope;
     components;
-    constructor(scope, components) {
+    icons;
+    constructor(scope, components, icons) {
         this.scope = scope;
         this.components = components;
+        this.icons = icons;
     }
     /**
      * Updates a platform skill on its own (spec §7.2): the skill package (zip) as the raw body
@@ -73,9 +86,14 @@ let AdminComponentsController = class AdminComponentsController {
         const actor = requireUser(principal);
         return this.components.uploadAgentTemplateVersion({ accountId: actor.account.id, ...actorOpts(actor) }, p.id, body.content);
     }
-    /** `GET ?kind=`: every platform component of the kind (plugin, owner, scope, version, orgs on). */
+    /**
+     * `GET ?kind=`: every platform component of the kind (plugin, owner, scope, version, orgs on),
+     * each with its display name and its plugin's icon (`icon`, the admin route; null without one).
+     */
     async list(q) {
-        return { components: await this.scope.list(q.kind) };
+        return {
+            components: await withIcons(this.icons, await this.scope.list(q.kind), { kind: "admin" }),
+        };
     }
     /**
      * A component's versions, newest first: `{ versions: [{ version, catalogVersion, updatedOnOwn,
@@ -178,7 +196,8 @@ AdminComponentsController = __decorate([
     Controller("api/v1/admin/components"),
     SuperAdmin(),
     __param(0, Inject(ComponentScopeService)),
-    __param(1, Inject(PlatformComponents))
+    __param(1, Inject(PlatformComponents)),
+    __param(2, Inject(PluginIcons))
 ], AdminComponentsController);
 export { AdminComponentsController };
 /**
@@ -189,21 +208,24 @@ export { AdminComponentsController };
  */
 let OrgComponentsController = class OrgComponentsController {
     scope;
-    constructor(scope) {
+    icons;
+    constructor(scope, icons) {
         this.scope = scope;
+        this.icons = icons;
     }
     /**
      * The platform components offered to the org (`?kind=`, `?itemId=`: only those; Task 10): each
      * 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).
+     * admin may switch it. Members read it (the workspace pages are read-only for them). Each has
+     * its display name and `icon`, its plugin's icon on the org's catalog route (null without one,
+     * or when the org's catalog does not show the plugin to the reader: the share gate holds).
      */
     async list(org, q) {
-        return {
-            components: await this.scope.orgList(org.orgId, {
-                ...(q.kind !== undefined && { kind: q.kind }),
-                ...(q.itemId !== undefined && { itemId: q.itemId }),
-            }),
-        };
+        const rows = await this.scope.orgList(org.orgId, {
+            ...(q.kind !== undefined && { kind: q.kind }),
+            ...(q.itemId !== undefined && { itemId: q.itemId }),
+        });
+        return { components: await withIcons(this.icons, rows, orgIconScope(org)) };
     }
     async setSwitch(principal, org, p, body) {
         const actor = requireUser(principal);
@@ -229,6 +251,7 @@ __decorate([
 ], OrgComponentsController.prototype, "setSwitch", null);
 OrgComponentsController = __decorate([
     Controller("api/v1/orgs/:orgId/components"),
-    __param(0, Inject(ComponentScopeService))
+    __param(0, Inject(ComponentScopeService)),
+    __param(1, Inject(PluginIcons))
 ], OrgComponentsController);
 export { OrgComponentsController };

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

@@ -4,12 +4,14 @@ export declare const ComponentKindSchema: z.ZodEnum<{
     agent_template: "agent_template";
     connector_template: "connector_template";
     skill: "skill";
+    theme: "theme";
 }>;
 export declare const OrgComponentListQuery: z.ZodObject<{
     kind: z.ZodOptional<z.ZodEnum<{
         agent_template: "agent_template";
         connector_template: "connector_template";
         skill: "skill";
+        theme: "theme";
     }>>;
     itemId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -19,6 +21,7 @@ export declare const ComponentListQuery: z.ZodObject<{
         agent_template: "agent_template";
         connector_template: "connector_template";
         skill: "skill";
+        theme: "theme";
     }>;
 }, z.core.$strict>;
 export declare const ComponentParams: z.ZodObject<{
@@ -26,6 +29,7 @@ export declare const ComponentParams: z.ZodObject<{
         agent_template: "agent_template";
         connector_template: "connector_template";
         skill: "skill";
+        theme: "theme";
     }>;
     id: z.ZodString;
 }, z.core.$strip>;

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

@@ -1,8 +1,11 @@
+import type { LocalizedName, ThemeScheme } from "@capybara-hq/plugin-sdk";
 import { ApiError } from "../errors.js";
 import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { OrgLock } from "../orgs/org-lock.js";
+import { type ThemeSwatch } from "../themes/theme-state.js";
+import { type ThemePreview } from "../themes/theme-usage.js";
 import type { ActorOpts } from "./catalog.service.js";
 import { ComponentPromotion } from "./component-promotion.js";
 import { type ComponentKind } from "./component-state.js";
@@ -38,7 +41,14 @@ export interface ComponentScopePreview {
         plugins: string[];
         /** An agent template's: the owner of each clashing template, in `skills`' order. */
         owners?: Owner[];
+        /** A theme's: the clashing themes on in the org (`skills` then empty). */
+        themes?: string[];
     }[];
+    /**
+     * A theme the change takes away from some orgs (themes spec §6): the orgs among them whose
+     * default it is and how many people picked it. Absent when no theme is taken away.
+     */
+    themes?: ThemePreview[];
     scopeHash: string;
 }
 /** A component's own scope (`orgs` only with `named`), a disable, or following its plugin again. */
@@ -58,7 +68,13 @@ export type ComponentTarget = {
 export interface ComponentView {
     kind: ComponentKind;
     id: string;
+    /** Skill or template name; a connector template's id (the file's base name). */
     name: string;
+    /** A connector template's localized display name (null: show `name`). */
+    displayName: {
+        zh: string;
+        en: string;
+    } | null;
     description: string | null;
     /** The plugin it came from (null: none). */
     plugin: string | null;
@@ -91,6 +107,11 @@ export interface ComponentView {
      * other scopes, builtin plugins and orgs' own rows.
      */
     offCount: number;
+    /** A theme: its name and swatches from its current version (absent for other kinds). */
+    theme?: {
+        name: LocalizedName;
+        swatches: Partial<Record<ThemeScheme, ThemeSwatch>>;
+    };
 }
 /** One version of a platform component (`GET admin/components/:kind/:id/versions`). */
 export interface ComponentVersionView {
@@ -111,7 +132,10 @@ export interface OrgComponentView {
     /** The org's switch (null: never switched). */
     switch: boolean | null;
     on: boolean;
-    /** Of a builtin plugin: it cannot be switched off (an `all` one can, layering spec §4). */
+    /**
+     * Of a builtin plugin, or the platform default theme (themes spec §7): it cannot be switched off
+     * (an `all` one can, layering spec §4).
+     */
     locked: boolean;
 }
 /**
@@ -120,6 +144,11 @@ export interface OrgComponentView {
  * show with their switches. Never a component the org cannot see.
  */
 export interface OrgOfferedComponentView extends OrgComponentView {
+    /** A connector template's localized display name (null: show `name`). */
+    displayName: {
+        zh: string;
+        en: string;
+    } | null;
     description: string | null;
     itemId: string | null;
     version: string;
@@ -157,6 +186,11 @@ export type ComponentSwitchResult = {
             refs: string[];
         }[];
         connectorsKept: number;
+        /**
+         * A theme: whether it is the org's default and how many of its members picked it (themes
+         * spec §6). Absent for other kinds and for a theme nobody there chose.
+         */
+        themes?: ThemePreview[];
     };
     confirm: string;
 };
@@ -166,6 +200,8 @@ type AuditOpts = ActorOpts & {
 };
 /**
  * 409 `plugin.skill_conflict` listing the orgs whose own skills use a component's name (rule 10);
+ * for a theme 409 `theme.id_taken` listing the orgs where another theme with its id is on (details
+ * `[{ theme, orgId, themes, plugins }]`);
  * for an agent template 409 `agent_template.name_taken` listing the orgs that already use its
  * roster type (ruling P4-13; details `[{ orgId, type, templateId, owner }]`, one per clashing
  * template, `owner` as save-as names it).
@@ -181,10 +217,11 @@ export declare function nameConflictError(conflicts: ComponentScopePreview["conf
  * An org admin switches one component on or off in the org (only that component, rule 5); one of a
  * builtin plugin -> 409 `plugin.scope_locked` (an `all` one may go off, layering spec §4); switching
  * off something in use is previewed with its agents first.
- * Name clashes are checked for skills only: an org agent template always carries its plugin's
- * type, so one with a platform template's type is a copy of it. Components are resolved at read
- * time (skills/usable.ts, agents/templates.ts), so nothing is enqueued. Stateless, shared by every
- * replica.
+ * Name clashes are checked for skills, agent templates by their roster type, and themes by their
+ * id among the themes on in an org (themes spec §6). A change that would take the platform default
+ * theme away from an org is refused (409 `theme.platform_default`, themes spec §7). Components are
+ * resolved at read time (skills/usable.ts, agents/templates.ts), so nothing is enqueued.
+ * Stateless, shared by every replica.
  */
 export declare class ComponentScopeService {
     private readonly kdb;
@@ -203,7 +240,7 @@ export declare class ComponentScopeService {
     /**
      * What the admin routes act on (ruling P3-23): the platform component `id`, an org row the org
      * promoted already (its platform row), or an org's own row not promoted yet. A connector
-     * template has no org rows; anything else -> 404 `component.not_found`.
+     * template or a theme has no org rows; anything else -> 404 `component.not_found`.
      */
     private resolve;
     /**
@@ -224,12 +261,13 @@ export declare class ComponentScopeService {
     /**
      * The org's copies of platform skills or agent templates linked without a pin (ruling B2), by
      * platform id: they resolve to it, so agents that select them use it (none for connector
-     * templates).
+     * templates and themes).
      */
     private linkedCopies;
     /**
      * The orgs' own skills (org scope) and agent templates, not linked to a platform component
-     * (ruling P2-11): listed read-only, on in their org only. Connector templates have none.
+     * (ruling P2-11): listed read-only, on in their org only. Connector templates have none; an
+     * org's own theme is a platform_themes row with its org as owner, listed with the platform ones.
      */
     private orgOwned;
     /** The preview of a scope change, a disable or a return to following the plugin (nothing written). */
@@ -257,7 +295,8 @@ export declare class ComponentScopeService {
      * The org admin's switch of one component (`PUT orgs/:orgId/components/:kind/:id/switch`): only
      * this component (rule 5). A component not offered to the org -> 404. On: refused while the
      * component or its plugin is disabled (`plugin.disabled`) or an own skill of the org has its name
-     * (`plugin.skill_conflict`, rule 10). Off: of a builtin plugin -> `plugin.scope_locked`; while it
+     * (`plugin.skill_conflict`, rule 10; a theme: `theme.id_taken`). Off: the platform default theme
+     * while it is on -> `theme.platform_default`; of a builtin plugin -> `plugin.scope_locked`; while it
      * is on, without `confirm` the preview (agents that use it) and its hash are returned, with the
      * current hash the switch is written (a changed preview -> `plugin.switch_stale`).
      */
@@ -314,6 +353,17 @@ export declare class ComponentScopeService {
      * (an org row not promoted yet: `[owner]`), else read.
      */
     private targetOf;
+    /**
+     * 409 `theme.platform_default` when theme `c` is the platform default and `t` would leave it
+     * narrower than `all` or gone (themes spec §7), in the caller's transaction, before any write.
+     */
+    private assertKeepsPlatformDefault;
+    /**
+     * Theme `c`'s availability under `t`: gone when disabled (or its plugin is disabled or deleted
+     * while it follows it), else `all` when its effective scope (its own, or its plugin's; builtin:
+     * `all`) is `all`, else narrower.
+     */
+    private themeAfter;
     /** Live orgs (`only`: that one), sorted by id. */
     private liveOrgs;
     private on;