@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/catalog/catalog-content.js

@@ -0,0 +1,430 @@
+// Reading a catalog version's stored content (templates, skills, agent templates, icons) and the
+// 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, 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 { 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) {
+    const t = file.template;
+    return {
+        id,
+        displayName: file.displayName,
+        description: file.description ?? "",
+        plugin: t.plugin,
+        connector: t.connector,
+        endpoint: t.endpoint,
+        editableEndpoint: t.editableEndpoint ?? [],
+        auth: t.auth,
+        ownership: t.ownership ??
+            (typeof t.auth.ownership === "string" ? t.auth.ownership : null),
+    };
+}
+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`.
+ */
+async function latestVersionRow(db, itemId, includeDisabled) {
+    if (!UUID_RE.test(itemId))
+        throw itemNotFound();
+    const item = await db
+        .selectFrom("catalog_items")
+        .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.disabled))
+        throw itemNotFound();
+    const v = await db
+        .selectFrom("catalog_item_versions")
+        .select(["manifest", "object_prefix", "files"])
+        .where("item_id", "=", itemId)
+        .where("version", "=", item.latest_version)
+        .executeTakeFirst();
+    if (!v)
+        throw itemNotFound();
+    return { item, v };
+}
+/** The icon's path in the version's files (undefined without an icon). */
+const iconPath = (v) => {
+    const icon = v.manifest.icon;
+    return icon === undefined ? undefined : packagePath(icon);
+};
+/** Whether the item's latest version has an icon; unreadable counts as none. */
+export async function catalogHasIcon(db, itemId) {
+    try {
+        const { v } = await latestVersionRow(db, itemId, true);
+        const path = iconPath(v);
+        return path !== undefined && v.files.some((f) => f.path === path);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reads the icon of the item's latest version (served only through kernel routes, with nosniff and
+ * a CSP sandbox in the response headers; the web only shows it with `<img>`). Item missing, deleted
+ * or (when `includeDisabled` is false) disabled -> `catalog.item_not_found` (decided before reading
+ * 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, 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 readCatalogDisplayFiles(db, [f]);
+    if (!file)
+        throw iconNotFound();
+    const problem = iconProblem(path, file.data);
+    if (problem !== undefined)
+        throw new ApiError("internal", `Stored icon is invalid: ${problem}`);
+    return {
+        data: file.data,
+        contentType: /\.svg$/i.test(path) ? "image/svg+xml" : "image/png",
+    };
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const itemNotFound = () => new ApiError("catalog.item_not_found", "Catalog item not found");
+const fail = (path, message) => new ApiError("validation_failed", "Request validation failed", [{ path, message }]);
+/**
+ * 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 function requiredActions(m) {
+    const out = [];
+    if (m.extension)
+        out.push("org.extensions.manage");
+    if ((m.connectorTemplates ?? []).length > 0)
+        out.push("connectors.manage");
+    if ((m.skills ?? []).length > 0)
+        out.push("skills.manage");
+    if ((m.agents ?? []).length > 0)
+        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`). `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) {
+        if (!can(role, a))
+            throw new ApiError("forbidden", "Insufficient organization role");
+    }
+}
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const UNSAFE_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+/** 对象的全部叶子点路径（数组与非对象值算叶子）。 */
+function leafPaths(v, base = "") {
+    const out = [];
+    for (const [k, x] of Object.entries(v)) {
+        const p = base ? `${base}.${k}` : k;
+        if (isObj(x) && Object.keys(x).length > 0)
+            out.push(...leafPaths(x, p));
+        else
+            out.push(p);
+    }
+    return out;
+}
+/** The value at a dot path of `v` (own keys only), undefined when absent. */
+export function getPath(v, path) {
+    let node = v;
+    for (const seg of path.split(".")) {
+        if (!isObj(node) || !Object.hasOwn(node, seg))
+            return undefined;
+        node = node[seg];
+    }
+    return node;
+}
+/** Sets the value at a dot path of `obj`, creating the objects on the way. */
+export function setPath(obj, path, value) {
+    const segs = path.split(".");
+    let node = obj;
+    for (const seg of segs.slice(0, -1)) {
+        if (!isObj(node[seg]))
+            node[seg] = {};
+        node = node[seg];
+    }
+    node[segs[segs.length - 1]] = value;
+}
+/** The connector `kind` provided by extension `plugin` loaded on this replica (from the registry). */
+export function findConnectorIn(registry, plugin, kind) {
+    return registry
+        .list("connector")
+        .find((e) => e.plugin === plugin && e.impl?.kind === kind)?.impl;
+}
+/**
+ * 模板的连接器插件此刻是否可用：插件加载且提供该 kind，并满足 `pluginVersion`（若写了）；不可用返回原因
+ * （模型不可见，给管理员看的英文）。
+ */
+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 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 super admin to upgrade it`;
+    }
+    return undefined;
+}
+/**
+ * Builds the connector install input from a connector template plus what the org filled in (C30):
+ * the endpoint comes from the template, only paths listed in `editableEndpoint` (or fields under
+ * them) may be changed by the org, changing another path -> `validation_failed`; the auth method
+ * comes from the template, the org only gives credentials (static credentials via `credential`,
+ * OAuth via `client`). Re-checks the template's plugin, kind and `pluginVersion` against the
+ * connectors loaded on this replica right now (unmet -> `catalog.not_deployed`); the endpoint
+ * (merged as a whole) schema check, credential pattern check and OAuth URL policy are re-checked by
+ * `ConnectorsService.create`.
+ */
+export function templateConnectorInput(deps, template, ref, input, defaultName, at = "connector") {
+    const problem = templatePluginProblem(deps, template);
+    if (problem !== undefined)
+        throw new ApiError("catalog.not_deployed", problem);
+    const given = input ?? {};
+    const editable = template.editableEndpoint ?? [];
+    const endpoint = structuredClone(template.endpoint);
+    if (given.endpoint !== undefined) {
+        if (!isObj(given.endpoint))
+            throw fail(`${at}.endpoint`, "Expected an object");
+        for (const p of leafPaths(given.endpoint)) {
+            const segs = p.split(".");
+            if (segs.some((s) => UNSAFE_KEYS.has(s))) {
+                throw fail(`${at}.endpoint.${p}`, "Invalid key");
+            }
+            const allowed = editable.some((e) => p === e || p.startsWith(`${e}.`));
+            if (!allowed) {
+                throw fail(`${at}.endpoint.${p}`, "This endpoint field is set by the template and cannot be changed");
+            }
+        }
+        for (const e of editable) {
+            const v = getPath(given.endpoint, e);
+            if (v !== undefined)
+                setPath(endpoint, e, v);
+        }
+    }
+    const auth = template.auth;
+    const oauth = auth.type === "oauth_code" || auth.type === "oauth_client";
+    if (oauth && given.credential !== undefined) {
+        throw fail(`${at}.credential`, "This connector uses OAuth; provide client instead");
+    }
+    if (!oauth && given.client !== undefined) {
+        throw fail(`${at}.client`, "This connector does not use OAuth; provide credential instead");
+    }
+    const credential = oauth ? given.client : given.credential;
+    return {
+        name: given.name ?? defaultName,
+        ...(given.slug !== undefined && { slug: given.slug }),
+        connector: template.connector,
+        endpoint,
+        auth,
+        ...(credential !== undefined && { credential }),
+        template: {
+            ...ref,
+            ...(template.defaultToolPolicies !== undefined && {
+                defaultToolPolicies: template.defaultToolPolicies,
+            }),
+        },
+    };
+}
+/** 从部署存储读目录版本里的文件（按版本行的 sha256 校验）；`under` 给出时只读该目录下的文件，路径去掉该前缀。 */
+export async function readCatalogFiles(storage, objectPrefix, files, under) {
+    storage.assertAvailable();
+    if (objectPrefix === null)
+        return [];
+    const store = storage.deployment();
+    const dir = under === undefined ? "" : `${under}/`;
+    const out = [];
+    for (const f of files) {
+        if (!f.path.startsWith(dir))
+            continue;
+        const got = await store.get(`${objectPrefix}${f.path}`);
+        if (!got) {
+            throw new ApiError("storage.unavailable", `Catalog file ${f.path} is missing from object storage`);
+        }
+        const data = new Uint8Array(await new Response(got.body).arrayBuffer());
+        if (createHash("sha256").update(data).digest("hex") !== f.sha256) {
+            throw new ApiError("internal", `Catalog file ${f.path} does not match its recorded hash`);
+        }
+        out.push({ path: f.path.slice(dir.length), size: data.byteLength, sha256: f.sha256, data });
+    }
+    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 {
+        // Stored files: a version imported before phase D keeps installing (its invocation keys are
+        // read leniently; `skillInvocation` ignores values of the wrong type)
+        return checkSkillFiles(files, { invocationKeys: false });
+    }
+    catch (e) {
+        if (e instanceof SkillArchiveError) {
+            throw new ApiError("internal", `Stored skill is invalid: ${e.problems.join("; ")}`);
+        }
+        throw e;
+    }
+}
+/** The connector templates of a catalog version, read from storage (id = the file's base name). */
+export async function readCatalogTemplates(storage, v) {
+    const refs = v.manifest.connectorTemplates ?? [];
+    if (refs.length === 0)
+        return [];
+    const paths = refs.map((r) => packagePath(r.path));
+    const files = await readCatalogFiles(storage, v.object_prefix, v.files.filter((f) => paths.includes(f.path)));
+    return paths.map((path) => {
+        const f = files.find((x) => x.path === path);
+        let parsed;
+        try {
+            parsed = f && parseConnectorTemplateFile(JSON.parse(new TextDecoder().decode(f.data)));
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (!parsed || "errors" in parsed) {
+            throw new ApiError("internal", `Stored connector template ${path} is missing or invalid`);
+        }
+        return { id: path.split("/").pop().replace(/\.json$/, ""), file: parsed };
+    });
+}
+/**
+ * The agent templates of a catalog version (`manifest.agents`, listed explicitly since import),
+ * parsed from storage (checked at import; parsed again in case storage was changed).
+ */
+export async function readCatalogAgentTemplates(storage, v) {
+    const refs = v.manifest.agents ?? [];
+    if (refs.length === 0)
+        return [];
+    const paths = refs.map((r) => packagePath(r.path));
+    const files = await readCatalogFiles(storage, v.object_prefix, v.files.filter((f) => paths.includes(f.path)));
+    return paths.map((path) => {
+        const f = files.find((x) => x.path === path);
+        const parsed = f && parseAgentTemplate(new TextDecoder().decode(f.data));
+        if (!parsed || "errors" in parsed) {
+            throw new ApiError("internal", `Stored agent template ${path} is missing or invalid`);
+        }
+        // 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,41 @@
+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 files.
+ */
+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,86 @@
+// Catalog display files in PG (`catalog_files`, migration 0100): a plugin's icon, its connector
+// templates' icons and its setup guide files. 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 { 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 files.
+ */
+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 ?? [])
+        for (const f of g.files ?? [])
+            out.add(packagePath(f.path));
+    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 {
+}

package/dist/catalog/catalog-import.module.js

@@ -0,0 +1,60 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from "@nestjs/common";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { SuperAdminLockModule } from "../identity/super-admin.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { OrgLockModule } from "../orgs/org-lock.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { StorageModule } from "../storage/storage.module.js";
+import { CatalogService } from "./catalog.service.js";
+import { ComponentPromotion } from "./component-promotion.js";
+import { CatalogItemLock, CatalogSourceLock } from "./locks.js";
+import { MarketplacesService } from "./marketplaces.service.js";
+import { PlatformComponents } from "./platform-components.js";
+import { PluginImport } from "./plugin-import.js";
+// Its own file so that `SkillsModule` can import it (an owner's new version of a promoted skill is
+// written to its platform row, ruling P3-4) without a module file cycle through `CatalogModule`.
+/**
+ * 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.
+ */
+let CatalogImportModule = class CatalogImportModule {
+};
+CatalogImportModule = __decorate([
+    Module({
+        imports: [
+            ExtensionsModule,
+            SuperAdminLockModule,
+            // an org upload re-checks the owner org's admin (`PluginImport`, ruling P3-7)
+            OrgLockModule,
+            StorageModule,
+            // a failed post-import platform sync enqueues the migration job (`PluginImport.syncPlatform`)
+            QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
+        ],
+        providers: [
+            CatalogSourceLock,
+            CatalogItemLock,
+            MarketplacesService,
+            PluginImport,
+            PlatformComponents,
+            // promote on share (ruling P3-3): the admin component routes and the owner's 可共享
+            ComponentPromotion,
+            CatalogService,
+        ],
+        exports: [
+            MarketplacesService,
+            PluginImport,
+            PlatformComponents,
+            ComponentPromotion,
+            CatalogService,
+            CatalogItemLock,
+        ],
+    })
+], CatalogImportModule);
+export { CatalogImportModule };