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

package/dist/catalog/catalog-content.js

@@ -0,0 +1,326 @@
+// Reading a catalog version's stored content (templates, skills, agent templates, icons) and the
+// org install helpers (no providers), shared by PluginInstaller, PluginUpgrader 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 { 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 { 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 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", "policy"])
+        .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"))
+        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, storage, itemId, includeDisabled) {
+    const { item, 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]);
+    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",
+        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;
+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`). */
+export async function lockOrgForActions(orgLock, orgId, actor, actions) {
+    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 enterprise 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 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;
+}
+/** 校验技能文件并取名字与描述（导入时已校验过；这里防存储被改）。 */
+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) };
+    });
+}

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

@@ -0,0 +1,186 @@
+import type { Connector, ConnectorTemplateSpec, LocalizedName, PluginManifest } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelSchemaDb, SourceFormat } from "../db/kernel-schema.js";
+import type { StorageService } from "../storage/storage.service.js";
+import type { CatalogItemView, CatalogPolicy, CatalogVersionSource, PermissionsMismatch, SourceDetail } from "./catalog.service.js";
+import type { TranslationReport } from "./claude/report.js";
+import { type ImportedAs } from "./marketplaces.service.js";
+/**
+ * The object storage prefix of one import (relative to `deployment/`):
+ * `directory/<itemId>/<version>/<importId>/`. Each import gets a new `importId`, so the losing one of
+ * two concurrent imports of the same version never overwrites the committed version's files; reads
+ * always go through the `object_prefix` stored on the version row. Build metadata's `+` is written
+ * as `_` (a `+` in a key can turn into a space through URL query encoding).
+ */
+export declare const catalogObjectPrefix: (itemId: string, version: string, importId: string) => string;
+/**
+ * Checks a connector template against the loaded connector `c` (problem paths start with `at`): the
+ * endpoint matches its `endpointSchema` and carries no credential-like headers / query / URL user
+ * info (the same rule as connector installs); every `editableEndpoint` path exists in the endpoint
+ * schema.
+ */
+export declare function templateProblems(c: Connector, t: ConnectorTemplateSpec, at: string): string[];
+/** Writes the files to `deployment/<prefix><path>` ({@link PUT_CONCURRENCY} at a time). */
+export declare function putCatalogFiles(storage: StorageService, prefix: string, files: {
+    path: string;
+    size: number;
+    data: Uint8Array;
+}[]): Promise<void>;
+/** Compares the marketplace's permission summary with the computed keys ({@link PermissionsMismatch}). */
+export declare function permissionsMismatch(declared: string[] | undefined, actual: string[] | undefined): PermissionsMismatch;
+/** The fields the list shows (the item's publisher / description / displayName). */
+export interface CatalogListing {
+    publisher: string;
+    description: string;
+    displayName: LocalizedName | null;
+}
+/** Input of {@link writeCatalogVersion}. */
+export interface CatalogVersionWrite {
+    /** null: the CLI (no account). */
+    actor: string | null;
+    actorTokenId?: string;
+    name: string;
+    /** null: a git plugin without package.json. */
+    packageName: string | null;
+    /**
+     * The version recorded (from {@link precheckCatalogImport}: the plugin's own, or with build
+     * metadata when that release was imported with other content).
+     */
+    version: string;
+    /** The content digest of the plugin's files. */
+    contentDigest: string;
+    /** The normalized plugin.json. */
+    manifest: PluginManifest;
+    listing: CatalogListing;
+    /** The id of the item to create when there is none yet (the one the storage prefix used). */
+    newItemId: string;
+    source: {
+        source: CatalogVersionSource;
+        ref: string;
+        integrity?: string;
+        detail?: SourceDetail;
+    };
+    /** Imported from a marketplace: the item records it. */
+    marketplaceId?: string;
+    objectPrefix: string | null;
+    extensionSha256: string | null;
+    files: {
+        path: string;
+        size: number;
+        sha256: string;
+    }[];
+    size: number;
+    /** The format the plugin was read from (default `capybara`). */
+    sourceFormat?: SourceFormat;
+    /** The translation report of a Claude Code plugin. */
+    translation?: TranslationReport | null;
+    /** The root LICENSE text. */
+    licenseText?: string | null;
+    /** The root LICENSE was too long (or not UTF-8) to store. */
+    licenseTruncated?: boolean;
+    /** Merged into the detail of the `catalog.imported` audit. */
+    auditDetail?: Record<string, unknown>;
+}
+/**
+ * The identity of a git source, `<host>/<repo>:<path>` (host lower case, no `.git`), or null when
+ * the source is not git. An item without package.json is identified by it instead of a package name.
+ */
+export declare function gitIdentity(detail: SourceDetail | undefined): string | null;
+/** What is being imported, as far as the version conflict rules need it. */
+export interface ImportIdentity {
+    packageName: string | null;
+    /** The plugin's own version (plugin.json, else the fallback of spec §5.3). */
+    version: string;
+    contentDigest: string;
+    integrity?: string;
+    detail?: SourceDetail;
+    marketplaceId?: string;
+}
+type ExistingVersion = {
+    version: string;
+    content_digest: string | null;
+    integrity: string | null;
+};
+/**
+ * The version a new import records (Decision 6, spec §5.3): the plugin's own version, unless that
+ * release is already imported. A version of the same release (equal but for build metadata) with
+ * the same content (digest; for versions without one, the same integrity) -> `catalog.version_exists`
+ * "already imported"; other content -> `<version>+git.<sha12>` (git) or `+sha256.<12>` (any other
+ * source, the digest's first 12 hex), never overwriting the imported version. A git commit already
+ * recorded with other content (a Claude Code plugin whose marketplace entry changed while its own
+ * commit did not, see `claudeContentDigest`) falls back to `+sha256.<12>`.
+ */
+export declare function recordedVersion(existing: ExistingVersion[], p: ImportIdentity): string;
+/**
+ * Conflict precheck before writing (no lock; {@link writeCatalogVersion}'s re-check inside the
+ * transaction is final): an item with the same name from another npm package (or, without one,
+ * another git source) -> `catalog.name_conflict`; the release already imported with the same
+ * content -> `catalog.version_exists`. Returns the existing item (undefined when there is none) and
+ * the version to record ({@link recordedVersion}).
+ */
+export declare function precheckCatalogImport(db: KernelSchemaDb, name: string, p: ImportIdentity): Promise<{
+    existing: {
+        id: string;
+    } | undefined;
+    version: string;
+}>;
+/**
+ * Writes a catalog version in the caller's transaction (`db` is its handle; the caller has
+ * re-checked the enterprise admin and holds the name's {@link CatalogItemLock}): checks conflicts again (the same source; no version of
+ * the release with the same content; `version` not taken meanwhile), creates the item when there is
+ * none or adds the version (latest and display fields change only for a newer version, a version
+ * equal but for build metadata being newer as the later import), and writes the version row (with
+ * its content digest) and the `catalog.imported` audit. Returns the item id.
+ */
+export declare function writeCatalogVersion(db: KernelSchemaDb, w: CatalogVersionWrite): Promise<string>;
+/**
+ * An extension name belongs to the npm package that first installed it (`extension_name_owners`,
+ * Ruling P3): when another package owns it, the import is refused right away with
+ * `extension.name_conflict` (the same code as at install), instead of failing only at deploy time.
+ */
+export declare function assertPluginNameOwner(db: KernelSchemaDb, name: string, packageName: string | null): Promise<void>;
+/** A catalog version as {@link marketplaceLatest} compares it with its marketplace entries. */
+type RecordedVersion = ImportedAs & {
+    imported_at?: Date;
+};
+/** What the marketplace says about a marketplace-imported item. */
+export interface MarketplaceStatus {
+    /** See {@link CatalogItemView.latestMarketplaceVersion}. */
+    latest: string | null;
+    /** See {@link CatalogItemView.contentChanged}. */
+    contentChanged: boolean;
+}
+/**
+ * For each marketplace-imported item, its marketplace (when enabled): the highest compatible
+ * version listed, and whether a compatible entry's content changed at an imported version.
+ */
+export declare function marketplaceLatest(db: KernelSchemaDb, config: KernelConfig, items: {
+    id: string;
+    name: string;
+    marketplace_id?: string | null;
+}[], versions: ReadonlyMap<string, readonly RecordedVersion[]>): Promise<Map<string, MarketplaceStatus>>;
+/** Org install counts per item (see {@link CatalogItemView.installs}). */
+export declare function countInstalls(db: KernelSchemaDb, items: {
+    id: string;
+    name: string;
+    latest_version: string;
+}[], versions: ReadonlyMap<string, {
+    version: string;
+    extension_sha256: string | null;
+}[]>): Promise<Map<string, number>>;
+export declare function itemView(i: {
+    id: string;
+    name: string;
+    publisher: string;
+    display_name: LocalizedName | null;
+    description: string;
+    policy: CatalogPolicy;
+    latest_version: string;
+    marketplace_id?: string | null;
+    updated_at: Date;
+}, versions: {
+    version: string;
+    source: string;
+    imported_at?: Date;
+}[], installs?: number, marketplace?: MarketplaceStatus): CatalogItemView;
+export {};