toolfactory 0.1.1

package/dist/project/apply.js

@@ -0,0 +1,360 @@
+/**
+ * The one writer and the one differ. A plan is a list of files; applying it writes
+ * generated files, keeps `manual` (adopted) files untouched, refreshes managed regions
+ * inside author-owned files, merges owned keys into shared structured files, deletes
+ * orphans, and records SHAs in the lock file. Every kind carries its own inverse: a region file
+ * its markers, a full file its path, a merge file the key paths recorded in the lock.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { LOCK_PATH, readLock, serializeLock, sha256 } from "./lock.js";
+function locate(text, region) {
+    const start = text.indexOf(region.begin);
+    if (start < 0)
+        return undefined;
+    const end = text.indexOf(region.end, start + region.begin.length);
+    if (end < 0)
+        return undefined;
+    return { start: start + region.begin.length, end };
+}
+export function extractRegions(text, file) {
+    const parts = [];
+    for (const region of file.regions) {
+        const at = locate(text, region);
+        if (!at)
+            return undefined;
+        parts.push(text.slice(at.start, at.end));
+    }
+    return parts;
+}
+export function replaceRegions(text, file) {
+    let next = text;
+    for (const region of file.regions) {
+        const at = locate(next, region);
+        if (!at)
+            return undefined;
+        next = next.slice(0, at.start) + region.content + next.slice(at.end);
+    }
+    return next;
+}
+/** A region file's inverse: the named regions blanked, their markers and the author's bytes kept. */
+function emptyRegions(text, markers) {
+    return replaceRegions(text, { regions: markers.map((region) => ({ ...region, content: "" })) });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Objects merge key by key, except the paths a merge file owns whole, which are replaced. */
+export function deepMerge(base, patch, owned = [], prefix = "") {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        out[key] =
+            isRecord(value) && isRecord(out[key]) && !owned.includes(path)
+                ? deepMerge(out[key], value, owned, path)
+                : value;
+    }
+    return out;
+}
+/** The values a merge file owns, read back out of a document; an owned object comes back whole. */
+export function pickPatch(document, patch, owned = [], prefix = "") {
+    const out = {};
+    for (const [key, value] of Object.entries(patch)) {
+        const current = document[key];
+        const path = prefix ? `${prefix}.${key}` : key;
+        out[key] =
+            isRecord(value) && isRecord(current) && !owned.includes(path)
+                ? pickPatch(current, value, owned, path)
+                : current;
+    }
+    return out;
+}
+/** The dotted paths a patch writes: one per leaf value, and one per object it owns whole. */
+export function patchKeys(patch, owned = [], prefix = "") {
+    const keys = [];
+    for (const [key, value] of Object.entries(patch)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (isRecord(value) && !owned.includes(path) && Object.keys(value).length > 0) {
+            keys.push(...patchKeys(value, owned, path));
+        }
+        else {
+            keys.push(path);
+        }
+    }
+    return keys;
+}
+function walk(document, key) {
+    const chain = [document];
+    let node = document;
+    for (const part of key.split(".").slice(0, -1)) {
+        node = node[part];
+        if (!isRecord(node))
+            return chain;
+        chain.push(node);
+    }
+    return chain;
+}
+function hasKey(document, key) {
+    const parts = key.split(".");
+    const chain = walk(document, key);
+    return chain.length === parts.length && parts.at(-1) in chain.at(-1);
+}
+/** Uninstall dotted paths from a document, pruning the objects the removal empties. */
+export function removeKeys(document, keys) {
+    let removed = false;
+    for (const key of keys) {
+        if (!hasKey(document, key))
+            continue;
+        const parts = key.split(".");
+        const chain = walk(document, key);
+        delete chain.at(-1)[parts.at(-1)];
+        removed = true;
+        for (let depth = chain.length - 1; depth > 0; depth--) {
+            if (Object.keys(chain[depth]).length > 0)
+                break;
+            delete chain[depth - 1][parts[depth - 1]];
+        }
+    }
+    return removed;
+}
+function parseDocument(text, format) {
+    return (format === "toml" ? parseToml(text) : JSON.parse(text));
+}
+function serializeDocument(document, format) {
+    return format === "toml"
+        ? `${stringifyToml(document)}\n`
+        : `${JSON.stringify(document, null, 2)}\n`;
+}
+/** The content toolfactory manages, as one string for hashing and comparison. */
+export function managedContent(file) {
+    if (file.kind === "file")
+        return file.content;
+    if (file.kind === "region")
+        return file.regions.map((r) => r.content).join(" ");
+    return JSON.stringify(file.patch);
+}
+/** A symbolic link's managed content is its target; every other kind's is what it holds. */
+function isLink(file) {
+    return file.kind === "file" && file.symlink === true;
+}
+function currentManagedContent(root, file) {
+    const path = join(root, file.path);
+    if (isLink(file)) {
+        const entry = lstatSync(path, { throwIfNoEntry: false });
+        // A regular file or directory standing where the link belongs matches no target: it is drift.
+        return entry && (entry.isSymbolicLink() ? readlinkSync(path) : "");
+    }
+    if (!existsSync(path))
+        return undefined;
+    const text = readFileSync(path, "utf8");
+    if (file.kind === "file")
+        return text;
+    if (file.kind === "region")
+        return extractRegions(text, file)?.join(" ");
+    return JSON.stringify(pickPatch(parseDocument(text, file.format), file.patch, file.owned));
+}
+/** The two structured formats merge files use; the extension is the only discriminator needed. */
+function documentFormat(path) {
+    return path.endsWith(".toml") ? "toml" : "json";
+}
+/** The keys the lock recorded for a path that the current patch no longer writes. */
+function staleKeys(lock, path, current = []) {
+    return (lock.files[path]?.keys ?? []).filter((key) => !current.includes(key));
+}
+/** Whether any uninstalled key is still in the document — the only reason to touch a merge file. */
+function stranded(root, path, keys) {
+    if (keys.length === 0 || !existsSync(join(root, path)))
+        return false;
+    const document = parseDocument(readFileSync(join(root, path), "utf8"), documentFormat(path));
+    return keys.some((key) => hasKey(document, key));
+}
+/** The marker pairs the lock recorded for a path that the current plan no longer writes. */
+function staleRegions(lock, path, current = []) {
+    return (lock.files[path]?.regions ?? []).filter((region) => !current.some((planned) => planned.begin === region.begin));
+}
+/** Whether any uninstalled region still carries content — the only reason to touch a region file. */
+function filled(root, path, markers) {
+    if (markers.length === 0 || !existsSync(join(root, path)))
+        return false;
+    const parts = extractRegions(readFileSync(join(root, path), "utf8"), { regions: markers });
+    return parts?.some((part) => part.trim() !== "") === true;
+}
+/** lstat, not stat: a dangling symlink (its target just deleted) is still present and still ours. */
+function present(root, path) {
+    return lstatSync(join(root, path), { throwIfNoEntry: false }) !== undefined;
+}
+/** Compare a plan to the tree without writing. */
+export function check(root, plan, toolfactoryVersion) {
+    const lock = readLock(root) ?? { toolfactoryVersion, files: {} };
+    const drift = [];
+    const planned = new Set(plan.map((file) => file.path));
+    for (const file of plan) {
+        if (lock.files[file.path]?.state === "manual")
+            continue;
+        const current = currentManagedContent(root, file);
+        if (current === undefined) {
+            // An output file is rebuilt, not tracked: absent is not drift, only stale is.
+            if (file.kind === "file" && file.output)
+                continue;
+            drift.push({
+                path: file.path,
+                kind: existsSync(join(root, file.path)) ? "unmarked" : "missing",
+            });
+        }
+        else if (current !== managedContent(file)) {
+            drift.push({ path: file.path, kind: "changed" });
+        }
+        else if (file.kind === "merge" &&
+            stranded(root, file.path, staleKeys(lock, file.path, patchKeys(file.patch, file.owned)))) {
+            drift.push({ path: file.path, kind: "changed" });
+        }
+        else if (file.kind === "region" &&
+            filled(root, file.path, staleRegions(lock, file.path, file.regions))) {
+            drift.push({ path: file.path, kind: "changed" });
+        }
+    }
+    for (const path of Object.keys(lock.files)) {
+        const entry = lock.files[path];
+        if (planned.has(path) || entry?.state !== "generated" || !present(root, path))
+            continue;
+        // A merge file toolfactory stops writing loses its keys, not its existence.
+        if (entry.keys && !stranded(root, path, entry.keys))
+            continue;
+        // A region file likewise loses its regions: once they are empty, nothing of ours is stranded.
+        if (entry.regions && !filled(root, path, entry.regions))
+            continue;
+        drift.push({ path, kind: "orphan" });
+    }
+    return drift;
+}
+function render(root, file, previous) {
+    const path = join(root, file.path);
+    if (file.kind === "file")
+        return file.content;
+    if (file.kind === "region") {
+        if (existsSync(path)) {
+            const text = readFileSync(path, "utf8");
+            // The region inverse first: a marker pair a previous plan wrote and this one dropped — a
+            // shared file that lost one of its owners — is emptied before the current regions are filled.
+            const stale = staleRegions(previous, file.path, file.regions);
+            const replaced = replaceRegions(emptyRegions(text, stale) ?? text, file);
+            if (replaced === undefined) {
+                throw new Error(`${file.path} exists but is missing a toolfactory region marker; restore the markers or run \`toolfactory adopt ${file.path}\`.`);
+            }
+            return replaced;
+        }
+        return replaceRegions(file.template, file) ?? file.template;
+    }
+    if (!existsSync(path))
+        return serializeDocument(deepMerge({}, file.patch), file.format);
+    const text = readFileSync(path, "utf8");
+    const document = parseDocument(text, file.format);
+    // The patch's inverse first: keys a previous patch wrote and this one dropped are uninstalled.
+    const uninstalled = removeKeys(document, staleKeys(previous, file.path, patchKeys(file.patch, file.owned)));
+    // A document that already carries the patch is left byte-for-byte alone, so a rebuild never
+    // reserializes the author's file (and, for TOML, never drops their comments).
+    if (!uninstalled &&
+        JSON.stringify(pickPatch(document, file.patch, file.owned)) === JSON.stringify(file.patch)) {
+        return text;
+    }
+    return serializeDocument(deepMerge(document, file.patch, file.owned), file.format);
+}
+/** Write a plan to the tree and refresh the lock. */
+export function apply(root, plan, toolfactoryVersion) {
+    const previous = readLock(root) ?? { toolfactoryVersion, files: {} };
+    const lock = { toolfactoryVersion, files: {} };
+    const result = {
+        written: [],
+        deleted: [],
+        unchanged: [],
+        manual: [],
+        stripped: [],
+    };
+    for (const file of plan) {
+        const state = previous.files[file.path]?.state ?? "generated";
+        const path = join(root, file.path);
+        if (state === "manual") {
+            lock.files[file.path] = { sha256: previous.files[file.path]?.sha256 ?? "", state };
+            result.manual.push(file.path);
+            continue;
+        }
+        const keys = file.kind === "merge" ? patchKeys(file.patch, file.owned) : undefined;
+        const regions = file.kind === "region" ? file.regions.map(({ begin, end }) => ({ begin, end })) : undefined;
+        if (isLink(file)) {
+            if (currentManagedContent(root, file) === managedContent(file)) {
+                result.unchanged.push(file.path);
+            }
+            else {
+                mkdirSync(dirname(path), { recursive: true });
+                // Whatever stands there — a stale link, or a real file or directory — makes way for the link.
+                rmSync(path, { recursive: true, force: true });
+                symlinkSync(managedContent(file), path);
+                result.written.push(file.path);
+            }
+        }
+        else {
+            const next = render(root, file, previous);
+            if (existsSync(path) && readFileSync(path, "utf8") === next) {
+                result.unchanged.push(file.path);
+            }
+            else {
+                mkdirSync(dirname(path), { recursive: true });
+                writeFileSync(path, next, { mode: file.kind === "file" ? file.mode : undefined });
+                result.written.push(file.path);
+            }
+        }
+        lock.files[file.path] = {
+            sha256: sha256(managedContent(file)),
+            state: "generated",
+            keys,
+            regions,
+        };
+    }
+    for (const [path, entry] of Object.entries(previous.files)) {
+        if (lock.files[path])
+            continue;
+        if (entry.state === "manual") {
+            lock.files[path] = entry;
+            continue;
+        }
+        if (!present(root, path))
+            continue;
+        if (entry.keys) {
+            // The inverse of a merge file is its keys: the author keeps the file and everything else in it.
+            const format = documentFormat(path);
+            const document = parseDocument(readFileSync(join(root, path), "utf8"), format);
+            if (removeKeys(document, entry.keys)) {
+                writeFileSync(join(root, path), serializeDocument(document, format));
+                result.written.push(path);
+            }
+            continue;
+        }
+        if (entry.regions) {
+            // The inverse of a region file is its markers: the author keeps the file, the markers, and
+            // every byte outside them, so re-selecting the surface refills them with no further code.
+            const text = readFileSync(join(root, path), "utf8");
+            const emptied = emptyRegions(text, entry.regions);
+            // Markers already gone: nothing of ours is left to uninstall.
+            if (emptied === undefined || emptied === text)
+                continue;
+            writeFileSync(join(root, path), emptied);
+            result.stripped.push(path);
+            continue;
+        }
+        rmSync(join(root, path));
+        result.deleted.push(path);
+    }
+    const lockPath = join(root, LOCK_PATH);
+    mkdirSync(dirname(lockPath), { recursive: true });
+    writeFileSync(lockPath, serializeLock(lock));
+    return result;
+}
+export function setState(root, path, state, toolfactoryVersion) {
+    const lock = readLock(root) ?? { toolfactoryVersion, files: {} };
+    const entry = lock.files[path];
+    if (!entry)
+        throw new Error(`${path} is not a toolfactory-managed file.`);
+    lock.files[path] = { ...entry, state };
+    writeFileSync(join(root, LOCK_PATH), serializeLock(lock));
+}

package/dist/project/apply.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/project/apply.test.js

@@ -0,0 +1,285 @@
+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 { apply, check, setState } from "./apply.js";
+import { buildPlan } from "./plan.js";
+function tmp() {
+    return mkdtempSync(join(tmpdir(), "tf-apply-"));
+}
+function regionPlan(content) {
+    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 = [{ 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 = [{ 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 = [{ 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 = [{ 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 = [
+            { kind: "file", path: "a.txt", content: "a\n" },
+            { kind: "file", path: "b.txt", content: "b\n" },
+        ];
+        apply(root, planA, "0.1.0");
+        const planB = [{ 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 = {
+            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) => [
+            {
+                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 = [
+            {
+                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) => [
+            {
+                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 = [
+            {
+                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) => [
+            {
+                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 = [
+            { 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 = [{ 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"] } };
+        expect(() => buildPlan(project)).toThrow(/Surface "web" requires surface "mcp"/);
+    });
+});