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

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

@@ -0,0 +1,86 @@
+/**
+ * The translation report of a Claude Code plugin import (package ecosystem spec §8.4): every
+ * component, field or file the allowlist translation did not take over unchanged becomes one item
+ * with a reason, in five groups. The report is part of the one import review and of its
+ * `reviewHash`; the web mirrors these types in `apps/web/src/lib/catalog.ts`.
+ */
+/** Report groups, in display order. */
+export type TranslationGroup = "imported" | "converted" | "needsInput" | "ignored" | "warnings";
+/** What an item is about. */
+export type TranslationComponent = "plugin" | "skill" | "command" | "agent" | "hook" | "mcpServer" | "field" | "file";
+/** Why an item is in its group (one localized message per code in the web). */
+export type TranslationCode = "skill_imported" | "agent_imported"
+/** Phase D: a command became an ordinary skill (`.capybara-generated/commands/<name>/`). */
+ | "command_imported" | "mcp_template" | "skill_root_relocated" | "version_from_entry" | "version_fallback" | "publisher_from_marketplace" | "dependency_mapped" | "entry_components_merged" | "agent_model_mapped"
+/** `*` in an agent's `tools` (Claude's wildcard): the template inherits the parent's tools. */
+ | "agent_tools_inherited"
+/** Phase D: `disable-model-invocation: true`: a person invokes it from the `/` menu only. */
+ | "skill_manual_only"
+/** Phase D: `context: fork`: runs as a sub-agent (`detail.agent`) when a person invokes it. */
+ | "skill_forked" | "mcp_header_variable" | "mcp_url_variable" | "dependency_not_imported"
+/** Before phase D only (not imported); no longer emitted, kept for stored reports. */
+ | "skill_manual_invocation"
+/** Before phase D only (not imported); no longer emitted, kept for stored reports. */
+ | "command_manual_invocation"
+/** Before phase D only (not imported); no longer emitted, kept for stored reports. */
+ | "skill_needs_subagents"
+/** Phase D: a command that cannot become a skill (`detail.problem`). */
+ | "command_invalid"
+/** Phase B only (agents were not imported); no longer emitted, kept for stored reports. */
+ | "agent_needs_subagents" | "agent_invalid" | "agent_field_ignored" | "hooks_not_run" | "hooks_module" | "mcp_unsupported_transport" | "mcp_invalid" | "skill_invalid" | "not_applicable" | "unknown_field" | "other_harness" | "skill_ignored_restrictions" | "skill_claude_variables" | "session_start_pin_hint" | "mcp_auth_none" | "mcp_type_assumed" | "connector_not_loaded" | "agent_tools_unmapped"
+/** A pattern in `disallowedTools` disallows its whole tool (narrower, never wider). */
+ | "agent_tools_narrowed" | "agent_skills_truncated"
+/** Phase D: the body has `!`command`` / ```! shell injections, which stay text. */
+ | "skill_shell_injection"
+/** Phase D: a forked skill's `agent` is neither built in nor an agent of the plugin. */
+ | "skill_agent_unknown"
+/** Phase D: invocation keys (`detail.keys`) the strict checks refuse are left out (`detail.problem`). */
+ | "skill_invocation_key_ignored"
+/** Phase D: the body has `@file` references (`detail.files`), which stay text. */
+ | "skill_file_reference";
+/** One report item. */
+export interface TranslationItem {
+    group: TranslationGroup;
+    component: TranslationComponent;
+    /** Skill / server / hook event / field name. */
+    name: string;
+    /** Path relative to the plugin root, when the item is a file or directory. */
+    path?: string;
+    code: TranslationCode;
+    /** Values for the localized message (e.g. { keys: "allowed-tools, model" }, { transport: "sse" }). */
+    detail?: Record<string, string | number>;
+}
+/** The report of one translated plugin. */
+export interface TranslationReport {
+    format: "claude-code";
+    /** `.claude-plugin/plugin.json`, or null when the tree has none. */
+    manifestPath: string | null;
+    /** The plugin has a SessionStart hook: the pinned suggestion is expanded by default (§8.4). */
+    sessionStart: boolean;
+    /** Items sorted by group order, then component, then name. At most {@link CLAUDE_REPORT_MAX_ITEMS} (then one "unknown_field" item named "…" with detail { more: n }). */
+    items: TranslationItem[];
+}
+/** Most items a report keeps before the "{ more }" item. */
+export declare const CLAUDE_REPORT_MAX_ITEMS = 500;
+/** The group each code belongs to. */
+export declare const TRANSLATION_CODE_GROUP: Readonly<Record<TranslationCode, TranslationGroup>>;
+/**
+ * Untrusted text made safe for terminals, logs and the web: C0, DEL and C1 control characters and
+ * the bidirectional formatting characters (U+061C, U+200E, U+200F, U+202A-U+202E, U+2066-U+2069)
+ * become `?`.
+ */
+export declare const printable: (s: string) => string;
+/**
+ * Builds an item; the group follows from the code. The name, the path and every string detail
+ * value pass through {@link printable}, so no route (a parser error, a template error, a file name)
+ * can carry control or bidi characters into the report.
+ */
+export declare function item(code: TranslationCode, component: TranslationComponent, name: string, extra?: {
+    path?: string;
+    detail?: Record<string, string | number>;
+}): TranslationItem;
+/**
+ * Sorts items by group order, component order, name, then path and code (code unit order, so the
+ * order is stable across hosts), and caps them at {@link CLAUDE_REPORT_MAX_ITEMS}.
+ */
+export declare function sortItems(items: readonly TranslationItem[]): TranslationItem[];

package/dist/catalog/claude/report.js

@@ -0,0 +1,121 @@
+/**
+ * The translation report of a Claude Code plugin import (package ecosystem spec §8.4): every
+ * component, field or file the allowlist translation did not take over unchanged becomes one item
+ * with a reason, in five groups. The report is part of the one import review and of its
+ * `reviewHash`; the web mirrors these types in `apps/web/src/lib/catalog.ts`.
+ */
+/** Most items a report keeps before the "{ more }" item. */
+export const CLAUDE_REPORT_MAX_ITEMS = 500;
+/** The group each code belongs to. */
+export const TRANSLATION_CODE_GROUP = {
+    skill_imported: "imported",
+    agent_imported: "imported",
+    command_imported: "imported",
+    mcp_template: "converted",
+    skill_root_relocated: "converted",
+    version_from_entry: "converted",
+    version_fallback: "converted",
+    publisher_from_marketplace: "converted",
+    dependency_mapped: "converted",
+    entry_components_merged: "converted",
+    agent_model_mapped: "converted",
+    agent_tools_inherited: "converted",
+    skill_manual_only: "converted",
+    skill_forked: "converted",
+    mcp_header_variable: "needsInput",
+    mcp_url_variable: "needsInput",
+    dependency_not_imported: "needsInput",
+    skill_manual_invocation: "ignored",
+    command_manual_invocation: "ignored",
+    skill_needs_subagents: "ignored",
+    command_invalid: "ignored",
+    agent_needs_subagents: "ignored",
+    agent_invalid: "ignored",
+    agent_field_ignored: "ignored",
+    hooks_not_run: "ignored",
+    hooks_module: "ignored",
+    mcp_unsupported_transport: "ignored",
+    mcp_invalid: "ignored",
+    skill_invalid: "ignored",
+    not_applicable: "ignored",
+    unknown_field: "ignored",
+    other_harness: "ignored",
+    skill_ignored_restrictions: "warnings",
+    skill_claude_variables: "warnings",
+    session_start_pin_hint: "warnings",
+    mcp_auth_none: "warnings",
+    mcp_type_assumed: "warnings",
+    connector_not_loaded: "warnings",
+    agent_tools_unmapped: "warnings",
+    agent_tools_narrowed: "warnings",
+    agent_skills_truncated: "warnings",
+    skill_shell_injection: "warnings",
+    skill_agent_unknown: "warnings",
+    skill_invocation_key_ignored: "warnings",
+    skill_file_reference: "warnings",
+};
+const GROUP_ORDER = [
+    "imported",
+    "converted",
+    "needsInput",
+    "ignored",
+    "warnings",
+];
+const COMPONENT_ORDER = [
+    "plugin",
+    "skill",
+    "command",
+    "agent",
+    "hook",
+    "mcpServer",
+    "field",
+    "file",
+];
+/**
+ * Untrusted text made safe for terminals, logs and the web: C0, DEL and C1 control characters and
+ * the bidirectional formatting characters (U+061C, U+200E, U+200F, U+202A-U+202E, U+2066-U+2069)
+ * become `?`.
+ */
+export const printable = (s) => 
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are replaced
+s.replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "?");
+/**
+ * Builds an item; the group follows from the code. The name, the path and every string detail
+ * value pass through {@link printable}, so no route (a parser error, a template error, a file name)
+ * can carry control or bidi characters into the report.
+ */
+export function item(code, component, name, extra = {}) {
+    const detail = extra.detail === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(extra.detail).map(([k, v]) => [
+            k,
+            typeof v === "string" ? printable(v) : v,
+        ]));
+    return {
+        group: TRANSLATION_CODE_GROUP[code],
+        component,
+        name: printable(name),
+        ...(extra.path !== undefined && { path: printable(extra.path) }),
+        code,
+        ...(detail !== undefined && { detail }),
+    };
+}
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * Sorts items by group order, component order, name, then path and code (code unit order, so the
+ * order is stable across hosts), and caps them at {@link CLAUDE_REPORT_MAX_ITEMS}.
+ */
+export function sortItems(items) {
+    const sorted = [...items].sort((a, b) => GROUP_ORDER.indexOf(a.group) - GROUP_ORDER.indexOf(b.group) ||
+        COMPONENT_ORDER.indexOf(a.component) - COMPONENT_ORDER.indexOf(b.component) ||
+        cmp(a.name, b.name) ||
+        cmp(a.path ?? "", b.path ?? "") ||
+        cmp(a.code, b.code));
+    if (sorted.length <= CLAUDE_REPORT_MAX_ITEMS)
+        return sorted;
+    const more = sorted.length - CLAUDE_REPORT_MAX_ITEMS;
+    return [
+        ...sorted.slice(0, CLAUDE_REPORT_MAX_ITEMS),
+        item("unknown_field", "field", "…", { detail: { more } }),
+    ];
+}

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

@@ -0,0 +1,56 @@
+import { type ClaudeEntryOverlay } from "./manifest.js";
+import { type TranslationReport } from "./report.js";
+/**
+ * Translates a Claude Code plugin tree into a Capybara plugin tree (package ecosystem spec §8): a
+ * synthesized `.capybara-plugin/plugin.json` listing every imported skill and generated connector
+ * template explicitly, the templates under `.capybara-generated/connectors/`, and the allowlist
+ * translation report. Pure: no I/O. The input is hostile: every problem is a report item, and only
+ * the cases {@link translateClaudePlugin} names refuse the import. Skill files are never modified;
+ * only a root `SKILL.md`'s files move under `skills/<name>/`.
+ */
+/** Options of {@link translateClaudePlugin}. */
+export interface ClaudeTranslateOptions {
+    /** Marketplace entry name / repo name (§8.2 "no plugin.json"). */
+    fallbackName: string;
+    /** Entry version, else `0.0.0-git.g<sha12>`. */
+    fallbackVersion: string;
+    /** Marketplace `owner.name`, else `<host>/<owner>`. */
+    fallbackPublisher: string;
+    /** For the "version_from_entry" item. */
+    entryVersion?: string;
+    overlay?: ClaudeEntryOverlay;
+    /** Accept `http://` loopback MCP URLs (tests; `marketplaces.allowInsecureLoopback`). */
+    allowInsecureLoopback?: boolean;
+}
+/** The translated plugin. */
+export interface ClaudeTranslation {
+    /**
+     * The original files plus `.capybara-plugin/plugin.json` (synthesized) and
+     * `.capybara-generated/connectors/<id>.json`; a root SKILL.md's files moved under
+     * `skills/<name>/`. `package.json` is left out: in a Claude plugin it is npm metadata for other
+     * harnesses, which the Capybara reader would otherwise check against the synthesized manifest.
+     */
+    tree: Map<string, Uint8Array>;
+    report: TranslationReport;
+    /** `repository` of the Claude manifest (display only, spec §8.2). */
+    repository?: string;
+    /**
+     * {@link CLAUDE_TRANSLATOR_REVISION} when phase D changed what this tree translates to (it has a
+     * command, a manual-only or a forked skill): folded into the content digest (phase D spec §8.3).
+     */
+    translatorRevision?: string;
+}
+/**
+ * The tree looks like a Claude plugin: no `.capybara-plugin/plugin.json` and one of
+ * `.claude-plugin/plugin.json`, `hooks/hooks.json`, `.mcp.json`, `commands/`, `agents/`, a root
+ * `SKILL.md`; or `hint` (a Claude marketplace entry). A tree with only `skills/` stays the A1
+ * skills-only plugin.
+ */
+export declare function isClaudePluginTree(files: ReadonlyMap<string, Uint8Array>, hint?: ClaudeEntryOverlay): boolean;
+/**
+ * Translates the tree (see the file header). Throws `PluginPackageError("catalog.invalid_manifest")`
+ * only for: a plugin name Capybara cannot use (including an unreadable `plugin.json`), a
+ * `strict: false` conflict, a path leaving the root, and a plugin with no importable skill and no
+ * template.
+ */
+export declare function translateClaudePlugin(files: ReadonlyMap<string, Uint8Array>, o: ClaudeTranslateOptions): ClaudeTranslation;