toolfactory 0.1.1

package/dist/surfaces/openclaw-native.test.d.ts

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

package/dist/surfaces/openclaw-native.test.js

@@ -0,0 +1,246 @@
+import { execFileSync } from "node:child_process";
+import { describe, expect, it } from "vitest";
+import { scaffoldDrift } from "../hosts/openclaw.js";
+import { computeCoverage, renderCoverageMarkdown } from "../report/coverage.js";
+import { HOST_DIR, OPENCLAW_ADDITIONS, OPENCLAW_SCAFFOLD, surface } from "./openclaw-native.js";
+const echo = {
+    name: "echo",
+    description: "Return the text you pass in.",
+    inputSchema: {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        type: "object",
+        properties: { text: { type: "string" } },
+        required: ["text"],
+    },
+    outputSchema: {
+        type: "object",
+        properties: { echoed: { type: "string" } },
+        required: ["echoed"],
+    },
+    requires: [],
+};
+const shoot = { name: "shoot", inputSchema: { type: "object" }, requires: ["browser"] };
+function project(overrides = {}) {
+    return {
+        root: "/repo",
+        tool: {
+            schemaVersion: 1,
+            identity: "package.json",
+            binding: "typescript",
+            surfaces: ["openclaw-native", "mcp"],
+            bundle: { runtime: "package" },
+            tests: { examples: { echo: { text: "hello" } } },
+        },
+        identity: { name: "hello", version: "0.1.0", description: "Say hello" },
+        identityExtra: {},
+        operations: [echo, shoot],
+        toolfactoryVersion: "0.1.0",
+        ...overrides,
+    };
+}
+/** A zero-operation plugin whose whole contribution is one declared host registration. */
+function voice() {
+    const base = project();
+    return {
+        ...base,
+        tool: {
+            ...base.tool,
+            openclaw: {
+                registers: [
+                    {
+                        api: "registerRealtimeVoiceProvider",
+                        contract: "realtimeVoiceProviders",
+                        ids: ["codex"],
+                    },
+                ],
+                pluginApi: ">=2026.8.2",
+                dependencies: { ws: "^8.18.0" },
+            },
+        },
+        operations: [],
+    };
+}
+/** Every planned file as text: full files verbatim, region files as the region toolfactory owns. */
+function emitted(target) {
+    return Object.fromEntries(surface
+        .plan(target)
+        .map((file) => [
+        file.path,
+        file.kind === "file"
+            ? file.content
+            : file.kind === "region"
+                ? file.regions.map((region) => region.content).join("")
+                : JSON.stringify(file.patch),
+    ]));
+}
+describe("openclaw-native", () => {
+    it("projects only the operations OpenClaw can run and pins the scaffold in one place", () => {
+        const files = emitted(project());
+        const manifest = JSON.parse(files[`${HOST_DIR}/openclaw.plugin.json`] ?? "{}");
+        expect(manifest.contracts).toEqual({ tools: ["echo"] });
+        expect(manifest.activation).toEqual({ onStartup: true });
+        expect(surface.verdict?.(shoot, project())).toEqual({
+            kind: "excluded",
+            reason: "excluded:implement-in-hosts",
+        });
+        // The escape hatch is where the author writes it; the README has to say so.
+        expect(files[`${HOST_DIR}/README.md`]).toContain("excluded:implement-in-hosts");
+        expect(files[`${HOST_DIR}/README.md`]).toContain("`shoot` — requires browser");
+        const pkg = JSON.parse(files[`${HOST_DIR}/package.json`] ?? "{}");
+        expect(pkg.openclaw).toEqual({
+            extensions: ["./dist/index.js"],
+            compat: { pluginApi: OPENCLAW_SCAFFOLD.pluginApi },
+            build: { openclawVersion: OPENCLAW_SCAFFOLD.openclawVersion },
+        });
+        // Nothing to expect of the inspector until the plugin declares a registration.
+        expect(pkg.pluginInspector).toBeUndefined();
+        // TypeScript core: in-process import of the author's module, no subprocess.
+        expect(pkg.dependencies.hello).toBe("file:../..");
+        expect(files[`${HOST_DIR}/src/index.ts`]).toContain('from "hello/dist/ops.js"');
+        // JSON Schema goes through untouched via Type.Unsafe; $schema is what OpenClaw strips.
+        expect(files[`${HOST_DIR}/src/index.ts`]).toContain('"text"');
+        expect(files[`${HOST_DIR}/src/index.ts`]).not.toContain("$schema");
+        // Module load must be side-effect-free: every host loader, and `plugin-inspector check
+        // --runtime`, import the entry long before a tool runs.
+        expect(files[`${HOST_DIR}/src/index.ts`]).toContain("const dataDir = () => join(");
+        expect(files[`${HOST_DIR}/src/index.ts`]).toContain("dataDir: dataDir(),");
+    });
+    it("serves the web app as a gateway route and a Control UI tab, in process, only in TypeScript", () => {
+        const withWeb = project({
+            tool: { ...project().tool, surfaces: ["openclaw-native", "mcp", "web", "npm"] },
+        });
+        const files = emitted(withWeb);
+        const index = files[`${HOST_DIR}/src/index.ts`] ?? "";
+        // The route hands requests to the core's own router, so `<prefix>/mcp` needs no second
+        // listener and `/env` stays off — the gateway's working directory is not the author's.
+        expect(index).toContain('import { handler } from "hello/dist/toolfactory/mcp.js";');
+        expect(index).toContain('const WEB_PATH = "/plugins/hello/web";');
+        expect(index).toContain('auth: "gateway"');
+        expect(index).toContain("handler({ path: `${WEB_PATH}/mcp`, prefix: WEB_PATH, env: false })");
+        expect(index).toContain('surface: "tab" as const');
+        expect(index).toContain("api.registerControlUiDescriptor(descriptor)");
+        // Neither registrar is a manifest contract key; both are what the inspector expects to see.
+        expect(JSON.parse(files[`${HOST_DIR}/openclaw.plugin.json`] ?? "{}").contracts).toEqual({
+            tools: ["echo"],
+        });
+        expect(JSON.parse(files[`${HOST_DIR}/package.json`] ?? "{}").pluginInspector.plugin.expect
+            .registrations).toEqual(["registerHttpRoute", "registerControlUiDescriptor"]);
+        expect(files[`${HOST_DIR}/src/index.test.ts`]).toContain("serves the web app as a Control UI tab");
+        // A Python core's plugin is an out-of-process shim: there is no handler to mount.
+        const python = emitted(project({
+            tool: {
+                ...withWeb.tool,
+                binding: "python",
+                surfaces: ["openclaw-native", "mcp", "web", "pypi"],
+            },
+        }));
+        expect(python[`${HOST_DIR}/src/index.ts`]).not.toContain("registerHttpRoute");
+    });
+    it("degrades a non-TypeScript core to an out-of-process shim", () => {
+        const python = project({
+            tool: { ...project().tool, binding: "python" },
+        });
+        expect(surface.verdict?.(echo, python)).toEqual({
+            kind: "degraded",
+            reason: "degraded:out-of-process",
+        });
+        const index = emitted(python)[`${HOST_DIR}/src/index.ts`] ?? "";
+        expect(index).toContain('"run", "python", "-m", "hello.toolfactory.cli"');
+        // The host's state directory reaches an out-of-process kernel as the environment variable
+        // every surface reads it from.
+        expect(index).toContain('env["HELLO_DATA_DIR"] = dataDir();');
+        expect(index).not.toContain("ops.js");
+        expect(JSON.parse(emitted(python)[`${HOST_DIR}/package.json`] ?? "{}").dependencies).toEqual(OPENCLAW_SCAFFOLD.dependencies);
+    });
+    it("drives manifest, inspector and test from one `registers` declaration", () => {
+        const target = voice();
+        const files = emitted(target);
+        const manifest = JSON.parse(files[`${HOST_DIR}/openclaw.plugin.json`] ?? "{}");
+        expect(manifest.contracts).toEqual({ tools: [], realtimeVoiceProviders: ["codex"] });
+        const pkg = JSON.parse(files[`${HOST_DIR}/package.json`] ?? "{}");
+        expect(pkg.pluginInspector.plugin.expect).toEqual({
+            registrations: ["registerRealtimeVoiceProvider"],
+            manifestContracts: ["realtimeVoiceProviders"],
+        });
+        // The author's extra dependency merges after the scaffold's; the core is not imported at all.
+        expect(pkg.dependencies).toEqual({ ...OPENCLAW_SCAFFOLD.dependencies, ws: "^8.18.0" });
+        expect(pkg.peerDependencies.openclaw).toBe(">=2026.8.2");
+        expect(pkg.openclaw.compat.pluginApi).toBe(">=2026.8.2");
+        // The generated region stops at the entry: the registration itself is the author's tail.
+        const region = files[`${HOST_DIR}/src/index.ts`] ?? "";
+        expect(region).toContain("const entry = defineToolPlugin({");
+        expect(region).not.toContain("registerRealtimeVoiceProvider(");
+        expect(region).toContain('Parameters<OpenClawPluginApi["registerRealtimeVoiceProvider"]>[0]');
+        expect(region).not.toContain("typebox");
+        const template = surface.plan(target).find((file) => file.path.endsWith("src/index.ts"));
+        expect(template?.kind === "region" && template.template).toContain("export default entry;");
+        // The generated test records the registration the declaration promised.
+        const test = files[`${HOST_DIR}/src/index.test.ts`] ?? "";
+        expect(test).toContain("entry.register(api as OpenClawPluginApi)");
+        expect(test).toContain('registered["registerRealtimeVoiceProvider"]');
+        expect(files[`${HOST_DIR}/README.md`]).toContain("codex-app-server-extensions.ts");
+    });
+    it("projects a discriminating scripted-model e2e lane, and none without a tool to call", () => {
+        const files = emitted(project());
+        const fixtures = JSON.parse(files[`${HOST_DIR}/e2e/fixtures.json`] ?? "{}");
+        // Leg 1 asks for the operation with the authored example arguments; leg 2 answers OK only
+        // when the tool's own result carries a name its output schema promises; leg 3 catches the rest.
+        expect(fixtures.fixtures).toEqual([
+            {
+                match: { toolName: "echo", hasToolResult: false },
+                response: { toolCalls: [{ name: "echo", arguments: { text: "hello" } }] },
+            },
+            {
+                match: { hasToolResult: true, toolResultContains: "echoed" },
+                response: { content: "HELLO_OK" },
+            },
+            { match: { hasToolResult: true }, response: { content: "HELLO_FAIL" } },
+        ]);
+        const e2e = files[`${HOST_DIR}/e2e/openclaw.e2e.test.ts`] ?? "";
+        expect(e2e).toContain('expect(turn.payloads[0].text).toBe("HELLO_OK")');
+        expect(e2e).toContain('"plugins", "install", "--link", pluginDir');
+        // The three constraints that are not discoverable anywhere else.
+        expect(e2e).toContain('key !== "VITEST" && !key.startsWith("VITEST_")');
+        expect(files[`${HOST_DIR}/vitest.e2e.config.ts`]).toContain('include: ["e2e/**/*.e2e.test.ts"]');
+        const pkg = JSON.parse(files[`${HOST_DIR}/package.json`] ?? "{}");
+        expect(pkg.scripts["test:e2e"]).toBe(OPENCLAW_ADDITIONS.e2eScript);
+        expect(pkg.devDependencies["@copilotkit/aimock"]).toBe(OPENCLAW_ADDITIONS.aimock);
+        // `file:../..` becomes a node_modules symlink out of the install root, which OpenClaw's
+        // install-time safety scan refuses; install-links materialises it instead.
+        expect(files[`${HOST_DIR}/.npmrc`]).toContain("install-links=true");
+        // Without it `tsc` emits a dist/ from source that failed type-checking.
+        expect(JSON.parse(files[`${HOST_DIR}/tsconfig.json`] ?? "{}").compilerOptions.noEmitOnError).toBe(true);
+        // The lane is opt-in: a real turn really runs the operation, so no `tests.examples` entry
+        // (and no operation at all) means no lane.
+        const base = project();
+        const unexampled = emitted({ ...base, tool: { ...base.tool, tests: { examples: {} } } });
+        expect(unexampled[`${HOST_DIR}/e2e/fixtures.json`]).toBeUndefined();
+        const none = emitted(voice());
+        expect(none[`${HOST_DIR}/e2e/fixtures.json`]).toBeUndefined();
+        expect(JSON.parse(none[`${HOST_DIR}/package.json`] ?? "{}").scripts["test:e2e"]).toBeUndefined();
+    });
+    it("reports what a zero-operation plugin contributes instead of an empty table", () => {
+        const coverage = computeCoverage(voice(), [surface]);
+        expect(coverage.rows).toEqual([]);
+        const markdown = renderCoverageMarkdown(coverage, [], 7);
+        expect(markdown).not.toContain("| operation |");
+        expect(markdown).toContain("`registerRealtimeVoiceProvider` → `realtimeVoiceProviders`: `codex`");
+    });
+});
+/** C2: the scaffold constants are only trustworthy while the real generator still writes them. */
+function hasOpenclaw() {
+    try {
+        execFileSync("openclaw", ["--version"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+describe.skipIf(!hasOpenclaw())("openclaw scaffold", () => {
+    it("still matches `openclaw plugins init --type tool`", () => {
+        expect(scaffoldDrift(project())).toEqual([]);
+        // A declared `pluginApi` is an intentional override, not drift.
+        expect(scaffoldDrift(voice())).toEqual([]);
+    });
+});

package/dist/surfaces/pypi.d.ts

@@ -0,0 +1,5 @@
+import type { Surface } from "../model.js";
+export declare const README_PATH = "README.md";
+export declare const MCP_NAME_BEGIN = "<!-- tf:mcp-name -->";
+export declare const MCP_NAME_END = "<!-- /tf:mcp-name -->";
+export declare const surface: Surface;

package/dist/surfaces/pypi.js

@@ -0,0 +1,82 @@
+/**
+ * PyPI package: identity projected into pyproject.toml (merge; the author owns the rest),
+ * the console script for the CLI, and the MCP Registry ownership marker, which for PyPI is
+ * an `mcp-name:` line in the README the registry reads back off the published project page.
+ */
+import { cliEntryPoint, projectTable, pythonPackage } from "../bindings/python.js";
+import { registryName } from "./mcp-registry.js";
+import { compact, has } from "./shared.js";
+import { WEB_DIR } from "./web.js";
+export const README_PATH = "README.md";
+export const MCP_NAME_BEGIN = "<!-- tf:mcp-name -->";
+export const MCP_NAME_END = "<!-- /tf:mcp-name -->";
+export const surface = {
+    id: "pypi",
+    plan(project) {
+        if (project.tool.binding !== "python") {
+            throw new Error('Surface "pypi" requires the python binding.');
+        }
+        const authored = project.tool.identity === "pyproject.toml";
+        const registry = has(project, "mcp-registry");
+        const patch = {
+            project: compact({
+                ...(authored ? {} : projectTable(project)),
+                readme: registry ? README_PATH : undefined,
+                scripts: has(project, "cli")
+                    ? { [project.identity.name]: cliEntryPoint(project) }
+                    : undefined,
+            }),
+            // The kernel serves the built page from inside its own package, so the wheel has to
+            // carry it: `packages` only copies the package tree, `force-include` maps anything else.
+            ...(has(project, "web")
+                ? {
+                    tool: {
+                        hatch: {
+                            build: {
+                                targets: {
+                                    wheel: {
+                                        "force-include": {
+                                            [`${WEB_DIR}/dist`]: `${pythonPackage(project)}/${WEB_DIR}`,
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                }
+                : {}),
+        };
+        const files = [
+            {
+                kind: "merge",
+                path: "pyproject.toml",
+                format: "toml",
+                patch,
+                owned: ["project.scripts"],
+            },
+        ];
+        if (!registry)
+            return files;
+        const marker = `\n<!-- mcp-name: ${registryName(project)} -->\n`;
+        return [
+            ...files,
+            {
+                kind: "region",
+                path: README_PATH,
+                regions: [{ begin: MCP_NAME_BEGIN, end: MCP_NAME_END, content: marker }],
+                template: [
+                    `# ${project.identity.name}`,
+                    "",
+                    project.identity.description ?? "",
+                    "",
+                    MCP_NAME_BEGIN,
+                    MCP_NAME_END,
+                    "",
+                ].join("\n"),
+            },
+        ];
+    },
+    validate(project) {
+        return [{ label: "uv build", command: "uv", args: ["build"], cwd: project.root }];
+    },
+};

package/dist/surfaces/readme.d.ts

@@ -0,0 +1,7 @@
+import type { Project, Surface } from "../model.js";
+export declare const README_PATH = "README.md";
+export declare const INSTALL_BEGIN = "<!-- tf:install -->";
+export declare const INSTALL_END = "<!-- /tf:install -->";
+/** The content of the generated region — everything between the markers, not the markers. */
+export declare function installContent(project: Project): string;
+export declare const surface: Surface;

package/dist/surfaces/readme.js

@@ -0,0 +1,181 @@
+/**
+ * Surface "readme": the `<!-- tf:install -->` region of `README.md`, always generated (like
+ * `workflows` and `agents`; never in `tool.json.surfaces`). One install line per selected
+ * distribution surface, in the exact shape that surface's own installer accepts, so the
+ * humans-and-agents-facing half of distribution cannot drift from the artifacts. The prose
+ * around the region — what the tool is, how to use it — is the author's, forever.
+ *
+ * Every line works from a plain checkout; the ones that need a GitHub repository (`npx skills
+ * add`, the Agent Skill badge, the marketplace and Hermes clone URLs) appear only once the
+ * identity file carries one, so a tool built without GitHub still gets an accurate section.
+ *
+ * When `mcp` is selected alongside a package registry, the MCP line also carries the two
+ * first-party one-click badges (VS Code's `vscode.dev/redirect/mcp/install`, Cursor's
+ * `cursor.com/en/install-mcp`), both computed from the exact same `{command, args, env}` launch
+ * the plain-text line renders — a badge can never point somewhere the text line does not.
+ */
+import { githubSlug } from "../hosts/github.js";
+import { projectName } from "../identity/name.js";
+import { HOST_DIR as BROWSER_HOST_DIR, zipName } from "./browser-extension.js";
+import { HOST_DIR as DSH_HOST_DIR, dshTarball } from "./dsh.js";
+import { pluginDir as hermesPluginDir } from "./hermes-native.js";
+import { HOST_DIR as OPENCLAW_HOST_DIR } from "./openclaw-native.js";
+import { envName, has, npmName, pypiName, requiredConfig } from "./shared.js";
+export const README_PATH = "README.md";
+export const INSTALL_BEGIN = "<!-- tf:install -->";
+export const INSTALL_END = "<!-- /tf:install -->";
+/** A stable label for repositories that ship an Agent Skill; unlike skills.sh's live count badge,
+ * it does not depend on a separate registry index. */
+function skillBadge(slug) {
+    return `[![Agent Skill](https://img.shields.io/badge/Agent_Skill-available-5B5BD6)](https://github.com/${slug})`;
+}
+/**
+ * The kernel MCP server's published launch, unpinned — `{command, args}`, plus an `env` map of
+ * blank placeholders for whatever config the tool requires. The one source both `mcpCommand`
+ * (the plain-text line) and the VS Code / Cursor install badges below encode: a badge can never
+ * name a launch the text line does not.
+ */
+function launchConfig(project) {
+    const { command, args } = project.tool.binding === "python"
+        ? (() => {
+            const pypi = pypiName(project);
+            // `uvx <pkg>` runs the command of the same name; a dotted tool name renames the package.
+            return pypi === project.identity.name
+                ? { command: "uvx", args: [pypi, "mcp"] }
+                : { command: "uvx", args: ["--from", pypi, project.identity.name, "mcp"] };
+        })()
+        : { command: "npx", args: ["-y", npmName(project), "mcp"] };
+    const required = requiredConfig(project);
+    return required.length
+        ? { command, args, env: Object.fromEntries(required.map((key) => [envName(key), ""])) }
+        : { command, args };
+}
+function mcpCommand(project) {
+    const { command, args } = launchConfig(project);
+    return [command, ...args].join(" ");
+}
+/** github.com/github/github-mcp-server's README badge, verbatim shields.io style. */
+function vscodeBadge(project) {
+    const config = encodeURIComponent(JSON.stringify(launchConfig(project)));
+    const url = `https://vscode.dev/redirect/mcp/install?name=${encodeURIComponent(project.identity.name)}&config=${config}`;
+    return `[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](${url})`;
+}
+/** cursor.com/docs/mcp/install-links's own badge SVG and `en/install-mcp` redirect. */
+function cursorBadge(project) {
+    const config = Buffer.from(JSON.stringify(launchConfig(project))).toString("base64");
+    const url = `https://cursor.com/en/install-mcp?name=${encodeURIComponent(project.identity.name)}&config=${config}`;
+    return `[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](${url})`;
+}
+function installLines(project) {
+    const { identity } = project;
+    const slug = githubSlug(identity.repository);
+    const lines = [];
+    if (has(project, "skill") && slug) {
+        lines.push(`- **Agent Skill** — \`npx skills add ${slug}\``);
+    }
+    if (has(project, "mcp")) {
+        // The one-click badges need a published package to point at: they read the same launch
+        // config the text line does, so they only appear once there is somewhere to `npx`/`uvx` from.
+        const badges = has(project, "npm") || has(project, "pypi")
+            ? ` ${vscodeBadge(project)} ${cursorBadge(project)}`
+            : "";
+        lines.push(`- **MCP server** — \`${mcpCommand(project)}\`${badges}`);
+    }
+    if (has(project, "mcpb")) {
+        lines.push(`- **Claude Desktop extension** — download \`${identity.name}.mcpb\` from the GitHub Release and double-click to install`);
+    }
+    if (has(project, "claude")) {
+        // The repository is its own marketplace (`.claude-plugin/marketplace.json`); Copilot CLI
+        // reads the same file with the same command.
+        lines.push(`- **Claude Code plugin** — \`claude plugin marketplace add ${slug ?? "."}\`, then \`claude plugin install ${identity.name}@${identity.name}\``);
+    }
+    if (has(project, "codex")) {
+        // `.agents/plugins/marketplace.json` lists the repository's own plugin (`codex.ts`).
+        lines.push(`- **Codex plugin** — \`codex plugin marketplace add ${slug ?? "."}\`, then \`codex plugin add ${identity.name}@${identity.name}\``);
+    }
+    if (has(project, "gemini")) {
+        lines.push(slug
+            ? `- **Gemini CLI extension** — \`gemini extensions install https://github.com/${slug}\``
+            : "- **Gemini CLI extension** — `gemini extensions link .` from a checkout");
+    }
+    if (has(project, "openclaw-native")) {
+        const clawhub = has(project, "clawhub")
+            ? `; published: \`openclaw plugins install clawhub:${projectName.openclawPackage(identity.name)}\``
+            : "";
+        lines.push(`- **OpenClaw plugin** — \`openclaw plugins install --link ${OPENCLAW_HOST_DIR}\` from a checkout${clawhub}`);
+    }
+    if (has(project, "hermes-native")) {
+        const source = slug ? `https://github.com/${slug}` : "file://$PWD";
+        lines.push(`- **Hermes plugin** — \`hermes plugins install ${source}#${hermesPluginDir(project)}\``);
+    }
+    if (has(project, "dsh")) {
+        // `dsh plugin` is a pnpm forwarder: it installs a path, a tarball or a registry spec.
+        lines.push(`- **DSH plugin** (experimental) — \`dsh plugin --profile <profile> add ./${DSH_HOST_DIR}\` from a checkout, or the release tarball \`${dshTarball(project)}\``);
+    }
+    if (has(project, "browser-extension")) {
+        // Three channels, in the order a reader needs them: build-and-load from a checkout, the
+        // release assets (only Mozilla's signed xpi is a real self-hosted install — Chrome drops
+        // side-loaded unpacked extensions), the store listings. Pairing is the last step of each.
+        const zips = ["chrome", "firefox", "edge"].map((browser) => `\`${zipName(project, browser)}\``);
+        lines.push([
+            `- **Browser extension** — from a checkout: \`npm --prefix ${BROWSER_HOST_DIR} install && npm --prefix ${BROWSER_HOST_DIR} exec --no -- wxt build\`,`,
+            `  then \`chrome://extensions\` → developer mode → Load unpacked → \`${BROWSER_HOST_DIR}/.output/chrome-mv3\``,
+            `  (Firefox: \`npm --prefix ${BROWSER_HOST_DIR} exec --no -- web-ext run\`). Each GitHub Release attaches the`,
+            `  store uploads ${zips.join(", ")}, and the Mozilla-signed \`.xpi\`,`,
+            "  which is the only download-and-install channel now that Chrome no longer keeps side-loaded unpacked",
+            "  extensions; the Chrome Web Store, Firefox Add-ons and Edge Add-ons listings appear once the release's",
+            `  submit step has each store's credentials. Then pair it: \`${mcpCommand(project)} --http --pair\``,
+            "  prints the `<url>#<token>` the extension's options page accepts.",
+        ].join("\n"));
+    }
+    if (has(project, "web")) {
+        // Not an install: the one command that puts the page in front of a human, from wherever the
+        // tool already is. The same listener answers `/mcp`, so the page needs nothing else running.
+        lines.push(`- **Web app** — \`${mcpCommand(project)} --http --open\` serves the operations page beside the`, "  MCP endpoint on one port and opens it; over MCP or a skill, the `web` operation does the same and", "  returns the URL.");
+    }
+    if (has(project, "npm"))
+        lines.push(`- **npm package** — \`npm install ${npmName(project)}\``);
+    if (has(project, "pypi"))
+        lines.push(`- **PyPI package** — \`uv add ${pypiName(project)}\``);
+    return lines;
+}
+/** The content of the generated region — everything between the markers, not the markers. */
+export function installContent(project) {
+    const slug = githubSlug(project.identity.repository);
+    const badge = has(project, "skill") && slug ? [skillBadge(slug), ""] : [];
+    const lines = installLines(project);
+    return `${[
+        "",
+        "## Install",
+        "",
+        ...badge,
+        ...(lines.length
+            ? lines
+            : ["_No installable surface is selected: this repository ships source only._"]),
+        "",
+    ].join("\n")}\n`;
+}
+function template(project) {
+    return [
+        `# ${project.identity.name}`,
+        "",
+        project.identity.description ?? "One paragraph: what this tool does, and for whom.",
+        "",
+        INSTALL_BEGIN,
+        INSTALL_END,
+        "",
+    ].join("\n");
+}
+export const surface = {
+    id: "readme",
+    plan(project) {
+        return [
+            {
+                kind: "region",
+                path: README_PATH,
+                regions: [{ begin: INSTALL_BEGIN, end: INSTALL_END, content: installContent(project) }],
+                template: template(project),
+            },
+        ];
+    },
+};

package/dist/surfaces/registry.d.ts

@@ -0,0 +1,6 @@
+import type { Surface, SurfaceId } from "../model.js";
+export declare function registerSurface(surface: Surface): void;
+export declare function getSurface(id: SurfaceId): Surface;
+export declare function selectedSurfaces(ids: readonly SurfaceId[]): Surface[];
+/** A selection is valid only when every surface's declared dependencies are selected too. */
+export declare function assertSurfaceRequirements(ids: readonly SurfaceId[]): void;

package/dist/surfaces/registry.js

@@ -0,0 +1,73 @@
+import { surface as agentPlugins } from "./agent-plugins.js";
+import { surface as agents } from "./agents.js";
+import { surface as browserExtension } from "./browser-extension.js";
+import { surface as claude } from "./claude.js";
+import { surface as codex } from "./codex.js";
+import { surface as cursor } from "./cursor.js";
+import { surface as dsh } from "./dsh.js";
+import { clawhub } from "./external.js";
+import { surface as gemini } from "./gemini.js";
+import { surface as hermesNative } from "./hermes-native.js";
+import { cli, mcp } from "./kernel.js";
+import { surface as mcpRegistry } from "./mcp-registry.js";
+import { surface as mcpb } from "./mcpb.js";
+import { surface as npm } from "./npm.js";
+import { surface as openclawNative } from "./openclaw-native.js";
+import { surface as pypi } from "./pypi.js";
+import { surface as readme } from "./readme.js";
+import { surface as skill } from "./skill.js";
+import { surface as web } from "./web.js";
+import { surface as workflows } from "./workflows.js";
+const registry = {
+    "agent-plugins": agentPlugins,
+    agents,
+    "browser-extension": { ...browserExtension, requires: ["mcp"] },
+    claude,
+    codex,
+    // Declared dependencies (§3): these projectors point at a file another surface writes, so a
+    // selection without it would ship an artifact referencing nothing. Refused at plan time.
+    cursor: { ...cursor, requires: ["agent-plugins"] },
+    clawhub,
+    // Reaches the kernel only through DSH's own MCP client, so the bundle is inert without it.
+    dsh: { ...dsh, requires: ["mcp"] },
+    // The manifest's only payload is the kernel's launch row: an extension without it is a
+    // context file and nothing else.
+    gemini: { ...gemini, requires: ["mcp"] },
+    cli,
+    mcp,
+    "mcp-registry": mcpRegistry,
+    // The bundle root is the npm tarball with its production dependencies installed into it, and
+    // its one row launches the kernel MCP server: without either surface there is nothing to pack.
+    mcpb: { ...mcpb, requires: ["mcp", "npm"] },
+    npm,
+    skill,
+    "hermes-native": hermesNative,
+    "openclaw-native": openclawNative,
+    pypi,
+    readme,
+    web: { ...web, requires: ["mcp"] },
+    workflows,
+};
+export function registerSurface(surface) {
+    registry[surface.id] = surface;
+}
+export function getSurface(id) {
+    const surface = registry[id];
+    if (!surface)
+        throw new Error(`Surface "${id}" is not implemented in this toolfactory version.`);
+    return surface;
+}
+export function selectedSurfaces(ids) {
+    return ids.map(getSurface);
+}
+/** A selection is valid only when every surface's declared dependencies are selected too. */
+export function assertSurfaceRequirements(ids) {
+    const selected = new Set(ids);
+    for (const id of ids) {
+        for (const required of getSurface(id).requires ?? []) {
+            if (selected.has(required))
+                continue;
+            throw new Error(`Surface "${id}" requires surface "${required}", which is not selected (surfaces: ${ids.join(", ")}). Select "${required}" or drop "${id}".`);
+        }
+    }
+}

package/dist/surfaces/shared.d.ts

@@ -0,0 +1,49 @@
+import { type Operation, type Project, type Verdict } from "../model.js";
+export declare const TOOLFACTORY_DIR = "dev.toolfactory";
+export declare function json(value: unknown): string;
+/** Drop undefined values so projections never emit `"key": undefined`. */
+export declare function compact<T extends Record<string, unknown>>(record: T): Partial<T>;
+export declare function has(project: Project, surface: string): boolean;
+export declare function npmName(project: Project): string;
+export declare function pypiName(project: Project): string;
+/** The launch command for the kernel MCP server as an installed package or a committed build. */
+export declare function kernelLaunch(project: Project, placeholderRoot: string): {
+    command: string;
+    args: string[];
+};
+/** Verdict for surfaces that only carry MCP tool calls: no host capabilities at all. */
+export declare function mcpVerdict(operation: Operation): Verdict;
+/** Verdict for skills hosts: non-portable operations are bridged by the agent driving the host's own tools. */
+/** A CLI has a human at the terminal, so user-input is native there; other host capabilities are not. */
+export declare function cliVerdict(operation: Operation): Verdict;
+/** A skill never executes: the agent drives the CLI or MCP server, so everything it can reach is bridged. */
+export declare function skillVerdict(operation: Operation): Verdict;
+export declare function configProperties(project: Project): Record<string, Record<string, unknown>>;
+export declare function isSensitive(property: Record<string, unknown>): boolean;
+export declare function requiredConfig(project: Project): string[];
+/** The environment variable a config key is read from, on every surface and in every environment. */
+export declare function envName(key: string): string;
+/**
+ * Environment variable a host-native shim reads to find the tool's checkout when the host
+ * copied the plugin elsewhere (Hermes' doctor, OpenClaw's extensions directory).
+ */
+export declare function rootEnvName(project: Project): string;
+/**
+ * The environment variable a host passes the tool's per-instance data directory
+ * (caches, session state) through, on every surface. The kernel falls back to an
+ * XDG-style default when it is unset.
+ */
+export declare function dataDirEnvName(project: Project): string;
+/**
+ * The credentials a live run needs: every config key that is both `required` and sensitive.
+ * A tool with none has nothing to gate a live tier on, so no live test and no `live` CI job.
+ */
+export declare function liveCredentials(project: Project): string[];
+/**
+ * The operation the generated example test calls: the first one with arguments in
+ * `tool.json` `tests.examples`, else the first operation with no arguments.
+ */
+export declare function liveExample(project: Project): {
+    name: string;
+    args: Record<string, unknown>;
+} | undefined;