@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

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

@@ -0,0 +1,143 @@
+import { type AgentTemplate, type ConnectorTemplateFile, type PluginManifest } from "@capybara-hq/plugin-sdk";
+import { LEGACY_FORMAT_MESSAGE, type PackageTgzLimits, packagePath } from "../packages/tgz.js";
+export { LEGACY_FORMAT_MESSAGE, packagePath };
+/**
+ * Reads a plugin tgz (spec §4.1): `package/.capybara-plugin/plugin.json` plus the skills, connector
+ * templates and extension it describes. The tgz is untrusted input and is unpacked by the extension
+ * package tgz rules (`packages/tgz.ts` {@link unpackPackageTgz}: size, decompression cap, entry
+ * count, regular files only, safe paths under `package/`). No code from the package runs here; the extension's module graph is
+ * checked by `readExtensionPackage`. The checks after unpacking live in {@link readPluginFiles},
+ * shared with the git reader (`git-source.ts`), which reads the tree from a commit instead.
+ *
+ * A tgz in the pre-0.1.0 format (a `capybara` section in package.json, or `app.yaml`, and no
+ * plugin.json) is rejected first, with {@link LEGACY_FORMAT_MESSAGE}: there is no reader for the
+ * old formats.
+ */
+/** Codes of {@link PluginPackageError}. */
+export type PluginPackageErrorCode = "catalog.invalid_manifest" | "catalog.legacy_format";
+/** The plugin package is invalid; `issues` lists the problems (English, shown to the admin). */
+export declare class PluginPackageError extends Error {
+    readonly code: PluginPackageErrorCode;
+    readonly issues: string[];
+    constructor(code: PluginPackageErrorCode, issues: string[]);
+}
+/** A skill of the plugin. `dir` is relative to the package root; `files` are relative to `dir`. */
+export interface PluginPackageSkill {
+    name: string;
+    dir: string;
+    files: string[];
+}
+/** A connector template of the plugin; `id` is the file's base name. */
+export interface PluginPackageConnectorTemplate {
+    id: string;
+    /** Relative to the package root (no leading `./`). */
+    path: string;
+    file: ConnectorTemplateFile;
+}
+/** An agent template of the plugin (sub-agents spec §16.1). */
+export interface PluginPackageAgentTemplate {
+    /** The template name (frontmatter `name`); the roster type is `<plugin>:<name>`. */
+    name: string;
+    /** Relative to the package root (no leading `./`). */
+    path: string;
+    template: AgentTemplate;
+}
+/** A validated plugin file tree. Paths are relative to the plugin root (no `package/`). */
+export interface PluginContents {
+    /** `{}` when a git plugin has no package.json. */
+    packageJson: Record<string, unknown>;
+    manifest: PluginManifest;
+    files: Map<string, Uint8Array>;
+    skills: PluginPackageSkill[];
+    connectorTemplates: PluginPackageConnectorTemplate[];
+    /** Agent templates (listed in plugin.json `agents`, else scanned from `agents/*.md`). */
+    agentTemplates: PluginPackageAgentTemplate[];
+    /** {@link contentDigest} of `files` (the same for a tgz and a git tree of the same files). */
+    contentDigest: string;
+}
+/** A read and validated plugin tgz. */
+export interface PluginPackage extends PluginContents {
+    /** Hex sha256 of the whole tgz. */
+    sha256: string;
+    /** tgz bytes. */
+    size: number;
+}
+/** Options of {@link readPluginPackage}; `hostZodVersion` defaults to the kernel's zod. */
+export interface ReadPluginPackageOptions extends PackageTgzLimits {
+    hostSdkVersion: string;
+    hostZodVersion?: string;
+    /**
+     * A marketplace archive: a tgz without `plugin.json` whose root has `skills/` is a skills-only
+     * plugin with this name and publisher (package.json optional, like git), versioned by `version`
+     * (the entry's) or else {@link archiveFallbackVersion} (spec §5.3).
+     */
+    fallback?: {
+        name: string;
+        version?: string;
+        publisher: string;
+    };
+}
+/**
+ * The content digest of a plugin's files (Decision 5): sha256 (hex) over the file list sorted by
+ * path (code unit order), each entry `path + "\0" + sha256(content) + "\n"`. Paths are relative to
+ * the plugin root, so a tgz and a git tree of the same files have the same digest. Paths are hashed
+ * byte for byte as they were read: no Unicode normalization (an NFC and an NFD spelling of the same
+ * name are different files, as they are to git and tar). Both readers refuse control characters in
+ * paths, so `\0` and `\n` cannot occur inside a path and the list is unambiguous; a path with one
+ * is refused here too.
+ */
+export declare function contentDigest(files: ReadonlyMap<string, Uint8Array>): string;
+/**
+ * The version of an archive plugin that has none (spec §5.3): `0.0.0-sha256.h<12>` from the content
+ * digest. The `h` keeps the prerelease identifier alphanumeric (twelve hex digits with a leading
+ * zero are not valid semver).
+ */
+export declare const archiveFallbackVersion: (digest: string) => string;
+/** Largest icon (plugin or connector template) in bytes. */
+export declare const PLUGIN_ICON_MAX_BYTES: number;
+/**
+ * Whether an icon really is an svg / png (only the file header and UTF-8 text are looked at, nothing
+ * is rendered) within {@link PLUGIN_ICON_MAX_BYTES}; undefined when it is.
+ */
+export declare function iconProblem(path: string, data: Uint8Array): string | undefined;
+/**
+ * Reads and validates a plugin tgz (see the file header). Invalid -> {@link PluginPackageError}:
+ * `catalog.legacy_format` for the pre-0.1.0 format, otherwise `catalog.invalid_manifest` listing
+ * every problem it can find, each naming the path it is about (unpacking and manifest parse
+ * problems stop at the first stage that fails).
+ */
+export declare function readPluginPackage(bytes: Uint8Array, opts: ReadPluginPackageOptions): Promise<PluginPackage>;
+/** Options of {@link readPluginFiles}. */
+export interface ReadPluginFilesOptions {
+    hostSdkVersion: string;
+    /** Defaults to the kernel's zod. */
+    hostZodVersion?: string;
+    /**
+     * tgz: true (`package.json` must be there and match the manifest). Git: false (spec §4.1: it is
+     * needed only for npm); when it is absent nothing of it is checked.
+     */
+    requirePackageJson: boolean;
+    /**
+     * Without `plugin.json` and `requirePackageJson: false`, a tree with `skills/` is a skills-only
+     * plugin with this name and version (Decision 3: the marketplace entry name, or the last segment
+     * of the repo URL; the version per spec §5.3). Ignored when `plugin.json` exists.
+     */
+    fallbackName?: string;
+    fallbackVersion?: string;
+    /**
+     * The publisher of that skills-only plugin: the marketplace manifest's `owner.name`, else the
+     * repo owner (`<host>/<owner>`).
+     */
+    fallbackPublisher?: string;
+    /**
+     * false: skip the SKILL.md invocation key checks (a translated Claude Code plugin, whose source
+     * SKILL.md files are kept as written; the translator reported the keys it ignores). Default true.
+     */
+    invocationKeys?: boolean;
+}
+/**
+ * Validates a plugin's file tree (paths relative to the plugin root, `/`-separated, already safe):
+ * the tgz reader after unpacking and the git reader share every check here. Throws
+ * {@link PluginPackageError} like {@link readPluginPackage}.
+ */
+export declare function readPluginFiles(files: Map<string, Uint8Array>, opts: ReadPluginFilesOptions): PluginContents;

package/dist/catalog/plugin-package.js

@@ -0,0 +1,382 @@
+import { createHash } from "node:crypto";
+import { AGENT_TEMPLATE_LIMITS, CATALOG_ITEM_NAME_RE, CONNECTOR_TEMPLATE_LIMITS, hostSdkProblem, PLUGIN_MANIFEST_FILE, PLUGIN_MANIFEST_LIMITS, parseAgentTemplate, parseConnectorTemplateFile, parsePluginManifest, parseSkillMd, SKILL_ENTRY_FILE, validatePluginPackageJsonFor, } from "@capybara-hq/plugin-sdk";
+import { HOST_ZOD_VERSION, LEGACY_FORMAT_MESSAGE, PackageTgzError, packagePath, parsePackageJsonFile, unpackPackageTgz, } from "../packages/tgz.js";
+export { LEGACY_FORMAT_MESSAGE, packagePath };
+/** The plugin package is invalid; `issues` lists the problems (English, shown to the admin). */
+export class PluginPackageError extends Error {
+    code;
+    issues;
+    constructor(code, issues) {
+        super(code === "catalog.legacy_format"
+            ? (issues[0] ?? LEGACY_FORMAT_MESSAGE)
+            : `Invalid plugin package: ${issues[0] ?? "unknown problem"}`);
+        this.name = "PluginPackageError";
+        this.code = code;
+        this.issues = issues;
+    }
+}
+/**
+ * The content digest of a plugin's files (Decision 5): sha256 (hex) over the file list sorted by
+ * path (code unit order), each entry `path + "\0" + sha256(content) + "\n"`. Paths are relative to
+ * the plugin root, so a tgz and a git tree of the same files have the same digest. Paths are hashed
+ * byte for byte as they were read: no Unicode normalization (an NFC and an NFD spelling of the same
+ * name are different files, as they are to git and tar). Both readers refuse control characters in
+ * paths, so `\0` and `\n` cannot occur inside a path and the list is unambiguous; a path with one
+ * is refused here too.
+ */
+export function contentDigest(files) {
+    const h = createHash("sha256");
+    for (const path of [...files.keys()].sort()) {
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are refused
+        if (/[\u0000-\u001f\u007f]/.test(path)) {
+            throw new Error(`unsafe path ${JSON.stringify(path)} in a content digest`);
+        }
+        const data = files.get(path);
+        h.update(`${path}\0${createHash("sha256").update(data).digest("hex")}\n`);
+    }
+    return h.digest("hex");
+}
+/**
+ * The version of an archive plugin that has none (spec §5.3): `0.0.0-sha256.h<12>` from the content
+ * digest. The `h` keeps the prerelease identifier alphanumeric (twelve hex digits with a leading
+ * zero are not valid semver).
+ */
+export const archiveFallbackVersion = (digest) => `0.0.0-sha256.h${digest.slice(0, 12)}`;
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const decode = (data) => {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(data);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Largest icon (plugin or connector template) in bytes. */
+export const PLUGIN_ICON_MAX_BYTES = CONNECTOR_TEMPLATE_LIMITS.iconBytes;
+/**
+ * Whether an icon really is an svg / png (only the file header and UTF-8 text are looked at, nothing
+ * is rendered) within {@link PLUGIN_ICON_MAX_BYTES}; undefined when it is.
+ */
+export function iconProblem(path, data) {
+    if (data.byteLength > PLUGIN_ICON_MAX_BYTES) {
+        return `${path} is larger than ${PLUGIN_ICON_MAX_BYTES} bytes`;
+    }
+    if (/\.png$/i.test(path)) {
+        const sig = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+        return sig.every((b, i) => data[i] === b) ? undefined : `${path} is not a PNG image`;
+    }
+    const text = decode(data);
+    if (text === undefined)
+        return `${path} is not a UTF-8 SVG document`;
+    return /<svg[\s>/]/i.test(text) ? undefined : `${path} is not an SVG document`;
+}
+/** package.json parsed, or undefined when it is not valid (only used to name a legacy package). */
+const parsedOrUndefined = (data) => {
+    try {
+        return parsePackageJsonFile({ data });
+    }
+    catch (e) {
+        if (e instanceof PackageTgzError)
+            return undefined;
+        throw e;
+    }
+};
+const invalid = (issues) => {
+    throw new PluginPackageError("catalog.invalid_manifest", issues);
+};
+/** Runs a step that reports problems as {@link PackageTgzError} (unpacking, package.json). */
+async function step(f) {
+    try {
+        return await f();
+    }
+    catch (e) {
+        if (e instanceof PackageTgzError)
+            return invalid(e.issues);
+        throw e;
+    }
+}
+/** {@link step} for synchronous steps. */
+function stepSync(f) {
+    try {
+        return f();
+    }
+    catch (e) {
+        if (e instanceof PackageTgzError)
+            return invalid(e.issues);
+        throw e;
+    }
+}
+/**
+ * Without package.json only the host SDK check of `validatePluginPackageJsonFor` applies (the
+ * peerDependencies rules are about package.json itself).
+ */
+function hostSdkIssues(manifest, hostSdkVersion) {
+    const sdk = manifest.extension?.manifest.sdk;
+    const problem = sdk === undefined ? undefined : hostSdkProblem(sdk, hostSdkVersion);
+    return problem === undefined ? [] : [problem];
+}
+/**
+ * Reads and validates a plugin tgz (see the file header). Invalid -> {@link PluginPackageError}:
+ * `catalog.legacy_format` for the pre-0.1.0 format, otherwise `catalog.invalid_manifest` listing
+ * every problem it can find, each naming the path it is about (unpacking and manifest parse
+ * problems stop at the first stage that fails).
+ */
+export async function readPluginPackage(bytes, opts) {
+    const unpacked = await step(() => unpackPackageTgz(bytes, opts));
+    const files = new Map(unpacked.map((f) => [f.path, f.data]));
+    const fb = opts.fallback !== undefined && !files.has(PLUGIN_MANIFEST_FILE) ? opts.fallback : null;
+    const contents = readPluginFiles(files, {
+        hostSdkVersion: opts.hostSdkVersion,
+        ...(opts.hostZodVersion !== undefined && { hostZodVersion: opts.hostZodVersion }),
+        requirePackageJson: fb === null,
+        ...(fb !== null && {
+            fallbackName: fb.name,
+            fallbackVersion: fb.version ?? archiveFallbackVersion(contentDigest(files)),
+            fallbackPublisher: fb.publisher,
+        }),
+    });
+    return {
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+        size: bytes.byteLength,
+        ...contents,
+    };
+}
+/** Synthesized `plugin.json` of a skills-only tree without one (Decision 3). */
+function fallbackManifest(files, opts) {
+    if (opts.requirePackageJson || opts.fallbackName === undefined)
+        return undefined;
+    if (opts.fallbackVersion === undefined)
+        return undefined;
+    if (![...files.keys()].some((p) => p.startsWith("skills/")))
+        return undefined;
+    const parsed = parsePluginManifest({
+        schemaVersion: 1,
+        name: opts.fallbackName,
+        version: opts.fallbackVersion,
+        publisher: opts.fallbackPublisher ?? opts.fallbackName,
+        description: `Skills of ${opts.fallbackName} (no ${PLUGIN_MANIFEST_FILE})`,
+    });
+    if ("errors" in parsed) {
+        return invalid(parsed.errors.map((e) => `${PLUGIN_MANIFEST_FILE} (derived): ${e}`));
+    }
+    return parsed;
+}
+/**
+ * Validates a plugin's file tree (paths relative to the plugin root, `/`-separated, already safe):
+ * the tgz reader after unpacking and the git reader share every check here. Throws
+ * {@link PluginPackageError} like {@link readPluginPackage}.
+ */
+export function readPluginFiles(files, opts) {
+    const pj = files.get("package.json");
+    const manifestBytes = files.get(PLUGIN_MANIFEST_FILE);
+    if (manifestBytes === undefined) {
+        // The old formats are recognised only to say so; nothing in them is read. app.yaml is checked
+        // before package.json is parsed, so an old bundle with a broken package.json is still legacy.
+        const pkg = pj && parsedOrUndefined(pj);
+        if (files.has("app.yaml") || (isObj(pkg) && pkg.capybara !== undefined)) {
+            const who = isObj(pkg) && typeof pkg.name === "string" ? `Package ${pkg.name}` : "The package";
+            throw new PluginPackageError("catalog.legacy_format", [`${who} ${LEGACY_FORMAT_MESSAGE}`]);
+        }
+    }
+    const fallback = manifestBytes === undefined ? fallbackManifest(files, opts) : undefined;
+    if (manifestBytes === undefined && fallback === undefined) {
+        if (pj)
+            stepSync(() => parsePackageJsonFile({ data: pj }));
+        return invalid([`${PLUGIN_MANIFEST_FILE} not found in the package (the plugin manifest)`]);
+    }
+    const packageJson = pj === undefined && !opts.requirePackageJson
+        ? undefined
+        : stepSync(() => parsePackageJsonFile(pj && { data: pj }));
+    let manifest;
+    if (manifestBytes === undefined)
+        manifest = fallback;
+    else {
+        const text = decode(manifestBytes);
+        if (text === undefined)
+            return invalid([`${PLUGIN_MANIFEST_FILE} is not valid UTF-8 text`]);
+        const parsed = parsePluginManifest(text);
+        if ("errors" in parsed) {
+            return invalid(parsed.errors.map((e) => `${PLUGIN_MANIFEST_FILE}: ${e}`));
+        }
+        manifest = parsed;
+    }
+    const issues = packageJson !== undefined
+        ? validatePluginPackageJsonFor(packageJson, manifest, opts.hostSdkVersion, {
+            hostZodVersion: opts.hostZodVersion ?? HOST_ZOD_VERSION,
+        })
+        : hostSdkIssues(manifest, opts.hostSdkVersion);
+    const under = (dir) => [...files.keys()].filter((p) => p.startsWith(`${dir}/`));
+    // Skills: listed, or scanned from skills/*/SKILL.md.
+    const skillDirs = [];
+    if (manifest.skills !== undefined) {
+        manifest.skills.forEach((s, i) => {
+            const dir = packagePath(s.path);
+            if (!files.has(`${dir}/${SKILL_ENTRY_FILE}`)) {
+                issues.push(`skills.${i}: ${s.path}/${SKILL_ENTRY_FILE} not found in the package`);
+            }
+            else
+                skillDirs.push(dir);
+        });
+    }
+    else {
+        const re = new RegExp(`^(skills/[^/]+)/${SKILL_ENTRY_FILE}$`);
+        for (const p of [...files.keys()].sort()) {
+            const m = re.exec(p);
+            if (m)
+                skillDirs.push(m[1]);
+        }
+        if (skillDirs.length > PLUGIN_MANIFEST_LIMITS.skills) {
+            issues.push(`skills/ holds ${skillDirs.length} skills; a plugin may have at most ${PLUGIN_MANIFEST_LIMITS.skills}`);
+        }
+    }
+    const skills = [];
+    const skillNames = new Map();
+    for (const dir of skillDirs) {
+        const path = `${dir}/${SKILL_ENTRY_FILE}`;
+        const md = decode(files.get(path));
+        if (md === undefined) {
+            issues.push(`${path}: not valid UTF-8 text`);
+            continue;
+        }
+        const r = parseSkillMd(md, { invocationKeys: opts.invocationKeys !== false });
+        if ("errors" in r) {
+            issues.push(...r.errors.map((e) => `${path}: ${e}`));
+            continue;
+        }
+        const other = skillNames.get(r.name);
+        if (other !== undefined) {
+            issues.push(`${path}: skill name "${r.name}" is also used by ${other}/${SKILL_ENTRY_FILE}`);
+            continue;
+        }
+        skillNames.set(r.name, dir);
+        skills.push({
+            name: r.name,
+            dir,
+            files: under(dir)
+                .map((p) => p.slice(dir.length + 1))
+                .sort(),
+        });
+    }
+    // Connector templates: listed, or scanned from connectors/*.json.
+    const templatePaths = [];
+    if (manifest.connectorTemplates !== undefined) {
+        manifest.connectorTemplates.forEach((t, i) => {
+            const path = packagePath(t.path);
+            if (!files.has(path)) {
+                issues.push(`connectorTemplates.${i}: ${t.path} not found in the package`);
+            }
+            else
+                templatePaths.push(path);
+        });
+    }
+    else {
+        for (const p of [...files.keys()].sort()) {
+            if (/^connectors\/[^/]+\.json$/.test(p))
+                templatePaths.push(p);
+        }
+        if (templatePaths.length > PLUGIN_MANIFEST_LIMITS.connectorTemplates) {
+            issues.push(`connectors/ holds ${templatePaths.length} connector templates; a plugin may have at most ${PLUGIN_MANIFEST_LIMITS.connectorTemplates}`);
+        }
+    }
+    const connectorTemplates = [];
+    for (const path of templatePaths) {
+        const id = path.split("/").pop().replace(/\.json$/, "");
+        if (!CATALOG_ITEM_NAME_RE.test(id)) {
+            issues.push(`${path}: the template id "${id}" must match ^[a-z0-9][a-z0-9-]{0,63}$`);
+            continue;
+        }
+        const json = decode(files.get(path));
+        if (json === undefined) {
+            issues.push(`${path}: not valid JSON`);
+            continue;
+        }
+        // Pass the text so the file gets the same size limit and BOM handling as plugin.json.
+        const r = parseConnectorTemplateFile(json);
+        if ("errors" in r) {
+            issues.push(...r.errors.map((e) => `${path}: ${e}`));
+            continue;
+        }
+        if (r.icon !== undefined) {
+            const icon = files.get(packagePath(r.icon));
+            const problem = icon === undefined ? `${r.icon} not found in the package` : iconProblem(r.icon, icon);
+            if (problem !== undefined)
+                issues.push(`${path}: icon ${problem}`);
+        }
+        connectorTemplates.push({ id, path, file: r });
+    }
+    // Agent templates: listed, or scanned from agents/*.md.
+    const agentPaths = [];
+    if (manifest.agents !== undefined) {
+        manifest.agents.forEach((a, i) => {
+            const path = packagePath(a.path);
+            if (!files.has(path))
+                issues.push(`agents.${i}: ${a.path} not found in the package`);
+            else
+                agentPaths.push(path);
+        });
+    }
+    else {
+        for (const p of [...files.keys()].sort()) {
+            if (/^agents\/[^/]+\.md$/.test(p))
+                agentPaths.push(p);
+        }
+        if (agentPaths.length > AGENT_TEMPLATE_LIMITS.perPlugin) {
+            issues.push(`agents/ holds ${agentPaths.length} agent templates; a plugin may have at most ${AGENT_TEMPLATE_LIMITS.perPlugin}`);
+        }
+    }
+    const agentTemplates = [];
+    const agentNames = new Map();
+    for (const path of agentPaths) {
+        const md = decode(files.get(path));
+        if (md === undefined) {
+            issues.push(`${path}: not valid UTF-8 text`);
+            continue;
+        }
+        const r = parseAgentTemplate(md);
+        if ("errors" in r) {
+            issues.push(...r.errors.map((e) => `${path}: ${e}`));
+            continue;
+        }
+        const other = agentNames.get(r.template.name);
+        if (other !== undefined) {
+            issues.push(`${path}: agent template name "${r.template.name}" is also used by ${other}`);
+            continue;
+        }
+        agentNames.set(r.template.name, path);
+        agentTemplates.push({ name: r.template.name, path, template: r.template });
+    }
+    if (manifest.icon !== undefined) {
+        const icon = files.get(packagePath(manifest.icon));
+        const problem = icon === undefined
+            ? `${manifest.icon} not found in the package`
+            : iconProblem(manifest.icon, icon);
+        if (problem !== undefined)
+            issues.push(`icon: ${problem}`);
+    }
+    const ext = manifest.extension;
+    if (ext !== undefined) {
+        if (!files.has(packagePath(ext.entry))) {
+            issues.push(`extension.entry: ${ext.entry} not found in the package (the plugin has an extension but no build output; build it before packing or committing it)`);
+        }
+        for (const k of ["migrations", "ui"]) {
+            const dir = ext[k];
+            if (dir !== undefined && under(packagePath(dir)).length === 0) {
+                issues.push(`extension.${k}: directory ${dir} is missing or empty`);
+            }
+        }
+    }
+    else if (skillDirs.length === 0 && templatePaths.length === 0 && agentPaths.length === 0) {
+        issues.push("a plugin must contain an extension, a skill, a connector template or an agent template");
+    }
+    if (issues.length > 0)
+        invalid(issues);
+    return {
+        packageJson: (packageJson ?? {}),
+        manifest,
+        files,
+        skills,
+        connectorTemplates,
+        agentTemplates,
+        contentDigest: contentDigest(files),
+    };
+}