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

package/dist/catalog/claude/agents.d.ts

@@ -0,0 +1,27 @@
+import { type TranslationItem } from "./report.js";
+/**
+ * Claude Code `agents/*.md` -> Capybara agent templates (sub-agents spec §16.4). Pure: no I/O. The
+ * source file is never rewritten: each imported agent becomes a generated template
+ * `.capybara-generated/agents/<name>.md` whose frontmatter is the translated fields (written as
+ * JSON, which is YAML) and whose body is the source body, byte for byte. Every problem is a report
+ * item; nothing here refuses the import.
+ */
+/** Where the generated templates live. */
+export declare const GENERATED_AGENTS_DIR = ".capybara-generated/agents";
+/** One translated agent. */
+export interface TranslatedAgent {
+    name: string;
+    /** The source file. */
+    source: string;
+    /** The generated template's path. */
+    path: string;
+    data: Uint8Array;
+}
+/**
+ * Translates the agent files at `paths` of plugin `plugin` (in the order given; the first of a name
+ * wins). Returns the generated templates and the report items.
+ */
+export declare function translateClaudeAgents(files: ReadonlyMap<string, Uint8Array>, paths: readonly string[], plugin: string): {
+    agents: TranslatedAgent[];
+    items: TranslationItem[];
+};

package/dist/catalog/claude/agents.js

@@ -0,0 +1,270 @@
+import { AGENT_TEMPLATE_LIMITS, AGENT_TEMPLATE_NAME_RE, isSkillName, parseAgentTemplate, } from "@capybara-hq/plugin-sdk";
+import { parse as parseYaml } from "yaml";
+import { cut, decodeUtf8, isObj, showName } from "./manifest.js";
+import { item } from "./report.js";
+/**
+ * Claude Code `agents/*.md` -> Capybara agent templates (sub-agents spec §16.4). Pure: no I/O. The
+ * source file is never rewritten: each imported agent becomes a generated template
+ * `.capybara-generated/agents/<name>.md` whose frontmatter is the translated fields (written as
+ * JSON, which is YAML) and whose body is the source body, byte for byte. Every problem is a report
+ * item; nothing here refuses the import.
+ */
+/** Where the generated templates live. */
+export const GENERATED_AGENTS_DIR = ".capybara-generated/agents";
+/** Claude Code tool names -> Capybara tool keys (spec §16.4; anything else is dropped). */
+const TOOL_MAP = {
+    Bash: "sandbox_bash",
+    Read: "sandbox_read",
+    Write: "sandbox_write",
+    Edit: "sandbox_edit",
+    MultiEdit: "sandbox_edit",
+    Glob: "sandbox_glob",
+    Grep: "sandbox_grep",
+    Skill: "skill_load",
+    TodoWrite: "todo__write",
+    ToolSearch: "tool_search",
+};
+/** Claude ignores these for plugin agents: `not_applicable`. */
+const NOT_APPLICABLE = new Set(["permissionMode", "hooks", "mcpServers"]);
+/** Fields Capybara does not translate: `agent_field_ignored` (with any unknown field). */
+const MAPPED = new Set([
+    "name",
+    "description",
+    "tools",
+    "disallowedTools",
+    "model",
+    "maxTurns",
+    "skills",
+    "effort",
+]);
+const ALIASES = {
+    haiku: "fast",
+    sonnet: "standard",
+    opus: "capable",
+    fable: "capable",
+    inherit: "inherit",
+};
+const FAMILIES = [
+    [/haiku/i, "fast"],
+    [/sonnet/i, "standard"],
+    [/opus|fable/i, "capable"],
+];
+const EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"]);
+const FRONTMATTER_MAX_CHARS = 64 * 1024;
+/** Splits a tool list (a YAML list, or a comma separated string; commas inside `(…)` kept). */
+function toolNames(v) {
+    if (Array.isArray(v))
+        return v.every((x) => typeof x === "string") ? v.map((x) => x.trim()) : null;
+    if (typeof v !== "string")
+        return null;
+    const out = [];
+    let depth = 0;
+    let cur = "";
+    for (const ch of v) {
+        if (ch === "(")
+            depth++;
+        else if (ch === ")")
+            depth = Math.max(0, depth - 1);
+        if (ch === "," && depth === 0) {
+            out.push(cur.trim());
+            cur = "";
+        }
+        else
+            cur += ch;
+    }
+    out.push(cur.trim());
+    return out.filter((x) => x !== "");
+}
+/** The frontmatter mapping and the raw body (after the closing `---` line), or a problem. */
+function split(text) {
+    const src = text.startsWith("") ? text.slice(1) : text;
+    const m = /^---[ \t]*\r?\n/.exec(src);
+    if (!m)
+        return { problem: "no YAML frontmatter" };
+    const rest = src.slice(m[0].length);
+    const close = /^---[ \t]*(?:\r?\n|$)/m.exec(rest);
+    if (!close)
+        return { problem: "the frontmatter is not closed by a '---' line" };
+    const front = rest.slice(0, close.index);
+    if (front.length > FRONTMATTER_MAX_CHARS)
+        return { problem: "the frontmatter is too long" };
+    let data;
+    try {
+        data = parseYaml(front, { uniqueKeys: true, maxAliasCount: 50 });
+    }
+    catch (e) {
+        return { problem: `the frontmatter is not valid YAML: ${String(e).split("\n")[0]}` };
+    }
+    if (!isObj(data))
+        return { problem: "the frontmatter is not a YAML mapping" };
+    return { fm: data, body: rest.slice(close.index + close[0].length) };
+}
+/**
+ * Translates the agent files at `paths` of plugin `plugin` (in the order given; the first of a name
+ * wins). Returns the generated templates and the report items.
+ */
+export function translateClaudeAgents(files, paths, plugin) {
+    const items = [];
+    const agents = [];
+    for (const source of paths) {
+        const base = source.split("/").pop().replace(/\.md$/, "");
+        const at = { path: source };
+        const invalid = (label, problem) => items.push(item("agent_invalid", "agent", showName(label), { ...at, detail: { problem } }));
+        const data = files.get(source);
+        const text = data === undefined ? undefined : decodeUtf8(data);
+        if (text === undefined) {
+            invalid(base, data === undefined ? "file not found" : "not valid UTF-8 text");
+            continue;
+        }
+        const parts = split(text);
+        if ("problem" in parts) {
+            invalid(base, parts.problem);
+            continue;
+        }
+        const { fm, body } = parts;
+        const name = fm.name;
+        if (typeof name !== "string" || name.trim() === "") {
+            invalid(base, "name is required");
+            continue;
+        }
+        if (!AGENT_TEMPLATE_NAME_RE.test(name)) {
+            invalid(name, "name must match ^[a-z0-9][a-z0-9-]{0,63}$ (agents are never renamed)");
+            continue;
+        }
+        if (typeof fm.description !== "string" || fm.description.trim() === "") {
+            invalid(name, "description is required");
+            continue;
+        }
+        if (agents.some((a) => a.name === name)) {
+            invalid(name, `the name ${name} is also used by another agent of this plugin`);
+            continue;
+        }
+        if (agents.length >= AGENT_TEMPLATE_LIMITS.perPlugin) {
+            invalid(name, `a plugin may have at most ${AGENT_TEMPLATE_LIMITS.perPlugin} agents`);
+            continue;
+        }
+        const add = (code, detail) => items.push(item(code, "agent", name, { ...at, detail }));
+        const out = {
+            name,
+            description: cut(fm.description, AGENT_TEMPLATE_LIMITS.descriptionChars),
+        };
+        const ignored = [];
+        const unmapped = [];
+        const narrowed = [];
+        // tools: an allowlist; a pattern such as Bash(git:*) is dropped (mapping it would widen it)
+        if (fm.tools !== undefined) {
+            const names = toolNames(fm.tools);
+            if (names === null)
+                ignored.push("tools");
+            // "*" anywhere (Claude's wildcard) inherits the parent's tools: never wider, but said
+            else if (names.includes("*"))
+                add("agent_tools_inherited", {});
+            else {
+                const keys = [];
+                for (const n of names) {
+                    const k = TOOL_MAP[n];
+                    if (k === undefined)
+                        unmapped.push(n);
+                    else if (!keys.includes(k))
+                        keys.push(k);
+                }
+                out.tools = keys;
+            }
+        }
+        // disallowedTools: a pattern disallows its whole tool (narrower, never wider)
+        if (fm.disallowedTools !== undefined) {
+            const names = toolNames(fm.disallowedTools);
+            if (names === null)
+                ignored.push("disallowedTools");
+            else {
+                const keys = [];
+                for (const n of names) {
+                    const k = TOOL_MAP[n.replace(/\(.*$/s, "").trim()];
+                    if (k === undefined)
+                        unmapped.push(n);
+                    else if (!keys.includes(k))
+                        keys.push(k);
+                    if (k !== undefined && n.includes("("))
+                        narrowed.push(n);
+                }
+                if (keys.length > 0)
+                    out.disallowedTools = keys;
+            }
+        }
+        if (fm.model !== undefined) {
+            const raw = typeof fm.model === "string" ? fm.model.trim() : "";
+            const alias = ALIASES[raw];
+            if (alias !== undefined)
+                out.model = alias;
+            else {
+                const tier = FAMILIES.find(([re]) => re.test(raw))?.[1] ?? "inherit";
+                out.model = tier;
+                add("agent_model_mapped", { from: showName(raw || String(fm.model)), to: tier });
+            }
+        }
+        if (fm.maxTurns !== undefined) {
+            if (Number.isInteger(fm.maxTurns) && fm.maxTurns >= 1) {
+                out.maxSteps = fm.maxTurns;
+            }
+            else
+                ignored.push("maxTurns");
+        }
+        if (fm.effort !== undefined) {
+            if (typeof fm.effort === "string" && EFFORTS.has(fm.effort)) {
+                out.effort = fm.effort;
+            }
+            else
+                ignored.push("effort");
+        }
+        if (fm.skills !== undefined) {
+            const list = toolNames(fm.skills);
+            if (list === null)
+                ignored.push("skills");
+            else {
+                const kept = [];
+                const dropped = [];
+                for (const s of list) {
+                    const own = s.startsWith(`${plugin}:`) ? s.slice(plugin.length + 1) : s;
+                    if (isSkillName(own) && kept.length < AGENT_TEMPLATE_LIMITS.skills && !kept.includes(own))
+                        kept.push(own);
+                    else
+                        dropped.push(s);
+                }
+                if (kept.length > 0)
+                    out.skills = kept;
+                if (dropped.length > 0)
+                    add("agent_skills_truncated", { skills: dropped.join(", ") });
+            }
+        }
+        const notApplicable = Object.keys(fm).filter((k) => NOT_APPLICABLE.has(k));
+        ignored.push(...Object.keys(fm).filter((k) => !MAPPED.has(k) && !NOT_APPLICABLE.has(k)));
+        if (unmapped.length > 0)
+            add("agent_tools_unmapped", { tools: unmapped.join(", ") });
+        if (narrowed.length > 0)
+            add("agent_tools_narrowed", { tools: narrowed.join(", ") });
+        if (notApplicable.length > 0) {
+            add("not_applicable", { keys: notApplicable.sort().join(", ") });
+        }
+        if (ignored.length > 0) {
+            add("agent_field_ignored", { keys: ignored.map(showName).sort().join(", ") });
+        }
+        // The generated template: translated frontmatter (JSON is YAML), the body unchanged
+        const generated = `---\n${JSON.stringify(out, null, 2)}\n---\n${body}`;
+        const check = parseAgentTemplate(generated);
+        if ("errors" in check) {
+            invalid(name, check.errors.join("; "));
+            continue;
+        }
+        agents.push({
+            name,
+            source,
+            path: `${GENERATED_AGENTS_DIR}/${name}.md`,
+            data: new TextEncoder().encode(generated),
+        });
+        items.push(item("agent_imported", "agent", name, {
+            ...at,
+            detail: { type: `${plugin}:${name}`, model: out.model ?? "inherit" },
+        }));
+    }
+    return { agents, items };
+}

package/dist/catalog/claude/commands.d.ts

@@ -0,0 +1,50 @@
+import { type DroppedInvocationKey } from "../../skills/invocation-keys.js";
+import { type TranslationComponent, type TranslationItem } from "./report.js";
+/**
+ * Claude Code commands (`commands/*.md`, listed paths, or the `commands` object map with `source`
+ * or inline `content`) become ordinary skills (phase D spec §8.2, decided 2026-10-27: the model can
+ * invoke them too, as in Claude Code; only `disable-model-invocation: true` makes one manual-only).
+ * Each command's generated SKILL.md lives at `.capybara-generated/commands/<name>/SKILL.md`; the
+ * source file is never rewritten. Pure: no I/O.
+ */
+/** Where the generated SKILL.md of each command lives. */
+export declare const GENERATED_COMMANDS_DIR = ".capybara-generated/commands";
+/** Folded into the content digest of a plugin whose translation phase D changed (§8.3). */
+export declare const CLAUDE_TRANSLATOR_REVISION = "claude-translation-2";
+/**
+ * The `skill_invocation_key_ignored` item of a skill or command whose invocation keys the strict
+ * checks refuse (they are left out; batch 1 review M3, I4), or none.
+ */
+export declare function invocationKeyItems(component: TranslationComponent, name: string, at: {
+    path?: string;
+}, dropped: readonly DroppedInvocationKey[]): TranslationItem[];
+/** The result of {@link translateClaudeCommands}. */
+export interface TranslatedCommands {
+    /** Generated files: `.capybara-generated/commands/<name>/SKILL.md`. */
+    generated: Map<string, Uint8Array>;
+    /** The generated skill directories, for the manifest's `skills` (in command order). */
+    skillPaths: string[];
+    /** The generated skills' names and directories, in the same order. */
+    skills: {
+        name: string;
+        dir: string;
+    }[];
+    /** Per command: `command_imported` or `command_invalid`, then the skill items. */
+    items: TranslationItem[];
+}
+/**
+ * Translates the commands (see the file header). `skillNames` are the plugin's imported skills (a
+ * skill wins over a command of the same name, as in Claude Code); `room` is how many more skills
+ * the plugin may have. `skillItems` adds the per-skill items (manual-only, forked, shell
+ * injections, ignored restrictions) the translator reports for skills too.
+ */
+export declare function translateClaudeCommands(files: ReadonlyMap<string, Uint8Array>, commands: {
+    name: string;
+    path?: string;
+    content?: string;
+}[], skillNames: ReadonlySet<string>, opts: {
+    room: number;
+    skillItems: (component: "command", name: string, at: {
+        path?: string;
+    }, fm: Readonly<Record<string, unknown>>, body: string) => TranslationItem[];
+}): TranslatedCommands;

package/dist/catalog/claude/commands.js

@@ -0,0 +1,179 @@
+import { isSkillName, parseSkillMd, SKILL_ENTRY_FILE, SKILL_LIMITS } from "@capybara-hq/plugin-sdk";
+import { parse as parseYaml } from "yaml";
+import { cleanInvocationKeys, INVOCATION_KEYS, } from "../../skills/invocation-keys.js";
+import { cut, decodeUtf8, isObj, showName } from "./manifest.js";
+import { item } from "./report.js";
+/**
+ * Claude Code commands (`commands/*.md`, listed paths, or the `commands` object map with `source`
+ * or inline `content`) become ordinary skills (phase D spec §8.2, decided 2026-10-27: the model can
+ * invoke them too, as in Claude Code; only `disable-model-invocation: true` makes one manual-only).
+ * Each command's generated SKILL.md lives at `.capybara-generated/commands/<name>/SKILL.md`; the
+ * source file is never rewritten. Pure: no I/O.
+ */
+/** Where the generated SKILL.md of each command lives. */
+export const GENERATED_COMMANDS_DIR = ".capybara-generated/commands";
+/** Folded into the content digest of a plugin whose translation phase D changed (§8.3). */
+export const CLAUDE_TRANSLATOR_REVISION = "claude-translation-2";
+/**
+ * The `skill_invocation_key_ignored` item of a skill or command whose invocation keys the strict
+ * checks refuse (they are left out; batch 1 review M3, I4), or none.
+ */
+export function invocationKeyItems(component, name, at, dropped) {
+    if (dropped.length === 0)
+        return [];
+    return [
+        item("skill_invocation_key_ignored", component, name, {
+            ...at,
+            detail: {
+                keys: dropped.map((d) => d.key).join(", "),
+                problem: dropped.map((d) => d.problem).join("; "),
+            },
+        }),
+    ];
+}
+/**
+ * Claude Code's docs write `argument-hint: [pr-number] [priority] [assignee]`, which is not valid
+ * YAML. The frontmatter with every top-level `argument-hint:` value quoted as written, or null
+ * when there is none to quote.
+ */
+function quoteArgumentHint(front) {
+    let changed = false;
+    const lines = front.split("\n").map((l) => {
+        const m = /^argument-hint:[ \t]*(.*?)[ \t]*$/.exec(l);
+        if (m === null || m[1] === "")
+            return l;
+        changed = true;
+        return `argument-hint: ${JSON.stringify(m[1])}`;
+    });
+    return changed ? lines.join("\n") : null;
+}
+const readYaml = (text) => parseYaml(text, { uniqueKeys: true, maxAliasCount: 50 });
+const FRONTMATTER_MAX_CHARS = 64 * 1024;
+/** A command's frontmatter mapping and body, or a problem (English, for the report). */
+function readCommand(text) {
+    const src = (text.startsWith("") ? text.slice(1) : text).replace(/\r\n?/g, "\n");
+    const lines = src.split("\n");
+    // A command needs no frontmatter: the whole file is then its body
+    if (lines[0]?.trimEnd() !== "---")
+        return { fm: {}, body: src };
+    const end = lines.findIndex((l, i) => i > 0 && l.trimEnd() === "---");
+    if (end < 0)
+        return { problem: "the frontmatter is not closed by a '---' line" };
+    const front = lines.slice(1, end).join("\n");
+    if (front.length > FRONTMATTER_MAX_CHARS)
+        return { problem: "the frontmatter is too long" };
+    let data;
+    try {
+        data = readYaml(front);
+    }
+    catch (e) {
+        // Read again with the argument hint quoted (I4); any other problem stays the first error
+        const quoted = quoteArgumentHint(front);
+        try {
+            if (quoted === null)
+                throw e;
+            data = readYaml(quoted);
+        }
+        catch {
+            return { problem: `the frontmatter is not valid YAML: ${String(e).split("\n")[0]}` };
+        }
+    }
+    if (data === null || data === undefined)
+        data = {};
+    if (!isObj(data))
+        return { problem: "the frontmatter is not a YAML mapping" };
+    return { fm: data, body: lines.slice(end + 1).join("\n") };
+}
+/** The first non-empty body line, flattened to one line and cut to the skill description limit. */
+const firstLine = (body) => {
+    const line = body.split("\n").find((l) => l.trim() !== "") ?? "";
+    return cut(line.replace(/\s+/g, " "), SKILL_LIMITS.descriptionMaxChars);
+};
+/**
+ * Translates the commands (see the file header). `skillNames` are the plugin's imported skills (a
+ * skill wins over a command of the same name, as in Claude Code); `room` is how many more skills
+ * the plugin may have. `skillItems` adds the per-skill items (manual-only, forked, shell
+ * injections, ignored restrictions) the translator reports for skills too.
+ */
+export function translateClaudeCommands(files, commands, skillNames, opts) {
+    const generated = new Map();
+    const skillPaths = [];
+    const skills = [];
+    const items = [];
+    const taken = new Set();
+    for (const c of commands) {
+        const at = c.path !== undefined ? { path: c.path } : {};
+        const invalid = (problem) => items.push(item("command_invalid", "command", showName(c.name), { ...at, detail: { problem } }));
+        if (!isSkillName(c.name)) {
+            invalid("the command name must be 1-64 lowercase letters, digits and single hyphens (commands are never renamed)");
+            continue;
+        }
+        if (skillNames.has(c.name)) {
+            invalid("a skill of this plugin has this name; the skill wins, as in Claude Code");
+            continue;
+        }
+        if (taken.has(c.name)) {
+            invalid("another command of this plugin has this name");
+            continue;
+        }
+        let text;
+        if (c.content !== undefined)
+            text = c.content;
+        else if (c.path !== undefined) {
+            const data = files.get(c.path);
+            if (data === undefined) {
+                invalid("file not found");
+                continue;
+            }
+            text = decodeUtf8(data);
+            if (text === undefined) {
+                invalid("not valid UTF-8 text");
+                continue;
+            }
+        }
+        else {
+            invalid("the command has neither a source file nor content");
+            continue;
+        }
+        const parts = readCommand(text);
+        if ("problem" in parts) {
+            invalid(parts.problem);
+            continue;
+        }
+        const { fm, body } = parts;
+        const description = typeof fm.description === "string" && fm.description.trim() !== ""
+            ? cut(fm.description.replace(/\s+/g, " "), SKILL_LIMITS.descriptionMaxChars)
+            : firstLine(body);
+        if (description === "") {
+            invalid("no description");
+            continue;
+        }
+        if (skills.length >= opts.room) {
+            invalid("too many skills");
+            continue;
+        }
+        // Invocation keys the strict checks refuse are left out, with a warning (M3)
+        const clean = cleanInvocationKeys(fm);
+        const front = { name: c.name, description };
+        for (const k of INVOCATION_KEYS) {
+            if (clean.frontmatter[k] !== undefined)
+                front[k] = clean.frontmatter[k];
+        }
+        const md = `---\n${JSON.stringify(front, null, 2)}\n---\n${body}`;
+        const parsed = parseSkillMd(md);
+        if ("errors" in parsed) {
+            invalid(parsed.errors.join("; "));
+            continue;
+        }
+        taken.add(c.name);
+        const dir = `${GENERATED_COMMANDS_DIR}/${c.name}`;
+        generated.set(`${dir}/${SKILL_ENTRY_FILE}`, new TextEncoder().encode(md));
+        skillPaths.push(dir);
+        skills.push({ name: c.name, dir });
+        items.push(item("command_imported", "command", c.name, at));
+        items.push(...invocationKeyItems("command", c.name, at, clean.dropped));
+        // The invocation keys as the generated SKILL.md has them; the other keys as the command wrote
+        items.push(...opts.skillItems("command", c.name, at, { ...clean.frontmatter, ...parsed.frontmatter }, body));
+    }
+    return { generated, skillPaths, skills, items };
+}

package/dist/catalog/claude/manifest.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Lenient reading of Claude Code's plugin files (`.claude-plugin/plugin.json`, `.mcp.json`,
+ * `hooks/hooks.json`; format: spec Appendix A, re-checked against the Claude Code plugins
+ * reference on 2026-10-26). Claude's format is open-ended and keeps gaining fields, so there is no
+ * schema: every value is type-checked where it is used, and a wrong type is a report item, never
+ * an exception (spec §8.1).
+ */
+/** Claude Code's plugin manifest. */
+export declare const CLAUDE_PLUGIN_FILE = ".claude-plugin/plugin.json";
+/**
+ * Component fields a marketplace entry may carry (stored in `ClaudeEntryOverlay.components`). The
+ * first six are the ones Claude's `strict` rule appends or rejects; the rest apply only to a plugin
+ * without its own `plugin.json` (the entry is then the manifest).
+ */
+export declare const CLAUDE_STRICT_COMPONENT_KEYS: readonly ["skills", "commands", "agents", "hooks", "outputStyles", "themes"];
+export declare const CLAUDE_COMPONENT_KEYS: readonly ["skills", "commands", "agents", "hooks", "outputStyles", "themes", "mcpServers", "lspServers", "userConfig", "channels", "monitors", "workflows", "experimental", "settings"];
+/** A Claude marketplace entry's overlay on the plugin (stored per entry, `marketplace_entries.claude`). */
+export interface ClaudeEntryOverlay {
+    /** Default true (Claude's rule). */
+    strict: boolean;
+    /** Component fields of the entry ({@link CLAUDE_COMPONENT_KEYS}), raw JSON. */
+    components: Record<string, unknown>;
+    /** `author.name` of the entry, else of the marketplace `owner.name`. */
+    publisher?: string;
+}
+export declare const isObj: (v: unknown) => v is Record<string, unknown>;
+/**
+ * The content digest of a Claude Code plugin (Decision 5, Review Focus 5): {@link contentDigest}
+ * of the files as read, never of the translated tree, so it does not depend on the translator.
+ * When the marketplace entry carries component fields, they decide what is imported (Claude's
+ * `strict` rule), so `strict` and the components (canonical JSON) are folded in: an entry-only
+ * change at the same version is other content (`+git.<sha12>` / `+sha256.<12>`), not
+ * `catalog.version_exists`. An entry without components gives the files' own digest, the same as
+ * a direct git import of the plugin. Entry display fields (description, author) are listing data
+ * and are not folded in, as for a Capybara marketplace.
+ *
+ * Phase D (spec §8.3): `translatorRevision` (the translation's, set only when the tree has a
+ * command, a manual-only or a forked skill, whose translation phase D changed) is folded in last,
+ * so re-importing such a plugin at an already imported version records `+sha256.<12>` with the
+ * new skills, while every other plugin keeps its digest.
+ */
+export declare function claudeContentDigest(files: ReadonlyMap<string, Uint8Array>, overlay: ClaudeEntryOverlay | undefined, translatorRevision?: string): string;
+export declare const decodeUtf8: (data: Uint8Array) => string | undefined;
+/** A JSON file of the tree: its value, or why it could not be read (English, for the report). */
+export type JsonRead = {
+    value: unknown;
+} | {
+    problem: string;
+};
+/** Reads a JSON file with the plugin manifest's size cap; never throws. */
+export declare function readJsonFile(data: Uint8Array): JsonRead;
+/** Cuts a string to `max` code points (trimmed). */
+export declare const cut: (s: string, max: number) => string;
+/** A short, printable rendering of an untrusted key for the report (see {@link printable}). */
+export declare const showName: (s: string) => string;
+/**
+ * Resolves a component path of a Claude manifest (`./x`, or `.` / `./` for the root where
+ * `allowRoot`) to a path relative to the plugin root (`""` is the root). A non-string, a path
+ * without `./` or the root where it is not allowed is a `{ problem }` (the caller reports it); a
+ * path that leaves the root, or is not a safe relative path at all, refuses the import naming it
+ * (spec §8.1: paths stay inside the root).
+ */
+export declare function componentPath(p: unknown, where: string, allowRoot?: boolean): {
+    rel: string;
+} | {
+    problem: string;
+};
+/** A string or an array as a list (anything else is `null`). */
+export declare const asList: (v: unknown) => unknown[] | null;