toolfactory 0.1.1 → 0.2.0

package/dist/surfaces/mcp-registry.test.js

@@ -52,6 +52,29 @@ describe("mcp-registry Dockerfile", () => {
         expect(npmBuilt.Dockerfile).not.toContain("corepack enable");
         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/");
     });
 });
 describe("mcp-registry server.json oci package", () => {

package/dist/surfaces/mcpb.d.ts

@@ -8,4 +8,5 @@ export declare const MANIFEST_PATH = "hosts/mcpb/manifest.json";
 export declare const MCPB_PIN = "2.1.2";
 /** What `mcpb init` writes for a new bundle, and the floor the directory submission requires. */
 export declare const MANIFEST_VERSION = "0.2";
+export declare const UV_MANIFEST_VERSION = "0.4";
 export declare const surface: Surface;

package/dist/surfaces/mcpb.js

@@ -3,21 +3,21 @@
  * Anthropic's Connectors Directory takes a *local* server through.
  *
  * A bundle is a zip whose root is the server plus its dependencies plus a `manifest.json`. That
- * root is a staging tree, not the repository: the payload is exactly the npm tarball with
- * production dependencies installed into it, which `src/project/gate.ts` builds under
- * `dist/mcpb/` at package time. So this surface emits one tracked file — the manifest — and the
- * packaging step copies it in; nothing here duplicates what `npm pack` already decides ships.
+ * root is a staging tree, not the repository: TypeScript stages the npm tarball with production
+ * dependencies, while Python stages its `pyproject.toml` and source for host-managed uv. This
+ * surface emits one tracked file — the manifest — and the packaging step copies it in.
  *
- * `manifest_version` is `0.2`, which is what `mcpb init` itself writes for a new bundle (0.3 and
- * 0.4 exist, and add icon variants, localization and the `uv` server type — none of which this
- * projection uses) and the floor Anthropic's directory submission requires.
+ * TypeScript uses `manifest_version` `0.2`, the floor Anthropic's directory submission requires.
+ * Python uses v0.4's official `uv` server type, which keeps the bundle portable without shipping
+ * an interpreter or a virtual environment.
  *
  * `privacy_policies` (the URLs of the privacy policies of the services a bundle talks to, which
  * Anthropic's directory submission requires) comes from `tool.json` `mcpb.privacyPolicies`; a
  * homepage is not one, so nothing is invented when the key is absent.
  */
+import { kernelDir as pythonKernelDir, pythonPackage } from "../bindings/python.js";
 import { KERNEL_DIR, NODE_ENGINES } from "../bindings/typescript.js";
-import { compact, configProperties, envName, isSensitive, json, mcpVerdict } from "./shared.js";
+import { compact, configProperties, envName, has, isSensitive, json, mcpVerdict, } from "./shared.js";
 export const HOST_DIR = "hosts/mcpb";
 export const MANIFEST_PATH = `${HOST_DIR}/manifest.json`;
 /**
@@ -27,6 +27,7 @@ export const MANIFEST_PATH = `${HOST_DIR}/manifest.json`;
 export const MCPB_PIN = "2.1.2";
 /** What `mcpb init` writes for a new bundle, and the floor the directory submission requires. */
 export const MANIFEST_VERSION = "0.2";
+export const UV_MANIFEST_VERSION = "0.4";
 /**
  * The kernel's built `mcp` entry inside the bundle root — the same file the `mcp-registry`
  * surface's Dockerfile runs, because both start from the published package's `dist/`.
@@ -47,11 +48,9 @@ const USER_CONFIG_TYPES = new Set(["string", "number", "boolean"]);
 export const surface = {
     id: "mcpb",
     plan(project) {
-        if (project.tool.binding !== "typescript") {
-            // A python bundle would have to vendor an interpreter's site-packages into the bundle root
-            // (Claude Desktop ships Node, not Python), which `npm pack` plus `npm install` gives the
-            // TypeScript binding for free and `uv` gives no equivalent of.
-            throw new Error('Surface "mcpb" requires the typescript binding: a bundle root is the npm tarball with its production dependencies installed into it.');
+        const python = project.tool.binding === "python";
+        if (python && !has(project, "pypi")) {
+            throw new Error('Surface "mcpb" with the python binding requires the "pypi" surface, the canonical runtime distribution.');
         }
         const { identity } = project;
         const properties = configProperties(project);
@@ -70,7 +69,7 @@ export const surface = {
         // kernel reads its configuration from the same environment names it does everywhere else.
         const env = Object.fromEntries(Object.keys(properties).map((key) => [envName(key), `\${user_config.${key}}`]));
         const manifest = compact({
-            manifest_version: MANIFEST_VERSION,
+            manifest_version: python ? UV_MANIFEST_VERSION : MANIFEST_VERSION,
             name: identity.name,
             display_name: identity.name,
             version: identity.version,
@@ -83,15 +82,29 @@ export const surface = {
             privacy_policies: project.tool.mcpb?.privacyPolicies,
             keywords: identity.keywords,
             server: {
-                type: "node",
-                entry_point: entryPoint(),
+                type: python ? "uv" : "node",
+                entry_point: python ? `${pythonKernelDir(project)}/mcp.py` : entryPoint(),
                 // `${__dirname}` is the installed bundle's own directory: an install is an unzip
-                // somewhere else, so nothing in the launch may be repository-relative.
-                mcp_config: compact({
-                    command: "node",
-                    args: [`\${__dirname}/${entryPoint()}`],
-                    env: Object.keys(env).length ? env : undefined,
-                }),
+                // somewhere else, so nothing in the launch may be repository-relative. For `uv`, this
+                // delegates dependency resolution and Python provisioning to the host's supported runtime.
+                mcp_config: python
+                    ? compact({
+                        command: "uv",
+                        args: [
+                            "run",
+                            "--directory",
+                            "${__dirname}",
+                            "python",
+                            "-m",
+                            `${pythonPackage(project)}.toolfactory.mcp`,
+                        ],
+                        env: Object.keys(env).length ? env : undefined,
+                    })
+                    : compact({
+                        command: "node",
+                        args: [`\${__dirname}/${entryPoint()}`],
+                        env: Object.keys(env).length ? env : undefined,
+                    }),
             },
             // Exactly the operations the kernel's own `tools/list` serves (§4.3): the manifest is what
             // the install UI shows before the server ever runs, so it must not promise more.
@@ -99,7 +112,7 @@ export const surface = {
                 .filter((operation) => mcpVerdict(operation).kind !== "excluded")
                 .map((operation) => compact({ name: operation.name, description: operation.description })),
             user_config: userConfig.length ? Object.fromEntries(userConfig) : undefined,
-            compatibility: { runtimes: { node: NODE_ENGINES } },
+            compatibility: { runtimes: python ? { python: ">=3.11" } : { node: NODE_ENGINES } },
         });
         return [{ kind: "file", path: MANIFEST_PATH, content: json(manifest) }];
     },

package/dist/surfaces/mcpb.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { NODE_ENGINES } from "../bindings/typescript.js";
-import { MCPB_PIN, surface as mcpb } from "./mcpb.js";
+import { MCPB_PIN, surface as mcpb, UV_MANIFEST_VERSION } from "./mcpb.js";
 const echo = {
     name: "echo",
     description: "Echoes.",
@@ -90,8 +90,36 @@ describe("mcpb", () => {
         // No privacy_policies unless tool.json names them (see the module docs).
         expect(manifestFile.content).not.toContain("privacy_policies");
     });
-    it("declares the kernel's own Node floor, and refuses a binding whose package is not the bundle", () => {
-        expect(() => mcpb.plan({ ...project, tool: { ...project.tool, binding: "python" } })).toThrow(/requires the typescript binding/);
+    it("uses the official v0.4 uv bundle contract for Python, with its canonical PyPI surface", () => {
+        const pythonProject = {
+            ...project,
+            tool: { ...project.tool, binding: "python", surfaces: ["mcp", "pypi", "mcpb"] },
+        };
+        const [file] = mcpb.plan(pythonProject);
+        if (file?.kind !== "file")
+            throw new Error("expected one whole file");
+        expect(JSON.parse(file.content)).toMatchObject({
+            manifest_version: UV_MANIFEST_VERSION,
+            server: {
+                type: "uv",
+                entry_point: "src/hello_tool/toolfactory/mcp.py",
+                mcp_config: {
+                    command: "uv",
+                    args: [
+                        "run",
+                        "--directory",
+                        "${__dirname}",
+                        "python",
+                        "-m",
+                        "hello_tool.toolfactory.mcp",
+                    ],
+                },
+            },
+            compatibility: { runtimes: { python: ">=3.11" } },
+        });
+        expect(() => mcpb.plan({ ...pythonProject, tool: { ...pythonProject.tool, surfaces: ["mcp", "mcpb"] } })).toThrow(/requires the "pypi" surface/);
+    });
+    it("declares the kernel's own Node floor and validates with the pinned official CLI", () => {
         expect(mcpb.validate?.(project)).toEqual([
             {
                 label: "mcpb validate",

package/dist/surfaces/npm.js

@@ -4,7 +4,7 @@
  */
 import { githubSlug } from "../hosts/github.js";
 import { registryName } from "./mcp-registry.js";
-import { compact, has, npmName } from "./shared.js";
+import { compact, has, npmName, pypiName } from "./shared.js";
 import { WEB_DIR } from "./web.js";
 /**
  * npm's object form. A bare URL string is only valid as one of npm's shorthands, so `publint`
@@ -17,14 +17,30 @@ function repositoryField(repository) {
     const slug = githubSlug(repository);
     return { type: "git", url: slug ? `git+https://github.com/${slug}.git` : repository };
 }
+/**
+ * A deliberately thin cross-registry bridge: npm supplies discovery and a familiar `npx` entry,
+ * while uvx resolves the canonical Python distribution. `uvx` owns Python acquisition, caching,
+ * and the package install; the npm package never downloads an interpreter itself.
+ */
+function pythonLauncher(project) {
+    const { identity } = project;
+    return `#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+
+const child = spawnSync("uvx", ["--from", ${JSON.stringify(`${pypiName(project)}==${identity.version}`)}, ${JSON.stringify(identity.name)}, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+if (child.error) throw child.error;
+process.exit(child.status ?? 1);
+`;
+}
 export const surface = {
     id: "npm",
     plan(project) {
-        if (project.tool.binding !== "typescript") {
-            throw new Error('Surface "npm" requires the typescript binding.');
-        }
         const { identity } = project;
         const authored = project.tool.identity === "package.json";
+        const python = project.tool.binding === "python";
+        const launcher = `bin/${identity.name}.mjs`;
         const patch = compact({
             name: authored ? undefined : npmName(project),
             version: authored ? undefined : identity.version,
@@ -35,21 +51,36 @@ export const surface = {
             keywords: authored ? undefined : identity.keywords,
             type: "module",
             bin: has(project, "cli") || has(project, "mcp")
-                ? { [identity.name]: "./dist/toolfactory/cli.js" }
+                ? {
+                    [identity.name]: python ? `./${launcher}` : "./dist/toolfactory/cli.js",
+                }
                 : undefined,
             // `web/dist` only with the `web` surface: the kernel serves the built page from inside
             // the installed package, so `npx <tool> mcp --http --open` works without a checkout.
-            files: [
-                "dist",
-                "src",
-                "schemas",
-                ...(has(project, "web") ? [`${WEB_DIR}/dist`] : []),
-                "README.md",
-                "LICENSE",
-            ],
+            files: python
+                ? ["bin", "README.md", "LICENSE"]
+                : [
+                    "dist",
+                    "src",
+                    "schemas",
+                    ...(has(project, "web") ? [`${WEB_DIR}/dist`] : []),
+                    "README.md",
+                    "LICENSE",
+                ],
             mcpName: has(project, "mcp-registry") ? registryName(project) : undefined,
         });
-        return [{ kind: "merge", path: "package.json", format: "json", patch, owned: ["bin"] }];
+        return [
+            ...(python && (has(project, "cli") || has(project, "mcp"))
+                ? [{ kind: "file", path: launcher, content: pythonLauncher(project) }]
+                : []),
+            {
+                kind: "merge",
+                path: "package.json",
+                format: "json",
+                patch,
+                owned: ["bin", "files"],
+            },
+        ];
     },
     validate(project) {
         return [

package/dist/surfaces/openclaw-native.js

@@ -216,7 +216,7 @@ function packageJson(project, operations, kase) {
         : undefined;
     const extra = project.tool.openclaw;
     const e2e = kase ? { "test:e2e": OPENCLAW_ADDITIONS.e2eScript } : undefined;
-    return json(compact({
+    return compact({
         name: projectName.openclawPackage(project.identity.name),
         version: project.identity.version ?? "0.0.0",
         description: pluginDescription(project),
@@ -239,7 +239,7 @@ function packageJson(project, operations, kase) {
         pluginInspector: expectedRegistrations(project, operations).length
             ? pluginInspector(project, operations)
             : undefined,
-    }));
+    });
 }
 /**
  * `openclaw plugins build` regenerates this file; emitting it keeps `--check` green from a clean
@@ -256,7 +256,7 @@ function pluginManifest(project, operations) {
         registration.contract,
         registration.ids,
     ]);
-    return json(compact({
+    return compact({
         id: project.identity.name,
         name: displayName(project.identity.name),
         description: pluginDescription(project),
@@ -268,7 +268,7 @@ function pluginManifest(project, operations) {
             tools: operations.map((operation) => operation.name),
             ...Object.fromEntries(declared),
         },
-    }));
+    });
 }
 function executeBody(project, operation) {
     if (project.tool.binding === "typescript") {
@@ -819,9 +819,10 @@ export const surface = {
         const kase = e2eCase(project, operations);
         return [
             {
-                kind: "file",
+                kind: "merge",
                 path: `${HOST_DIR}/package.json`,
-                content: packageJson(project, operations, kase),
+                format: "json",
+                patch: packageJson(project, operations, kase),
             },
             {
                 kind: "file",
@@ -841,9 +842,10 @@ export const surface = {
                 content: OPENCLAW_SCAFFOLD.vitestConfig,
             },
             {
-                kind: "file",
+                kind: "merge",
                 path: `${HOST_DIR}/openclaw.plugin.json`,
-                content: pluginManifest(project, operations),
+                format: "json",
+                patch: pluginManifest(project, operations),
             },
             {
                 kind: "region",

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

@@ -1,6 +1,10 @@
 import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { scaffoldDrift } from "../hosts/openclaw.js";
+import { apply } from "../project/apply.js";
 import { computeCoverage, renderCoverageMarkdown } from "../report/coverage.js";
 import { HOST_DIR, OPENCLAW_ADDITIONS, OPENCLAW_SCAFFOLD, surface } from "./openclaw-native.js";
 const echo = {
@@ -74,6 +78,32 @@ function emitted(target) {
     ]));
 }
 describe("openclaw-native", () => {
+    it("keeps hand-authored package and manifest extensions through regeneration", () => {
+        const root = mkdtempSync(join(tmpdir(), "toolfactory-openclaw-"));
+        const target = { ...project(), root };
+        apply(root, surface.plan(target), "0.1.0");
+        const packagePath = join(root, HOST_DIR, "package.json");
+        const manifestPath = join(root, HOST_DIR, "openclaw.plugin.json");
+        writeFileSync(packagePath, JSON.stringify({
+            ...JSON.parse(readFileSync(packagePath, "utf8")),
+            scripts: { custom: "node custom.mjs" },
+            exports: { "./native": "./src/native.ts" },
+        }));
+        writeFileSync(manifestPath, JSON.stringify({
+            ...JSON.parse(readFileSync(manifestPath, "utf8")),
+            contracts: { customProviders: ["native"] },
+            nativeField: true,
+        }));
+        apply(root, surface.plan(target), "0.1.0");
+        expect(JSON.parse(readFileSync(packagePath, "utf8"))).toMatchObject({
+            scripts: { custom: "node custom.mjs" },
+            exports: { "./native": "./src/native.ts" },
+        });
+        expect(JSON.parse(readFileSync(manifestPath, "utf8"))).toMatchObject({
+            contracts: { customProviders: ["native"] },
+            nativeField: true,
+        });
+    });
     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`] ?? "{}");

package/dist/surfaces/pypi.js

@@ -26,19 +26,43 @@ export const surface = {
                     ? { [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.
+            // Hatch ignores a missing `only-include` path, unlike `force-include`, which makes
+            // `uv sync` work in a fresh checkout before the optional page is built. At package time,
+            // the gate builds `web/dist` first and Hatch maps it into the installed package.
             ...(has(project, "web")
                 ? {
                     tool: {
                         hatch: {
                             build: {
+                                // Hatch's normal file selection honors .gitignore; `web/dist` is ignored in
+                                // every generated project, so artifacts is the standard explicit opt-in for
+                                // the release build's compiled page.
+                                artifacts: [`${WEB_DIR}/dist/**`],
                                 targets: {
                                     wheel: {
-                                        "force-include": {
+                                        "only-include": [`src/${pythonPackage(project)}`, `${WEB_DIR}/dist`],
+                                        sources: {
+                                            src: "",
                                             [`${WEB_DIR}/dist`]: `${pythonPackage(project)}/${WEB_DIR}`,
                                         },
                                     },
+                                    // This is the source MCPB stages, so include every declared project metadata
+                                    // file alongside the package and built page. `only-include` ignores absent
+                                    // legal files without making fresh checkouts fail.
+                                    sdist: {
+                                        "only-include": [
+                                            "pyproject.toml",
+                                            "README.md",
+                                            "LICENSE",
+                                            "LICENSE.md",
+                                            "LICENSE.txt",
+                                            "NOTICE",
+                                            "NOTICE.md",
+                                            "NOTICE.txt",
+                                            `src/${pythonPackage(project)}`,
+                                            `${WEB_DIR}/dist`,
+                                        ],
+                                    },
                                 },
                             },
                         },

package/dist/surfaces/readme.d.ts

@@ -1,3 +1,19 @@
+/**
+ * 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 type { Project, Surface } from "../model.js";
 export declare const README_PATH = "README.md";
 export declare const INSTALL_BEGIN = "<!-- tf:install -->";

package/dist/surfaces/readme.js

@@ -14,6 +14,8 @@
  * `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 { nativeInstallLines } from "../distribution/native.js";
+import { systemInstallLines } from "../distribution/system.js";
 import { githubSlug } from "../hosts/github.js";
 import { projectName } from "../identity/name.js";
 import { HOST_DIR as BROWSER_HOST_DIR, zipName } from "./browser-extension.js";
@@ -21,6 +23,7 @@ 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";
+import { vsixName } from "./vscode-extension.js";
 export const README_PATH = "README.md";
 export const INSTALL_BEGIN = "<!-- tf:install -->";
 export const INSTALL_END = "<!-- /tf:install -->";
@@ -70,6 +73,10 @@ function installLines(project) {
     const { identity } = project;
     const slug = githubSlug(identity.repository);
     const lines = [];
+    lines.push(...nativeInstallLines(project).map((line) => `- **Native package** — ${line}`));
+    lines.push(...systemInstallLines(project).map((line) => `- **System package** — ${line}`));
+    if (has(project, "vscode-extension"))
+        lines.push(`- **VS Code extension** — download \`${vsixName(project)}\` from the release, then \`code --install-extension ${vsixName(project)}\``);
     if (has(project, "skill") && slug) {
         lines.push(`- **Agent Skill** — \`npx skills add ${slug}\``);
     }
@@ -114,16 +121,15 @@ function installLines(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.
+        // release assets (the signed Firefox XPI depends on configured signing credentials), and
+        // 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",
+            `  store uploads ${zips.join(", ")}. When Firefox signing credentials are configured, it also attaches a`,
+            "  Mozilla-signed `.xpi`; 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"));
@@ -133,8 +139,12 @@ function installLines(project) {
         // 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, "npm")) {
+        const pythonBridge = project.tool.binding === "python"
+            ? `; requires \`uv\`, and \`${identity.name}\` delegates to \`uvx --from ${pypiName(project)}==${identity.version} ${identity.name}\``
+            : "";
+        lines.push(`- **npm package** — \`npm install ${npmName(project)}\`${pythonBridge}`);
+    }
     if (has(project, "pypi"))
         lines.push(`- **PyPI package** — \`uv add ${pypiName(project)}\``);
     return lines;

package/dist/surfaces/registry.js

@@ -1,3 +1,5 @@
+import { nativePackageSurfaces } from "../distribution/native.js";
+import { systemPackageSurfaces } from "../distribution/system.js";
 import { surface as agentPlugins } from "./agent-plugins.js";
 import { surface as agents } from "./agents.js";
 import { surface as browserExtension } from "./browser-extension.js";
@@ -16,9 +18,12 @@ 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 vscodeExtension } from "./vscode-extension.js";
 import { surface as web } from "./web.js";
 import { surface as workflows } from "./workflows.js";
 const registry = {
+    ...Object.fromEntries(nativePackageSurfaces.map((surface) => [surface.id, surface])),
+    ...Object.fromEntries(systemPackageSurfaces.map((surface) => [surface.id, surface])),
     "agent-plugins": agentPlugins,
     agents,
     "browser-extension": { ...browserExtension, requires: ["mcp"] },
@@ -36,9 +41,9 @@ const registry = {
     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"] },
+    // TypeScript bundles stage their npm tarball; Python `uv` bundles stage the PyPI project's
+    // source. The projector enforces that binding-specific distribution dependency.
+    mcpb: { ...mcpb, requires: ["mcp"] },
     npm,
     skill,
     "hermes-native": hermesNative,
@@ -46,6 +51,7 @@ const registry = {
     pypi,
     readme,
     web: { ...web, requires: ["mcp"] },
+    "vscode-extension": { ...vscodeExtension, requires: ["mcp", "cli"] },
     workflows,
 };
 export function registerSurface(surface) {

package/dist/surfaces/vscode-extension.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { type Project, type Surface } from "../model.js";
+export declare const HOST_DIR = "hosts/vscode";
+export declare const vscodeConfigSchema: z.ZodObject<{
+    publisher: z.ZodOptional<z.ZodString>;
+    marketplace: z.ZodDefault<z.ZodBoolean>;
+    openvsx: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const VSCE_VERSION = "3.9.2";
+export declare const OVSX_VERSION = "1.1.1";
+export declare function extensionName(project: Project): string;
+export declare function publisher(project: Project): string;
+export declare function vsixName(project: Project): string;
+export declare const surface: Surface;