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

package/dist/catalog/platform-components.d.ts

@@ -1,4 +1,4 @@
-import { type AgentTemplate, type ConnectorTemplateFile } from "@capybara-hq/plugin-sdk";
+import { type AgentTemplate, type ConnectorTemplateFile, type ParsedTheme } from "@capybara-hq/plugin-sdk";
 import type { SkillManifest, SourceFormat } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -6,9 +6,9 @@ import type { KernelLogger } from "../log.js";
 import { type SkillPackageFile } from "../skills/package.js";
 import { type PrefixedStorage, StorageService } from "../storage/storage.service.js";
 import { CatalogItemLock } from "./locks.js";
-/** A skill or agent template version a sync wrote (`from` null: the component was created). */
+/** A skill, agent template or theme version a sync wrote (`from` null: the component was created). */
 export interface ChangedRef {
-    kind: "skill" | "agent_template";
+    kind: "skill" | "agent_template" | "theme";
     id: string;
     name: string;
     from: number | null;
@@ -31,11 +31,17 @@ export interface PlatformSyncResult {
     skills: ChangedRef[];
     agentTemplates: ChangedRef[];
     connectorTemplates: ChangedConnectorTemplateRef[];
+    themes: ChangedRef[];
 }
 /** The prefix (in `deployment/`) of a platform skill version's files. */
 export declare const platformSkillPrefix: (id: string, version: number) => string;
 /** The prefix (in `deployment/`) of a platform agent template version's file. */
 export declare const platformAgentTemplatePrefix: (id: string, version: number) => string;
+/**
+ * The prefix (in `deployment/`) of a platform theme's files (themes spec §6); a version's fonts
+ * and logo are under `<prefix><version>-<catalog version>/` ({@link syncVersionPrefix}).
+ */
+export declare const platformThemePrefix: (id: string) => string;
 /**
  * A fresh prefix (in `deployment/`) for a version written before its transaction (ruling P3-45):
  * `<id>/<version>-<uuid>/`, so two writers racing for one version number never overwrite each
@@ -73,6 +79,19 @@ interface TemplateStep {
     file: SkillPackageFile;
     template: AgentTemplate;
 }
+interface ThemeStep {
+    /** The theme id. */
+    name: string;
+    base: Base<number> | undefined;
+    /** The platform row id. */
+    id: string;
+    to: number;
+    /** null: the theme has no assets. */
+    prefix: string | null;
+    /** Fonts and logo, sanitized (paths relative to the plugin root). */
+    files: SkillPackageFile[];
+    theme: ParsedTheme;
+}
 interface ConnectorTemplateStep {
     name: string;
     base: Base<string> | undefined;
@@ -88,6 +107,7 @@ export interface SyncPlan {
     skills: SkillStep[];
     agentTemplates: TemplateStep[];
     connectorTemplates: ConnectorTemplateStep[];
+    themes: ThemeStep[];
 }
 /** A component changed between the plan and its write (a concurrent sync): plan again. */
 export declare class PlanStale extends Error {

package/dist/catalog/platform-components.js

@@ -7,10 +7,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-// Platform components (plugin scope phase 2, rulings A2 and C2): the skills, agent templates and
-// connector templates of a catalog item, stored once for the deployment. Files live under
-// `deployment/platform/{skills,agent-templates}/<id>/<version>/`, never under an org prefix (orgs
-// are purged by prefix).
+// Platform components (plugin scope phase 2, rulings A2 and C2): the skills, agent templates,
+// connector templates and themes of a catalog item, stored once for the deployment. Files live
+// under `deployment/platform/{skills,agent-templates,themes}/<id>/<version>…/`, never under an org
+// prefix (orgs are purged by prefix).
 import { createHash, randomUUID } from "node:crypto";
 import { parseAgentTemplate, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
@@ -24,7 +24,7 @@ import { packagePath } from "../packages/tgz.js";
 import { readSkillPackage, skillManifest } from "../skills/package.js";
 import { StorageService } from "../storage/storage.service.js";
 import { canonicalJson } from "../tools/canonical-json.js";
-import { readCatalogAgentTemplates, readCatalogFiles, readCatalogTemplates, skillFilesDigest, skillOf, } from "./catalog-content.js";
+import { readCatalogAgentTemplates, readCatalogFiles, readCatalogTemplates, readCatalogThemes, skillFilesDigest, skillOf, themeAssetsDigest, } from "./catalog-content.js";
 import { putCatalogFiles } from "./catalog-items.js";
 import { CatalogItemLock } from "./locks.js";
 import { assertNotAwaiting } from "./ownership.js";
@@ -32,6 +32,11 @@ import { assertNotAwaiting } from "./ownership.js";
 export const platformSkillPrefix = (id, version) => `platform/skills/${id}/${version}/`;
 /** The prefix (in `deployment/`) of a platform agent template version's file. */
 export const platformAgentTemplatePrefix = (id, version) => `platform/agent-templates/${id}/${version}/`;
+/**
+ * The prefix (in `deployment/`) of a platform theme's files (themes spec §6); a version's fonts
+ * and logo are under `<prefix><version>-<catalog version>/` ({@link syncVersionPrefix}).
+ */
+export const platformThemePrefix = (id) => `platform/themes/${id}/`;
 /**
  * A fresh prefix (in `deployment/`) for a version written before its transaction (ruling P3-45):
  * `<id>/<version>-<uuid>/`, so two writers racing for one version number never overwrite each
@@ -94,9 +99,10 @@ let PlatformComponents = class PlatformComponents {
             const plan = await this.plan(itemId, version);
             if (plan.skills.length === 0 &&
                 plan.agentTemplates.length === 0 &&
-                plan.connectorTemplates.length === 0) {
+                plan.connectorTemplates.length === 0 &&
+                plan.themes.length === 0) {
                 await this.markSynced(itemId, version);
-                return { skills: [], agentTemplates: [], connectorTemplates: [] };
+                return { skills: [], agentTemplates: [], connectorTemplates: [], themes: [] };
             }
             await this.writeFiles(plan);
             try {
@@ -109,6 +115,7 @@ let PlatformComponents = class PlatformComponents {
                     skills: r.skills.length,
                     agentTemplates: r.agentTemplates.length,
                     connectorTemplates: r.connectorTemplates.length,
+                    themes: r.themes.length,
                 });
                 return r;
             }
@@ -449,6 +456,7 @@ let PlatformComponents = class PlatformComponents {
             skills: [],
             agentTemplates: [],
             connectorTemplates: [],
+            themes: [],
         };
         for (const s of manifest.skills ?? []) {
             const files = await readCatalogFiles(this.files, row.object_prefix, row.files, packagePath(s.path));
@@ -524,17 +532,53 @@ let PlatformComponents = class PlatformComponents {
                 file: t.file,
             });
         }
+        // Themes (by plugin and id): changed when the definition or an asset changed
+        for (const t of await readCatalogThemes(this.files, v)) {
+            const live = await this.db
+                .selectFrom("platform_themes as p")
+                .innerJoin("platform_theme_versions as pv", (j) => j.onRef("pv.theme_id", "=", "p.id").onRef("pv.version", "=", "p.current_version"))
+                .leftJoin("catalog_item_versions as cv", (j) => j
+                .onRef("cv.item_id", "=", "p.catalog_item_id")
+                .onRef("cv.version", "=", "pv.catalog_version"))
+                .select(["p.id", "p.current_version", "pv.definition", "cv.files"])
+                .where("p.plugin_name", "=", plugin)
+                .where("p.name", "=", t.id)
+                .where("p.deleted_at", "is", null)
+                .executeTakeFirst();
+            if (live &&
+                canonicalJson(live.definition) === canonicalJson(t.theme) &&
+                live.files !== null &&
+                themeAssetsDigest(live.files, live.definition) === t.assetsDigest) {
+                continue;
+            }
+            const id = live?.id ?? randomUUID();
+            const to = (live?.current_version ?? 0) + 1;
+            plan.themes.push({
+                name: t.id,
+                base: live && { id: live.id, version: live.current_version },
+                id,
+                to,
+                prefix: t.assets.length > 0
+                    ? syncVersionPrefix(`${platformThemePrefix(id)}${to}/`, version)
+                    : null,
+                files: t.assets,
+                theme: t.theme,
+            });
+        }
         return plan;
     }
     /** Copies the planned versions' files to their platform prefixes. */
     async writeFiles(plan) {
-        if (plan.skills.length === 0 && plan.agentTemplates.length === 0)
+        const themes = plan.themes.filter((t) => t.prefix !== null);
+        if (plan.skills.length === 0 && plan.agentTemplates.length === 0 && themes.length === 0)
             return;
         this.files.assertAvailable();
         for (const s of plan.skills)
             await putCatalogFiles(this.files, s.prefix, s.files);
         for (const a of plan.agentTemplates)
             await putCatalogFiles(this.files, a.prefix, [a.file]);
+        for (const t of themes)
+            await putCatalogFiles(this.files, t.prefix, t.files);
     }
     /**
      * Writes the planned rows under the item name's lock (the lock of the import confirm), after
@@ -543,7 +587,12 @@ let PlatformComponents = class PlatformComponents {
     async apply(plan) {
         await this.itemLock.lock(plan.plugin);
         const t = this.db;
-        const out = { skills: [], agentTemplates: [], connectorTemplates: [] };
+        const out = {
+            skills: [],
+            agentTemplates: [],
+            connectorTemplates: [],
+            themes: [],
+        };
         // New component rows carry the plugin's owner and 可共享 flag (ruling P3-2); an org plugin's
         // skills and agent templates were created in its owner org (`origin_org_id`, immutable, F27),
         // and like the plugin they are not shown to other orgs until the super admin shows them
@@ -725,6 +774,66 @@ let PlatformComponents = class PlatformComponents {
                 to: plan.version,
             });
         }
+        for (const th of plan.themes) {
+            const live = await t
+                .selectFrom("platform_themes")
+                .select(["id", "current_version"])
+                .where("plugin_name", "=", plan.plugin)
+                .where("name", "=", th.name)
+                .where("deleted_at", "is", null)
+                .forUpdate()
+                .executeTakeFirst();
+            assertBase(live && { id: live.id, version: live.current_version }, th.base);
+            const description = th.theme.description?.en ?? null;
+            const descriptionZh = th.theme.description?.zh ?? null;
+            if (live) {
+                await t
+                    .updateTable("platform_themes")
+                    .set({
+                    current_version: th.to,
+                    description,
+                    description_zh: descriptionZh,
+                    catalog_item_id: plan.itemId,
+                    updated_at: new Date(),
+                })
+                    .where("id", "=", th.id)
+                    .execute();
+            }
+            else {
+                await t
+                    .insertInto("platform_themes")
+                    .values({
+                    id: th.id,
+                    catalog_item_id: plan.itemId,
+                    plugin_name: plan.plugin,
+                    name: th.name,
+                    description,
+                    description_zh: descriptionZh,
+                    current_version: th.to,
+                    scope_mode: "follow",
+                    ...owned,
+                    ...origin,
+                })
+                    .execute();
+            }
+            await t
+                .insertInto("platform_theme_versions")
+                .values({
+                theme_id: th.id,
+                version: th.to,
+                definition: JSON.stringify(th.theme),
+                object_prefix: th.prefix,
+                catalog_version: plan.version,
+            })
+                .execute();
+            out.themes.push({
+                kind: "theme",
+                id: th.id,
+                name: th.name,
+                from: th.base?.version ?? null,
+                to: th.to,
+            });
+        }
         return out;
     }
 };

package/dist/catalog/platform-migration.js

@@ -203,7 +203,8 @@ let PlatformMigration = class PlatformMigration {
             const version = await this.platformVersion(item.id, item.latest_version);
             try {
                 const r = await this.platform.syncFromVersion(item.id, version, { initial: false });
-                if (r.skills.length + r.agentTemplates.length + r.connectorTemplates.length > 0) {
+                const changed = r.skills.length + r.agentTemplates.length + r.connectorTemplates.length + r.themes.length;
+                if (changed > 0) {
                     stats.itemsSynced.push(`${item.name}@${version}`);
                 }
             }

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

@@ -1,4 +1,4 @@
-import { type AgentTemplate, type AgentTemplateTier, type LocalizedName, type PluginManifest } from "@capybara-hq/plugin-sdk";
+import { type AgentTemplate, type AgentTemplateTier, type LocalizedName, type PluginManifest, type ThemeScheme } from "@capybara-hq/plugin-sdk";
 import type { Queue } from "bullmq";
 import { ApiError } from "../errors.js";
 import { ExtensionAdminOps } from "../extensions/admin-ops.js";
@@ -134,6 +134,18 @@ export interface PluginReviewAgentTemplate {
     maxSteps?: number;
     skills?: string[];
 }
+/** One theme in a review (themes spec §6): what the super admin sees before confirming. */
+export interface PluginReviewTheme {
+    /** The theme id (the file's base name). */
+    id: string;
+    name: LocalizedName;
+    /** The schemes it defines. */
+    schemes: ThemeScheme[];
+    /** Number of fonts. */
+    fonts: number;
+    /** It replaces the logo mark, the wordmark or the favicon. */
+    logo: boolean;
+}
 /** The source of a staged import. */
 export interface PluginImportSource {
     /**
@@ -215,6 +227,11 @@ export interface PluginReview {
      * {@link pluginReviewHash} when empty, so their digests are unchanged.
      */
     agentTemplates?: PluginReviewAgentTemplate[];
+    /**
+     * Themes (themes spec §6). Absent without any; left out of {@link pluginReviewHash} when empty,
+     * so the digests of plugins without themes are unchanged.
+     */
+    themes?: PluginReviewTheme[];
     /**
      * Each dependency with the highest imported catalog version satisfying its range (null when
      * nothing does yet: the import still completes, an org install is refused until it is imported).
@@ -333,7 +350,9 @@ export interface StagedTarget {
 }
 /**
  * The API error of a plugin package that cannot be read in a catalog path: the pre-0.1.0 format ->
- * `catalog.legacy_format`, anything else -> `catalog.invalid_manifest` (issues as details).
+ * `catalog.legacy_format`; a failing theme (themes spec §5) -> `theme.invalid` (details
+ * `[{ theme, errors }]`) or `theme.unreadable` (details `[{ theme, issues }]`, the failing pairs);
+ * anything else -> `catalog.invalid_manifest` (issues as details).
  */
 export declare function catalogPackageError(e: PluginPackageError | ExtensionPackageError): ApiError;
 export declare class PluginImport {
@@ -629,10 +648,11 @@ export declare class PluginImport {
  * current version / package, its own review digest), every template field, each skill's name / path
  * / file count, the dependency resolution, the sha256 of every stored file, the format, the
  * translation report's items, the sha256 of the license text and the two review flags
- * (`claudeManifestIgnored`, `licenseTruncated`), and the agent templates when there are any.
+ * (`claudeManifestIgnored`, `licenseTruncated`), the agent templates when there are any and the
+ * themes when there are any.
  * Exported for tests. `repository` is display only.
  */
-export declare function pluginReviewHash(r: Pick<PluginReview, "name" | "version" | "contentDigest" | "extension" | "connectorTemplates" | "agentTemplates" | "skills" | "dependencies" | "format" | "translation" | "licenseText" | "claudeManifestIgnored" | "licenseTruncated">, files: {
+export declare function pluginReviewHash(r: Pick<PluginReview, "name" | "version" | "contentDigest" | "extension" | "connectorTemplates" | "agentTemplates" | "themes" | "skills" | "dependencies" | "format" | "translation" | "licenseText" | "claudeManifestIgnored" | "licenseTruncated">, files: {
     path: string;
     sha256: string;
 }[]): string;

package/dist/catalog/plugin-import.js

@@ -52,7 +52,7 @@ import { CatalogItemLock } from "./locks.js";
 import { assertNameFree, assertPackageFree, assertShareable, packageOwner, releaseExtensionClaim, shareGate, usableBy, } from "./ownership.js";
 import { PlatformComponents } from "./platform-components.js";
 import { PLATFORM_MIGRATION_JOB } from "./platform-migration.js";
-import { PluginPackageError, packagePath, readPluginFiles, readPluginPackage, } from "./plugin-package.js";
+import { PluginPackageError, packagePath, readPluginFiles, readPluginPackage, themeApiError, } from "./plugin-package.js";
 import { hasImportRequests, importRequestOf, resolveImportRequests } from "./request-rules.js";
 import { assertNameNotReserved } from "./reserved-names.js";
 import { addScopeOrg } from "./scope-orgs.js";
@@ -112,12 +112,17 @@ const reviewStale = (review) => new ApiError("plugin.review_stale", `The review
 const mismatch = (what) => new ApiError("marketplace.package_mismatch", `The downloaded package does not match the marketplace entry: ${what}`);
 /**
  * The API error of a plugin package that cannot be read in a catalog path: the pre-0.1.0 format ->
- * `catalog.legacy_format`, anything else -> `catalog.invalid_manifest` (issues as details).
+ * `catalog.legacy_format`; a failing theme (themes spec §5) -> `theme.invalid` (details
+ * `[{ theme, errors }]`) or `theme.unreadable` (details `[{ theme, issues }]`, the failing pairs);
+ * anything else -> `catalog.invalid_manifest` (issues as details).
  */
 export function catalogPackageError(e) {
     const legacy = e.code === "catalog.legacy_format" || e.code === "extension.legacy_format";
     if (legacy)
         return new ApiError("catalog.legacy_format", e.message, e.issues);
+    if (e.code === "theme.invalid" || e.code === "theme.unreadable") {
+        return themeApiError(e);
+    }
     return invalid(e.issues);
 }
 /** Runs a package read, mapping its errors with {@link catalogPackageError}. */
@@ -380,7 +385,7 @@ let PluginImport = class PluginImport {
         const objectFiles = content.files.filter((f) => content.objectPaths.has(f.path));
         if (objectFiles.length > 0 && retry === undefined) {
             if (source.kind === "bootstrap" && !this.files.available) {
-                throw new ApiError("storage.unavailable", `Bootstrap plugin ${m.name} ships skills, connector templates or agent templates, which are kept in object storage, and object storage is not running yet (it may be a bootstrap plugin itself); a required bootstrap plugin may ship only an icon and setup guides, an optional one is retried once the extensions have loaded`);
+                throw new ApiError("storage.unavailable", `Bootstrap plugin ${m.name} ships skills, connector templates, agent templates or themes, which are kept in object storage, and object storage is not running yet (it may be a bootstrap plugin itself); a required bootstrap plugin may ship only an icon and setup guides, an optional one is retried once the extensions have loaded`);
             }
             this.files.assertAvailable();
         }
@@ -430,6 +435,7 @@ let PluginImport = class PluginImport {
             skills: content.skills,
             connectorTemplates: content.templates,
             ...(content.agentTemplates.length > 0 && { agentTemplates: content.agentTemplates }),
+            ...(content.themes.length > 0 && { themes: content.themes }),
             dependencies,
             source: src,
             provenance: (opts.provenance ?? NOT_NPM).provenance,
@@ -1456,6 +1462,23 @@ let PluginImport = class PluginImport {
             const { name, description, instructions, model, ...rest } = a.template;
             return { name, path: a.path, description, instructions, model: model ?? "inherit", ...rest };
         });
+        // Themes: the file as written, the assets as sanitized by the reader (never the uploaded
+        // originals: a shared path, e.g. the plugin icon, is stored sanitized too)
+        const themes = pkg.themes.map((t) => {
+            keepObject(t.path);
+            for (const [path, data] of t.assets) {
+                stored.set(path, fileOf(path, data));
+                objectPaths.add(path);
+            }
+            const logo = t.theme.logo;
+            return {
+                id: t.id,
+                name: t.theme.name,
+                schemes: ["dark", "light"].filter((k) => t.theme.schemes[k] !== undefined),
+                fonts: t.theme.fonts?.length ?? 0,
+                logo: logo !== undefined && Object.keys(logo).length > 0,
+            };
+        });
         if (problems.length > 0)
             throw invalid(problems);
         return {
@@ -1465,6 +1488,7 @@ let PluginImport = class PluginImport {
             templates,
             skills,
             agentTemplates,
+            themes,
             notLoaded,
             templatePaths,
         };
@@ -1639,7 +1663,7 @@ export { PluginImport };
  */
 function normalizedManifest(pkg) {
     const pinned = new Map((pkg.manifest.skills ?? []).map((s) => [packagePath(s.path), s.pinned]));
-    const { agents: _, ...manifest } = pkg.manifest;
+    const { agents: _, themes: __, ...manifest } = pkg.manifest;
     return {
         ...manifest,
         skills: pkg.skills.map((s) => {
@@ -1651,6 +1675,7 @@ function normalizedManifest(pkg) {
         ...(pkg.agentTemplates.length > 0 && {
             agents: pkg.agentTemplates.map((a) => ({ path: `./${a.path}` })),
         }),
+        ...(pkg.themes.length > 0 && { themes: pkg.themes.map((t) => ({ path: `./${t.path}` })) }),
     };
 }
 /** package.json `name`, or null without one (a git plugin; never the string "undefined"). */
@@ -1682,13 +1707,17 @@ function actionOf(s, sha256, version) {
  * current version / package, its own review digest), every template field, each skill's name / path
  * / file count, the dependency resolution, the sha256 of every stored file, the format, the
  * translation report's items, the sha256 of the license text and the two review flags
- * (`claudeManifestIgnored`, `licenseTruncated`), and the agent templates when there are any.
+ * (`claudeManifestIgnored`, `licenseTruncated`), the agent templates when there are any and the
+ * themes when there are any.
  * Exported for tests. `repository` is display only.
  */
 export function pluginReviewHash(r, files) {
     const e = r.extension;
     const lic = r.licenseText;
-    const canonical = JSON.stringify([
+    // canonicalJson, not JSON.stringify: the review is stored as jsonb, which reorders object keys,
+    // so a template's auth / endpoint object would hash differently at confirm (plugin.review_stale
+    // on every import of a plugin whose connector template has a non-trivial auth block).
+    const canonical = canonicalJson([
         r.name,
         r.version,
         r.contentDigest,
@@ -1715,6 +1744,10 @@ export function pluginReviewHash(r, files) {
         ...((r.agentTemplates ?? []).length > 0
             ? [(r.agentTemplates ?? []).map((a) => [a.path, canonicalJson(a)])]
             : []),
+        // themes, only when there are any, tagged (never read as agent templates)
+        ...((r.themes ?? []).length > 0
+            ? [{ themes: (r.themes ?? []).map((t) => [t.id, canonicalJson(t)]) }]
+            : []),
     ]);
     return createHash("sha256").update(canonical).digest("hex").slice(0, 32);
 }
@@ -1785,7 +1818,8 @@ function ownStaging(owner) {
 /**
  * An org upload's custom deny, by content (ruling P3-15'): skills or agent templates ->
  * `customSkills`, connector templates -> `customConnectors`; each `deny` -> 403
- * `catalog.custom_disabled`. A package carrying neither passes.
+ * `catalog.custom_disabled`. A package carrying neither passes; themes are covered by neither
+ * switch (themes spec §6), so a themes-only upload passes.
  */
 async function assertCustomContent(db, content) {
     if (content.skills.length > 0 || content.agentTemplates.length > 0) {

package/dist/catalog/plugin-install.d.ts

@@ -11,6 +11,7 @@ import { OrgLock } from "../orgs/org-lock.js";
 import type { OrgAction } from "../orgs/roles.js";
 import { type SkillConflict, SkillsService } from "../skills/skills.service.js";
 import { StorageService } from "../storage/storage.service.js";
+import { type ThemePreview } from "../themes/theme-usage.js";
 import type { ConnectorDetail, CreateConnectorInput, ToolIssue } from "../tools/connectors.service.js";
 import { ConnectorsService } from "../tools/connectors.service.js";
 import { type CatalogVersionFiles, type TemplateDeps } from "./catalog-content.js";
@@ -42,7 +43,7 @@ export interface PluginInstallInput {
  * agent template (ref = its agent_templates id; like a skill, `skill_version` records the version
  * an install or upgrade added to an existing template).
  */
-export type ComponentKind = "extension" | "connector" | "skill" | "plugin" | "agent_template";
+export type ComponentKind = "extension" | "connector" | "skill" | "plugin" | "agent_template" | "theme";
 export interface UninstallReport {
     removed: {
         kind: ComponentKind;
@@ -84,6 +85,11 @@ export interface UninstallPreview {
             ref: string;
         }[];
     }[];
+    /**
+     * The plugin's themes on in the org through it (`follow`) that go off with it (themes spec §6):
+     * whether it is the org's default and how many people picked it. Absent when there are none.
+     */
+    themes?: ThemePreview[];
 }
 /** The confirm hash of an uninstall preview: sha256 over its sorted JSON (the scheme of `diffHash`). */
 export declare function uninstallPreviewHash(p: UninstallPreview): string;
@@ -303,6 +309,12 @@ export declare class PluginInstaller {
      * and a name two plugins of the same plan both bring (the one installed first is the source).
      */
     private assertNoSkillConflicts;
+    /**
+     * Refuses installing a plugin whose themes would come on in the org (they follow it) while
+     * another theme with the same id is on there (themes spec §6, rule 10): 409 `theme.id_taken`,
+     * details `[{ theme, orgId, themes, plugins }]`, before anything is written.
+     */
+    private assertNoThemeClashes;
     /** The connector checks of templates against what this replica loads right now. */
     templateDeps(): TemplateDeps;
     /**
@@ -453,6 +465,13 @@ export declare class PluginInstaller {
      * nothing written), and keeps the connectors it created as the org's own (`org_owned`).
      */
     private writeUninstall;
+    /**
+     * 409 `theme.platform_default` when uninstalling `installId` would switch the platform default
+     * theme off in the org (one of the plugin's `follow` themes on there through it, themes spec §7),
+     * in the caller's transaction before anything is written. A missing install passes (the
+     * uninstall reports it).
+     */
+    assertKeepsPlatformDefault(orgId: string, installId: string): Promise<void>;
     /**
      * The oldest other live install (not in `removing`) that has component `kind` / `ref`, or
      * undefined.

package/dist/catalog/plugin-install.js

@@ -28,10 +28,11 @@ import { OrgLock } from "../orgs/org-lock.js";
 import { packagePath } from "../packages/tgz.js";
 import { SkillsService, skillConflictError, skillConflicts, } from "../skills/skills.service.js";
 import { StorageService } from "../storage/storage.service.js";
+import { assertNotPlatformDefault, themesPreview, } from "../themes/theme-usage.js";
 import { ConnectorsService } from "../tools/connectors.service.js";
 import { findConnectorIn, lockOrgForActions, readCatalogAgentTemplates, readCatalogFiles, readCatalogTemplates, requiredActions, templateConnectorInput, templatePluginProblem, } from "./catalog-content.js";
 import { versionUsable } from "./catalog-items.js";
-import { agentDefinitionRefs, componentOn, connectorTemplateState, connectorTemplatesOn, listedIn, loadComponents, loadScopeState, pluginFactsOf, referenceIds, switchOf, } from "./component-state.js";
+import { agentDefinitionRefs, componentOn, connectorTemplateState, connectorTemplatesOn, listedIn, loadComponents, loadScopeState, pluginFactsOf, referenceIds, switchOf, themeIdClashes, } from "./component-state.js";
 import { assertItemInstallable, disabledPluginItems, pluginItemDisabled, resolveRequestsByInstall, } from "./request-rules.js";
 import { visibleTo } from "./scope.js";
 import { ScopeNoLongerWanted, ScopeStillWanted, wantedByScope } from "./scope-state.js";
@@ -336,12 +337,14 @@ let PluginInstaller = class PluginInstaller {
     async preflight(orgId, actor, itemId, version) {
         const plan = await this.plan(orgId, actor, itemId, version, null, "", undefined);
         await this.assertNoSkillConflicts(orgId, plan);
+        await this.assertNoThemeClashes(orgId, itemId);
         return { actions: planActions(plan) };
     }
     async install(orgId, actor, itemId, version, input, opts = {}) {
         const { switchOn, via, ...actorOpts } = opts;
         const plan = await this.plan(orgId, actor, itemId, version, input, "", undefined);
         await this.assertNoSkillConflicts(orgId, plan);
+        await this.assertNoThemeClashes(orgId, itemId);
         let installId;
         try {
             installId = await this.execute(orgId, actor, plan, actorOpts, {
@@ -386,6 +389,39 @@ let PluginInstaller = class PluginInstaller {
         if (conflicts.length > 0)
             throw skillConflictError(conflicts);
     }
+    /**
+     * Refuses installing a plugin whose themes would come on in the org (they follow it) while
+     * another theme with the same id is on there (themes spec §6, rule 10): 409 `theme.id_taken`,
+     * details `[{ theme, orgId, themes, plugins }]`, before anything is written.
+     */
+    async assertNoThemeClashes(orgId, itemId) {
+        const themes = await loadComponents(this.db, "theme", { itemId });
+        if (themes.length === 0)
+            return;
+        const st = await loadScopeState(this.db, "theme", themes);
+        const conflicts = [];
+        for (const c of themes) {
+            const p = pluginFactsOf(st, c.itemId, orgId);
+            const listed = listedIn(st, c.id, orgId);
+            const sw = switchOf(st, c.id, orgId);
+            if (componentOn(c, p, listed, sw) ||
+                !componentOn(c, p && { ...p, installed: true }, listed, sw)) {
+                continue;
+            }
+            const clash = await themeIdClashes(this.db, orgId, c, c.name);
+            if (clash.length > 0) {
+                conflicts.push({
+                    theme: c.name,
+                    orgId,
+                    themes: clash.map((x) => x.id),
+                    plugins: clash.map((x) => x.plugin ?? "platform"),
+                });
+            }
+        }
+        if (conflicts.length > 0) {
+            throw new ApiError("theme.id_taken", `The plugin's themes would come on next to themes with the same id already on in this organization (${conflicts.map((c) => c.theme).join(", ")}); switch those themes off first`, conflicts);
+        }
+    }
     /** The connector checks of templates against what this replica loads right now. */
     templateDeps() {
         const versions = new Map(this.registry.manifests().map((m) => [m.name, m.version]));
@@ -1108,6 +1144,10 @@ let PluginInstaller = class PluginInstaller {
                 }
             }
         }
+        // An org's own uninstall never takes the platform default theme away from it (themes spec §7;
+        // a scope sync uninstall follows a scope change or disable that was guarded already)
+        if (via !== "scope")
+            await this.assertKeepsPlatformDefault(orgId, installId);
         const outcome = await this.uninstallIn(orgId, actor, installId, {
             report,
             removing: new Set(),
@@ -1131,6 +1171,24 @@ let PluginInstaller = class PluginInstaller {
         });
         return report;
     }
+    /**
+     * 409 `theme.platform_default` when uninstalling `installId` would switch the platform default
+     * theme off in the org (one of the plugin's `follow` themes on there through it, themes spec §7),
+     * in the caller's transaction before anything is written. A missing install passes (the
+     * uninstall reports it).
+     */
+    async assertKeepsPlatformDefault(orgId, installId) {
+        const found = await this.db
+            .selectFrom("plugin_installs")
+            .select("id")
+            .where("id", "=", installId)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!found)
+            return;
+        const p = await this.previewUninstall(orgId, installId);
+        await assertNotPlatformDefault(this.db, (p.themes ?? []).map((t) => t.id), () => "narrower");
+    }
     /**
      * The oldest other live install (not in `removing`) that has component `kind` / `ref`, or
      * undefined.
@@ -1883,8 +1941,19 @@ let PluginInstaller = class PluginInstaller {
                     }
                 }
             }
+            const themes = await loadComponents(t, "theme", { itemId });
+            const tst = await loadScopeState(t, "theme", themes);
+            for (const c of themes) {
+                if (c.scopeMode === "follow" &&
+                    componentOn(c, pluginFactsOf(tst, c.itemId, orgId), listedIn(tst, c.id, orgId), switchOf(tst, c.id, orgId))) {
+                    lostThemes.set(c.id, new Set([orgId]));
+                }
+            }
         };
+        /** The themes that go off in the org with the install (and the dependencies it removes). */
+        const lostThemes = new Map();
         await visit(row.item_id, comps, true, new Set([installId]));
+        const themes = await themesPreview(t, lostThemes);
         return {
             installId,
             name: row.name,
@@ -1894,6 +1963,7 @@ let PluginInstaller = class PluginInstaller {
             agents: [...used.values()]
                 .map((a) => ({ ...a, uses: a.uses.sort((x, y) => x.ref.localeCompare(y.ref)) }))
                 .sort((x, y) => x.id.localeCompare(y.id)),
+            ...(themes !== undefined && { themes }),
         };
     }
     /**