toolfactory 0.1.1 → 0.2.0

package/dist/surfaces/distribution.test.js

@@ -1,8 +1,12 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 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 { MCP_NAME_BEGIN, MCP_NAME_END, surface as pypi } 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 = {}) {
@@ -47,14 +51,123 @@ describe("npm", () => {
         });
         expect(npm.validate?.(project(["npm"])).map((command) => command.args.join(" "))).toContain("--yes publint --strict");
     });
+    it("makes a Python npm package a thin uvx launcher for its canonical PyPI distribution", () => {
+        const python = project(["npm", "pypi", "cli", "mcp"], {
+            tool: { ...project([]).tool, binding: "python", surfaces: ["npm", "pypi", "cli", "mcp"] },
+        });
+        const files = npm.plan(python);
+        const launcher = files.find((file) => file.path === "bin/hello.mjs");
+        const packageJson = files.find((file) => file.path === "package.json");
+        if (launcher?.kind !== "file" || packageJson?.kind !== "merge") {
+            throw new Error("expected a launcher and package metadata");
+        }
+        expect(launcher.content).toContain('spawnSync("uvx", ["--from", "hello==0.1.0", "hello"');
+        expect(launcher.content).toContain("...process.argv.slice(2)");
+        expect(packageJson.patch).toMatchObject({
+            name: "hello",
+            version: "0.1.0",
+            bin: { hello: "./bin/hello.mjs" },
+            files: ["bin", "README.md", "LICENSE"],
+        });
+        expect(region(python)).toContain("requires `uv`, and `hello` delegates to `uvx --from hello==0.1.0 hello`");
+    });
+    it("ships the built web page in Python's prebuilt wheel before release publication", () => {
+        const python = project(["pypi", "web"], {
+            tool: { ...project([]).tool, binding: "python", surfaces: ["pypi", "web"] },
+        });
+        const [file] = pypi.plan(python);
+        if (file?.kind !== "merge")
+            throw new Error("expected Python package metadata");
+        expect(file.patch).toMatchObject({
+            tool: {
+                hatch: {
+                    build: {
+                        artifacts: ["web/dist/**"],
+                        targets: {
+                            wheel: {
+                                "only-include": ["src/hello", "web/dist"],
+                                sources: { src: "", "web/dist": "hello/web" },
+                            },
+                        },
+                    },
+                },
+            },
+        });
+        expect(JSON.stringify(file.patch)).not.toContain("force-include");
+    });
+});
+const uv = spawnSync("uv", ["--version"], { encoding: "utf8" }).status === 0;
+describe.skipIf(!uv)("Python release source", () => {
+    it("stages the built page and metadata from the canonical sdist for a uv bundle", () => {
+        const root = mkdtempSync(join(tmpdir(), "toolfactory-python-sdist-"));
+        mkdirSync(join(root, "src", "hello"), { recursive: true });
+        mkdirSync(join(root, "web", "dist"), { recursive: true });
+        writeFileSync(join(root, "pyproject.toml"), `[project]
+name = "hello"
+version = "0.1.0"
+readme = "README.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+artifacts = ["web/dist/**"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hello"]
+only-include = ["src/hello", "web/dist"]
+
+[tool.hatch.build.targets.wheel.sources]
+src = ""
+"web/dist" = "hello/web"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["pyproject.toml", "README.md", "LICENSE", "src/hello", "web/dist"]
+`);
+        writeFileSync(join(root, "README.md"), "# hello\n");
+        writeFileSync(join(root, "LICENSE"), "MIT\n");
+        writeFileSync(join(root, ".gitignore"), "dist/\n");
+        writeFileSync(join(root, "src", "hello", "__init__.py"), "");
+        mkdirSync(join(root, "web", "dist", "assets"), { recursive: true });
+        writeFileSync(join(root, "web", "dist", "index.html"), '<link rel="stylesheet" href="assets/app.css"><script src="assets/app.js"></script>\n');
+        writeFileSync(join(root, "web", "dist", "assets", "app.css"), "main{color:#000}\n");
+        writeFileSync(join(root, "web", "dist", "assets", "app.js"), "console.log('hello')\n");
+        const build = spawnSync("uv", ["build", "--out-dir", "dist/release/pypi"], {
+            cwd: root,
+            encoding: "utf8",
+        });
+        expect(build.status, build.stderr).toBe(0);
+        const wheel = spawnSync("unzip", ["-l", join(root, "dist", "release", "pypi", "hello-0.1.0-py2.py3-none-any.whl")], { encoding: "utf8" });
+        expect(wheel.status, wheel.stderr).toBe(0);
+        expect(wheel.stdout).toContain("hello/web/assets/app.css");
+        expect(wheel.stdout).toContain("hello/web/assets/app.js");
+        const stage = join(root, "dist", "mcpb");
+        mkdirSync(stage, { recursive: true });
+        const extract = spawnSync("tar", [
+            "-xzf",
+            join(root, "dist", "release", "pypi", "hello-0.1.0.tar.gz"),
+            "-C",
+            stage,
+            "--strip-components=1",
+        ], { encoding: "utf8" });
+        expect(extract.status, extract.stderr).toBe(0);
+        const sync = spawnSync("uv", ["sync", "--quiet", "--no-dev"], { cwd: stage, encoding: "utf8" });
+        expect(sync.status, sync.stderr).toBe(0);
+        expect(existsSync(join(stage, "README.md"))).toBe(true);
+        expect(existsSync(join(stage, "LICENSE"))).toBe(true);
+        expect(existsSync(join(stage, "web", "dist", "index.html"))).toBe(true);
+        expect(existsSync(join(stage, "web", "dist", "assets", "app.css"))).toBe(true);
+        expect(existsSync(join(stage, "web", "dist", "assets", "app.js"))).toBe(true);
+    });
 });
 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({
+        if (file?.kind !== "merge")
+            throw new Error("expected a merge file");
+        expect(file.patch).toMatchObject({
             name: "hello",
             owner: { name: "GoatInAHat" },
             plugins: [{ name: "hello", source: "./", description: "Say hello" }],
@@ -91,12 +204,13 @@ describe("readme", () => {
         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.
+        // The extension's three channels — unpacked from a checkout, release assets (including an
+        // optional signed XPI), and 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("When Firefox signing credentials are configured, it also attaches a\n  Mozilla-signed `.xpi`");
+        expect(body).not.toContain("Chrome no longer keeps side-loaded unpacked");
         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", () => {

package/dist/surfaces/dsh.js

@@ -21,7 +21,7 @@
 import { Scalar, stringify as yamlStringify } from "yaml";
 import { getBinding } from "../bindings/index.js";
 import { projectName } from "../identity/name.js";
-import { compact, configProperties, envName, json, kernelLaunch, mcpVerdict } from "./shared.js";
+import { compact, configProperties, envName, kernelLaunch, mcpVerdict } from "./shared.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.
@@ -37,6 +37,8 @@ export const PATCH_FILE = "cordis.patch.yml";
  * passes to `dsh --patch` to drive the working tree.
  */
 export const LOCAL_PATCH_FILE = "cordis.local.patch.yml";
+const PATCH_BEGIN = "# tf:mcp";
+const PATCH_END = "# /tf:mcp";
 /** DSH's first-party MCP bridge; the only plugin the bundle names. */
 const MCP_CLIENT = "@deepseek-ai/dsh-mcp-client";
 /** `headless` is one-shot and ships an app bundle; a profile without one blocks forever. */
@@ -64,7 +66,10 @@ function patch(project, launch) {
     const serverName = projectName.dshServer(project.identity.name);
     const env = Object.fromEntries(Object.keys(configProperties(project)).map((key) => [
         envName(key),
-        jsExpression(`process.env.${envName(key)}`),
+        // Schemastery's dict rejects the empty object produced when every `!!js`
+        // value resolves to undefined. Keep every declared key string-valued;
+        // an absent optional credential remains the empty string for the child.
+        jsExpression(`process.env.${envName(key)} ?? ""`),
     ]));
     const row = {
         id: rowId(project),
@@ -79,6 +84,9 @@ function patch(project, launch) {
     };
     return yamlStringify([{ insert: [row] }], { lineWidth: 0 });
 }
+function patchTemplate() {
+    return `${PATCH_BEGIN}\n${PATCH_END}\n\n# Yours: add Cordis rows or local code configuration below this marker.\n`;
+}
 /** The public name a bridged MCP tool takes in DSH; `mcp__<serverName>__<rawName>` is its contract. */
 export function toolName(project, operation) {
     return `mcp__${projectName.dshServer(project.identity.name)}__${operation}`;
@@ -105,20 +113,34 @@ export const surface = {
             dsh: { bundle: { patch: `./${PATCH_FILE}` } },
         });
         return [
-            { kind: "file", path: `${HOST_DIR}/package.json`, content: json(manifest) },
+            { kind: "merge", path: `${HOST_DIR}/package.json`, format: "json", patch: manifest },
             {
-                kind: "file",
+                kind: "region",
                 path: `${HOST_DIR}/${PATCH_FILE}`,
                 // `cwd` is deliberately absent: an installed bundle has no path to point at, and the
                 // published launch resolves through the registry from wherever DSH is running.
-                content: patch(project, kernelLaunch(project, ".")),
+                regions: [
+                    {
+                        begin: PATCH_BEGIN,
+                        end: PATCH_END,
+                        content: patch(project, kernelLaunch(project, ".")),
+                    },
+                ],
+                template: patchTemplate(),
             },
             {
-                kind: "file",
+                kind: "region",
                 path: `${HOST_DIR}/${LOCAL_PATCH_FILE}`,
                 // The kernel as `introspect` and `inspector.json` spawn it: repo-relative, so it resolves
                 // against the directory DSH itself was started in.
-                content: patch(project, getBinding(project.tool.binding).kernelCommand(project)),
+                regions: [
+                    {
+                        begin: PATCH_BEGIN,
+                        end: PATCH_END,
+                        content: patch(project, getBinding(project.tool.binding).kernelCommand(project)),
+                    },
+                ],
+                template: patchTemplate(),
             },
         ];
     },

package/dist/surfaces/dsh.test.js

@@ -31,9 +31,14 @@ const project = {
     packageManager: "npm",
 };
 const files = Object.fromEntries(dsh.plan(project).map((file) => {
-    if (file.kind !== "file")
-        throw new Error("expected whole files only");
-    return [file.path, file.content];
+    return [
+        file.path,
+        file.kind === "file"
+            ? file.content
+            : file.kind === "merge"
+                ? JSON.stringify(file.patch)
+                : file.regions.map((region) => region.content).join(""),
+    ];
 }));
 describe("dsh", () => {
     it("is two shipped files and no code: the bundle manifest and one mcp-client insert row", () => {
@@ -61,8 +66,8 @@ describe("dsh", () => {
                             command: "npx",
                             args: ["-y", "hello.tool@0.1.0", "mcp"],
                             env: {
-                                APIKEY: "process.env.APIKEY",
-                                REGION: "process.env.REGION",
+                                APIKEY: 'process.env.APIKEY ?? ""',
+                                REGION: 'process.env.REGION ?? ""',
                             },
                             failOnStartupError: true,
                         },
@@ -72,7 +77,7 @@ describe("dsh", () => {
         ]);
         // DSH scrubs KEY/PASSWORD/SECRET/TOKEN names before spawning, so every config variable is
         // restated as the `!!js` expression DSH evaluates when it loads the patch.
-        expect(patch).toContain("APIKEY: !!js process.env.APIKEY");
+        expect(patch).toContain('APIKEY: !!js process.env.APIKEY ?? ""');
     });
     it("validates by booting the checkout keylessly, and carries only MCP tool calls", () => {
         // The local row is the same shape against this working tree, and stays out of `files`.

package/dist/surfaces/gemini.js

@@ -19,7 +19,7 @@
  */
 import { projectName } from "../identity/name.js";
 import { AGENTS_PATH } from "./agents.js";
-import { compact, configProperties, envName, isSensitive, json, kernelLaunch, mcpVerdict, } from "./shared.js";
+import { compact, configProperties, envName, isSensitive, kernelLaunch, mcpVerdict, } from "./shared.js";
 export const MANIFEST_PATH = "gemini-extension.json";
 /**
  * The `@google/gemini-cli` release `validate()` runs. Pinned so the gate is reproducible;
@@ -48,7 +48,7 @@ export const surface = {
             contextFileName: AGENTS_PATH,
             settings: settings.length ? settings : undefined,
         });
-        return [{ kind: "file", path: MANIFEST_PATH, content: json(manifest) }];
+        return [{ kind: "merge", path: MANIFEST_PATH, format: "json", patch: manifest }];
     },
     validate(project) {
         // Gemini's own manifest validator: it parses the manifest, enforces the name and version

package/dist/surfaces/gemini.test.js

@@ -30,9 +30,9 @@ const project = {
     packageManager: "npm",
 };
 const [manifestFile, ...rest] = gemini.plan(project);
-if (manifestFile?.kind !== "file")
-    throw new Error("expected one whole file");
-const manifest = JSON.parse(manifestFile.content);
+if (manifestFile?.kind !== "merge")
+    throw new Error("expected one merge file");
+const manifest = manifestFile.patch;
 describe("gemini", () => {
     it("is one root manifest: a dashed name, the kernel launch, AGENTS.md as the context file", () => {
         expect(rest).toEqual([]);
@@ -54,7 +54,7 @@ describe("gemini", () => {
             ],
         });
         // `skills/` and `commands/` are auto-discovered from the extension root; no key names them.
-        expect(manifestFile.content).not.toContain('"skills"');
+        expect(JSON.stringify(manifestFile.patch)).not.toContain('"skills"');
     });
     it("validates through Gemini's own manifest validator, and carries only MCP tool calls", () => {
         expect(gemini.validate?.(project)).toEqual([

package/dist/surfaces/hermes-native.js

@@ -25,13 +25,11 @@
  * support. The fake-ctx test gets the same behavioural coverage with no Hermes import at all.
  */
 import { join } from "node:path";
-import { stringify as toml } from "smol-toml";
-import { stringify as yaml } from "yaml";
 import { KERNEL_DIR } from "../bindings/typescript.js";
 import { projectName } from "../identity/name.js";
 import { isPortable } from "../model.js";
 import { includedOperations } from "../report/coverage.js";
-import { compact, configProperties, dataDirEnvName, envName, isSensitive, pypiName, requiredConfig, rootEnvName, } from "./shared.js";
+import { compact, configProperties, dataDirEnvName, envName, has, isSensitive, pypiName, requiredConfig, rootEnvName, } from "./shared.js";
 export const HOST_DIR = "hosts/hermes";
 /**
  * `hermes_cli/plugins.py` `SUPPORTED_MANIFEST_VERSION` is 2 and the loader parses every field
@@ -57,6 +55,8 @@ export function hermesInstall() {
     return `curl -fsSL ${HERMES_PIN.installer} | bash -s -- --commit ${HERMES_PIN.commit} --skip-setup --skip-browser --skip-computer-use --non-interactive --no-skills`;
 }
 const HEADER = "# Generated by toolfactory. Do not edit; run `toolfactory build` to regenerate.\n";
+const INIT_BEGIN = "# tf:init";
+const INIT_END = "# /tf:init";
 /**
  * The plugin package. It is a sibling of the author's own package rather than part of it: a
  * Hermes directory plugin *is* a Python package, and the two must be importable side by side.
@@ -243,7 +243,7 @@ function manifest(project, operations) {
         optional_env: optional.length ? optional : undefined,
         python_dependencies: core ? [core] : undefined,
     });
-    return `${HEADER}${yaml(document)}`;
+    return document;
 }
 function pyproject(project) {
     const core = pinnedCore(project) ?? pypiName(project);
@@ -270,7 +270,7 @@ function pyproject(project) {
                 : undefined,
         }),
     });
-    return `${toml(document)}\n`;
+    return document;
 }
 /** isort order: plain `import` before `from`, alphabetical within each. */
 function sortImports(lines) {
@@ -287,14 +287,16 @@ function importBlock(core) {
 /** Python core: the handler calls the author's own operation in-process. */
 function pythonCore(project) {
     const pkg = projectName.pythonPackage(project.identity.name);
+    const web = has(project, "web");
     return {
         stdlib: ["import asyncio", "import inspect"],
         external: [
             "from pydantic import BaseModel",
-            `from ${pkg}.ops import OPERATIONS`,
+            `from ${pkg}.ops import OPERATIONS${web ? " as AUTHORED_OPERATIONS" : ""}`,
             `from ${pkg}.toolfactory.config import context`,
+            ...(web ? [`from ${pkg}.toolfactory.web import OPERATION as WEB_OPERATION`] : []),
         ],
-        body: `def _operation(name: str) -> Any:
+        body: `${web ? "OPERATIONS = [*AUTHORED_OPERATIONS, WEB_OPERATION]\n\n\n" : ""}def _operation(name: str) -> Any:
     """Fail loudly if the core package and this plugin disagree on the operations."""
     for operation in OPERATIONS:
         if operation.name == name:
@@ -355,7 +357,7 @@ def _handler(name: str) -> Callable[..., str]:
     return call`,
     };
 }
-function initPy(project, operations) {
+function initRegion(project, operations) {
     const core = project.tool.binding === "python" ? pythonCore(project) : typescriptCore(project);
     const names = envDeclarations(project).required.map((entry) => entry.name);
     return `${HEADER}"""Hermes plugin for ${project.identity.name}, registered through PluginContext.
@@ -383,7 +385,7 @@ def _ready() -> bool:
 ${core.body}
 
 
-def register(ctx: Any) -> None:
+def _register_generated(ctx: Any) -> None:
     # Hermes' own per-plugin data directory, through the variable every host uses.
     os.environ.setdefault(${JSON.stringify(dataDirEnvName(project))}, str(ctx.state.data_dir))
     for schema in TOOLS:
@@ -396,6 +398,20 @@ def register(ctx: Any) -> None:
             requires_env=list(REQUIRES_ENV),
             description=schema["description"],
         )
+
+
+def register(ctx: Any) -> None:
+    _register_generated(ctx)
+    register_native(ctx)
+`;
+}
+function initTemplate() {
+    return `${INIT_BEGIN}${INIT_END}
+
+
+# Yours: use the full PluginContext here. This hook runs after Toolfactory's generated tools.
+def register_native(ctx: Any) -> None:
+    pass
 `;
 }
 function readme(project, operations) {
@@ -472,9 +488,24 @@ export const surface = {
         const operations = includedOperations(project, surface);
         const dir = pluginDir(project);
         return [
-            { kind: "file", path: `${dir}/plugin.yaml`, content: manifest(project, operations) },
-            { kind: "file", path: `${dir}/__init__.py`, content: initPy(project, operations) },
-            { kind: "file", path: `${HOST_DIR}/pyproject.toml`, content: pyproject(project) },
+            {
+                kind: "merge",
+                path: `${dir}/plugin.yaml`,
+                format: "yaml",
+                patch: manifest(project, operations),
+            },
+            {
+                kind: "region",
+                path: `${dir}/__init__.py`,
+                regions: [{ begin: INIT_BEGIN, end: INIT_END, content: initRegion(project, operations) }],
+                template: initTemplate(),
+            },
+            {
+                kind: "merge",
+                path: `${HOST_DIR}/pyproject.toml`,
+                format: "toml",
+                patch: pyproject(project),
+            },
             { kind: "file", path: `${HOST_DIR}/README.md`, content: readme(project, operations) },
             {
                 kind: "file",

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

@@ -1,10 +1,11 @@
 import { execFileSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { parse as parseToml } from "smol-toml";
+import { join } from "node:path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { describe, expect, it } from "vitest";
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { apply } from "../project/apply.js";
 import { HOST_DIR, pluginDir, surface } from "./hermes-native.js";
 const echo = {
     name: "echo",
@@ -19,6 +20,12 @@ const echo = {
     requires: [],
 };
 const shoot = { name: "shoot", inputSchema: { type: "object" }, requires: ["browser"] };
+const web = {
+    name: "web",
+    description: "Open the generated operations page.",
+    inputSchema: { type: "object" },
+    requires: [],
+};
 function project(overrides = {}) {
     return {
         root: "/repo",
@@ -50,10 +57,35 @@ function project(overrides = {}) {
     };
 }
 function emitted(target) {
-    return Object.fromEntries(surface.plan(target).map((file) => [file.path, file.kind === "file" ? file.content : ""]));
+    return Object.fromEntries(surface
+        .plan(target)
+        .map((file) => [
+        file.path,
+        file.kind === "file"
+            ? file.content
+            : file.kind === "merge"
+                ? file.format === "yaml"
+                    ? stringifyYaml(file.patch)
+                    : file.format === "toml"
+                        ? stringifyToml(file.patch)
+                        : JSON.stringify(file.patch)
+                : file.regions.map((region) => region.content).join(""),
+    ]));
 }
 const python = project({ tool: { ...project().tool, binding: "python" } });
 describe("hermes-native", () => {
+    it("keeps native registrations in the author hook while refreshing generated registrations", () => {
+        const root = mkdtempSync(join(tmpdir(), "toolfactory-hermes-region-"));
+        const target = { ...project(), root };
+        apply(root, surface.plan(target), "0.1.0");
+        const path = join(root, pluginDir(target), "__init__.py");
+        writeFileSync(path, readFileSync(path, "utf8").replace("    pass\n", '    ctx.register_tool(name="native", toolset="native", schema={}, handler=lambda _: "{}")\n'));
+        apply(root, surface.plan({ ...target, operations: [echo] }), "0.1.0");
+        const text = readFileSync(path, "utf8");
+        expect(text).toContain('name="native"');
+        expect(text).toContain("def _register_generated(ctx: Any)");
+        expect(text).toContain("_register_generated(ctx)\n    register_native(ctx)");
+    });
     it("projects the manifest Hermes parses and the credentials it prompts for", () => {
         const files = emitted(project());
         const manifest = parseYaml(files[`${pluginDir(project())}/plugin.yaml`] ?? "");
@@ -104,6 +136,21 @@ describe("hermes-native", () => {
         expect(pyproject.project.dependencies).toEqual(["hello>=1.2.0,<2"]);
         expect(pyproject.tool.uv.sources.hello).toEqual({ path: "../..", editable: true });
     });
+    it("gives a Python Hermes plugin the generated web operation used by its tool schema", () => {
+        const target = project({
+            tool: {
+                ...project().tool,
+                binding: "python",
+                surfaces: ["hermes-native", "cli", "mcp", "web"],
+            },
+            operations: [echo, web],
+        });
+        const native = emitted(target)[`${pluginDir(target)}/__init__.py`] ?? "";
+        expect(native).toContain("from hello.ops import OPERATIONS as AUTHORED_OPERATIONS");
+        expect(native).toContain("from hello.toolfactory.web import OPERATION as WEB_OPERATION");
+        expect(native).toContain("OPERATIONS = [*AUTHORED_OPERATIONS, WEB_OPERATION]");
+        expect(native).toContain('handler=_handler(schema["name"])');
+    });
     it("emits a fake-ctx test that registers and calls a real handler, no Hermes import", () => {
         const shim = emitted(project())[`${HOST_DIR}/tests/test_plugin.py`] ?? "";
         expect(shim).not.toMatch(/^\s*(import|from) hermes/m);
@@ -136,12 +183,7 @@ describe.skipIf(!hasHermes())("hermes plugins doctor", () => {
     it("loads and registers the generated plugin", () => {
         const root = mkdtempSync(join(tmpdir(), "toolfactory-hermes-"));
         try {
-            for (const file of surface.plan(project())) {
-                if (file.kind !== "file")
-                    continue;
-                mkdirSync(dirname(join(root, file.path)), { recursive: true });
-                writeFileSync(join(root, file.path), file.content);
-            }
+            apply(root, surface.plan(project()), "0.1.0");
             const commands = surface.validate?.({ ...project(), root }) ?? [];
             const command = commands.find((c) => c.label === "hermes plugins doctor");
             if (!command)

package/dist/surfaces/mcp-registry.js

@@ -7,6 +7,7 @@ import { pythonPackage } from "../bindings/python.js";
 import { KERNEL_DIR } from "../bindings/typescript.js";
 import { githubOwner, projectName } from "../identity/name.js";
 import { compact, configProperties, envName, has, isSensitive, json, npmName, pypiName, requiredConfig, } from "./shared.js";
+import { WEB_DIR } from "./web.js";
 export const SERVER_SCHEMA_ID = "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json";
 /** `owner` from the identity file's GitHub repository, or the error every registry name needs it for. */
 function requireGithubOwner(identity) {
@@ -62,6 +63,42 @@ const DOCKER_PACKAGE_MANAGERS = {
         prune: "pnpm prune --prod",
     },
 };
+const DOCKERIGNORE_BEGIN = "# tf:dockerignore";
+const DOCKERIGNORE_END = "# /tf:dockerignore";
+/** Build context hygiene is generated, while the rest of `.dockerignore` stays author-owned. */
+function dockerignore() {
+    return {
+        kind: "region",
+        path: ".dockerignore",
+        regions: [
+            {
+                begin: DOCKERIGNORE_BEGIN,
+                end: DOCKERIGNORE_END,
+                content: `
+.git/
+.env
+.env.*
+!.env.example
+node_modules/
+**/node_modules/
+.venv/
+**/.venv/
+dist/
+coverage/
+test-results/
+playwright-report/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+**/__pycache__/
+.vscode-test/
+`,
+            },
+        ],
+        template: `${DOCKERIGNORE_BEGIN}\n${DOCKERIGNORE_END}\n\n# Add local build inputs to exclude below.\n`,
+    };
+}
 /**
  * The root `Dockerfile`, stdio only (§4.1: no `--host` flag exists to bind past loopback), one
  * multi-stage build per binding. `label` is `server.json`'s own `name`, byte for byte — the MCP
@@ -69,20 +106,34 @@ const DOCKER_PACKAGE_MANAGERS = {
  */
 export function dockerfileTemplate(project, label) {
     if (project.tool.binding === "python") {
+        const web = has(project, "web");
         return `# syntax=docker/dockerfile:1
-FROM ${UV_IMAGE} AS build
+${web
+            ? `FROM ${NODE_IMAGE} AS web
+WORKDIR /app
+COPY web/package.json web/package-lock.json ./web/
+RUN npm -C web ci
+COPY web ./web
+RUN npm -C web run build
+
+`
+            : ""}FROM ${UV_IMAGE} AS build
 WORKDIR /app
-COPY pyproject.toml ./
-COPY src ./src
-RUN uv sync --no-dev
+# pyproject metadata can name README, license, and other package assets; copy the project without
+# assuming optional metadata files exist.
+COPY . .
+${web ? "COPY --from=web /app/web/dist ./web/dist\n" : ""}RUN uv sync --no-dev
+RUN mkdir /app/runtime && cp pyproject.toml /app/runtime/ && cp -R src /app/runtime/src && for path in README README.md README.rst LICENSE LICENSE.md LICENSE.txt NOTICE NOTICE.md NOTICE.txt; do if [ -f "$path" ]; then cp "$path" /app/runtime/; fi; done
 
 FROM ${PYTHON_IMAGE}
 LABEL io.modelcontextprotocol.server.name="${label}"
 WORKDIR /app
 COPY --from=build /app/.venv ./.venv
-COPY --from=build /app/src ./src
-COPY --from=build /app/pyproject.toml ./
-ENV PATH="/app/.venv/bin:$PATH"
+COPY --from=build /app/runtime/ ./
+${web
+            ? `COPY --from=web /app/web/dist ./src/${pythonPackage(project)}/${WEB_DIR}
+`
+            : ""}ENV PATH="/app/.venv/bin:$PATH"
 ENTRYPOINT ${JSON.stringify(dockerEntrypoint(project))}
 `;
     }
@@ -155,6 +206,7 @@ export const surface = {
         return [
             { kind: "file", path: "server.json", content: json(server) },
             { kind: "file", path: "Dockerfile", content: dockerfileTemplate(project, name) },
+            dockerignore(),
         ];
     },
 };