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

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

@@ -1,36 +1,60 @@
-import { type AgentTemplate, type Connector, type ConnectorTemplateFile, type ConnectorTemplateSpec, type LocalizedName, type PluginManifest } from "@capybara-hq/plugin-sdk";
+import { type AgentTemplate, type Connector, type ConnectorTemplateFile, type ConnectorTemplateSpec, type LocalizedName, type ParsedTheme, 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";
 import type { StorageService } from "../storage/storage.service.js";
 import type { ConnectorTemplateRef, CreateConnectorInput } from "../tools/connectors.service.js";
 import type { CatalogItemView } from "./catalog.service.js";
+import { readDisplayFiles } from "./catalog-files.js";
 import type { ConnectorInstallInput, PluginInstallInput, PluginInstallView } from "./plugin-install.js";
-import type { CatalogRequestView } from "./requests.service.js";
+import type { OrgPluginState, PluginScope } from "./scope.js";
 /** A catalog item from an organization's view (`GET /orgs/:orgId/catalog`). */
-export interface OrgCatalogItem extends Omit<CatalogItemView, "installs" | "marketplaceId" | "latestMarketplaceVersion" | "newerInMarketplace"> {
+/** 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;
+    /** The owner org only (absent for other orgs): the version waiting for that confirmation. */
+    pendingVersion?: string | null;
+    scope: PluginScope;
+    /** Shipped with the deployment (a required bootstrap plugin): on in every org, never switchable. */
+    builtin: boolean;
     /**
-     * `yes` installable now; `needs_approval` needs enterprise admin approval (install returns 202 and
-     * creates a request); `granted` approved for this org; `disabled` disabled by the enterprise admin
-     * (members don't see it); `not_deployed` the plugin's extension is not on the deployment.
+     * 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 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).
      */
-    installable: "yes" | "needs_approval" | "granted" | "disabled" | "not_deployed";
+    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. */
+    notDeployed: boolean;
     /**
      * This org's live plugin install of the item (installing, installed or upgrading);
-     * `upgradeAvailable` is the version it can be upgraded to now (spec §10), null when none.
+     * `upgradeAvailable` is always null since plugin scope phase 2 (no per-org upgrade, ruling F2;
+     * kept for the web until its upgrade dialog goes).
      */
     installed: {
         pluginInstallId: string;
         version: string;
         upgradeAvailable: string | null;
     } | null;
-    /** This org's latest request for the item. */
+    /** This org's pending request for the item (spec §5.1), null when none. */
     request: {
         id: string;
-        stage: "org" | "deployment";
-        status: string;
+        kind: "access" | "enable";
+        createdAt: string;
     } | null;
 }
 /**
@@ -48,6 +72,14 @@ export interface OrgCatalogTemplate {
     editableEndpoint: string[];
     auth: Record<string, unknown>;
     ownership: "org" | "personal" | null;
+    /**
+     * The template's setup guide in the item's latest version (`GET …/catalog/:itemId/guides/
+     * :guideId`), null without one (spec 2026-11-09-setup-guides-v2-design.md §9.3).
+     */
+    guide: {
+        itemId: string;
+        guideId: string;
+    } | null;
 }
 /** `GET /orgs/:orgId/catalog/:itemId`: the item and what the install wizard needs (latest version). */
 export interface OrgCatalogDetail {
@@ -57,26 +89,35 @@ export interface OrgCatalogDetail {
     /** The plugin's extension (its name), null without one. */
     extension: string | null;
     templates: OrgCatalogTemplate[];
-    /** The plugin's dependencies (name and range). */
+    /**
+     * The plugin's dependencies (name and range); `implied` ones are the connector extensions its
+     * templates use that the org has off: the install switches them on first.
+     */
     dependencies: {
         name: string;
         range: string;
+        implied?: true;
     }[];
     /** The skill directories. */
     skills: string[];
     /** The agent template files (`agents/<name>.md`, sub-agents spec §16). */
     agents: string[];
+    /**
+     * An installed plugin whose connector templates on in the org miss a connector there
+     * (`needs_config`, ruling P2-10): those templates, for `POST …/catalog/:itemId/connectors`;
+     * empty otherwise (Task 10).
+     */
+    missingTemplates: OrgCatalogTemplate[];
 }
 /**
  * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
  * presets and editable paths, no credentials.
  */
-export declare function orgTemplateView(id: string, file: ConnectorTemplateFile): OrgCatalogTemplate;
+export declare function orgTemplateView(id: string, file: ConnectorTemplateFile, guide?: OrgCatalogTemplate["guide"]): OrgCatalogTemplate;
 /** An item's icon (the latest version's plugin icon). */
 export interface CatalogIcon {
     data: Uint8Array;
     contentType: "image/svg+xml" | "image/png";
-    policy: "allow" | "needs_approval" | "disabled";
 }
 /** The parts of a catalog version row an org install reads. */
 export interface CatalogVersionFiles {
@@ -88,6 +129,16 @@ export interface CatalogVersionFiles {
         sha256: string;
     }[];
 }
+/**
+ * The digest of a skill's files (paths relative to the skill directory): equal digests = the same
+ * content. Shared by the org upgrade diff and the platform components.
+ */
+export declare function skillFilesDigest(files: {
+    path: string;
+    sha256: string;
+}[]): string;
+/** The digest of the files under `dir/` of a catalog version (paths relative to it). */
+export declare function dirDigest(row: CatalogVersionFiles, dir: string): string;
 /** Whether the item's latest version has an icon; unreadable counts as none. */
 export declare function catalogHasIcon(db: KernelSchemaDb, itemId: string): Promise<boolean>;
 /**
@@ -97,14 +148,15 @@ export declare function catalogHasIcon(db: KernelSchemaDb, itemId: string): Prom
  * storage); no icon -> `catalog.icon_not_found`; stored content that is not a valid svg / png
  * (checked at import, this guards against tampered storage) -> `internal`.
  */
-export declare function readCatalogIcon(db: KernelSchemaDb, storage: StorageService, itemId: string, includeDisabled: boolean): Promise<CatalogIcon>;
+export declare function readCatalogIcon(db: KernelSchemaDb, itemId: string, includeDisabled: boolean): Promise<CatalogIcon>;
 export type { ConnectorInstallInput };
-/** The input of `POST /orgs/:orgId/catalog/:itemId/install` (default version: the latest). */
-export interface OrgInstallInput extends PluginInstallInput {
-    version?: string;
-}
-/** Install result: 201 installed; 202 needs enterprise admin approval, a request was created (or escalated). */
-export type OrgInstallResult = {
+/**
+ * The input of `POST /orgs/:orgId/catalog/:itemId/install`: the platform version is installed
+ * (ruling P2-17), so there is no version.
+ */
+export type OrgInstallInput = PluginInstallInput;
+/** Install result: 201 installed. */
+export interface OrgInstallResult {
     status: 201;
     installed: {
         itemId: string;
@@ -113,26 +165,19 @@ export type OrgInstallResult = {
     };
     /** The install view (its components, dependency installs included). */
     install: PluginInstallView;
-} | {
-    status: 202;
-    request: CatalogRequestView;
-};
-/** Upgrade result: 200 upgraded (the install view); 202 needs enterprise admin approval, a request was created. */
-export type OrgUpgradeResult = {
-    status: 200;
-    install: PluginInstallView;
-} | {
-    status: 202;
-    request: CatalogRequestView;
-};
+}
 /**
  * The org actions installing / uninstalling a plugin needs: the union over its components (an
  * extension -> `org.extensions.manage`, skills -> `skills.manage`, connector templates ->
  * `connectors.manage`, agent templates -> `agents.manage`), re-checked inside the org row lock.
  */
 export declare function requiredActions(m: PluginManifest): OrgAction[];
-/** Locks the org row in the caller's transaction (`orgLock` joins it) and re-checks the actor can do every action (else `forbidden`). */
-export declare function lockOrgForActions(orgLock: Pick<OrgLock, "lockAndAuthorize">, orgId: string, actor: string, actions: OrgAction[]): Promise<void>;
+/**
+ * Locks the org row in the caller's transaction (`orgLock` joins it) and re-checks the actor can do
+ * every action (else `forbidden`). `actor` null is the kernel itself (the plugin scope sync): the
+ * lock only.
+ */
+export declare function lockOrgForActions(orgLock: Pick<OrgLock, "lock" | "lockAndAuthorize">, orgId: string, actor: string | null, actions: OrgAction[]): Promise<void>;
 /** The value at a dot path of `v` (own keys only), undefined when absent. */
 export declare function getPath(v: unknown, path: string): unknown;
 /** Sets the value at a dot path of `obj`, creating the objects on the way. */
@@ -168,6 +213,16 @@ export declare function readCatalogFiles(storage: StorageService, objectPrefix:
     size: number;
     sha256: string;
 }[], under?: string): Promise<SkillPackageFile[]>;
+/**
+ * Reads a version's display files (icons, setup guide files; `catalog-files.ts`) from PG, sha256
+ * checked, in the order given; no object storage is involved. A listed file missing from PG is lost
+ * or tampered data (`internal`).
+ */
+export declare function readCatalogDisplayFiles(db: Parameters<typeof readDisplayFiles>[0], files: {
+    path: string;
+    size: number;
+    sha256: string;
+}[]): Promise<SkillPackageFile[]>;
 /** 校验技能文件并取名字与描述（导入时已校验过；这里防存储被改）。 */
 export declare function skillOf(files: SkillPackageFile[]): ReturnType<typeof checkSkillFiles>;
 /** The connector templates of a catalog version, read from storage (id = the file's base name). */
@@ -183,3 +238,35 @@ export declare function readCatalogAgentTemplates(storage: StorageService, v: Ca
     path: string;
     template: AgentTemplate;
 }[]>;
+/** A theme of a catalog version ({@link readCatalogThemes}). */
+export interface CatalogTheme {
+    /** The theme id (the file's base name). */
+    id: string;
+    /** Relative to the plugin root. */
+    path: string;
+    theme: ParsedTheme;
+    /** The theme's fonts and logo files (paths relative to the plugin root), sanitized. */
+    assets: SkillPackageFile[];
+    /** {@link themeAssetsDigest} of the version's records of those files. */
+    assetsDigest: string;
+}
+/** The asset paths a parsed theme references (fonts, logo mark and favicon), without `./`. */
+export declare function themeAssetPaths(theme: ParsedTheme): string[];
+/**
+ * The digest of a theme's assets as recorded on a catalog version (`files`): equal digests = the
+ * same fonts and logo. With the canonical definition it decides whether a theme changed.
+ */
+export declare function themeAssetsDigest(files: {
+    path: string;
+    sha256: string;
+}[], theme: ParsedTheme): string;
+/**
+ * The themes of a catalog version (`manifest.themes`, listed explicitly since import), parsed from
+ * storage and their assets checked again (checked at import; again in case storage was changed).
+ * Grammar and token names are checked again (a token renamed in core stays loud, themes spec
+ * §4.1), but not readability: the version passed it at import, and a later change of the built-in
+ * tokens must not block an update or a rollback to it. A theme that fails -> 400 `theme.invalid`
+ * as at import (themes spec §6: a failing new version blocks the plugin update with the same
+ * refusal).
+ */
+export declare function readCatalogThemes(storage: StorageService, v: CatalogVersionFiles): Promise<CatalogTheme[]>;

package/dist/catalog/catalog-content.js

@@ -1,20 +1,22 @@
 // Reading a catalog version's stored content (templates, skills, agent templates, icons) and the
-// org install helpers (no providers), shared by PluginInstaller, PluginUpgrader and
+// org install helpers (no providers), shared by PluginInstaller, PlatformPluginUpdater and
 // OrgCatalogService: kept out of org-catalog.service.ts so the installer's module never imports a
 // module whose provider injects PluginInstaller (an ESM import cycle would run decorators early).
 import { createHash } from "node:crypto";
-import { parseAgentTemplate, parseConnectorTemplateFile, } from "@capybara-hq/plugin-sdk";
+import { parseAgentTemplate, parseConnectorTemplateFile, parseThemeFile, themeIdOf, validateThemeAssets, } from "@capybara-hq/plugin-sdk";
+import { normalizeToolKeys } from "../agents/definition.js";
 import { ApiError } from "../errors.js";
 import { can } from "../orgs/roles.js";
 import { packagePath } from "../packages/tgz.js";
 import { checkSkillFiles, SkillArchiveError } from "../skills/package.js";
-import { iconProblem } from "./plugin-package.js";
+import { readDisplayFiles } from "./catalog-files.js";
+import { iconProblem, pluginThemeError, themeApiError } from "./plugin-package.js";
 import { satisfiesRange } from "./versions.js";
 /**
  * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
  * presets and editable paths, no credentials.
  */
-export function orgTemplateView(id, file) {
+export function orgTemplateView(id, file, guide = null) {
     const t = file.template;
     return {
         id,
@@ -27,9 +29,29 @@ export function orgTemplateView(id, file) {
         auth: t.auth,
         ownership: t.ownership ??
             (typeof t.auth.ownership === "string" ? t.auth.ownership : null),
+        guide,
     };
 }
 const iconNotFound = () => new ApiError("catalog.icon_not_found", "This catalog item has no icon");
+/**
+ * The digest of a skill's files (paths relative to the skill directory): equal digests = the same
+ * content. Shared by the org upgrade diff and the platform components.
+ */
+export function skillFilesDigest(files) {
+    return createHash("sha256")
+        .update(files
+        .map((f) => `${f.path}\0${f.sha256}\n`)
+        .sort()
+        .join(""))
+        .digest("hex");
+}
+/** The digest of the files under `dir/` of a catalog version (paths relative to it). */
+export function dirDigest(row, dir) {
+    const prefix = `${dir}/`;
+    return skillFilesDigest(row.files
+        .filter((f) => f.path.startsWith(prefix))
+        .map((f) => ({ path: f.path.slice(prefix.length), sha256: f.sha256 })));
+}
 /**
  * The item's latest version row; item missing, deleted or (when `includeDisabled` is false)
  * disabled -> `catalog.item_not_found`.
@@ -39,13 +61,13 @@ async function latestVersionRow(db, itemId, includeDisabled) {
         throw itemNotFound();
     const item = await db
         .selectFrom("catalog_items")
-        .select(["latest_version", "policy"])
+        .select(["latest_version", "disabled"])
         .where("id", "=", itemId)
         .where("deleted_at", "is", null)
         .executeTakeFirst();
     // An item the caller cannot see is "not found" before any version / storage is read, so "no icon"
     // never reveals that it exists
-    if (!item || (!includeDisabled && item.policy === "disabled"))
+    if (!item || (!includeDisabled && item.disabled))
         throw itemNotFound();
     const v = await db
         .selectFrom("catalog_item_versions")
@@ -80,13 +102,13 @@ export async function catalogHasIcon(db, itemId) {
  * storage); no icon -> `catalog.icon_not_found`; stored content that is not a valid svg / png
  * (checked at import, this guards against tampered storage) -> `internal`.
  */
-export async function readCatalogIcon(db, storage, itemId, includeDisabled) {
-    const { item, v } = await latestVersionRow(db, itemId, includeDisabled);
+export async function readCatalogIcon(db, itemId, includeDisabled) {
+    const { v } = await latestVersionRow(db, itemId, includeDisabled);
     const path = iconPath(v);
     const f = path === undefined ? undefined : v.files.find((x) => x.path === path);
     if (path === undefined || !f)
         throw iconNotFound();
-    const [file] = await readCatalogFiles(storage, v.object_prefix, [f]);
+    const [file] = await readCatalogDisplayFiles(db, [f]);
     if (!file)
         throw iconNotFound();
     const problem = iconProblem(path, file.data);
@@ -95,7 +117,6 @@ export async function readCatalogIcon(db, storage, itemId, includeDisabled) {
     return {
         data: file.data,
         contentType: /\.svg$/i.test(path) ? "image/svg+xml" : "image/png",
-        policy: item.policy,
     };
 }
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -118,8 +139,16 @@ export function requiredActions(m) {
         out.push("agents.manage");
     return out.length > 0 ? out : ["org.extensions.manage"];
 }
-/** Locks the org row in the caller's transaction (`orgLock` joins it) and re-checks the actor can do every action (else `forbidden`). */
+/**
+ * Locks the org row in the caller's transaction (`orgLock` joins it) and re-checks the actor can do
+ * every action (else `forbidden`). `actor` null is the kernel itself (the plugin scope sync): the
+ * lock only.
+ */
 export async function lockOrgForActions(orgLock, orgId, actor, actions) {
+    if (actor === null) {
+        await orgLock.lock(orgId);
+        return;
+    }
     const [first, ...rest] = actions;
     const { role } = await orgLock.lockAndAuthorize(orgId, actor, first);
     for (const a of rest) {
@@ -174,12 +203,12 @@ export function findConnectorIn(registry, plugin, kind) {
  */
 export function templatePluginProblem(d, template) {
     if (!d.findConnector(template.plugin, template.connector)) {
-        return `Connector extension ${template.plugin} providing "${template.connector}" is not deployed; ask the enterprise admin to install and enable it`;
+        return `Connector extension ${template.plugin} providing "${template.connector}" is not deployed; ask the super admin to install and enable it`;
     }
     const range = template.pluginVersion;
     const version = d.pluginVersion(template.plugin);
     if (range !== undefined && version !== undefined && !satisfiesRange(version, range)) {
-        return `Connector extension ${template.plugin} is deployed at version ${version}, but the template needs ${range}; ask the enterprise admin to upgrade it`;
+        return `Connector extension ${template.plugin} is deployed at version ${version}, but the template needs ${range}; ask the super admin to upgrade it`;
     }
     return undefined;
 }
@@ -266,6 +295,20 @@ export async function readCatalogFiles(storage, objectPrefix, files, under) {
     }
     return out;
 }
+/**
+ * Reads a version's display files (icons, setup guide files; `catalog-files.ts`) from PG, sha256
+ * checked, in the order given; no object storage is involved. A listed file missing from PG is lost
+ * or tampered data (`internal`).
+ */
+export async function readCatalogDisplayFiles(db, files) {
+    const stored = await readDisplayFiles(db, files);
+    return files.map((f) => {
+        const got = stored.get(f.path);
+        if (!got)
+            throw new ApiError("internal", `Catalog file ${f.path} is not stored`);
+        return got;
+    });
+}
 /** 校验技能文件并取名字与描述（导入时已校验过；这里防存储被改）。 */
 export function skillOf(files) {
     try {
@@ -318,6 +361,71 @@ export async function readCatalogAgentTemplates(storage, v) {
         if (!parsed || "errors" in parsed) {
             throw new ApiError("internal", `Stored agent template ${path} is missing or invalid`);
         }
-        return { path, template: parsed.template };
+        // an rc package's template may name old builtins: read as the current names (tool naming
+        // spec §8.3); rc `<x>__<tool>` keys are read with the org's scope by `loadTemplates`
+        return { path, template: normalizeToolKeys(parsed.template) };
     });
 }
+/** The asset paths a parsed theme references (fonts, logo mark and favicon), without `./`. */
+export function themeAssetPaths(theme) {
+    const refs = (theme.fonts ?? []).map((f) => f.file);
+    for (const ref of [theme.logo?.mark, theme.logo?.favicon])
+        if (ref !== undefined)
+            refs.push(ref);
+    return [...new Set(refs.map((r) => packagePath(r)))];
+}
+/**
+ * The digest of a theme's assets as recorded on a catalog version (`files`): equal digests = the
+ * same fonts and logo. With the canonical definition it decides whether a theme changed.
+ */
+export function themeAssetsDigest(files, theme) {
+    const paths = new Set(themeAssetPaths(theme));
+    return skillFilesDigest(files.filter((f) => paths.has(f.path)));
+}
+/**
+ * The themes of a catalog version (`manifest.themes`, listed explicitly since import), parsed from
+ * storage and their assets checked again (checked at import; again in case storage was changed).
+ * Grammar and token names are checked again (a token renamed in core stays loud, themes spec
+ * §4.1), but not readability: the version passed it at import, and a later change of the built-in
+ * tokens must not block an update or a rollback to it. A theme that fails -> 400 `theme.invalid`
+ * as at import (themes spec §6: a failing new version blocks the plugin update with the same
+ * refusal).
+ */
+export async function readCatalogThemes(storage, v) {
+    const refs = v.manifest.themes ?? [];
+    if (refs.length === 0)
+        return [];
+    const read = async (paths) => (await readCatalogFiles(storage, v.object_prefix, v.files.filter((f) => paths.includes(f.path)))).map((f) => [f.path, f.data]);
+    const paths = refs.map((r) => packagePath(r.path));
+    const texts = new Map(await read(paths));
+    const parsed = paths.map((path) => {
+        const id = themeIdOf(path);
+        const data = texts.get(path);
+        if (data === undefined)
+            throw new ApiError("internal", `Stored theme ${path} is missing`);
+        const r = parseThemeFile(id, new TextDecoder().decode(data), { readability: false });
+        if ("errors" in r)
+            throw themeApiError(pluginThemeError([{ theme: id, problems: r.errors }]));
+        return { id, path, theme: r };
+    });
+    const files = new Map(await read([...new Set(parsed.flatMap((t) => themeAssetPaths(t.theme)))]));
+    const out = [];
+    for (const { id, path, theme } of parsed) {
+        const { assets, errors } = validateThemeAssets(theme, files);
+        if (errors.length > 0)
+            throw themeApiError(pluginThemeError([{ theme: id, problems: errors }]));
+        out.push({
+            id,
+            path,
+            theme,
+            assets: [...assets].map(([p, bytes]) => ({
+                path: p,
+                size: bytes.byteLength,
+                sha256: createHash("sha256").update(bytes).digest("hex"),
+                data: bytes,
+            })),
+            assetsDigest: themeAssetsDigest(v.files, theme),
+        });
+    }
+    return out;
+}

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

@@ -0,0 +1,42 @@
+import { type PluginManifest } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+type Db = Pick<KernelSchemaDb, "selectFrom" | "insertInto" | "deleteFrom">;
+/** A stored file as a version row lists it. */
+interface FileMeta {
+    path: string;
+    size: number;
+    sha256: string;
+}
+/**
+ * The display file paths of a plugin (package paths): the plugin icon, the connector templates'
+ * icons (given by the caller, which parsed the templates) and the setup guide documents (both
+ * languages; the caller keeps the ones the package has).
+ */
+export declare function displayFilePaths(m: PluginManifest, templateIcons?: string[]): Set<string>;
+/**
+ * Stores display files (one row per sha256; a file already there gets its `touched_at` renewed, so
+ * the sweep never removes the bytes of an import in progress). Runs in the caller's transaction
+ * when there is one: the staging row that lists the files commits with them.
+ */
+export declare function putDisplayFiles(db: Db, files: {
+    sha256: string;
+    data: Uint8Array;
+}[]): Promise<void>;
+/**
+ * The display files of `files` found in PG, by path, each checked against its recorded sha256 (a
+ * mismatch is tampering: `internal`). Files not in PG are absent from the result.
+ */
+export declare function readDisplayFiles(db: Db, files: FileMeta[]): Promise<Map<string, {
+    path: string;
+    size: number;
+    sha256: string;
+    data: Uint8Array;
+}>>;
+/**
+ * Removes display files no catalog version and no import staging lists, last stored more than
+ * `olderThanMs` ago (the staging cleanup passes the staging TTL: an import storing a file renews
+ * it, and a concurrent renewal makes the row fail the age check when the delete re-reads it).
+ * Returns the rows removed.
+ */
+export declare function sweepDisplayFiles(db: Db, olderThanMs: number): Promise<number>;
+export {};

package/dist/catalog/catalog-files.js

@@ -0,0 +1,89 @@
+// Catalog display files in PG (`catalog_files`, migration 0100): a plugin's icon, its connector
+// templates' icons and its setup guide documents. They are small (64 KiB each at most, by the plugin
+// format) and must be readable without object storage: a bootstrap plugin is imported before any
+// object-store extension runs, and the object-store plugin's own icon can never wait for itself.
+// Skills, connector templates and agent templates stay in object storage under the version's
+// `object_prefix` (they are copied into platform components there).
+import { createHash } from "node:crypto";
+import { setupGuideDocPath } from "@capybara-hq/plugin-sdk";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { packagePath } from "../packages/tgz.js";
+/**
+ * The display file paths of a plugin (package paths): the plugin icon, the connector templates'
+ * icons (given by the caller, which parsed the templates) and the setup guide documents (both
+ * languages; the caller keeps the ones the package has).
+ */
+export function displayFilePaths(m, templateIcons = []) {
+    const out = new Set();
+    if (m.icon !== undefined)
+        out.add(packagePath(m.icon));
+    for (const icon of templateIcons)
+        out.add(packagePath(icon));
+    for (const g of m.setupGuides ?? []) {
+        out.add(setupGuideDocPath(g.id, "en"));
+        out.add(setupGuideDocPath(g.id, "zh"));
+    }
+    return out;
+}
+/**
+ * Stores display files (one row per sha256; a file already there gets its `touched_at` renewed, so
+ * the sweep never removes the bytes of an import in progress). Runs in the caller's transaction
+ * when there is one: the staging row that lists the files commits with them.
+ */
+export async function putDisplayFiles(db, files) {
+    const unique = new Map(files.map((f) => [f.sha256, f.data]));
+    // sorted: two imports storing overlapping sets lock the rows in the same order
+    for (const sha256 of [...unique.keys()].sort()) {
+        const data = unique.get(sha256);
+        await db
+            .insertInto("catalog_files")
+            .values({ sha256, data: Buffer.from(data) })
+            .onConflict((oc) => oc.column("sha256").doUpdateSet({ touched_at: sql `now()` }))
+            .execute();
+    }
+}
+/**
+ * The display files of `files` found in PG, by path, each checked against its recorded sha256 (a
+ * mismatch is tampering: `internal`). Files not in PG are absent from the result.
+ */
+export async function readDisplayFiles(db, files) {
+    const out = new Map();
+    if (files.length === 0)
+        return out;
+    const rows = await db
+        .selectFrom("catalog_files")
+        .select(["sha256", "data"])
+        .where("sha256", "in", [...new Set(files.map((f) => f.sha256))])
+        .execute();
+    const bySha = new Map(rows.map((r) => [r.sha256, new Uint8Array(r.data)]));
+    for (const f of files) {
+        const data = bySha.get(f.sha256);
+        if (data === undefined)
+            continue;
+        if (createHash("sha256").update(data).digest("hex") !== f.sha256) {
+            throw new ApiError("internal", `Catalog file ${f.path} does not match its recorded hash`);
+        }
+        out.set(f.path, { path: f.path, size: data.byteLength, sha256: f.sha256, data });
+    }
+    return out;
+}
+/**
+ * Removes display files no catalog version and no import staging lists, last stored more than
+ * `olderThanMs` ago (the staging cleanup passes the staging TTL: an import storing a file renews
+ * it, and a concurrent renewal makes the row fail the age check when the delete re-reads it).
+ * Returns the rows removed.
+ */
+export async function sweepDisplayFiles(db, olderThanMs) {
+    const r = await db
+        .deleteFrom("catalog_files as f")
+        .where("f.touched_at", "<", sql `now() - make_interval(secs => ${olderThanMs / 1000})`)
+        .where(({ not, exists, selectFrom }) => not(exists(selectFrom("catalog_item_versions as v")
+        .select(sql `1`.as("x"))
+        .where(sql `v.files @> jsonb_build_array(jsonb_build_object('sha256', f.sha256))`))))
+        .where(({ not, exists, selectFrom }) => not(exists(selectFrom("plugin_import_staging as s")
+        .select(sql `1`.as("x"))
+        .where(sql `s.manifest->'files' @> jsonb_build_array(jsonb_build_object('sha256', f.sha256))`))))
+        .executeTakeFirst();
+    return Number(r.numDeletedRows);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * The platform side of the catalog: marketplaces, the one import review (prepare -> confirm), the
+ * items and their platform components. The CLI's `capybara plugins *` and `capybara bootstrap` run on this
+ * part alone.
+ */
+export declare class CatalogImportModule {
+}