toolfactory 0.1.1 → 0.2.0

package/src/project/gate.ts

@@ -9,6 +9,18 @@
  * A step here is a command and nothing else. GitHub Actions `uses:` steps are runner provisioning
  * (checkout, toolchains, caches) and stay in `src/surfaces/workflows.ts`, which wraps this list.
  */
+
+import {
+  type NativePackageId,
+  nativePackageSteps,
+  nativeRegistryRows,
+  nativeToolchainSteps,
+} from "../distribution/native.js";
+import {
+  type SystemPackageId,
+  systemPackageSteps,
+  systemRegistryRows,
+} from "../distribution/system.js";
 import { githubSlug } from "../hosts/github.js";
 import { githubOwner, projectName } from "../identity/name.js";
 import { isInstructionOnly, type PackageManager, type Project, type SurfaceId } from "../model.js";
@@ -28,6 +40,14 @@ import {
   npmName,
   pypiName,
 } from "../surfaces/shared.js";
+import {
+  extensionName,
+  OVSX_VERSION,
+  publisher,
+  VSCE_VERSION,
+  HOST_DIR as VSCODE_HOST_DIR,
+  vsixName,
+} from "../surfaces/vscode-extension.js";
 
 export interface GateStep {
   /** Step label: the CI step name, and the banner the shell script echoes. */
@@ -121,11 +141,18 @@ export function gateSteps(project: Project): GateStep[] {
   const pm = commands(project);
   const cli = toolfactoryCli(project);
   const openclaw = has(project, "openclaw-native");
-  const steps: GateStep[] = [
-    ...bootstrapSteps(project),
-    { name: "toolfactory check", run: `${cli} check` },
-    outputsStep(project),
-  ];
+  const steps: GateStep[] = [...bootstrapSteps(project)];
+  if (!typescript && has(project, "hermes-native")) {
+    // Hermes' launcher clears PYTHONPATH and runs its own venv. Its plugin dependency
+    // declaration is advisory, so Doctor can import a native Python core only after the
+    // project is installed into that interpreter. Run after bootstrap's `uv sync` on CI.
+    steps.push({
+      name: "Install core into Hermes",
+      run: 'uv pip install --python "$HOME/.hermes/hermes-agent/venv/bin/python" --editable .',
+      when: "ci",
+    });
+  }
+  steps.push({ name: "toolfactory check", run: `${cli} check` }, outputsStep(project));
   if (has(project, "claude")) {
     steps.push({
       name: "Install Claude Code CLI",
@@ -133,7 +160,11 @@ export function gateSteps(project: Project): GateStep[] {
       when: "ci",
     });
   }
-  if (has(project, "web") || has(project, "browser-extension")) {
+  if (
+    has(project, "web") ||
+    has(project, "browser-extension") ||
+    has(project, "vscode-extension")
+  ) {
     // The web smoke and the browser extension's own Playwright smoke both drive Chromium;
     // their own npm installs fetch the browser, the runner needs its system libraries.
     steps.push({
@@ -142,6 +173,7 @@ export function gateSteps(project: Project): GateStep[] {
       when: "ci",
     });
   }
+  steps.push(...nativeToolchainSteps(project));
   steps.push({
     name: "toolfactory validate",
     run: `${cli} validate`,
@@ -153,6 +185,7 @@ export function gateSteps(project: Project): GateStep[] {
     name: "author tests",
     run: typescript ? pm.test : "uv run --with pytest pytest -q",
   });
+  if (typescript) steps.push({ name: "author integration tests", run: pm.run("test:integration") });
   if (openclaw) {
     // T3, credential-free: one real OpenClaw agent turn against a scripted model. The suite only
     // exists when `tool.json` `tests.examples` names an operation the plugin carries, which is
@@ -213,13 +246,16 @@ const LEGAL_BUNDLE_PATHS = [
  * the release workflow's `package` job, which uploads the directory as one artifact. Publishing
  * to a registry stays a CI concern; producing the artifacts never is.
  */
-export function packageSteps(project: Project): GateStep[] {
+export function packageSteps(project: Project, options: { system?: boolean } = {}): GateStep[] {
   const cli = toolfactoryCli(project);
   const name = project.identity.name;
   const steps: GateStep[] = [
     { name: "release directory", run: `rm -rf ${RELEASE_DIR} && mkdir -p ${RELEASE_DIR}` },
     ...bootstrapSteps(project),
     outputsStep(project),
+    ...nativeToolchainSteps(project),
+    ...nativePackageSteps(project),
+    ...systemPackageSteps(project, { include: options.system !== false }),
   ];
   if (has(project, "web")) {
     steps.push({
@@ -232,27 +268,35 @@ export function packageSteps(project: Project): GateStep[] {
   if (has(project, "npm")) {
     steps.push({ name: "npm tarball", run: `npm pack --pack-destination ${RELEASE_DIR}` });
   }
+  if (has(project, "pypi")) {
+    // Keep the wheel and sdist apart from the release's npm tarballs, plugin bundles and web
+    // archive: PyPA's publisher accepts only Python distribution files. The MCPB stage below
+    // unpacks this same canonical sdist rather than reproducing its source-file selection.
+    steps.push({ name: "python distributions", run: `uv build --out-dir ${RELEASE_DIR}/pypi` });
+  }
   if (has(project, "mcpb")) {
-    // A bundle root is the published package with its production dependencies installed into
-    // it, so it is built from the tarball `npm pack` just wrote rather than from the checkout:
-    // whatever ships to npm is exactly what ships to Claude Desktop. `--ignore-scripts` because
-    // nothing in a bundle root may run a build; the tarball already carries `dist/`.
     const stage = "dist/mcpb";
-    const tarball = npmTarball(project);
     steps.push({
       name: "MCPB bundle",
-      run: [
-        `rm -rf ${stage} && mkdir -p ${stage}`,
-        `tar -xzf ${RELEASE_DIR}/${tarball} -C ${stage} --strip-components=1`,
-        `npm --prefix ${stage} install --omit=dev --ignore-scripts`,
-        `cp ${MCPB_MANIFEST_PATH} ${stage}/manifest.json`,
-        `npx -y @anthropic-ai/mcpb@${MCPB_PIN} pack ${stage} ${RELEASE_DIR}/${name}.mcpb`,
-      ].join(" && "),
+      run:
+        project.tool.binding === "python"
+          ? [
+              `rm -rf ${stage} && mkdir -p ${stage}`,
+              `tar -xzf ${RELEASE_DIR}/pypi/*.tar.gz -C ${stage} --strip-components=1`,
+              `cp ${MCPB_MANIFEST_PATH} ${stage}/manifest.json`,
+              `npx -y @anthropic-ai/mcpb@${MCPB_PIN} pack ${stage} ${RELEASE_DIR}/${name}.mcpb`,
+            ].join(" && ")
+          : [
+              // The Node bundle root is the published package with production dependencies
+              // installed, so whatever ships to npm is exactly what ships to Claude Desktop.
+              `rm -rf ${stage} && mkdir -p ${stage}`,
+              `tar -xzf ${RELEASE_DIR}/${npmTarball(project)} -C ${stage} --strip-components=1`,
+              `npm --prefix ${stage} install --omit=dev --ignore-scripts`,
+              `cp ${MCPB_MANIFEST_PATH} ${stage}/manifest.json`,
+              `npx -y @anthropic-ai/mcpb@${MCPB_PIN} pack ${stage} ${RELEASE_DIR}/${name}.mcpb`,
+            ].join(" && "),
     });
   }
-  if (has(project, "pypi")) {
-    steps.push({ name: "python distributions", run: `uv build --out-dir ${RELEASE_DIR}` });
-  }
   if (has(project, "openclaw-native")) {
     // ClawHub's reusable workflow has no build step of its own, so the tarball it publishes has
     // to arrive already built (`package_artifact_name`).
@@ -314,6 +358,12 @@ export function packageSteps(project: Project): GateStep[] {
     });
   }
   // COVERAGE.md is tracked; coverage.json is a build output that need not be, so recompute it.
+  if (has(project, "vscode-extension")) {
+    steps.push({
+      name: "VS Code extension VSIX",
+      run: `npm --prefix ${VSCODE_HOST_DIR} install && npm --prefix ${VSCODE_HOST_DIR} run vsix && cp ${VSCODE_HOST_DIR}/extension.vsix ${RELEASE_DIR}/${vsixName(project)}`,
+    });
+  }
   steps.push({
     name: "coverage report",
     run: `cp COVERAGE.md ${RELEASE_DIR}/ && ${cli} coverage > ${RELEASE_DIR}/coverage.json`,
@@ -340,6 +390,8 @@ export function openclawTarball(project: Project): string {
 export interface Registry {
   /** Stable id: the release job suffix, the `secrets status` row, the unpublish step name. */
   id:
+    | NativePackageId
+    | SystemPackageId
     | "npm"
     | "pypi"
     | "mcp-registry"
@@ -350,7 +402,9 @@ export interface Registry {
     | "chrome"
     | "firefox"
     | "edge"
-    | "safari";
+    | "safari"
+    | "vscode-marketplace"
+    | "open-vsx";
   /** The surfaces whose selection publishes here; all must be selected. */
   surfaces: SurfaceId[];
   /** Environment names the publish leg consumes (repository scope); [] for OIDC/GITHUB_TOKEN legs. */
@@ -432,6 +486,22 @@ const ASC_SECRETS = ["ASC_KEY_ID", "ASC_ISSUER_ID", "ASC_PRIVATE_KEY"];
 export const RELEASE_SECRET_NAMES = [
   "NPM_TOKEN",
   "CLAWHUB_TOKEN",
+  "VSCE_PAT",
+  "OVSX_PAT",
+  "CARGO_REGISTRY_TOKEN",
+  "NUGET_API_KEY",
+  "MAVEN_CENTRAL_USERNAME",
+  "MAVEN_CENTRAL_PASSWORD",
+  "MAVEN_GPG_PRIVATE_KEY",
+  "MAVEN_GPG_PASSPHRASE",
+  "RUBYGEMS_API_KEY",
+  "HOMEBREW_TAP_TOKEN",
+  "SCOOP_BUCKET_TOKEN",
+  "CHOCOLATEY_API_KEY",
+  "APT_GPG_PRIVATE_KEY",
+  "APT_GPG_KEY_ID",
+  "COPR_LOGIN",
+  "COPR_TOKEN",
   ...CHROME_SECRETS,
   ...FIREFOX_SECRETS,
   ...EDGE_SECRETS,
@@ -459,6 +529,29 @@ export function registries(project: Project): Registry[] {
   const wxtSubmit = `npm --prefix ${BROWSER_HOST_DIR} exec --no -- wxt submit --dry-run`;
 
   const rows: Registry[] = [
+    ...nativeRegistryRows(project),
+    ...systemRegistryRows(project),
+    {
+      id: "vscode-marketplace",
+      surfaces: ["vscode-extension"],
+      secrets: ["VSCE_PAT"],
+      url: "https://marketplace.visualstudio.com/manage",
+      probe: `npx --yes @vscode/vsce@${VSCE_VERSION} verify-pat ${publisher(project)}`,
+      exists: `npx --yes @vscode/vsce@${VSCE_VERSION} show ${publisher(project)}.${extensionName(project)} --json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>process.exit(JSON.parse(s).versions.some(v=>v.version==="${version}")?0:1))'`,
+      gate: allSet(["VSCE_PAT"]),
+      retractUrl: "https://marketplace.visualstudio.com/manage",
+      retractHard: `npx --yes @vscode/vsce@${VSCE_VERSION} unpublish ${publisher(project)}.${extensionName(project)} --force`,
+    },
+    {
+      id: "open-vsx",
+      surfaces: ["vscode-extension"],
+      secrets: ["OVSX_PAT"],
+      url: "https://open-vsx.org/user-settings/tokens",
+      probe: `npx --yes ovsx@${OVSX_VERSION} verify-pat ${publisher(project)}`,
+      exists: `curl -fsS -o /dev/null https://open-vsx.org/api/${publisher(project)}/${extensionName(project)}/${version}`,
+      gate: allSet(["OVSX_PAT"]),
+      retractUrl: "https://open-vsx.org/user-settings/extensions",
+    },
     {
       id: "npm",
       surfaces: ["npm"],
@@ -612,7 +705,9 @@ export function registries(project: Project): Registry[] {
   const selected = rows.filter(
     (row) =>
       row.surfaces.every((surface) => has(project, surface)) &&
-      (row.id !== "safari" || project.tool.browserExtension?.safari === true),
+      (row.id !== "safari" || project.tool.browserExtension?.safari === true) &&
+      (row.id !== "vscode-marketplace" || project.tool.vscode?.marketplace !== false) &&
+      (row.id !== "open-vsx" || project.tool.vscode?.openvsx !== false),
   );
   const mcpRegistry = selected.find((row) => row.id === "mcp-registry");
   if (mcpRegistry) {
@@ -623,6 +718,14 @@ export function registries(project: Project): Registry[] {
       ? packages.map((row) => `[ "$${gateVariable(row)}" = true ]`).join(" && ")
       : "true";
   }
+  const runtime = selected.find(
+    (row) => row.id === (project.tool.binding === "python" ? "pypi" : "npm"),
+  );
+  for (const row of selected.filter(
+    (row) => row.id === "vscode-marketplace" || row.id === "open-vsx",
+  )) {
+    if (runtime) row.gate = `(${row.gate}) && { ${runtime.exists} || { ${runtime.gate}; }; }`;
+  }
   return selected;
 }
 
@@ -649,6 +752,10 @@ export function manualSteps(project: Project): string[] {
   const has_ = (id: Registry["id"]) => rows.some((row) => row.id === id);
   const slug = githubSlug(project.identity.repository);
   const steps: string[] = [];
+  if (has_("vscode-marketplace") || has_("open-vsx"))
+    steps.push(
+      "VS Code: register the publisher in Visual Studio Marketplace; create the Open VSX namespace and accept its publisher agreement before setting VSCE_PAT / OVSX_PAT. tool.vscode.publisher selects that identity.",
+    );
   if (has_("oci")) {
     steps.push(
       `ghcr.io: the first push publishes a private image whatever the repository's visibility, and GitHub has no visibility API — flip it once at ${rows.find((row) => row.id === "oci")?.url}.`,

package/src/project/lock.ts

@@ -23,6 +23,18 @@ export const LockSchema = z.object({
        * patch — or deselecting the surface that added it — uninstalls it instead of stranding it.
        */
       keys: z.array(z.string()).optional(),
+      /** A keyed array's inverse: the entries Toolfactory owns at each dotted path. */
+      keyedArrays: z
+        .record(
+          z.string(),
+          z.object({
+            id: z.string(),
+            values: z.array(z.string()),
+            /** The last projected entry shape lets a later plan remove only stale generated leaves. */
+            entries: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+          }),
+        )
+        .optional(),
       /**
        * A region file's inverse, exactly as `keys` is a merge file's: the marker pairs its
        * projector wrote. Regions the current plan no longer writes are emptied before the current

package/src/surfaces/agent-plugins.ts

@@ -4,7 +4,7 @@
  * Validation is Ajv against the cached official schemas; the spec forbids fetching at load.
  */
 import type { Project, Surface } from "../model.js";
-import { json, kernelLaunch, mcpVerdict } from "./shared.js";
+import { kernelLaunch, mcpVerdict } from "./shared.js";
 
 export const MCP_SCHEMA_ID = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
 export const PLUGIN_SCHEMA_ID = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
@@ -24,12 +24,13 @@ export const surface: Surface = {
     const launch = kernelLaunch(project, "${PLUGIN_ROOT}");
     return [
       {
-        kind: "file",
+        kind: "merge",
         path: "mcp.json",
-        content: json({
+        format: "json",
+        patch: {
           $schema: MCP_SCHEMA_ID,
           mcpServers: { [project.identity.name]: { type: "stdio", ...launch } },
-        }),
+        },
       },
     ];
   },

package/src/surfaces/agents.test.ts

@@ -129,6 +129,22 @@ describe("agents", () => {
     expect(setup).toContain("npm install --no-audit --no-fund");
   });
 
+  it("installs uv before Python projects run the vendored setup workflow", () => {
+    const workflow = planned(
+      project(["cli"], { binding: "python" }),
+      ".github/workflows/agent-config.yml",
+    );
+    if (workflow.kind !== "file") throw new Error("expected an agent-config workflow file");
+    const install = "uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0";
+    expect(workflow.content).toContain(install);
+    expect(workflow.content.indexOf(install)).toBeLessThan(
+      workflow.content.indexOf("run: bash .agents/setup --all"),
+    );
+    const typescript = planned(project(["cli"]), ".github/workflows/agent-config.yml");
+    if (typescript.kind !== "file") throw new Error("expected an agent-config workflow file");
+    expect(typescript.content).toBe(TEMPLATE_FILES[".github/workflows/agent-config.yml"]);
+  });
+
   it("owns the agent adapters, the binding's ignores and the build outputs in .gitignore", () => {
     const bare = region(project(["cli"]), IGNORE_PATH);
     const agentBlocks = (TEMPLATE_FILES[IGNORE_PATH] ?? "").split("# ─── Secrets")[0] ?? "";

package/src/surfaces/agents.ts

@@ -89,6 +89,13 @@ export const RELOAD: Reload[] = [
       "`hermes skills trust` once in this repo, then a new conversation: the resolved skill directories are stable for a conversation.",
     line: "Run `hermes skills trust` once in this repo, then start a new Hermes conversation — every invocation re-scans plugins, skills and AGENTS.md. `/reload-mcp` only affects an already-open session; `hermes gateway restart` is only for the messaging gateway.",
   },
+  {
+    harness: "GSD",
+    env: [],
+    mcp: "`python3 .agents/sync.py --all` renders the shared `.mcp.json` even on a GSD-only machine. Refresh with `mcp_servers(refresh=true)`; start a new session after changing a connected server. Approve `mcp_discover` interactively once before unattended stdio use.",
+    instructions:
+      "Reads `AGENTS.md` and `.agents/skills/` natively; `/reload` refreshes resources. `--bare` omits them.",
+  },
   {
     harness: "Gemini CLI",
     env: [],
@@ -191,7 +198,8 @@ function layoutSection(project: Project): string[] {
     has(project, "openclaw-native") ||
     has(project, "hermes-native") ||
     has(project, "dsh") ||
-    has(project, "browser-extension")
+    has(project, "browser-extension") ||
+    has(project, "vscode-extension")
   ) {
     lines.push(
       "- `hosts/<id>/` — the host-native escape hatch for a selected host; nothing else creates it.",
@@ -274,6 +282,15 @@ function installSection(project: Project): string[] {
       "  KEY/PASSWORD/SECRET/TOKEN names before spawning an MCP server.",
     );
   }
+  if (has(project, "vscode-extension")) {
+    lines.push(
+      "- **VS Code extension**: `npm --prefix hosts/vscode install`, then open `hosts/vscode` in VS Code",
+      "  and press F5. Development and `npm --prefix hosts/vscode test` use the checkout's kernel.",
+      "  `npm --prefix hosts/vscode run vsix` packages it; install with `code --install-extension hosts/vscode/extension.vsix`.",
+      "  Use Developer: Reload Window after rebuilding an installed extension. Native activation, contributions",
+      "  and every VS Code API are available in your own files; include your license in the extension directory.",
+    );
+  }
   if (has(project, "browser-extension")) {
     const { command, args } = getBinding(project.tool.binding).cliCommand(project);
     lines.push(
@@ -292,7 +309,8 @@ function installSection(project: Project): string[] {
     !openclaw &&
     !hermes &&
     !has(project, "dsh") &&
-    !has(project, "browser-extension")
+    !has(project, "browser-extension") &&
+    !has(project, "vscode-extension")
   ) {
     lines.push(
       "_No host-native surface (`openclaw-native`, `hermes-native`, `dsh`, `browser-extension`) or",
@@ -681,6 +699,22 @@ function devcontainer(project: Project): string {
   return `${JSON.stringify({ ...document, features }, null, 2)}\n`;
 }
 
+/** The vendor-owned workflow gains the Python prerequisite it cannot know. */
+function agentConfigWorkflow(project: Project): string {
+  const path = ".github/workflows/agent-config.yml";
+  const workflow = TEMPLATE_FILES[path] ?? "";
+  if (isInstructionOnly(project.tool) || project.tool.binding !== "python") return workflow;
+  const setup = "      - name: Run the shared setup entry point\n";
+  if (!workflow.includes(setup))
+    throw new Error(`${path} no longer has the setup step; re-vendor before adding uv.`);
+  return workflow.replace(
+    setup,
+    "      - name: Install uv\n" +
+      "        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0\n\n" +
+      setup,
+  );
+}
+
 /** Whole-file carriers: no per-project content, `adopt` is the escape hatch. */
 function vendored(project: Project): PlannedFile[] {
   const skip = new Set([SETUP_PATH, IGNORE_PATH, ".devcontainer/devcontainer.json"]);
@@ -691,7 +725,8 @@ function vendored(project: Project): PlannedFile[] {
         ([path, content]): PlannedFile => ({
           kind: "file",
           path,
-          content,
+          content:
+            path === ".github/workflows/agent-config.yml" ? agentConfigWorkflow(project) : content,
           ...(path.endsWith("sync.py") ? { mode: 0o755 } : {}),
         }),
       ),

package/src/surfaces/claude.ts

@@ -12,7 +12,6 @@ import {
   envName,
   has,
   isSensitive,
-  json,
   kernelLaunch,
   mcpVerdict,
   requiredConfig,
@@ -79,8 +78,13 @@ export const surface: Surface = {
       plugins: [compact({ name: identity.name, source: "./", description: identity.description })],
     });
     return [
-      { kind: "file", path: ".claude-plugin/plugin.json", content: json(manifest) },
-      { kind: "file", path: ".claude-plugin/marketplace.json", content: json(marketplace) },
+      { kind: "merge", path: ".claude-plugin/plugin.json", format: "json", patch: manifest },
+      {
+        kind: "merge",
+        path: ".claude-plugin/marketplace.json",
+        format: "json",
+        patch: marketplace,
+      },
     ];
   },
   validate(project) {

package/src/surfaces/codex.test.ts

@@ -33,8 +33,8 @@ describe("codex", () => {
   it("makes the repository its own single-plugin marketplace, and validates with the real codex CLI", () => {
     const files = codex.plan(project(["codex", "mcp"]));
     const marketplace = files.find((entry) => entry.path === ".agents/plugins/marketplace.json");
-    if (marketplace?.kind !== "file") throw new Error("expected a whole file");
-    expect(JSON.parse(marketplace.content)).toMatchObject({
+    if (marketplace?.kind !== "merge") throw new Error("expected a merge manifest");
+    expect(marketplace.patch).toMatchObject({
       name: "hello",
       interface: { displayName: "Hello" },
       plugins: [
@@ -64,8 +64,18 @@ describe("codex", () => {
     const target = project(["skill", "codex"]);
     target.tool.runtime = "none";
     const manifest = codex.plan(target).find((entry) => entry.path === ".codex-plugin/plugin.json");
-    if (manifest?.kind !== "file") throw new Error("expected a manifest");
-    expect(JSON.parse(manifest.content)).toMatchObject({ skills: "./skills/" });
-    expect(JSON.parse(manifest.content)).not.toHaveProperty("mcpServers");
+    if (manifest?.kind !== "merge") throw new Error("expected a manifest");
+    expect(manifest.patch).toMatchObject({ skills: "./skills/" });
+    expect(manifest.patch).not.toHaveProperty("mcpServers");
+  });
+
+  it("can omit the eager MCP server while retaining the plugin skill", () => {
+    const target = project(["skill", "codex", "mcp"]);
+    target.tool.codex = { mcp: false };
+    const manifest = codex.plan(target).find((entry) => entry.path === ".codex-plugin/plugin.json");
+    if (manifest?.kind !== "merge") throw new Error("expected a manifest");
+    const parsed = manifest.patch;
+    expect(parsed.skills).toBe("./skills/");
+    expect(parsed).not.toHaveProperty("mcpServers");
   });
 });

package/src/surfaces/codex.ts

@@ -10,7 +10,7 @@
 
 import { projectName } from "../identity/name.js";
 import type { Surface } from "../model.js";
-import { compact, has, json, kernelLaunch, mcpVerdict } from "./shared.js";
+import { compact, has, kernelLaunch, mcpVerdict } from "./shared.js";
 
 /** The Codex CLI (`@openai/codex`) `validate()` is proven against — pin for a deterministic gate. */
 export const CODEX_PIN = "0.152.1";
@@ -43,9 +43,10 @@ export const surface: Surface = {
       license: identity.license,
       keywords: identity.keywords,
       skills: has(project, "skill") ? "./skills/" : undefined,
-      mcpServers: has(project, "mcp")
-        ? { [identity.name]: kernelLaunch(project, "${PLUGIN_ROOT}") }
-        : undefined,
+      mcpServers:
+        has(project, "mcp") && project.tool.codex?.mcp !== false
+          ? { [identity.name]: kernelLaunch(project, "${PLUGIN_ROOT}") }
+          : undefined,
       interface: codexInterface,
     });
     // `source: "local"` + `path: "."` is the marketplace root itself: one repository, one
@@ -64,8 +65,13 @@ export const surface: Surface = {
       ],
     });
     return [
-      { kind: "file", path: ".codex-plugin/plugin.json", content: json(manifest) },
-      { kind: "file", path: ".agents/plugins/marketplace.json", content: json(marketplace) },
+      { kind: "merge", path: ".codex-plugin/plugin.json", format: "json", patch: manifest },
+      {
+        kind: "merge",
+        path: ".agents/plugins/marketplace.json",
+        format: "json",
+        patch: marketplace,
+      },
     ];
   },
   validate(project) {

package/src/surfaces/cursor.ts

@@ -4,15 +4,7 @@
  */
 import { projectName } from "../identity/name.js";
 import type { Surface } from "../model.js";
-import {
-  compact,
-  configProperties,
-  envName,
-  has,
-  json,
-  mcpVerdict,
-  requiredConfig,
-} from "./shared.js";
+import { compact, configProperties, envName, has, mcpVerdict, requiredConfig } from "./shared.js";
 
 export const surface: Surface = {
   id: "cursor",
@@ -51,7 +43,7 @@ export const surface: Surface = {
       mcpServers: has(project, "agent-plugins") ? "./mcp.json" : undefined,
       variables,
     });
-    return [{ kind: "file", path: ".cursor-plugin/plugin.json", content: json(manifest) }];
+    return [{ kind: "merge", path: ".cursor-plugin/plugin.json", format: "json", patch: manifest }];
   },
   verdict: (operation) => {
     const verdict = mcpVerdict(operation);