toolfactory 0.1.1 → 0.2.0

package/src/surfaces/distribution.test.ts

@@ -1,9 +1,13 @@
+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 type { Operation, Project, SurfaceId } from "../model.js";
 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: Operation = { name: "echo", inputSchema: { type: "object" }, requires: [] };
@@ -52,14 +56,142 @@ describe("npm", () => {
       "--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" }],
@@ -103,14 +235,17 @@ describe("readme", () => {
     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`");
   });
 

package/src/surfaces/dsh.test.ts

@@ -36,8 +36,14 @@ const project: Project = {
 
 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(""),
+    ];
   }),
 );
 
@@ -68,8 +74,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,
             },
@@ -79,7 +85,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", () => {

package/src/surfaces/dsh.ts

@@ -22,7 +22,7 @@ import { Scalar, stringify as yamlStringify } from "yaml";
 import { getBinding } from "../bindings/index.js";
 import { projectName } from "../identity/name.js";
 import type { Project, Surface } from "../model.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
@@ -40,6 +40,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";
@@ -71,7 +73,10 @@ function patch(project: Project, launch: { command: string; args: string[] }): s
   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 = {
@@ -88,6 +93,10 @@ function patch(project: Project, launch: { command: string; args: string[] }): s
   return yamlStringify([{ insert: [row] }], { lineWidth: 0 });
 }
 
+function patchTemplate(): string {
+  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: Project, operation: string): string {
   return `mcp__${projectName.dshServer(project.identity.name)}__${operation}`;
@@ -117,20 +126,34 @@ export const surface: 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/src/surfaces/gemini.test.ts

@@ -34,8 +34,8 @@ const project: Project = {
 };
 
 const [manifestFile, ...rest] = gemini.plan(project);
-if (manifestFile?.kind !== "file") throw new Error("expected one whole file");
-const manifest = JSON.parse(manifestFile.content) as Record<string, unknown>;
+if (manifestFile?.kind !== "merge") throw new Error("expected one merge file");
+const manifest = manifestFile.patch as Record<string, unknown>;
 
 describe("gemini", () => {
   it("is one root manifest: a dashed name, the kernel launch, AGENTS.md as the context file", () => {
@@ -58,7 +58,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", () => {

package/src/surfaces/gemini.ts

@@ -26,7 +26,6 @@ import {
   configProperties,
   envName,
   isSensitive,
-  json,
   kernelLaunch,
   mcpVerdict,
 } from "./shared.js";
@@ -64,7 +63,7 @@ export const surface: 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/src/surfaces/hermes-native.test.ts

@@ -1,11 +1,12 @@
 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 type { Operation, Project } from "../model.js";
+import { apply } from "../project/apply.js";
 import { HOST_DIR, pluginDir, surface } from "./hermes-native.js";
 
 const echo: Operation = {
@@ -21,6 +22,12 @@ const echo: Operation = {
   requires: [],
 };
 const shoot: Operation = { name: "shoot", inputSchema: { type: "object" }, requires: ["browser"] };
+const web: Operation = {
+  name: "web",
+  description: "Open the generated operations page.",
+  inputSchema: { type: "object" },
+  requires: [],
+};
 
 function project(overrides: Partial<Project> = {}): Project {
   return {
@@ -55,13 +62,45 @@ function project(overrides: Partial<Project> = {}): Project {
 
 function emitted(target: Project): Record<string, string> {
   return Object.fromEntries(
-    surface.plan(target).map((file) => [file.path, file.kind === "file" ? file.content : ""]),
+    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`] ?? "") as Record<
@@ -128,6 +167,22 @@ describe("hermes-native", () => {
     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);
@@ -162,11 +217,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) throw new Error("the hermes surface no longer declares a doctor validator");

package/src/surfaces/hermes-native.ts

@@ -25,8 +25,6 @@
  * 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, type Operation, type Project, type Surface, type Verdict } from "../model.js";
@@ -36,6 +34,7 @@ import {
   configProperties,
   dataDirEnvName,
   envName,
+  has,
   isSensitive,
   pypiName,
   requiredConfig,
@@ -71,6 +70,8 @@ export function hermesInstall(): string {
 }
 
 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
@@ -250,7 +251,7 @@ def test_register_adds_every_declared_tool() -> None:
 `;
 }
 
-function manifest(project: Project, operations: Operation[]): string {
+function manifest(project: Project, operations: Operation[]): Record<string, unknown> {
   const { identity } = project;
   const { required, optional } = envDeclarations(project);
   const shim = project.tool.binding !== "python";
@@ -277,10 +278,10 @@ function manifest(project: Project, operations: Operation[]): string {
     optional_env: optional.length ? optional : undefined,
     python_dependencies: core ? [core] : undefined,
   });
-  return `${HEADER}${yaml(document)}`;
+  return document as Record<string, unknown>;
 }
 
-function pyproject(project: Project): string {
+function pyproject(project: Project): Record<string, unknown> {
   const core = pinnedCore(project) ?? pypiName(project);
   const python = project.tool.binding === "python";
   const document = compact({
@@ -305,7 +306,7 @@ function pyproject(project: Project): string {
         : undefined,
     }),
   });
-  return `${toml(document)}\n`;
+  return document as Record<string, unknown>;
 }
 
 /** isort order: plain `import` before `from`, alphabetical within each. */
@@ -333,14 +334,16 @@ interface PluginCore {
 /** Python core: the handler calls the author's own operation in-process. */
 function pythonCore(project: Project): PluginCore {
   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:
@@ -403,7 +406,7 @@ def _handler(name: str) -> Callable[..., str]:
   };
 }
 
-function initPy(project: Project, operations: Operation[]): string {
+function initRegion(project: Project, operations: Operation[]): string {
   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.
@@ -431,7 +434,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:
@@ -444,6 +447,21 @@ 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(): string {
+  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
 `;
 }
 
@@ -549,9 +567,24 @@ export const surface: 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/src/surfaces/mcp-registry.test.ts

@@ -65,6 +65,34 @@ describe("mcp-registry Dockerfile", () => {
 
     const py = files(project({ tool: { ...project().tool, binding: "python" } }));
     expect(py.Dockerfile).toContain('ENTRYPOINT ["python","-m","hello.toolfactory.mcp"]');
+    expect(py.Dockerfile).toContain("COPY . .\nRUN uv sync --no-dev");
+    expect(py.Dockerfile).not.toContain("COPY pyproject.toml ./");
+    expect(py.Dockerfile).toContain(
+      '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',
+    );
+    expect(py.Dockerfile).toContain("COPY --from=build /app/runtime/ ./");
+    expect(py.Dockerfile).not.toContain("COPY --from=build /app .");
+
+    const pythonWeb = files(
+      project({
+        tool: { ...project().tool, binding: "python", surfaces: ["mcp-registry", "web"] },
+      }),
+    );
+    expect(pythonWeb.Dockerfile).toContain("FROM node:24-alpine AS web");
+    expect(pythonWeb.Dockerfile).toContain("COPY --from=web /app/web/dist ./src/hello/web");
+  });
+
+  it("ships an author-extensible Docker ignore region without excluding source metadata", () => {
+    const ignore = surface.plan(project()).find((file) => file.path === ".dockerignore");
+    if (ignore?.kind !== "region") throw new Error("expected a Docker ignore region");
+    expect(ignore.template).toContain("# tf:dockerignore\n# /tf:dockerignore");
+    expect(ignore.regions[0]?.content).toContain(".git/");
+    expect(ignore.regions[0]?.content).toContain(".env.*");
+    expect(ignore.regions[0]?.content).toContain("!.env.example");
+    expect(ignore.regions[0]?.content).toContain("**/node_modules/");
+    expect(ignore.regions[0]?.content).toContain("**/.venv/");
+    expect(ignore.regions[0]?.content).not.toContain("README");
+    expect(ignore.regions[0]?.content).not.toContain("web/");
   });
 });