toolfactory 0.1.1

package/dist/surfaces/browser-extension.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/surfaces/browser-extension.test.js

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+import { surface as browserExtension, browserVerdict, HOST_DIR, permissions, WXT_PIN, zipName, } from "./browser-extension.js";
+const echo = { name: "echo", inputSchema: { type: "object" }, requires: [] };
+const scrape = {
+    name: "scrape",
+    inputSchema: { type: "object" },
+    requires: ["browser"],
+};
+const summarize = {
+    name: "summarize",
+    inputSchema: { type: "object" },
+    requires: ["model"],
+};
+function fixture(overrides = {}) {
+    return {
+        root: "/repo",
+        tool: {
+            schemaVersion: 1,
+            identity: "plugin.json",
+            binding: "typescript",
+            surfaces: ["mcp", "web", "browser-extension"],
+            bundle: { runtime: "package" },
+            tests: { examples: { echo: { text: "hi" } } },
+            ...overrides,
+        },
+        identity: {
+            name: "hello.tool",
+            version: "0.1.0",
+            repository: "https://github.com/octo/hello",
+        },
+        identityExtra: {},
+        operations: [echo, scrape, summarize],
+        toolfactoryVersion: "0.1.0",
+        packageManager: "npm",
+    };
+}
+function planned(project) {
+    return Object.fromEntries(browserExtension.plan(project).map((file) => [file.path, file]));
+}
+function content(file) {
+    if (file?.kind === "file")
+        return file.content;
+    if (file?.kind === "region")
+        return file.regions.map((region) => region.content).join("");
+    throw new Error("expected a whole or region file");
+}
+describe("browser-extension", () => {
+    it("plans one WXT project: generated whole files, two regions the author owns, one merge", () => {
+        const files = planned(fixture());
+        expect(Object.keys(files).sort()).toEqual([
+            `${HOST_DIR}/.gitignore`,
+            `${HOST_DIR}/README.md`,
+            `${HOST_DIR}/TARGETS.md`,
+            `${HOST_DIR}/entrypoints/background.ts`,
+            `${HOST_DIR}/entrypoints/example.content.ts`,
+            `${HOST_DIR}/entrypoints/options/index.html`,
+            `${HOST_DIR}/entrypoints/options/main.tsx`,
+            `${HOST_DIR}/entrypoints/popup/index.html`,
+            `${HOST_DIR}/entrypoints/popup/main.tsx`,
+            `${HOST_DIR}/env.d.ts`,
+            `${HOST_DIR}/package.json`,
+            `${HOST_DIR}/tests/background.test.ts`,
+            `${HOST_DIR}/tests/smoke.mjs`,
+            `${HOST_DIR}/tsconfig.json`,
+            `${HOST_DIR}/utils/mcp.ts`,
+            `${HOST_DIR}/utils/page.css`,
+            `${HOST_DIR}/utils/page.tsx`,
+            `${HOST_DIR}/vitest.config.ts`,
+            `${HOST_DIR}/web-ext-config.mjs`,
+            `${HOST_DIR}/wxt.config.ts`,
+        ]);
+        // The manifest is never written here: WXT emits one per target out of these two inputs.
+        expect(Object.keys(files)).not.toContain(`${HOST_DIR}/manifest.json`);
+        expect(files[`${HOST_DIR}/package.json`]).toMatchObject({
+            kind: "merge",
+            patch: { name: "hello.tool-browser", devDependencies: { wxt: WXT_PIN } },
+        });
+        expect(files[`${HOST_DIR}/entrypoints/background.ts`]?.kind).toBe("region");
+        expect(files[`${HOST_DIR}/wxt.config.ts`]?.kind).toBe("region");
+        // WXT names an archive after `zip.name`, which the config sets to the tool's own name.
+        expect(zipName(fixture(), "firefox")).toBe("hello.tool-0.1.0-firefox.zip");
+        expect(content(files[`${HOST_DIR}/wxt.config.ts`])).toContain('zip: { name: "hello.tool" }');
+        // The popup is the `web` surface's tree, imported; without it, only the pairing form ships.
+        expect(content(files[`${HOST_DIR}/entrypoints/popup/main.tsx`])).toContain('from "@web/App"');
+        // Launching the web app here means popping the same tree out of the 540px popup into a tab;
+        // the options page is already that tab, so it gets no button.
+        expect(content(files[`${HOST_DIR}/entrypoints/popup/main.tsx`])).toContain("<OpenFullPage />");
+        expect(content(files[`${HOST_DIR}/entrypoints/options/main.tsx`])).not.toContain("OpenFullPage");
+        expect(content(files[`${HOST_DIR}/utils/page.tsx`])).toContain("browser.runtime.openOptionsPage()");
+        const alone = planned(fixture({ surfaces: ["mcp", "browser-extension"] }));
+        expect(content(alone[`${HOST_DIR}/entrypoints/popup/main.tsx`])).not.toContain("@web/App");
+        expect(alone[`${HOST_DIR}/utils/page.css`]).toBeUndefined();
+    });
+    it("projects the manifest from capabilities, never from a hand-written permission list", () => {
+        // `storage` for the pairing store; `activeTab` because an operation declares `browser`.
+        expect(permissions(fixture(), [echo, scrape])).toEqual(["storage", "activeTab"]);
+        expect(permissions(fixture(), [echo])).toEqual(["storage"]);
+        expect(permissions(fixture({ browserExtension: { cookieExport: true, sidePanel: true } }), [echo])).toEqual(["storage", "cookies", "sidePanel"]);
+        const config = content(planned(fixture())[`${HOST_DIR}/wxt.config.ts`]);
+        // Loopback is portable only without a port (Firefox rejects a port in a match pattern), and
+        // the declared session domains are added to it — never `<all_urls>`.
+        expect(config).toContain('const HOST_PERMISSIONS = ["http://127.0.0.1/*", "http://localhost/*"];');
+        expect(config).toContain('id: "hello.tool@octo.github.io"');
+        const vandy = content(planned(fixture({ browserExtension: { authDomains: ["*://*.vanderbilt.edu/*"] } }))[`${HOST_DIR}/wxt.config.ts`]);
+        expect(vandy).toContain('"*://*.vanderbilt.edu/*"');
+        // A Chromium-only permission is dropped from the other engines' manifests, not shipped dead.
+        expect(config).toContain("CHROMIUM.includes(browser) || !CHROMIUM_ONLY.includes(permission)");
+    });
+    it("is native for browser and user-input operations, and degrades the export on Safari", () => {
+        const project = fixture();
+        expect(browserExtension.verdict?.(scrape, project)).toEqual({ kind: "native" });
+        expect(browserExtension.verdict?.(summarize, project)).toEqual({
+            kind: "excluded",
+            reason: "excluded:no-model-bridge",
+        });
+        for (const engine of ["chromium", "firefox", "safari"]) {
+            expect(browserVerdict(scrape, project, engine)).toEqual({ kind: "native" });
+            expect(browserVerdict(summarize, project, engine).kind).toBe("excluded");
+        }
+        // Safari Web Extensions cannot read httpOnly cookies, so an opted-in export degrades there.
+        const exporting = fixture({ browserExtension: { cookieExport: true } });
+        expect(browserVerdict(scrape, exporting, "firefox")).toEqual({ kind: "native" });
+        expect(browserVerdict(scrape, exporting, "safari")).toEqual({
+            kind: "degraded",
+            reason: "degraded:no-httponly-cookies",
+        });
+    });
+    it("validates with the extension's own pinned CLIs, from inside the extension", () => {
+        const project = fixture();
+        const commands = browserExtension.validate?.(project) ?? [];
+        expect(commands.map((command) => [command.command, ...command.args].join(" "))).toEqual([
+            "npm install",
+            "npm exec --no -- wxt prepare",
+            expect.stringContaining("hosts/browser"),
+            "npm exec --no -- wxt build",
+            "npm exec --no -- wxt build -b firefox",
+            "npm exec --no -- web-ext lint -s .output/firefox-mv2",
+            "npm exec --no -- playwright install chromium",
+            "npm run test",
+            "node tests/smoke.mjs",
+        ]);
+        // wxt reads its entrypoints from the working directory, so every step runs in the host dir.
+        expect(new Set(commands.map((command) => command.cwd))).toEqual(new Set([`/repo/${HOST_DIR}`, "/repo"]));
+    });
+});

package/dist/surfaces/claude.d.ts

@@ -0,0 +1,2 @@
+import type { Surface } from "../model.js";
+export declare const surface: Surface;

package/dist/surfaces/claude.js

@@ -0,0 +1,81 @@
+/**
+ * Claude Code plugin: an unconditional projection whenever selected, validated by
+ * `claude plugin validate .`. Reuses the root `skills/`; MCP servers are declared inline.
+ * The repository is also its own single-plugin marketplace, because that is the only shape
+ * `claude plugin marketplace add <owner>/<repo>` (and Copilot CLI's identical command) installs.
+ */
+import { githubSlug } from "../hosts/github.js";
+import { compact, configProperties, envName, has, isSensitive, json, kernelLaunch, mcpVerdict, requiredConfig, } from "./shared.js";
+export const surface = {
+    id: "claude",
+    plan(project) {
+        const { identity } = project;
+        const userConfig = Object.fromEntries(Object.entries(configProperties(project)).map(([key, property]) => [
+            key,
+            compact({
+                type: property.type === "number" || property.type === "integer"
+                    ? "number"
+                    : property.type === "boolean"
+                        ? "boolean"
+                        : "string",
+                title: property.title ?? key,
+                description: property.description ?? key,
+                sensitive: isSensitive(property) || undefined,
+                required: requiredConfig(project).includes(key) || undefined,
+                default: property.default,
+            }),
+        ]));
+        const launch = kernelLaunch(project, "${CLAUDE_PLUGIN_ROOT}");
+        const env = Object.fromEntries(Object.keys(configProperties(project)).map((key) => [envName(key), `\${user_config.${key}}`]));
+        const manifest = compact({
+            $schema: "https://json.schemastore.org/claude-code-plugin-manifest.json",
+            name: identity.name,
+            version: identity.version,
+            description: identity.description,
+            author: identity.author,
+            homepage: identity.homepage,
+            repository: identity.repository,
+            license: identity.license,
+            keywords: identity.keywords,
+            userConfig: Object.keys(userConfig).length ? userConfig : undefined,
+            // Inline rather than .mcp.json: a root .mcp.json doubles as the repo's own project MCP
+            // config in Claude Code, and repo templates commonly own that file.
+            mcpServers: has(project, "mcp")
+                ? {
+                    [identity.name]: compact({ ...launch, env: Object.keys(env).length ? env : undefined }),
+                }
+                : undefined,
+        });
+        // Required by the marketplace schema; the plugin's own author is the honest owner.
+        const owner = compact({
+            name: identity.author?.name ?? githubSlug(identity.repository)?.split("/")[0] ?? identity.name,
+            email: identity.author?.email,
+            url: identity.author?.url,
+        });
+        const marketplace = compact({
+            $schema: "https://json.schemastore.org/claude-code-marketplace.json",
+            name: identity.name,
+            description: identity.description,
+            owner,
+            // `source: "./"` is the marketplace root itself: one repository, one plugin, no submodule.
+            plugins: [compact({ name: identity.name, source: "./", description: identity.description })],
+        });
+        return [
+            { kind: "file", path: ".claude-plugin/plugin.json", content: json(manifest) },
+            { kind: "file", path: ".claude-plugin/marketplace.json", content: json(marketplace) },
+        ];
+    },
+    validate(project) {
+        return [
+            {
+                label: "claude plugin validate",
+                command: "claude",
+                // Not --strict: a repo-root CLAUDE.md (the AGENTS.md pointer every repo carries) is a
+                // strict-mode warning, and warnings never describe the generated manifest.
+                args: ["plugin", "validate", "."],
+                cwd: project.root,
+            },
+        ];
+    },
+    verdict: mcpVerdict,
+};

package/dist/surfaces/codex.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Codex plugin: `.codex-plugin/plugin.json` with the required `interface` block, plus
+ * `.agents/plugins/marketplace.json` listing the repository's own plugin (`source: {source:
+ * "local", path: "."}`) — the shape `codex plugin marketplace add <owner>/<repo>` (or a local
+ * path) reads, confirmed against developers.openai.com/codex/plugins/build and proven end to end
+ * in `validate()` below (`marketplace add` → `plugin add` → `plugin list --available`, real Codex
+ * CLI, no mocks). The public ChatGPT/Codex plugin directory is a separate hosted-review portal
+ * this surface does not reach.
+ */
+import type { Surface } from "../model.js";
+/** The Codex CLI (`@openai/codex`) `validate()` is proven against — pin for a deterministic gate. */
+export declare const CODEX_PIN = "0.152.1";
+export declare const surface: Surface;

package/dist/surfaces/codex.js

@@ -0,0 +1,101 @@
+/**
+ * Codex plugin: `.codex-plugin/plugin.json` with the required `interface` block, plus
+ * `.agents/plugins/marketplace.json` listing the repository's own plugin (`source: {source:
+ * "local", path: "."}`) — the shape `codex plugin marketplace add <owner>/<repo>` (or a local
+ * path) reads, confirmed against developers.openai.com/codex/plugins/build and proven end to end
+ * in `validate()` below (`marketplace add` → `plugin add` → `plugin list --available`, real Codex
+ * CLI, no mocks). The public ChatGPT/Codex plugin directory is a separate hosted-review portal
+ * this surface does not reach.
+ */
+import { projectName } from "../identity/name.js";
+import { compact, has, json, kernelLaunch, mcpVerdict } from "./shared.js";
+/** The Codex CLI (`@openai/codex`) `validate()` is proven against — pin for a deterministic gate. */
+export const CODEX_PIN = "0.152.1";
+export const surface = {
+    id: "codex",
+    plan(project) {
+        const { identity } = project;
+        const displayName = projectName.display(identity.name);
+        const codexInterface = {
+            displayName,
+            shortDescription: (identity.description ?? identity.name).slice(0, 80),
+            longDescription: identity.description ?? identity.name,
+            developerName: identity.author?.name ?? "unknown",
+            category: "Productivity",
+            capabilities: [],
+            ...(project.tool.codex?.interface ?? {}),
+        };
+        const manifest = compact({
+            name: identity.name,
+            version: identity.version ?? "0.1.0",
+            description: identity.description ?? identity.name,
+            author: compact({
+                name: identity.author?.name ?? "unknown",
+                email: identity.author?.email,
+                url: identity.author?.url,
+            }),
+            homepage: identity.homepage,
+            repository: identity.repository,
+            license: identity.license,
+            keywords: identity.keywords,
+            skills: has(project, "skill") ? "./skills/" : undefined,
+            mcpServers: has(project, "mcp")
+                ? { [identity.name]: kernelLaunch(project, "${PLUGIN_ROOT}") }
+                : undefined,
+            interface: codexInterface,
+        });
+        // `source: "local"` + `path: "."` is the marketplace root itself: one repository, one
+        // plugin. `policy.installation`/`policy.authentication`/`category` are required on every
+        // entry per the build guide; `ON_INSTALL` mirrors the guide's own sample.
+        const marketplace = compact({
+            name: identity.name,
+            interface: { displayName: codexInterface.displayName },
+            plugins: [
+                compact({
+                    name: identity.name,
+                    source: { source: "local", path: "." },
+                    policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" },
+                    category: codexInterface.category,
+                }),
+            ],
+        });
+        return [
+            { kind: "file", path: ".codex-plugin/plugin.json", content: json(manifest) },
+            { kind: "file", path: ".agents/plugins/marketplace.json", content: json(marketplace) },
+        ];
+    },
+    validate(project) {
+        // A fresh CODEX_HOME per run, matching the dsh surface's pattern: `marketplace add` reads
+        // marketplace.json, `plugin add` installs the plugin entry it names (parsing plugin.json),
+        // and `plugin list --available` confirms it resolves — the real install path end to end.
+        const pluginId = `${project.identity.name}@${project.identity.name}`;
+        // `plugin add` copies the plugin directory verbatim. Stage only the distributable tree: a
+        // source checkout may carry dependencies, a source-pinned toolfactory cache, nested Git data,
+        // or environment files that must never become part of an installed plugin.
+        const script = [
+            'TF_CODEX_HOME="$(mktemp -d)"; TF_STAGE="$(mktemp -d)"',
+            'tar --exclude=.git --exclude=*/.git --exclude=.cache --exclude=.env --exclude=.env.* --exclude=node_modules --exclude=dist -cf - . | tar -xf - -C "$TF_STAGE"',
+            'test ! -e "$TF_STAGE/.cache" && test ! -e "$TF_STAGE/.env" && test -z "$(find "$TF_STAGE" -type d -name .git -print -quit)" || { rm -rf "$TF_CODEX_HOME" "$TF_STAGE"; exit 1; }',
+            'cd "$TF_STAGE"',
+            `out="$({ CODEX_HOME="$TF_CODEX_HOME" npx -y @openai/codex@${CODEX_PIN} plugin marketplace add . --json && CODEX_HOME="$TF_CODEX_HOME" npx -y @openai/codex@${CODEX_PIN} plugin add ${pluginId} --json && CODEX_HOME="$TF_CODEX_HOME" npx -y @openai/codex@${CODEX_PIN} plugin list --available --json; } 2>&1)"`,
+            "status=$?",
+            'rm -rf "$TF_CODEX_HOME" "$TF_STAGE"',
+            'printf "%s\\n" "$out"',
+            "exit $status",
+        ].join("\n");
+        return [
+            {
+                label: "codex plugin marketplace add / plugin add / plugin list",
+                command: "sh",
+                args: ["-c", script],
+                cwd: project.root,
+            },
+        ];
+    },
+    verdict: (operation) => {
+        const verdict = mcpVerdict(operation);
+        return verdict.kind === "native"
+            ? { kind: "degraded", reason: "degraded:loader-unverified" }
+            : verdict;
+    },
+};

package/dist/surfaces/codex.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/surfaces/codex.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { surface as codex } from "./codex.js";
+const echo = { name: "echo", inputSchema: { type: "object" }, requires: [] };
+function project(surfaces) {
+    return {
+        root: "/repo",
+        tool: {
+            schemaVersion: 1,
+            identity: "plugin.json",
+            binding: "typescript",
+            surfaces,
+            bundle: { runtime: "package" },
+            tests: { examples: {} },
+        },
+        identity: {
+            name: "hello",
+            version: "0.1.0",
+            description: "Say hello",
+            author: { name: "GoatInAHat" },
+            repository: "https://github.com/GoatInAHat/Hello-Tool",
+        },
+        identityExtra: {},
+        operations: [echo],
+        toolfactoryVersion: "0.1.0",
+        packageManager: "npm",
+    };
+}
+describe("codex", () => {
+    it("makes the repository its own single-plugin marketplace, and validates with the real codex CLI", () => {
+        const files = codex.plan(project(["codex", "mcp"]));
+        const marketplace = files.find((entry) => entry.path === ".agents/plugins/marketplace.json");
+        if (marketplace?.kind !== "file")
+            throw new Error("expected a whole file");
+        expect(JSON.parse(marketplace.content)).toMatchObject({
+            name: "hello",
+            interface: { displayName: "Hello" },
+            plugins: [
+                {
+                    name: "hello",
+                    source: { source: "local", path: "." },
+                    policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" },
+                    category: "Productivity",
+                },
+            ],
+        });
+        const [command] = codex.validate?.(project(["codex", "mcp"])) ?? [];
+        const script = command?.args.join(" ") ?? "";
+        expect(command?.command).toBe("sh");
+        expect(script).toContain("plugin marketplace add . --json");
+        expect(script).toContain("plugin add hello@hello --json");
+        expect(script).toContain("plugin list --available --json");
+        expect(script).toContain('TF_CODEX_HOME="$(mktemp -d)"');
+        expect(script).toContain("--exclude=.cache --exclude=.env --exclude=.env.*");
+        expect(script).toContain("--exclude=.git --exclude=*/.git");
+        expect(script).toContain('CODEX_HOME="$TF_CODEX_HOME"');
+        expect(script).toContain('test ! -e "$TF_STAGE/.cache"');
+    });
+    it("ships only the skill when runtime is none", () => {
+        const target = project(["skill", "codex"]);
+        target.tool.runtime = "none";
+        const manifest = codex.plan(target).find((entry) => entry.path === ".codex-plugin/plugin.json");
+        if (manifest?.kind !== "file")
+            throw new Error("expected a manifest");
+        expect(JSON.parse(manifest.content)).toMatchObject({ skills: "./skills/" });
+        expect(JSON.parse(manifest.content)).not.toHaveProperty("mcpServers");
+    });
+});

package/dist/surfaces/cursor.d.ts

@@ -0,0 +1,2 @@
+import type { Surface } from "../model.js";
+export declare const surface: Surface;

package/dist/surfaces/cursor.js

@@ -0,0 +1,50 @@
+/**
+ * Cursor plugin: `.cursor-plugin/plugin.json`; config becomes `variables` (JSON Schema)
+ * and the bundle's `mcp.json` is shared. Loader unverified, like Codex.
+ */
+import { projectName } from "../identity/name.js";
+import { compact, configProperties, envName, has, json, mcpVerdict, requiredConfig, } from "./shared.js";
+export const surface = {
+    id: "cursor",
+    plan(project) {
+        const { identity } = project;
+        const properties = configProperties(project);
+        const variables = Object.keys(properties).length
+            ? {
+                type: "object",
+                properties: Object.fromEntries(Object.entries(properties).map(([key, property]) => [
+                    envName(key),
+                    compact({
+                        type: property.type ?? "string",
+                        title: property.title ?? key,
+                        description: property.description,
+                        default: property.default,
+                    }),
+                ])),
+                required: requiredConfig(project).map((key) => envName(key)),
+            }
+            : undefined;
+        const manifest = compact({
+            name: projectName.cursor(identity.name),
+            version: identity.version,
+            description: identity.description,
+            author: identity.author
+                ? compact({ name: identity.author.name ?? "unknown", email: identity.author.email })
+                : undefined,
+            homepage: identity.homepage,
+            repository: identity.repository,
+            license: identity.license,
+            keywords: identity.keywords,
+            skills: has(project, "skill") ? "./skills/" : undefined,
+            mcpServers: has(project, "agent-plugins") ? "./mcp.json" : undefined,
+            variables,
+        });
+        return [{ kind: "file", path: ".cursor-plugin/plugin.json", content: json(manifest) }];
+    },
+    verdict: (operation) => {
+        const verdict = mcpVerdict(operation);
+        return verdict.kind === "native"
+            ? { kind: "degraded", reason: "degraded:loader-unverified" }
+            : verdict;
+    },
+};

package/dist/surfaces/distribution.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/surfaces/distribution.test.js

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "vitest";
+import { buildPlan } from "../project/plan.js";
+import { surface as claude } from "./claude.js";
+import { surface as npm } from "./npm.js";
+import { MCP_NAME_BEGIN, MCP_NAME_END } from "./pypi.js";
+import { INSTALL_BEGIN, INSTALL_END, surface as readme } from "./readme.js";
+const echo = { name: "echo", inputSchema: { type: "object" }, requires: [] };
+function project(surfaces, overrides = {}) {
+    return {
+        root: "/repo",
+        tool: {
+            schemaVersion: 1,
+            identity: "plugin.json",
+            binding: "typescript",
+            surfaces,
+            bundle: { runtime: "package" },
+            tests: { examples: {} },
+        },
+        identity: {
+            name: "hello",
+            version: "0.1.0",
+            description: "Say hello",
+            author: { name: "GoatInAHat" },
+            repository: "https://github.com/GoatInAHat/Hello-Tool",
+        },
+        identityExtra: {},
+        operations: [echo],
+        toolfactoryVersion: "0.1.0",
+        packageManager: "npm",
+        ...overrides,
+    };
+}
+function region(target) {
+    const [file] = readme.plan(target);
+    if (file?.kind !== "region")
+        throw new Error("expected a region file");
+    return file.regions[0]?.content ?? "";
+}
+describe("npm", () => {
+    it("writes the repository in npm's object form, preserving the slug's case, and lints with publint", () => {
+        const [file] = npm.plan(project(["npm", "cli"]));
+        if (file?.kind !== "merge")
+            throw new Error("expected a merge file");
+        expect(file.patch.repository).toEqual({
+            type: "git",
+            url: "git+https://github.com/GoatInAHat/Hello-Tool.git",
+        });
+        expect(npm.validate?.(project(["npm"])).map((command) => command.args.join(" "))).toContain("--yes publint --strict");
+    });
+});
+describe("claude", () => {
+    it("makes the repository its own single-plugin marketplace", () => {
+        const files = claude.plan(project(["claude", "mcp"]));
+        const file = files.find((entry) => entry.path === ".claude-plugin/marketplace.json");
+        if (file?.kind !== "file")
+            throw new Error("expected a whole file");
+        expect(JSON.parse(file.content)).toMatchObject({
+            name: "hello",
+            owner: { name: "GoatInAHat" },
+            plugins: [{ name: "hello", source: "./", description: "Say hello" }],
+        });
+    });
+});
+describe("readme", () => {
+    it("plans one install line per selected surface inside an author-owned template", () => {
+        const [file] = readme.plan(project(["skill", "mcp", "claude", "npm"]));
+        if (file?.kind !== "region")
+            throw new Error("expected a region file");
+        expect(file.path).toBe("README.md");
+        expect(file.template).toContain(`${INSTALL_BEGIN}\n${INSTALL_END}`);
+        const body = file.regions[0]?.content ?? "";
+        expect(body).toContain("## Install");
+        expect(body).toContain("`npx skills add GoatInAHat/Hello-Tool`");
+        expect(body).toContain("[![Agent Skill](https://img.shields.io/badge/Agent_Skill-available-5B5BD6)](https://github.com/GoatInAHat/Hello-Tool)");
+        expect(body).toContain("`npx -y hello mcp`");
+        // The MCP line carries both first-party install badges once a package registry is selected,
+        // computed from the same unpinned `npx -y hello mcp` launch as the text line.
+        expect(body).toContain("https://vscode.dev/redirect/mcp/install?name=hello&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22hello%22%2C%22mcp%22%5D%7D");
+        expect(body).toContain("https://cursor.com/en/install-mcp?name=hello&config=");
+        expect(body).toContain("https://cursor.com/deeplink/mcp-install-dark.svg");
+        expect(body).toContain("`claude plugin marketplace add GoatInAHat/Hello-Tool`");
+        expect(body).toContain("`claude plugin install hello@hello`");
+        expect(body).toContain("`npm install hello`");
+        expect(body).not.toContain("openclaw");
+    });
+    it("adds the Codex, Gemini, MCPB and browser-extension lines, and skips the badges without a registry", () => {
+        const body = region(project(["mcp", "codex", "gemini", "mcpb", "browser-extension"]));
+        expect(body).not.toContain("vscode.dev/redirect/mcp/install");
+        expect(body).not.toContain("cursor.com/en/install-mcp");
+        expect(body).toContain("`codex plugin marketplace add GoatInAHat/Hello-Tool`");
+        expect(body).toContain("`codex plugin add hello@hello`");
+        expect(body).toContain("`gemini extensions install https://github.com/GoatInAHat/Hello-Tool`");
+        expect(body).toContain("download `hello.mcpb` from the GitHub Release and double-click to install");
+        // The extension's three channels — unpacked from a checkout, the release assets (only the
+        // signed xpi installs itself), the store listings — and the pairing step that ends each.
+        expect(body).toContain("Load unpacked → `hosts/browser/.output/chrome-mv3`");
+        expect(body).toContain("web-ext run");
+        expect(body).toContain("`hello-0.1.0-chrome.zip`, `hello-0.1.0-firefox.zip`, `hello-0.1.0-edge.zip`");
+        expect(body).toContain("Mozilla-signed `.xpi`");
+        expect(body).toContain("`npx -y hello mcp --http --pair`");
+    });
+    it("names the one command that opens the web app, and only when that surface is selected", () => {
+        expect(region(project(["mcp", "web"]))).toContain("`npx -y hello mcp --http --open`");
+        expect(region(project(["mcp"]))).not.toContain("--http --open");
+    });
+    it("carries pypi's mcp-name region beside its own, in one README the plan merges", () => {
+        const surfaces = ["pypi", "mcp-registry"];
+        const python = project(surfaces, {
+            root: "/nonexistent",
+            tool: { ...project(surfaces).tool, binding: "python" },
+        });
+        const file = buildPlan(python).find((planned) => planned.path === "README.md");
+        if (file?.kind !== "region")
+            throw new Error("expected a region file");
+        expect(file.regions.map((entry) => entry.begin).sort()).toEqual([INSTALL_BEGIN, MCP_NAME_BEGIN].sort());
+        expect(file.template).toContain(`${INSTALL_BEGIN}\n${INSTALL_END}`);
+        expect(file.template).toContain(`${MCP_NAME_BEGIN}\n${MCP_NAME_END}`);
+    });
+    it("falls back to the local checkout when the identity carries no GitHub repository", () => {
+        const surfaces = [
+            "skill",
+            "claude",
+            "codex",
+            "gemini",
+            "openclaw-native",
+            "hermes-native",
+            "clawhub",
+            "dsh",
+            "pypi",
+        ];
+        const local = region(project(surfaces, {
+            identity: { name: "hello", version: "0.1.0", description: "Say hello" },
+            tool: { ...project(surfaces).tool, binding: "python" },
+        }));
+        expect(local).not.toContain("skills.sh");
+        expect(local).not.toContain("npx skills add");
+        expect(local).toContain("`claude plugin marketplace add .`");
+        expect(local).toContain("`codex plugin marketplace add .`");
+        expect(local).toContain("`gemini extensions link .` from a checkout");
+        expect(local).toContain("`hermes plugins install file://$PWD#hosts/hermes/hello_hermes`");
+        expect(local).toContain("openclaw plugins install --link hosts/openclaw");
+        expect(local).toContain("openclaw plugins install clawhub:openclaw-plugin-hello");
+        expect(local).toContain("dsh plugin --profile <profile> add ./hosts/dsh");
+        expect(local).toContain("`uv add hello`");
+    });
+});

package/dist/surfaces/dsh.d.ts

@@ -0,0 +1,25 @@
+import type { Project, Surface } from "../model.js";
+/**
+ * The `@deepseek-ai/dsh` release `validate()` boots. Pinned, not `@alpha`: npm's `latest` tag
+ * lags the alpha line by weeks, so an unpinned install is neither current nor reproducible.
+ * Renovate bumps this constant (`renovate.json` `customManagers`).
+ */
+export declare const DSH_PIN = "0.1.2-alpha.5";
+export declare const HOST_DIR = "hosts/dsh";
+/** The patch file name `dsh.bundle.patch` points at; DSH's own convention for a Cordis overlay. */
+export declare const PATCH_FILE = "cordis.patch.yml";
+/**
+ * The same row against this checkout instead of the published package. Kept out of `files`, so
+ * `npm pack ./hosts/dsh` never ships it: it is what `validate()` boots and what a developer
+ * passes to `dsh --patch` to drive the working tree.
+ */
+export declare const LOCAL_PATCH_FILE = "cordis.local.patch.yml";
+/** `headless` is one-shot and ships an app bundle; a profile without one blocks forever. */
+export declare const PROFILE = "headless";
+/** The public name a bridged MCP tool takes in DSH; `mcp__<serverName>__<rawName>` is its contract. */
+export declare function toolName(project: Project, operation: string): string;
+/** The row id and, with it, the `# == <bundle>` layer `--dump-config` prints. */
+export declare function rowId(project: Project): string;
+/** The tarball `npm pack ./hosts/dsh` writes into the release assets, by name. */
+export declare function dshTarball(project: Project): string;
+export declare const surface: Surface;