@imenam/mcp-documentor 1.0.71 → 1.0.74

package/dist/src/core/git-sync.js

@@ -1,5 +1,7 @@
+import { execFile } from "child_process";
 import fs from "fs";
 import path from "path";
+import { fileURLToPath } from "url";
 import { simpleGit } from "simple-git";
 import { createLogger } from "@imenam/mcp-gui-interface";
 const logger = createLogger("GitSync");
@@ -20,6 +22,22 @@ const GITIGNORE_CONTENT = [
     "local-state.json",
     "",
 ].join("\n");
+/**
+ * Routes the two file kinds that both machines write concurrently to structured
+ * merge drivers. Versioned, so every clone gets the routing; the drivers
+ * themselves are registered per-machine by ensureMergeDrivers(). A clone without
+ * them just falls back to git's default text merge.
+ */
+const GITATTRIBUTES_CONTENT = [
+    "# Structured merges - drivers registered by SyncEngine.ensureMergeDrivers()",
+    "projects/**/*.md merge=mcpdoc",
+    "config.json merge=mcpdocjson",
+    "",
+].join("\n");
+const MERGE_DRIVERS = [
+    { name: "mcpdoc", script: "merge-doc.js", label: "mcp-documentor documentation merge" },
+    { name: "mcpdocjson", script: "merge-config.js", label: "mcp-documentor config merge" },
+];
 export class SyncEngine {
     storage;
     git;
@@ -61,6 +79,35 @@ export class SyncEngine {
         }
         return cfg;
     }
+    /**
+     * Registers the structured merge drivers in .git/config, which git never
+     * versions - so this runs on every machine, not just the one that created the
+     * repo. Values are absolute paths to the shipped scripts; git invokes them
+     * through a shell, hence the quoting and the forward slashes on Windows.
+     */
+    async ensureMergeDrivers() {
+        const driverDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "merge-drivers");
+        const node = process.execPath.replace(/\\/g, "/");
+        for (const driver of MERGE_DRIVERS) {
+            const script = path.join(driverDir, driver.script).replace(/\\/g, "/");
+            const command = `"${node}" "${script}" %O %A %B %P`;
+            // `git config --get` exits 1 when the key is unset - that is the "not
+            // registered yet" case, not an error.
+            const current = await this.gitDirect(["config", "--local", "--get", `merge.${driver.name}.driver`]);
+            if (current.stdout === command)
+                continue;
+            await this.gitDirect(["config", "--local", `merge.${driver.name}.name`, driver.label]);
+            const set = await this.gitDirect(["config", "--local", `merge.${driver.name}.driver`, command]);
+            if (set.ok) {
+                logger.info(`Registered merge driver "${driver.name}" -> ${script}`);
+            }
+            else {
+                // Without the driver git falls back to its default text merge: more
+                // conflicts, but nothing broken. Not worth failing every sync over.
+                logger.warn(`Could not register merge driver "${driver.name}": ${set.stderr}`);
+            }
+        }
+    }
     /**
      * Ensures the data dir is a git repo with a .gitignore and an authenticated
      * origin. The token is stored only in .git/config (which git never commits),
@@ -74,10 +121,18 @@ export class SyncEngine {
         if (!fs.existsSync(gitignorePath)) {
             fs.writeFileSync(gitignorePath, GITIGNORE_CONTENT, "utf-8");
         }
+        // Rewritten when it drifts, so an upgraded server updates the routing of
+        // repos that were initialized by an older version.
+        const attributesPath = path.join(this.dataDir, ".gitattributes");
+        const currentAttributes = fs.existsSync(attributesPath) ? fs.readFileSync(attributesPath, "utf-8") : "";
+        if (currentAttributes !== GITATTRIBUTES_CONTENT) {
+            fs.writeFileSync(attributesPath, GITATTRIBUTES_CONTENT, "utf-8");
+        }
         if (!fs.existsSync(path.join(this.dataDir, ".git"))) {
             await this.git.init();
             logger.info(`Initialized git repo in ${this.dataDir}`);
         }
+        await this.ensureMergeDrivers();
         // (Re)point origin at the authenticated URL.
         const remotes = await this.git.getRemotes(true);
         const origin = remotes.find((r) => r.name === "origin");
@@ -87,14 +142,18 @@ export class SyncEngine {
         else if (origin.refs.fetch !== authed) {
             await this.git.remote(["set-url", "origin", authed]);
         }
-        // Make sure we're on the configured branch.
-        const branches = await this.git.branchLocal();
-        if (branches.current !== cfg.branch) {
-            try {
-                await this.git.checkoutLocalBranch(cfg.branch);
-            }
-            catch {
-                await this.git.checkout(cfg.branch);
+        // Make sure we're on the configured branch - unless an operation is in
+        // flight, where a detached HEAD is the expected state and checking the
+        // branch back out would abort the rebase git is halfway through.
+        if ((await this.operationInProgress()) === "none") {
+            const branches = await this.git.branchLocal();
+            if (branches.current !== cfg.branch) {
+                try {
+                    await this.git.checkoutLocalBranch(cfg.branch);
+                }
+                catch {
+                    await this.git.checkout(cfg.branch);
+                }
             }
         }
     }
@@ -103,6 +162,7 @@ export class SyncEngine {
         const s = await this.git.status();
         return {
             branch: s.current ?? "",
+            operation: await this.operationInProgress(),
             ahead: s.ahead,
             behind: s.behind,
             dirty: s.files.map((f) => f.path),
@@ -110,12 +170,21 @@ export class SyncEngine {
         };
     }
     /**
-     * Defensive pull: only fast-forwards a clean working tree. Never auto-merges
-     * a divergent history, so local data is never silently overwritten.
+     * Defensive pull. A clean tree that is purely behind fast-forwards; a
+     * divergent one is rebased, so local commits replay on top of the remote and
+     * the history stays linear - which is what makes per-doc `git log` attribution
+     * readable when reporting who changed what. An uncommitted local change is
+     * never risked: the pull reports the divergence and applies nothing.
      */
     async pull() {
         const cfg = this.requireConfig();
         await this.ensureRepo();
+        // A merge or rebase left half-finished would otherwise look like a dirty
+        // tree and be reported as a plain divergence.
+        if ((await this.operationInProgress()) !== "none") {
+            const pending = await this.git.status();
+            return { status: "conflict", conflicted: pending.conflicted };
+        }
         await this.git.fetch("origin", cfg.branch);
         const remoteRef = `refs/remotes/origin/${cfg.branch}`;
         // No remote branch yet (fresh repo) — nothing to pull.
@@ -136,80 +205,262 @@ export class SyncEngine {
         }
         // Ensure upstream tracking so status ahead/behind is meaningful.
         await this.git.branch(["--set-upstream-to", `origin/${cfg.branch}`, cfg.branch]).catch(() => { });
-        const status = await this.git.status();
-        if (status.behind === 0)
+        let status = await this.git.status();
+        if (status.behind === 0 && status.files.length === 0)
             return { status: "up-to-date" };
-        // Uncommitted local changes block a safe merge — never risk clobbering them.
-        // Surface as diverged so the user commits/pushes (or stashes) first.
-        if (status.files.length > 0) {
-            return { status: "diverged", ahead: status.ahead, behind: status.behind };
-        }
+        // Uncommitted local edits cannot be rebased over, and reporting the
+        // divergence instead used to strand the caller: the pull asked for a push,
+        // which the remote rejected and which asked for a pull. Committing them
+        // resolves it - the edits become a commit the rebase can replay, nothing is
+        // published, and nothing can be clobbered.
+        const autoCommitted = status.files.length > 0 ? await this.commitLocalChanges() : false;
+        if (autoCommitted)
+            status = await this.git.status();
         const before = await this.git.revparse(["HEAD"]).catch(() => "");
         // Pure behind → fast-forward.
         if (status.ahead === 0) {
             await this.git.merge(["--ff-only", `origin/${cfg.branch}`]);
             const after = await this.git.revparse(["HEAD"]).catch(() => "");
-            return { status: "updated", changed: await this.diffNames(before, after) };
+            return { status: "updated", changed: await this.diffNames(before, after), autoCommitted };
         }
-        // Diverged with a clean tree → attempt a real merge. A conflict stops with
-        // markers in place (both versions preserved) so it can be resolved + pushed.
+        // Diverged with a clean tree → replay local commits on top of the remote. A
+        // conflict stops the rebase with both versions preserved in the index, so it
+        // can be resolved and the rebase continued.
         try {
-            await this.git.merge([`origin/${cfg.branch}`]);
+            await this.git.raw(["rebase", `origin/${cfg.branch}`]);
         }
         catch {
             const after = await this.git.status();
             if (after.conflicted.length > 0)
-                return { status: "conflict", conflicted: after.conflicted };
-            throw new Error("Merge failed without recorded conflicts. Resolve manually in the data directory.");
+                return { status: "conflict", conflicted: after.conflicted, autoCommitted };
+            throw new Error("Rebase failed without recorded conflicts. Inspect the data directory, or run `git rebase --abort` there to get back to the previous state.");
         }
-        const merged = await this.git.revparse(["HEAD"]).catch(() => "");
-        return { status: "updated", changed: await this.diffNames(before, merged) };
+        const rebased = await this.git.revparse(["HEAD"]).catch(() => "");
+        return { status: "updated", changed: await this.diffNames(before, rebased), autoCommitted };
     }
     async diffNames(before, after) {
         if (!before || !after || before === after)
             return [];
         return (await this.git.raw(["diff", "--name-only", before, after])).split("\n").filter(Boolean);
     }
+    /**
+     * Stages and commits whatever the working tree holds. Committing is what makes
+     * local edits safe to rebase over, so both push and pull go through here
+     * rather than asking the caller to tidy up first.
+     *
+     * .gitignore (written by ensureRepo) excludes all derived and machine-local
+     * state, so `add -A` only ever stages versioned files.
+     */
+    async commitLocalChanges(message) {
+        await this.git.add(["-A"]);
+        const status = await this.git.status();
+        const hasWork = status.staged.length > 0 || status.created.length > 0 || status.deleted.length > 0 || status.modified.length > 0;
+        if (!hasWork)
+            return false;
+        const machine = process.env.COMPUTERNAME || process.env.HOSTNAME || "unknown-machine";
+        await this.git.commit(message?.trim() || `docs sync from ${machine} · ${new Date().toISOString()}`);
+        return true;
+    }
     /** Stages versioned files, commits if there is anything to commit, and pushes. */
     async push(message) {
         const cfg = this.requireConfig();
         await this.ensureRepo();
-        // .gitignore (written by ensureRepo) excludes all derived/local state,
-        // so -A safely stages only versioned files (projects/, config.json, .gitignore).
-        await this.git.add(["-A"]);
-        const status = await this.git.status();
-        let committed = false;
-        if (status.staged.length > 0 || status.created.length > 0 || status.deleted.length > 0 || status.modified.length > 0) {
-            const machine = process.env.COMPUTERNAME || process.env.HOSTNAME || "unknown-machine";
-            const msg = message?.trim() || `docs sync from ${machine} · ${new Date().toISOString()}`;
-            await this.git.commit(msg);
-            committed = true;
+        // `add -A` would happily stage conflict markers and commit them as content,
+        // so an unfinished merge or rebase has to stop the push outright.
+        const operation = await this.operationInProgress();
+        const pending = await this.git.status();
+        if (operation !== "none" || pending.conflicted.length > 0) {
+            throw new Error(`A ${operation === "none" ? "conflict" : operation} is still unresolved (${pending.conflicted.length} conflicted file(s)). ` +
+                "Resolve it with resolve_sync_conflict before pushing, otherwise the conflict markers would be committed as documentation content.");
         }
+        const committed = await this.commitLocalChanges(message);
         try {
             await this.git.push(["-u", "origin", `HEAD:${cfg.branch}`]);
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
             if (/fetch first|non-fast-forward|\[rejected\]/i.test(msg)) {
-                throw new Error("Push rejected: the remote has commits you don't have locally. Run pull_docs to integrate them, then push again.");
+                throw new Error("Push rejected: the remote has commits you don't have locally. Run sync_docs, which integrates them and pushes in one step.");
             }
             throw e;
         }
         return { pushed: true, committed, message: committed ? "Committed and pushed." : "Nothing new to commit; pushed existing commits." };
     }
-    /** Bulk-resolve conflicts by taking one side, then stage the resolved files. */
-    async resolveConflict(strategy, paths) {
+    /**
+     * Detects whether a merge or a rebase is mid-flight. Read through
+     * `rev-parse --git-path` rather than assuming `.git` is a directory, so this
+     * still works in a worktree or a submodule.
+     */
+    async operationInProgress() {
+        const marker = async (name) => {
+            const rel = await this.git.raw(["rev-parse", "--git-path", name]).catch(() => "");
+            if (!rel.trim())
+                return false;
+            return fs.existsSync(path.resolve(this.dataDir, rel.trim()));
+        };
+        if ((await marker("rebase-merge")) || (await marker("rebase-apply")))
+            return "rebase";
+        if (await marker("MERGE_HEAD"))
+            return "merge";
+        return "none";
+    }
+    /** Index stages recorded for a conflicted path: 1 = base, 2 = ours, 3 = theirs. */
+    async conflictStages(filePath) {
+        const out = await this.git.raw(["ls-files", "-u", "--", filePath]).catch(() => "");
+        const stages = new Set();
+        for (const line of out.split("\n")) {
+            const match = line.match(/^\S+ \S+ (\d)\t/);
+            if (match)
+                stages.add(Number(match[1]));
+        }
+        return stages;
+    }
+    /**
+     * Finishes the in-flight merge or rebase once every conflict is staged.
+     * A rebase can stop again on the next replayed commit, so the caller is told
+     * what is still outstanding rather than being promised completion.
+     *
+     * `git rebase --continue` insists on an editor for the replayed commit
+     * message, and simple-git blocks both `-c core.editor` and GIT_EDITOR as
+     * injection vectors. This one command therefore goes out directly with a no-op
+     * editor - the value is a fixed literal here, never user input.
+     */
+    async continueOperation() {
+        const operation = await this.operationInProgress();
+        if (operation === "none")
+            return { operation, done: true, remaining: [] };
+        const before = await this.git.status();
+        if (before.conflicted.length > 0) {
+            return { operation, done: false, remaining: before.conflicted };
+        }
+        // A rebase legitimately stops again on the next commit's conflicts, so a
+        // non-zero exit is not necessarily a failure - the state read back below is
+        // the real report.
+        const run = await this.gitDirect(operation === "rebase" ? ["rebase", "--continue"] : ["commit", "--no-edit"], {
+            GIT_EDITOR: "true",
+        });
+        const error = run.ok ? undefined : run.stderr;
+        const still = await this.operationInProgress();
+        const after = await this.git.status();
+        const done = still === "none";
+        return { operation, done, remaining: after.conflicted, ...(!done && error ? { error } : {}) };
+    }
+    /**
+     * Runs one git command outside simple-git, which rejects a handful of config
+     * keys and environment variables as injection vectors - merge.*.driver and
+     * GIT_EDITOR among them. Everything passed here is a fixed literal or a path
+     * derived from the install location, never agent or user input.
+     */
+    gitDirect(args, env = {}) {
+        return new Promise((resolve) => {
+            execFile("git", args, { cwd: this.dataDir, env: { ...process.env, ...env } }, (error, stdout, stderr) => resolve({ ok: !error, stdout: stdout.trim(), stderr: (stderr || error?.message || "").trim() }));
+        });
+    }
+    /**
+     * The refs holding each side during the operation in flight. A rebase replays
+     * our commits onto the remote, so HEAD is the *remote* there - the mapping
+     * that makes every side label absolute.
+     */
+    sideRefs(operation) {
+        return operation === "rebase"
+            ? { local: "REBASE_HEAD", remote: "HEAD" }
+            : { local: "HEAD", remote: "MERGE_HEAD" };
+    }
+    async lastCommitFor(ref, filePath) {
+        const out = await this.git
+            .raw(["log", "-1", "--format=%an%x00%aI%x00%s", ref, "--", filePath])
+            .catch(() => "");
+        const [author, date, subject] = out.trim().split("\u0000");
+        return author ? { author, date: date ?? "", subject: subject ?? "" } : undefined;
+    }
+    /**
+     * Every conflicted file with its shape and its two authors - enough for the
+     * agent to decide what to look at without opening a single document.
+     */
+    async listConflicts() {
         this.requireConfig();
+        const operation = await this.operationInProgress();
+        const status = await this.git.status();
+        const refs = this.sideRefs(operation);
+        const localStage = operation === "rebase" ? 3 : 2;
+        const files = [];
+        for (const filePath of status.conflicted) {
+            const stages = await this.conflictStages(filePath);
+            let kind = "content";
+            let deletedOn;
+            if (!stages.has(1)) {
+                kind = "add-add";
+            }
+            else if (!stages.has(2) || !stages.has(3)) {
+                kind = "delete-modify";
+                const missing = stages.has(2) ? 3 : 2;
+                deletedOn = missing === localStage ? "local" : "remote";
+            }
+            files.push({
+                path: filePath,
+                kind,
+                ...(deletedOn ? { deletedOn } : {}),
+                local: await this.lastCommitFor(refs.local, filePath),
+                remote: await this.lastCommitFor(refs.remote, filePath),
+            });
+        }
+        return { operation, files };
+    }
+    /** Reads a conflicted file from the working tree, refusing to escape the data dir. */
+    readWorkingFile(relativePath) {
+        const absolute = path.resolve(this.dataDir, relativePath);
+        if (!absolute.startsWith(path.resolve(this.dataDir))) {
+            throw new Error(`Path "${relativePath}" is outside the documentation data directory.`);
+        }
+        if (!fs.existsSync(absolute))
+            throw new Error(`File "${relativePath}" does not exist.`);
+        return fs.readFileSync(absolute, "utf-8");
+    }
+    /** Writes a resolved file back and stages it when nothing is left conflicted in it. */
+    async writeResolvedFile(relativePath, content, stage) {
+        const absolute = path.resolve(this.dataDir, relativePath);
+        if (!absolute.startsWith(path.resolve(this.dataDir))) {
+            throw new Error(`Path "${relativePath}" is outside the documentation data directory.`);
+        }
+        fs.writeFileSync(absolute, content, "utf-8");
+        if (stage)
+            await this.git.add([relativePath]);
+    }
+    /**
+     * Bulk-resolve conflicts by keeping one side, then stage the result.
+     *
+     * The git flag depends on the operation in flight: a merge replays the remote
+     * onto our branch (--ours = local), while a rebase replays our commits onto
+     * the remote (--ours = remote). Picking the flag from the strategy alone would
+     * silently keep the wrong side under rebase.
+     */
+    async resolveConflict(side, paths) {
+        this.requireConfig();
+        const operation = await this.operationInProgress();
         const status = await this.git.status();
         const targets = paths && paths.length > 0 ? paths : status.conflicted;
         if (targets.length === 0)
-            return [];
-        // During a merge, "ours" = current branch (mine), "theirs" = incoming.
-        const sideFlag = strategy === "mine" ? "--ours" : "--theirs";
-        for (const p of targets) {
-            await this.git.raw(["checkout", sideFlag, "--", p]);
-            await this.git.add([p]);
+            return { resolved: [], operation };
+        const localFlag = operation === "rebase" ? "--theirs" : "--ours";
+        const remoteFlag = operation === "rebase" ? "--ours" : "--theirs";
+        const sideFlag = side === "local" ? localFlag : remoteFlag;
+        const wantedStage = sideFlag === "--ours" ? 2 : 3;
+        const resolved = [];
+        for (const filePath of targets) {
+            const stages = await this.conflictStages(filePath);
+            if (stages.size === 0)
+                continue;
+            if (stages.has(wantedStage)) {
+                await this.git.raw(["checkout", sideFlag, "--", filePath]);
+                await this.git.add([filePath]);
+            }
+            else {
+                // delete/modify conflict: the side we are keeping deleted the file, so
+                // there is nothing to check out - record the deletion instead.
+                await this.git.raw(["rm", "-f", "--", filePath]);
+            }
+            resolved.push(filePath);
         }
-        return targets;
+        return { resolved, operation };
     }
 }

package/dist/src/core/merge-drivers/merge-config.d.ts

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

package/dist/src/core/merge-drivers/merge-config.js

@@ -0,0 +1,68 @@
+/**
+ * Git merge driver for the versioned config.json.
+ *
+ * Invoked by git as: node merge-config.js %O %A %B
+ *
+ * The project list is shared state that both machines append to, so a textual
+ * merge conflicts on the JSON punctuation (a `union` merge would even produce
+ * invalid JSON). Merging the parsed structure instead means two machines that
+ * each create a project converge without any conflict, and the file stays valid
+ * by construction.
+ *
+ * Exit 0 = merged cleanly, exit 1 = conflicts remain.
+ */
+import fs from "fs";
+import { mergeScalar, mergeSet } from "./three-way.js";
+import { CLEAN, CONFLICT, read, fallback } from "./text-merge.js";
+function parse(text) {
+    if (text.trim() === "")
+        return {};
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function projects(config) {
+    return Array.isArray(config.projects) ? config.projects : [];
+}
+function main() {
+    const [basePath, oursPath, theirsPath] = process.argv.slice(2);
+    if (!oursPath || !theirsPath)
+        return CONFLICT;
+    const base = parse(read(basePath));
+    const ours = parse(read(oursPath));
+    const theirs = parse(read(theirsPath));
+    // Not the JSON we know how to reason about — don't guess.
+    if (!base || !ours || !theirs)
+        return fallback(basePath, oursPath, theirsPath);
+    // Key order mirrors StorageEngine.saveConfig so a merged file is byte-identical
+    // to what the next save would produce.
+    const result = { projects: mergeSet(projects(base), projects(ours), projects(theirs)) };
+    // A completed migration cannot be undone, so `true` absorbs a divergence
+    // instead of conflicting.
+    const migrated = mergeScalar(base.foldersMigrated, ours.foldersMigrated, theirs.foldersMigrated);
+    const migratedValue = migrated.conflict ? true : migrated.value;
+    if (migratedValue !== undefined)
+        result.foldersMigrated = migratedValue;
+    let conflicted = false;
+    for (const key of [...Object.keys(ours), ...Object.keys(theirs)]) {
+        if (key === "projects" || key === "foldersMigrated" || key in result)
+            continue;
+        const merged = mergeScalar(base[key], ours[key], theirs[key]);
+        if (merged.conflict) {
+            // An unknown key this driver has no rule for: keep ours and let the
+            // conflict surface rather than silently picking a side.
+            conflicted = true;
+            result[key] = merged.ours;
+        }
+        else if (merged.value !== undefined) {
+            result[key] = merged.value;
+        }
+    }
+    fs.writeFileSync(oursPath, JSON.stringify(result, null, 2), "utf-8");
+    return conflicted ? CONFLICT : CLEAN;
+}
+process.exit(main());

package/dist/src/core/merge-drivers/merge-doc.d.ts

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

package/dist/src/core/merge-drivers/merge-doc.js

@@ -0,0 +1,105 @@
+/**
+ * Git merge driver for documentation markdown files.
+ *
+ * Invoked by git as: node merge-doc.js %O %A %B %P
+ *   %O = common ancestor, %A = our version (MUST be overwritten with the result),
+ *   %B = their version, %P = the path being merged.
+ *
+ * Frontmatter is merged field by field with domain rules (updatedAt = latest,
+ * createdAt = earliest, list fields = 3-way set merge), so the bookkeeping
+ * metadata that every write touches never conflicts on its own. Only the body
+ * goes through git's textual merge.
+ *
+ * Exit 0 = merged cleanly, exit 1 = conflicts remain (markers are in the body).
+ */
+import fs from "fs";
+import matter from "gray-matter";
+import { mergeScalar, mergeSet, mergeKeyedList, laterDate, earlierDate } from "./three-way.js";
+import { CLEAN, CONFLICT, read, mergeText, fallback } from "./text-merge.js";
+/** Keeps the freshest snapshot of a tracked file when both sides re-snapshotted it. */
+function pickTrackedFile(ours, theirs) {
+    return laterDate(ours.lastModifiedAt, theirs.lastModifiedAt) === theirs.lastModifiedAt ? theirs : ours;
+}
+function mergeFrontmatter(base, ours, theirs) {
+    const conflicts = [];
+    const data = {};
+    const list = (o, k) => (Array.isArray(o[k]) ? o[k] : []);
+    const tracked = (o) => (Array.isArray(o.tracked_files) ? o.tracked_files : []);
+    // Field order mirrors StorageEngine.saveDoc so a merged file is byte-identical
+    // to what the next save would produce — no spurious diff on the following sync.
+    const title = mergeScalar(base.title, ours.title, theirs.title);
+    if (title.conflict) {
+        conflicts.push({ field: "title", ours: title.ours, theirs: title.theirs });
+        data.title = title.ours;
+    }
+    else {
+        data.title = title.value ?? "";
+    }
+    data.tracked_files = mergeKeyedList(tracked(base), tracked(ours), tracked(theirs), (f) => f.path, pickTrackedFile);
+    data.tags = mergeSet(list(base, "tags"), list(ours, "tags"), list(theirs, "tags"));
+    const relatedDocs = mergeSet(list(base, "related_docs"), list(ours, "related_docs"), list(theirs, "related_docs"));
+    if (relatedDocs.length > 0)
+        data.related_docs = relatedDocs;
+    // Bookkeeping timestamps: widest interval wins, never a conflict.
+    data.createdAt = earlierDate(ours.createdAt, theirs.createdAt) ?? "";
+    data.updatedAt = laterDate(ours.updatedAt, theirs.updatedAt) ?? "";
+    const known = new Set(["title", "tracked_files", "tags", "related_docs", "createdAt", "updatedAt"]);
+    for (const key of [...Object.keys(ours), ...Object.keys(theirs)]) {
+        if (known.has(key) || key in data)
+            continue;
+        const merged = mergeScalar(base[key], ours[key], theirs[key]);
+        if (merged.conflict) {
+            conflicts.push({ field: key, ours: merged.ours, theirs: merged.theirs });
+            data[key] = merged.ours;
+        }
+        else if (merged.value !== undefined) {
+            data[key] = merged.value;
+        }
+    }
+    return { data, conflicts };
+}
+/**
+ * Frontmatter conflicts cannot carry git markers — that would make the YAML
+ * unparseable and break every reader. They are surfaced as a marker block at the
+ * top of the body instead: visible to a human, greppable by tooling, and the
+ * document still loads.
+ */
+function conflictBlock(conflicts) {
+    const render = (v) => (typeof v === "string" ? v : JSON.stringify(v));
+    const lines = ["<<<<<<< ours (frontmatter)"];
+    for (const c of conflicts)
+        lines.push(`${c.field}: ${render(c.ours)}`);
+    lines.push("=======");
+    for (const c of conflicts)
+        lines.push(`${c.field}: ${render(c.theirs)}`);
+    lines.push(">>>>>>> theirs (frontmatter)", "");
+    return lines.join("\n");
+}
+function main() {
+    const [basePath, oursPath, theirsPath] = process.argv.slice(2);
+    if (!oursPath || !theirsPath)
+        return CONFLICT;
+    let base, ours, theirs;
+    try {
+        base = matter(read(basePath));
+        ours = matter(read(oursPath));
+        theirs = matter(read(theirsPath));
+    }
+    catch {
+        // Malformed YAML on any side — don't guess, fall back to a plain text merge.
+        return fallback(basePath, oursPath, theirsPath);
+    }
+    // A plain markdown file with no frontmatter on any side is not one of our
+    // docs (the driver would otherwise *add* a frontmatter block to it).
+    const hasFrontmatter = [base, ours, theirs].some((side) => Object.keys(side.data).length > 0);
+    if (!hasFrontmatter)
+        return fallback(basePath, oursPath, theirsPath);
+    const body = mergeText(base.content, ours.content, theirs.content);
+    if (!body)
+        return fallback(basePath, oursPath, theirsPath);
+    const front = mergeFrontmatter(base.data, ours.data, theirs.data);
+    const content = front.conflicts.length > 0 ? conflictBlock(front.conflicts) + body.text : body.text;
+    fs.writeFileSync(oursPath, matter.stringify(content, front.data), "utf-8");
+    return body.conflict || front.conflicts.length > 0 ? CONFLICT : CLEAN;
+}
+process.exit(main());

package/dist/src/core/merge-drivers/text-merge.d.ts

@@ -0,0 +1,15 @@
+export declare const CLEAN = 0;
+export declare const CONFLICT = 1;
+/** A driver argument may point at a missing file (add/add merges have no ancestor). */
+export declare function read(file: string | undefined): string;
+/** Runs git's own textual merge over three strings. Returns null if git itself failed. */
+export declare function mergeText(base: string, ours: string, theirs: string): {
+    text: string;
+    conflict: boolean;
+} | null;
+/**
+ * Last resort when structured merging is impossible: merge the raw files
+ * textually, exactly as git would have without this driver. Never leaves %A
+ * untouched — git requires the result to be written there either way.
+ */
+export declare function fallback(basePath: string, oursPath: string, theirsPath: string): number;