toolfactory 0.1.1

package/src/ops.ts

@@ -0,0 +1,333 @@
+/**
+ * toolfactory's own operations. toolfactory is a tool built with toolfactory: this file is
+ * the author-owned operation module, and `src/toolfactory/{cli,mcp}.ts` are generated from
+ * it by `toolfactory build`, exactly as for any other tool.
+ */
+import { z } from "zod";
+import * as commands from "./commands.js";
+import { BINDINGS, SURFACE_IDS } from "./model.js";
+import { operation } from "./toolfactory/types.js";
+
+const root = z
+  .string()
+  .default(".")
+  .describe("Project root (directory containing dev.toolfactory/)");
+const surfaceId = z.enum(SURFACE_IDS);
+
+export const operations = [
+  operation({
+    name: "init",
+    description:
+      "Create a new tool: dev.toolfactory/tool.json, the authored identity file, the kernel scaffold for the chosen language, and the first build of every selected surface.",
+    input: z.object({
+      root,
+      name: z
+        .string()
+        .describe("Tool name: lowercase letters, digits, hyphens, dots (Agent Plugins rule)"),
+      binding: z.enum(BINDINGS).describe("Language of the core logic: typescript or python"),
+      runtime: z
+        .enum(["kernel", "none"])
+        .optional()
+        .describe(
+          "`none` creates an instruction-only skill/Codex plugin with no executable payload",
+        ),
+      surfaces: z
+        .array(surfaceId)
+        .min(1)
+        .optional()
+        .describe(
+          "Surfaces to generate. Default: the skills-first minimum — skill, agent-plugins, mcp, cli and the binding's package registry; every host-specific plugin is opt-in.",
+        ),
+      description: z.string().optional().describe("One-line description"),
+      license: z.string().optional().describe("SPDX license identifier"),
+      repository: z
+        .string()
+        .optional()
+        .describe("Source repository URL (GitHub URL enables the MCP Registry name)"),
+      author: z.string().optional().describe("Author name"),
+      keywords: z
+        .array(z.string())
+        .optional()
+        .describe(
+          "Activation triggers for hosts that key off them (Kiro Powers, Agent Plugins); defaults to [name]",
+        ),
+      git: z
+        .boolean()
+        .default(true)
+        .describe("git init when the directory is not a repository yet, and make the first commit"),
+      setup: z
+        .boolean()
+        .default(true)
+        .describe(
+          "Run .agents/setup: render the harness adapters, install the git hooks, install dependencies",
+        ),
+      repo: z
+        .string()
+        .optional()
+        .describe("owner/name of a GitHub repository to create with gh and push to"),
+      public: z.boolean().default(false).describe("Create that repository public, not private"),
+      dryRun: z
+        .boolean()
+        .default(false)
+        .describe("Print the gh invocations instead of running them"),
+      reviewers: z
+        .array(z.string())
+        .default([])
+        .describe(
+          "GitHub logins that must approve a live run, when the repository gets a live tier",
+        ),
+    }),
+    output: z.object({
+      written: z.array(z.string()),
+      agentConfig: z.object({ setup: z.boolean(), harnesses: z.array(z.string()) }),
+      repository: z
+        .object({
+          repository: z.string(),
+          visibility: z.string(),
+          topics: z.array(z.string()),
+          secrets: z.array(z.string()),
+          commands: z.array(z.string()),
+          dryRun: z.boolean(),
+        })
+        .optional(),
+      nextSteps: z.array(z.string()),
+    }),
+    annotations: { idempotentHint: true },
+    requires: ["shell", "net", "fs"],
+    handler: async (args) => commands.init(args),
+  }),
+  operation({
+    name: "introspect",
+    description:
+      "Spawn the kernel MCP server, list its tools, and snapshot them to dev.toolfactory/ops.json.",
+    input: z.object({ root }),
+    output: z.object({ path: z.string(), changed: z.boolean(), operations: z.number() }),
+    annotations: { idempotentHint: true },
+    handler: async ({ root }) => {
+      const { path, changed, ops } = await commands.introspect(root);
+      return { path, changed, operations: ops.tools.length };
+    },
+  }),
+  operation({
+    name: "build",
+    description:
+      "Generate every selected surface in-tree from the identity file and the operation snapshot, and refresh the lock.",
+    input: z.object({ root }),
+    output: z.object({
+      written: z.array(z.string()),
+      deleted: z.array(z.string()),
+      unchanged: z.array(z.string()),
+      manual: z.array(z.string()),
+      stripped: z
+        .array(z.string())
+        .describe(
+          "Region files whose generated regions were emptied because their surface is no longer selected; the authored remainder stays.",
+        ),
+      nudge: z
+        .string()
+        .optional()
+        .describe(
+          "One line when a surface that published somewhere was deselected since the last tag, pointing at `unpublish`.",
+        ),
+    }),
+    annotations: { idempotentHint: true },
+    handler: async ({ root }) => commands.build(root).result,
+  }),
+  operation({
+    name: "check",
+    description:
+      "Fail if the operation snapshot or any generated file drifted from the code (the CI drift gate).",
+    input: z.object({ root }),
+    output: z.object({ ok: z.literal(true) }),
+    annotations: { readOnlyHint: true },
+    handler: async ({ root }) => {
+      await commands.check(root);
+      return { ok: true as const };
+    },
+  }),
+  operation({
+    name: "validate",
+    description:
+      "Run each selected surface's own upstream validator (agentskills, claude plugin validate, MCP Inspector, openclaw, hermes, npm pack, uv build).",
+    input: z.object({ root, surface: surfaceId.optional().describe("Only this surface") }),
+    output: z.object({
+      outcomes: z.array(z.object({ label: z.string(), command: z.string(), ok: z.boolean() })),
+    }),
+    annotations: { readOnlyHint: true },
+    handler: async ({ root, surface }) => ({
+      outcomes: commands
+        .validate(root, surface)
+        .map(({ label, command, ok }) => ({ label, command, ok })),
+    }),
+  }),
+  operation({
+    name: "coverage",
+    description:
+      "The operation × surface verdict matrix: native, bridged, degraded, or excluded, with reasons.",
+    input: z.object({ root }),
+    output: z.object({
+      surfaces: z.array(z.string()),
+      rows: z.array(
+        z.object({
+          operation: z.string(),
+          verdicts: z.record(
+            z.string(),
+            z.object({ kind: z.string(), reason: z.string().optional() }),
+          ),
+        }),
+      ),
+    }),
+    annotations: { readOnlyHint: true },
+    handler: async ({ root }) => commands.coverage(root),
+  }),
+  operation({
+    name: "adopt",
+    description:
+      "Stop regenerating one file; it becomes the author's (recorded as manual in the lock).",
+    input: z.object({ root, path: z.string().describe("Repo-relative path of a generated file") }),
+    output: z.object({ adopted: z.string() }),
+    handler: async ({ root, path }) => {
+      commands.adopt(root, path);
+      return { adopted: path };
+    },
+  }),
+  operation({
+    name: "unadopt",
+    description: "Return an adopted file to toolfactory and regenerate it.",
+    input: z.object({ root, path: z.string().describe("Repo-relative path of an adopted file") }),
+    output: z.object({ regenerated: z.string() }),
+    handler: async ({ root, path }) => {
+      commands.unadopt(root, path);
+      return { regenerated: path };
+    },
+  }),
+  operation({
+    name: "eject",
+    description: "Adopt every file a surface owns, so the author takes it over entirely.",
+    input: z.object({ root, surface: surfaceId }),
+    output: z.object({ adopted: z.array(z.string()) }),
+    handler: async ({ root, surface }) => ({ adopted: commands.eject(root, surface) }),
+  }),
+  operation({
+    name: "bootstrap-repo",
+    description:
+      "Prepare the GitHub repository from the local .env: the `live-tests` environment with its required reviewers and the sensitive config keys inside it, the release registries' tokens at repository scope, GitHub Pages with source = Actions, and npm's trusted publisher. Values go to `gh` on stdin and are never returned.",
+    input: z.object({
+      root,
+      reviewers: z
+        .array(z.string())
+        .default([])
+        .describe("GitHub logins that must approve a live run"),
+      dryRun: z
+        .boolean()
+        .default(false)
+        .describe("Print the gh invocations instead of running them"),
+    }),
+    output: z.object({
+      repository: z.string(),
+      environment: z.string(),
+      reviewers: z.array(z.string()),
+      secrets: z.array(z.string()).describe("Names written, never values"),
+      missing: z.array(z.string()).describe("Declared names the local .env has no value for"),
+      commands: z.array(z.string()),
+      manual: z.array(z.string()).describe("The one-time human steps no API can do"),
+      dryRun: z.boolean(),
+    }),
+    requires: ["shell", "net", "secret"],
+    handler: async (args) => commands.bootstrapRepo(args),
+  }),
+  operation({
+    name: "secrets",
+    description:
+      "Every credential this project's surfaces need — the tool's own sensitive config keys and the release registries' tokens — with where each one is set, whether it is present locally and on GitHub, and (check) whether the registry accepts it. Never a value.",
+    input: z.object({
+      root,
+      action: z
+        .enum(["status", "check"])
+        .default("status")
+        .describe("status: the inventory. check: run each registry's own credential probe."),
+      key: z.string().optional().describe("Only this secret"),
+    }),
+    output: z.object({
+      secrets: z.array(
+        z.object({
+          name: z.string(),
+          kind: z.enum(["config", "release"]),
+          required: z.boolean(),
+          needs: z.array(z.string()),
+          local: z.boolean(),
+          github: z.boolean().optional(),
+          url: z.string().optional(),
+          howTo: z.array(z.string()),
+          check: z.object({ ok: z.boolean(), command: z.string() }).optional(),
+        }),
+      ),
+      manual: z.array(z.string()),
+    }),
+    annotations: { readOnlyHint: true },
+    requires: ["shell", "net", "secret"],
+    handler: async (args) => commands.secrets(args),
+  }),
+  operation({
+    name: "unpublish",
+    description:
+      "Retract what a deselected surface used to publish. Git is the ledger: the previous tag's dev.toolfactory/tool.json says what was selected then, and every registry row that lost its surface is checked for the version that tag published and then retracted with the registry's own CLI — or reported with the exact page, where there is no API.",
+    input: z.object({
+      root,
+      ref: z
+        .string()
+        .default("HEAD")
+        .describe("Diff against the tag before this ref (the release passes the tag being cut)"),
+      dryRun: z.boolean().default(false).describe("List the retractions instead of running them"),
+      hard: z
+        .boolean()
+        .default(false)
+        .describe("Use the destructive retraction where one exists (npm unpublish --force)"),
+    }),
+    output: z.object({
+      from: z.string().optional(),
+      dropped: z.array(surfaceId),
+      steps: z.array(z.object({ name: z.string(), run: z.string() })),
+      ran: z
+        .array(z.object({ name: z.string(), ok: z.boolean(), durationMs: z.number() }))
+        .optional(),
+    }),
+    requires: ["shell", "net", "secret"],
+    handler: async ({ root, ref, dryRun, hard }) => commands.unpublish(root, { ref, dryRun, hard }),
+  }),
+  operation({
+    name: "gate",
+    description:
+      "Run the gate here, in order: build, the drift check, every selected surface's upstream validator, the author's checks and tests, and the credential-free host end-to-end. The same step list the generated ci.yml renders, so a project with no CI has the identical gate.",
+    input: z.object({ root }),
+    output: z.object({
+      steps: z.array(z.object({ name: z.string(), ok: z.boolean(), durationMs: z.number() })),
+    }),
+    requires: ["shell", "net", "fs"],
+    handler: async ({ root }) => commands.gate(root),
+  }),
+  operation({
+    name: "package",
+    description:
+      "Build every release asset into dist/release/ — npm tarball, Python distributions, OpenClaw plugin tarball, plugin bundle zip, web build, coverage — by the same steps the release workflow's package job runs. Publishing stays a CI concern.",
+    input: z.object({ root }),
+    output: z.object({
+      steps: z.array(z.object({ name: z.string(), ok: z.boolean(), durationMs: z.number() })),
+    }),
+    requires: ["shell", "net", "fs"],
+    handler: async ({ root }) => commands.packageRelease(root),
+  }),
+  operation({
+    name: "doctor",
+    description:
+      "Report which upstream CLIs this machine can delegate to (git, gh, npm, uv, claude, openclaw, clawhub, hermes, uvx, agentskills, MCP Inspector, docker).",
+    input: z.object({}),
+    output: z.object({
+      toolfactory: z.string(),
+      node: z.string(),
+      tools: z.record(z.string(), z.string()),
+    }),
+    annotations: { readOnlyHint: true },
+    handler: async () => commands.doctor(),
+  }),
+];

package/src/project/apply.test.ts

@@ -0,0 +1,348 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readlinkSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import type { MergeFile, PlannedFile, Project, RegionFile } from "../model.js";
+import { apply, check, setState } from "./apply.js";
+import { buildPlan } from "./plan.js";
+
+function tmp(): string {
+  return mkdtempSync(join(tmpdir(), "tf-apply-"));
+}
+
+function regionPlan(content: string): RegionFile {
+  return {
+    kind: "region",
+    path: "SKILL.md",
+    regions: [{ begin: "<!-- tf:ops -->", end: "<!-- /tf:ops -->", content }],
+    template: ["# Title", "", "Author prose.", "", "<!-- tf:ops -->", "<!-- /tf:ops -->", ""].join(
+      "\n",
+    ),
+  };
+}
+
+describe("apply / check — full files", () => {
+  it("applies a plan and check then reports it clean", () => {
+    const root = tmp();
+    const plan: PlannedFile[] = [{ kind: "file", path: "README.md", content: "hello\n" }];
+    const result = apply(root, plan, "0.1.0");
+    expect(result.written).toEqual(["README.md"]);
+    expect(readFileSync(join(root, "README.md"), "utf8")).toBe("hello\n");
+    expect(check(root, plan, "0.1.0")).toEqual([]);
+  });
+
+  it("reports a hand-edited generated file as changed", () => {
+    const root = tmp();
+    const plan: PlannedFile[] = [{ kind: "file", path: "README.md", content: "hello\n" }];
+    apply(root, plan, "0.1.0");
+    writeFileSync(join(root, "README.md"), "tampered\n");
+    expect(check(root, plan, "0.1.0")).toEqual([{ path: "README.md", kind: "changed" }]);
+  });
+
+  it("a manual file is skipped by both drift and rewriting", () => {
+    const root = tmp();
+    const planA: PlannedFile[] = [{ kind: "file", path: "README.md", content: "hello\n" }];
+    apply(root, planA, "0.1.0");
+    setState(root, "README.md", "manual", "0.1.0");
+    writeFileSync(join(root, "README.md"), "author-owned\n");
+
+    const planB: PlannedFile[] = [{ kind: "file", path: "README.md", content: "regenerated\n" }];
+    expect(check(root, planB, "0.1.0")).toEqual([]);
+    const result = apply(root, planB, "0.1.0");
+    expect(result.manual).toEqual(["README.md"]);
+    expect(readFileSync(join(root, "README.md"), "utf8")).toBe("author-owned\n");
+  });
+
+  it("reports an orphaned generated file via check and removes it on apply", () => {
+    const root = tmp();
+    const planA: PlannedFile[] = [
+      { kind: "file", path: "a.txt", content: "a\n" },
+      { kind: "file", path: "b.txt", content: "b\n" },
+    ];
+    apply(root, planA, "0.1.0");
+    const planB: PlannedFile[] = [{ kind: "file", path: "b.txt", content: "b\n" }];
+    expect(check(root, planB, "0.1.0")).toEqual([{ path: "a.txt", kind: "orphan" }]);
+    const result = apply(root, planB, "0.1.0");
+    expect(result.deleted).toEqual(["a.txt"]);
+    expect(existsSync(join(root, "a.txt"))).toBe(false);
+  });
+
+  it("writes a symbolic link, restores one a real file replaced, and unlinks it as an orphan", () => {
+    const root = tmp();
+    mkdirSync(join(root, "skills/hello"), { recursive: true });
+    writeFileSync(join(root, "skills/hello/SKILL.md"), "---\n---\n");
+    const link: PlannedFile = {
+      kind: "file",
+      path: ".agents/skills/hello",
+      content: "../../skills/hello",
+      symlink: true,
+    };
+    apply(root, [link], "0.1.0");
+    expect(readlinkSync(join(root, ".agents/skills/hello"))).toBe("../../skills/hello");
+    expect(check(root, [link], "0.1.0")).toEqual([]);
+
+    rmSync(join(root, ".agents/skills/hello"));
+    writeFileSync(join(root, ".agents/skills/hello"), "not a link\n");
+    expect(check(root, [link], "0.1.0")).toEqual([
+      { path: ".agents/skills/hello", kind: "changed" },
+    ]);
+    apply(root, [link], "0.1.0");
+    expect(lstatSync(join(root, ".agents/skills/hello")).isSymbolicLink()).toBe(true);
+
+    expect(apply(root, [], "0.1.0").deleted).toEqual([".agents/skills/hello"]);
+    expect(existsSync(join(root, ".agents/skills/hello"))).toBe(false);
+    expect(existsSync(join(root, "skills/hello/SKILL.md"))).toBe(true);
+
+    // lstat, not stat: with its target gone the link is dangling — still present, still ours.
+    apply(root, [link], "0.1.0");
+    rmSync(join(root, "skills"), { recursive: true });
+    expect(check(root, [], "0.1.0")).toEqual([{ path: ".agents/skills/hello", kind: "orphan" }]);
+    expect(apply(root, [], "0.1.0").deleted).toEqual([".agents/skills/hello"]);
+    expect(
+      lstatSync(join(root, ".agents/skills/hello"), { throwIfNoEntry: false }),
+    ).toBeUndefined();
+  });
+});
+
+describe("apply / check — region files", () => {
+  it("writes the template with the region filled when the file is absent", () => {
+    const root = tmp();
+    apply(root, [regionPlan("- op-a\n")], "0.1.0");
+    const text = readFileSync(join(root, "SKILL.md"), "utf8");
+    expect(text).toContain("Author prose.");
+    expect(text).toContain("- op-a\n");
+  });
+
+  it("preserves the author's body outside the markers when the region is rebuilt", () => {
+    const root = tmp();
+    apply(root, [regionPlan("- op-a\n")], "0.1.0");
+    const path = join(root, "SKILL.md");
+    writeFileSync(
+      path,
+      readFileSync(path, "utf8").replace(
+        "Author prose.",
+        "Author prose.\n\nMore notes the author wrote by hand.",
+      ),
+    );
+    apply(root, [regionPlan("- op-a\n- op-b\n")], "0.1.0");
+    const text = readFileSync(path, "utf8");
+    expect(text).toContain("More notes the author wrote by hand.");
+    expect(text).toContain("- op-b\n");
+  });
+
+  it("a region file toolfactory stops writing loses its regions, not its existence", () => {
+    const root = tmp();
+    apply(root, [regionPlan("- op-a\n")], "0.1.0");
+    const path = join(root, "SKILL.md");
+    const authored = readFileSync(path, "utf8").replace(
+      "Author prose.",
+      "Author prose.\n\nA paragraph only the author can write.",
+    );
+    writeFileSync(path, authored);
+    expect(check(root, [], "0.1.0")).toEqual([{ path: "SKILL.md", kind: "orphan" }]);
+
+    const result = apply(root, [], "0.1.0");
+    expect(result).toMatchObject({ stripped: ["SKILL.md"], deleted: [] });
+    const emptied = readFileSync(path, "utf8");
+    expect(emptied).toContain("A paragraph only the author can write.");
+    expect(emptied).toContain("<!-- tf:ops --><!-- /tf:ops -->");
+    expect(emptied).not.toContain("- op-a");
+    // Silent once emptied: nothing of toolfactory's is stranded in the file any more.
+    expect(check(root, [], "0.1.0")).toEqual([]);
+
+    // Re-selection needs no code of its own: the preserved markers are refilled in place.
+    apply(root, [regionPlan("- op-a\n")], "0.1.0");
+    expect(readFileSync(path, "utf8")).toBe(authored);
+  });
+
+  it("empties the region a surface stopped owning while another surface keeps the file", () => {
+    const root = tmp();
+    const install = { begin: "<!-- tf:install -->", end: "<!-- /tf:install -->" };
+    const mcpName = { begin: "<!-- tf:mcp-name -->", end: "<!-- /tf:mcp-name -->" };
+    const plan = (registry: boolean): RegionFile[] => [
+      {
+        kind: "region",
+        path: "README.md",
+        regions: [
+          { ...install, content: "\n`npx -y hello mcp`\n" },
+          ...(registry
+            ? [{ ...mcpName, content: "\n<!-- mcp-name: io.github.o/hello -->\n" }]
+            : []),
+        ],
+        template: [
+          "# hello",
+          "",
+          install.begin,
+          install.end,
+          "",
+          mcpName.begin,
+          mcpName.end,
+          "",
+        ].join("\n"),
+      },
+    ];
+    apply(root, plan(true), "0.1.0");
+    expect(check(root, plan(false), "0.1.0")).toEqual([{ path: "README.md", kind: "changed" }]);
+    apply(root, plan(false), "0.1.0");
+    const text = readFileSync(join(root, "README.md"), "utf8");
+    expect(text).not.toContain("mcp-name: io.github.o/hello");
+    expect(text).toContain("<!-- tf:mcp-name --><!-- /tf:mcp-name -->");
+    expect(text).toContain("`npx -y hello mcp`");
+    expect(check(root, plan(false), "0.1.0")).toEqual([]);
+  });
+
+  it("check reports a missing region marker as unmarked", () => {
+    const root = tmp();
+    mkdirSync(root, { recursive: true });
+    writeFileSync(join(root, "SKILL.md"), "# Title\n\nNo markers in this file at all.\n");
+    expect(check(root, [regionPlan("- op-a\n")], "0.1.0")).toEqual([
+      { path: "SKILL.md", kind: "unmarked" },
+    ]);
+  });
+});
+
+describe("apply / check — merge files", () => {
+  it("merges a JSON patch, keeping keys it does not own", () => {
+    const root = tmp();
+    mkdirSync(root, { recursive: true });
+    writeFileSync(
+      join(root, "package.json"),
+      JSON.stringify({ name: "old", scripts: { test: "vitest" } }, null, 2),
+    );
+    const plan: MergeFile[] = [
+      {
+        kind: "merge",
+        path: "package.json",
+        format: "json",
+        patch: { name: "hello", version: "0.1.0" },
+      },
+    ];
+    apply(root, plan, "0.1.0");
+    const document = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    expect(document).toEqual({ name: "hello", scripts: { test: "vitest" }, version: "0.1.0" });
+    expect(check(root, plan, "0.1.0")).toEqual([]);
+  });
+
+  it("replaces an owned object whole, so a renamed key does not leave its old name behind", () => {
+    const root = tmp();
+    mkdirSync(root, { recursive: true });
+    const bin = (name: string): MergeFile[] => [
+      {
+        kind: "merge",
+        path: "package.json",
+        format: "json",
+        patch: { name, bin: { [name]: "./dist/cli.js" } },
+        owned: ["bin"],
+      },
+    ];
+    apply(root, bin("hello"), "0.1.0");
+    apply(root, bin("renamed"), "0.1.0");
+    const document = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    expect(document.bin).toEqual({ renamed: "./dist/cli.js" });
+    writeFileSync(
+      join(root, "package.json"),
+      JSON.stringify({ ...document, bin: { ...document.bin, stale: "./x" } }),
+    );
+    expect(check(root, bin("renamed"), "0.1.0")).toEqual([
+      { path: "package.json", kind: "changed" },
+    ]);
+  });
+
+  it("round-trips a TOML patch, merging into and preserving existing content", () => {
+    const root = tmp();
+    mkdirSync(root, { recursive: true });
+    writeFileSync(
+      join(root, "pyproject.toml"),
+      '[project]\nname = "old"\ndependencies = ["zod"]\n',
+    );
+    const plan: MergeFile[] = [
+      {
+        kind: "merge",
+        path: "pyproject.toml",
+        format: "toml",
+        patch: { project: { name: "hello", version: "0.1.0" } },
+      },
+    ];
+    apply(root, plan, "0.1.0");
+    const text = readFileSync(join(root, "pyproject.toml"), "utf8");
+    expect(text).toContain('name = "hello"');
+    expect(text).toContain('version = "0.1.0"');
+    expect(text).toContain('dependencies = [ "zod" ]');
+    expect(check(root, plan, "0.1.0")).toEqual([]);
+  });
+});
+
+describe("apply / check — inverses and outputs", () => {
+  it("uninstalls the keys a patch stops writing, keeping every other key", () => {
+    const root = tmp();
+    mkdirSync(root, { recursive: true });
+    writeFileSync(
+      join(root, "package.json"),
+      JSON.stringify({ scripts: { test: "vitest" } }, null, 2),
+    );
+    const plan = (registry: boolean): MergeFile[] => [
+      {
+        kind: "merge",
+        path: "package.json",
+        format: "json",
+        patch: {
+          name: "hello",
+          ...(registry
+            ? { scripts: { smoke: "node smoke.js" }, mcpName: "io.github.o/hello", tf: { mark: 1 } }
+            : {}),
+        },
+      },
+    ];
+    apply(root, plan(true), "0.1.0");
+    expect(check(root, plan(false), "0.1.0")).toEqual([{ path: "package.json", kind: "changed" }]);
+    apply(root, plan(false), "0.1.0");
+    expect(JSON.parse(readFileSync(join(root, "package.json"), "utf8"))).toEqual({
+      name: "hello",
+      scripts: { test: "vitest" },
+    });
+    expect(check(root, plan(false), "0.1.0")).toEqual([]);
+  });
+
+  it("a merge file toolfactory stops writing loses its keys, not its existence", () => {
+    const root = tmp();
+    mkdirSync(root, { recursive: true });
+    writeFileSync(
+      join(root, "package.json"),
+      JSON.stringify({ scripts: { test: "vitest" } }, null, 2),
+    );
+    const plan: MergeFile[] = [
+      { kind: "merge", path: "package.json", format: "json", patch: { name: "hello" } },
+    ];
+    apply(root, plan, "0.1.0");
+    expect(check(root, [], "0.1.0")).toEqual([{ path: "package.json", kind: "orphan" }]);
+    expect(apply(root, [], "0.1.0").deleted).toEqual([]);
+    expect(JSON.parse(readFileSync(join(root, "package.json"), "utf8"))).toEqual({
+      scripts: { test: "vitest" },
+    });
+  });
+
+  it("an output file is drift only when it is present and stale", () => {
+    const root = tmp();
+    const path = "dev.toolfactory/coverage.json";
+    const plan: PlannedFile[] = [{ kind: "file", path, content: "{}\n", output: true }];
+    apply(root, plan, "0.1.0");
+    rmSync(join(root, path));
+    expect(check(root, plan, "0.1.0")).toEqual([]);
+    writeFileSync(join(root, path), "stale\n");
+    expect(check(root, plan, "0.1.0")).toEqual([{ path, kind: "changed" }]);
+  });
+
+  it("refuses a selection that omits a surface another one declares it requires", () => {
+    const project = { root: tmp(), tool: { surfaces: ["cli", "web"] } } as unknown as Project;
+    expect(() => buildPlan(project)).toThrow(/Surface "web" requires surface "mcp"/);
+  });
+});