@imenam/mcp-documentor 1.0.71 → 1.0.74

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

@@ -0,0 +1,53 @@
+/**
+ * Shared plumbing for the git merge drivers: reading driver arguments and
+ * delegating to git's own textual 3-way merge.
+ */
+import { spawnSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+export const CLEAN = 0;
+export const CONFLICT = 1;
+/** A driver argument may point at a missing file (add/add merges have no ancestor). */
+export function read(file) {
+    if (!file || !fs.existsSync(file))
+        return "";
+    return fs.readFileSync(file, "utf-8");
+}
+/** Runs git's own textual merge over three strings. Returns null if git itself failed. */
+export function mergeText(base, ours, theirs) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-documentor-merge-"));
+    try {
+        const files = {
+            base: path.join(dir, "base"),
+            ours: path.join(dir, "ours"),
+            theirs: path.join(dir, "theirs"),
+        };
+        fs.writeFileSync(files.base, base, "utf-8");
+        fs.writeFileSync(files.ours, ours, "utf-8");
+        fs.writeFileSync(files.theirs, theirs, "utf-8");
+        const res = spawnSync("git", 
+        // --diff3 keeps the common ancestor in the markers, so conflict inspection
+        // can show what each side changed rather than just what they disagree on.
+        ["merge-file", "--diff3", "--stdout", "-L", "ours", "-L", "base", "-L", "theirs", files.ours, files.base, files.theirs], { encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 });
+        // git merge-file returns the conflict count, or a negative value (255) on error.
+        if (res.status === null || res.status < 0 || res.status === 255)
+            return null;
+        return { text: res.stdout, conflict: res.status > 0 };
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * 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 function fallback(basePath, oursPath, theirsPath) {
+    const merged = mergeText(read(basePath), read(oursPath), read(theirsPath));
+    if (!merged)
+        return CONFLICT;
+    fs.writeFileSync(oursPath, merged.text, "utf-8");
+    return merged.conflict ? CONFLICT : CLEAN;
+}

package/dist/src/core/merge-drivers/three-way.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Generic 3-way merge primitives shared by the git merge drivers.
+ *
+ * All helpers follow git's contract: `base` is the common ancestor, `ours` is
+ * the side being merged into, `theirs` is the incoming side. A value that only
+ * one side changed is taken from that side; a value both sides changed to the
+ * same thing is not a conflict.
+ */
+export type Merged<T> = {
+    conflict: false;
+    value: T;
+} | {
+    conflict: true;
+    ours: T;
+    theirs: T;
+};
+/** Classic 3-way merge of a single value. Conflicts only when both sides diverged differently. */
+export declare function mergeScalar<T>(base: T | undefined, ours: T | undefined, theirs: T | undefined): Merged<T | undefined>;
+/**
+ * Set merge that honours deletions: an entry disappears only if a side that had
+ * it in `base` removed it. Plain union would resurrect deleted entries forever.
+ * Order is stable — base order first, then additions from ours, then theirs.
+ */
+export declare function mergeSet(base?: string[], ours?: string[], theirs?: string[]): string[];
+/**
+ * Set merge over objects identified by `keyOf`. Entries present on both sides
+ * with diverging content are resolved by `pick` rather than reported as a
+ * conflict — callers supply a domain rule (e.g. keep the freshest snapshot).
+ */
+export declare function mergeKeyedList<T>(base: T[] | undefined, ours: T[] | undefined, theirs: T[] | undefined, keyOf: (item: T) => string, pick: (ours: T, theirs: T) => T): T[];
+/** Later of two date-ish strings. Falls back to lexicographic order for unparseable values. */
+export declare function laterDate(a?: string, b?: string): string | undefined;
+/** Earlier of two date-ish strings. Falls back to lexicographic order. */
+export declare function earlierDate(a?: string, b?: string): string | undefined;

package/dist/src/core/merge-drivers/three-way.js

@@ -0,0 +1,86 @@
+/**
+ * Generic 3-way merge primitives shared by the git merge drivers.
+ *
+ * All helpers follow git's contract: `base` is the common ancestor, `ours` is
+ * the side being merged into, `theirs` is the incoming side. A value that only
+ * one side changed is taken from that side; a value both sides changed to the
+ * same thing is not a conflict.
+ */
+function eq(a, b) {
+    return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+/** Classic 3-way merge of a single value. Conflicts only when both sides diverged differently. */
+export function mergeScalar(base, ours, theirs) {
+    if (eq(ours, theirs))
+        return { conflict: false, value: ours };
+    if (eq(ours, base))
+        return { conflict: false, value: theirs };
+    if (eq(theirs, base))
+        return { conflict: false, value: ours };
+    return { conflict: true, ours, theirs };
+}
+/**
+ * Set merge that honours deletions: an entry disappears only if a side that had
+ * it in `base` removed it. Plain union would resurrect deleted entries forever.
+ * Order is stable — base order first, then additions from ours, then theirs.
+ */
+export function mergeSet(base = [], ours = [], theirs = []) {
+    const baseSet = new Set(base);
+    const ourSet = new Set(ours);
+    const theirSet = new Set(theirs);
+    const result = [];
+    for (const item of base) {
+        const removed = !ourSet.has(item) || !theirSet.has(item);
+        if (!removed)
+            result.push(item);
+    }
+    for (const item of [...ours, ...theirs]) {
+        if (!baseSet.has(item) && !result.includes(item))
+            result.push(item);
+    }
+    return result;
+}
+/**
+ * Set merge over objects identified by `keyOf`. Entries present on both sides
+ * with diverging content are resolved by `pick` rather than reported as a
+ * conflict — callers supply a domain rule (e.g. keep the freshest snapshot).
+ */
+export function mergeKeyedList(base = [], ours = [], theirs = [], keyOf, pick) {
+    const index = (list) => new Map(list.map((item) => [keyOf(item), item]));
+    const baseMap = index(base);
+    const ourMap = index(ours);
+    const theirMap = index(theirs);
+    const keys = mergeSet([...baseMap.keys()], [...ourMap.keys()], [...theirMap.keys()]);
+    const result = [];
+    for (const key of keys) {
+        const o = ourMap.get(key);
+        const t = theirMap.get(key);
+        if (o && t)
+            result.push(eq(o, t) ? o : pick(o, t));
+        else if (o)
+            result.push(o);
+        else if (t)
+            result.push(t);
+    }
+    return result;
+}
+/** Later of two date-ish strings. Falls back to lexicographic order for unparseable values. */
+export function laterDate(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    const da = Date.parse(a);
+    const db = Date.parse(b);
+    if (Number.isNaN(da) || Number.isNaN(db))
+        return a > b ? a : b;
+    return da >= db ? a : b;
+}
+/** Earlier of two date-ish strings. Falls back to lexicographic order. */
+export function earlierDate(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return laterDate(a, b) === a ? b : a;
+}

package/dist/src/gui-worker.js

@@ -192,6 +192,7 @@ const READ_ONLY_WRITE_ROUTES = [
     { method: "PUT", prefix: "/api/doc/" },
     { method: "POST", prefix: "/api/images" },
     { method: "POST", prefix: "/api/configurations/apply" },
+    { method: "POST", prefix: "/api/sync" },
 ];
 app.use("*", async (c, next) => {
     if (isReadOnly()) {
@@ -314,6 +315,26 @@ app.get("/api/config", async (c) => {
         return c.json({ error: result.error }, 500);
     return c.json(result.data);
 });
+app.get("/api/sync/status", async (c) => {
+    const result = await ipcRequest("SYNC_STATUS", {}, 20000);
+    if (result.error)
+        return c.json({ error: result.error }, 500);
+    return c.json(result.data);
+});
+app.post("/api/sync", async (c) => {
+    let message;
+    try {
+        message = (await c.req.json())?.message;
+    }
+    catch {
+        // Body is optional — the commit message falls back to an auto-generated one.
+    }
+    // Network round-trips (fetch + push) plus a possible embedding reindex.
+    const result = await ipcRequest("SYNC_DOCS", { message }, 180000);
+    if (result.error)
+        return c.json({ error: result.error }, 500);
+    return c.json(result.data);
+});
 app.get("/api/projects", async (c) => {
     const result = await ipcRequest("LIST_PROJECTS");
     if (result.error)

package/dist/src/index.js

@@ -43,6 +43,7 @@ import { uploadImage } from "./tools/upload-image.js";
 import { getImage } from "./tools/get-image.js";
 import { SyncEngine } from "./core/git-sync.js";
 import { syncStatus, pullDocs, pushDocs, syncDocs, resolveSyncConflict } from "./tools/sync.js";
+import { listConflicts, getConflictHunks, resolveConflictHunks } from "./tools/conflicts.js";
 import { isReadOnly, WRITE_TOOLS } from "../shared/read-only.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -167,6 +168,12 @@ function handleIPCMessage(msg) {
     else if (msg.type === "GET_FILE_SECTION") {
         handleGetFileSection(msg);
     }
+    else if (msg.type === "SYNC_STATUS") {
+        handleSyncStatusIPC(msg);
+    }
+    else if (msg.type === "SYNC_DOCS") {
+        handleSyncDocsIPC(msg);
+    }
     else {
         logger.debug(`Unhandled message from GUI: ${msg.type}`);
     }
@@ -197,7 +204,14 @@ async function handleGetInitialState(msg) {
         broadcastToGUI({
             type: "INITIAL_STATE",
             correlationId: msg.correlationId,
-            data: { config, docs, projects: config.projects, bundles, readOnly: isReadOnly() },
+            data: {
+                config,
+                docs,
+                projects: config.projects,
+                bundles,
+                readOnly: isReadOnly(),
+                syncEnabled: syncEngine.isConfigured(),
+            },
             timestamp: new Date().toISOString(),
         });
     }
@@ -210,7 +224,7 @@ async function handleGetConfig(msg) {
     broadcastToGUI({
         type: "CONFIG_RESPONSE",
         correlationId: msg.correlationId,
-        data: { ...config, version: getConfig().version, readOnly: isReadOnly() },
+        data: { ...config, version: getConfig().version, readOnly: isReadOnly(), syncEnabled: syncEngine.isConfigured() },
         timestamp: new Date().toISOString(),
     });
 }
@@ -636,6 +650,81 @@ async function handleGitDiff(msg) {
         });
     }
 }
+/**
+ * Sync state for the GUI button. `configured` is false when the environment has
+ * no MCP_DOCUMENTOR_SYNC_REMOTE — the GUI then hides the button entirely.
+ */
+async function handleSyncStatusIPC(msg) {
+    try {
+        if (!syncEngine.isConfigured()) {
+            broadcastToGUI({
+                type: "SYNC_STATUS_RESPONSE",
+                correlationId: msg.correlationId,
+                data: { configured: false },
+                timestamp: new Date().toISOString(),
+            });
+            return;
+        }
+        const s = await syncEngine.status();
+        broadcastToGUI({
+            type: "SYNC_STATUS_RESPONSE",
+            correlationId: msg.correlationId,
+            data: { configured: true, ...s },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        broadcastToGUI({
+            type: "SYNC_STATUS_RESPONSE",
+            correlationId: msg.correlationId,
+            error: err.message,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
+async function handleSyncDocsIPC(msg) {
+    if (isReadOnly()) {
+        broadcastToGUI({
+            type: "SYNC_DOCS_RESPONSE",
+            correlationId: msg.correlationId,
+            error: "READ_ONLY mode: sync is disabled",
+            timestamp: new Date().toISOString(),
+        });
+        return;
+    }
+    try {
+        // Reuse the tool so the GUI and the agent get identical pull/push semantics.
+        const result = await syncDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore, {
+            message: msg.data?.message,
+        });
+        const text = result.content.map((c) => c.text).join("\n");
+        if (result.isError) {
+            broadcastToGUI({
+                type: "SYNC_DOCS_RESPONSE",
+                correlationId: msg.correlationId,
+                error: text,
+                timestamp: new Date().toISOString(),
+            });
+            return;
+        }
+        broadcastToGUI({
+            type: "SYNC_DOCS_RESPONSE",
+            correlationId: msg.correlationId,
+            data: { message: text },
+            timestamp: new Date().toISOString(),
+        });
+        // A pull can add/remove docs — push a fresh tree to every connected GUI.
+        await handleGetInitialState({});
+    }
+    catch (err) {
+        broadcastToGUI({
+            type: "SYNC_DOCS_RESPONSE",
+            correlationId: msg.correlationId,
+            error: err.message,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
 async function handleUpdateConfig(msg) {
     if (isReadOnly()) {
         broadcastToGUI({
@@ -1201,17 +1290,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
             name: "sync_status",
-            description: "Show the synchronization status: current branch, how many commits the local repo is ahead/behind the remote, conflicted files, and uncommitted changes. The sync target (repository, branch, token) is fixed by the server administrator via environment variables and cannot be changed from here.",
+            description: "Show the synchronization status: current branch, whether a merge or rebase is in progress, how many commits the local repo is ahead/behind the remote, conflicted files, and uncommitted changes. The sync target (repository, branch, token) is fixed by the server administrator via environment variables and cannot be changed from here.",
             inputSchema: { type: "object", properties: {} },
         },
         {
             name: "pull_docs",
-            description: "Pull documentation updates from the GitHub remote. Defensive: only fast-forwards a clean working tree, never auto-merges a divergent history (local data is never overwritten). Reindexes embeddings for new documents after a successful update.",
+            description: "Pull documentation updates from the GitHub remote. Defensive: fast-forwards when purely behind, and rebases local commits on top of the remote when the history diverged. Never touches an uncommitted local change. A conflict stops the rebase with both versions preserved - resolve it with resolve_sync_conflict. Reindexes embeddings for new documents after a successful update.",
             inputSchema: { type: "object", properties: {} },
         },
         {
             name: "push_docs",
-            description: "Commit local documentation changes (markdown + assets + project list) and push them to the GitHub remote.",
+            description: "Commit local documentation changes (markdown + assets + project list) and push them to the GitHub remote. Refuses to run while a conflict is unresolved, so conflict markers are never committed as documentation content.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1221,7 +1310,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
             name: "sync_docs",
-            description: "Full synchronization: pull (defensive) then push. If the pull reveals a divergence or conflict, the push is skipped so it can be resolved first.",
+            description: "Full synchronization: pull (fast-forward or rebase) then push. If the pull reveals a divergence or conflict, the push is skipped so it can be resolved first with resolve_sync_conflict.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1231,14 +1320,56 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
             name: "resolve_sync_conflict",
-            description: "Bulk-resolve sync merge conflicts by keeping one side for the conflicted files, then stage them. For nuanced resolution, edit the conflicted markdown files directly instead. After resolving, run push_docs.",
+            description: "Bulk-resolve sync conflicts by keeping one side for the conflicted files, stage them, and carry the merge or rebase to completion when nothing is left conflicted. Sides are absolute ('local' vs 'remote'), not git's ours/theirs, which swap meaning between a merge and a rebase. For nuanced resolution, edit the conflicted markdown files directly instead. After resolving, run push_docs.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    strategy: { type: "string", enum: ["mine", "theirs"], description: "'mine' keeps the local version, 'theirs' keeps the incoming remote version" },
+                    side: { type: "string", enum: ["local", "remote"], description: "'local' keeps this machine's version, 'remote' keeps the incoming version from the other machine" },
                     paths: { type: "array", items: { type: "string" }, description: "Specific conflicted file paths to resolve (defaults to all conflicted files)" },
                 },
-                required: ["strategy"],
+                required: ["side"],
+            },
+        },
+        {
+            name: "list_conflicts",
+            description: "List every file left conflicted by a sync, without opening any of them: which project and document each one is, whether it is a content / delete-modify / add-add conflict, how many hunks it has and in which markdown sections, and who last changed it on each side. Sides are absolute: 'local' is this machine, 'remote' is the other machine. Start here when a pull reports a conflict.",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "get_conflict_hunks",
+            description: "Return only the passages two machines disagree on in one conflicted document, as numbered hunks: the section each falls in, the common ancestor, and both sides. Output is capped per side so a large document never has to be read in full. Use this instead of get_doc when resolving a sync conflict.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Conflicted file path as reported by list_conflicts (e.g. 'projects/alpha/api.md')" },
+                    hunks: { type: "array", items: { type: "number" }, description: "Specific hunk numbers to return (defaults to all)" },
+                    max_chars_per_side: { type: "number", description: "Character budget per side, per hunk (default 1200). Anything beyond it is withheld and counted." },
+                },
+                required: ["path"],
+            },
+        },
+        {
+            name: "resolve_conflict_hunks",
+            description: "Resolve a conflicted document hunk by hunk. Each decision keeps the local side, the remote side, both (local first), neither, or your own replacement text. The file is only staged once every hunk has been decided, so conflict markers can never be committed as documentation content. When the file is the last one conflicted, the merge or rebase is carried to completion.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Conflicted file path as reported by list_conflicts" },
+                    decisions: {
+                        type: "array",
+                        description: "One entry per hunk you are deciding. Undecided hunks keep their markers.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                hunk: { type: "number", description: "Hunk number from get_conflict_hunks" },
+                                take: { type: "string", enum: ["local", "remote", "both", "none", "custom"], description: "'local' this machine, 'remote' the other machine, 'both' concatenates local then remote, 'none' drops the passage, 'custom' uses the provided content. 'both' is refused on frontmatter hunks, where it would duplicate a YAML key." },
+                                content: { type: "string", description: "Replacement text, required when take is 'custom'" },
+                            },
+                            required: ["hunk", "take"],
+                        },
+                    },
+                },
+                required: ["path", "decisions"],
             },
         },
         {
@@ -1342,6 +1473,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return await syncDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore, args);
             case "resolve_sync_conflict":
                 return await resolveSyncConflict(syncEngine, args);
+            case "list_conflicts":
+                return await listConflicts(syncEngine);
+            case "get_conflict_hunks":
+                return await getConflictHunks(syncEngine, args);
+            case "resolve_conflict_hunks":
+                return await resolveConflictHunks(syncEngine, args);
             case "reconnect_gui":
                 return await reconnectGui(args);
             default:
@@ -1368,9 +1505,6 @@ async function syncPullOnStartup() {
                 await reindexEmbeddings(storageEngine, embeddingEngine, embeddingStore, {});
             }
         }
-        else if (res.status === "diverged") {
-            logger.warn(`Startup sync: local history diverged (ahead ${res.ahead}, behind ${res.behind}). Started on local data — run sync_status / sync_docs to reconcile.`);
-        }
         else if (res.status === "conflict") {
             logger.warn(`Startup sync: merge conflict in ${res.conflicted.length} file(s). Started on local data — resolve with resolve_sync_conflict.`);
         }

package/dist/src/tools/conflicts.d.ts

@@ -0,0 +1,12 @@
+import type { SyncEngine } from "../core/git-sync.js";
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+};
+export declare function listConflicts(syncEngine: SyncEngine): Promise<ToolResult>;
+export declare function getConflictHunks(syncEngine: SyncEngine, args: unknown): Promise<ToolResult>;
+export declare function resolveConflictHunks(syncEngine: SyncEngine, args: unknown): Promise<ToolResult>;
+export {};

package/dist/src/tools/conflicts.js

@@ -0,0 +1,190 @@
+import matter from "gray-matter";
+import { z } from "zod";
+import { parseConflicts, applyResolutions, preview, hasConflictMarkers } from "../core/conflict-inspector.js";
+const ok = (text) => ({ content: [{ type: "text", text }] });
+const err = (text) => ({ content: [{ type: "text", text }], isError: true });
+const NOT_CONFIGURED = "Sync is not configured. Set MCP_DOCUMENTOR_SYNC_REMOTE (and MCP_DOCUMENTOR_SYNC_TOKEN) in the server environment.";
+/** Documents live at projects/<project>/<id>.md — recover both for reporting. */
+function describeTarget(filePath) {
+    const match = filePath.match(/^projects\/([^/]+)\/(.+)\.md$/);
+    return match ? `project "${match[1]}", doc "${match[2]}"` : filePath;
+}
+function describeSide(label, side) {
+    if (!side)
+        return `  ${label}: (no commit recorded)`;
+    return `  ${label}: ${side.author} · ${side.date} · "${side.subject}"`;
+}
+export async function listConflicts(syncEngine) {
+    try {
+        if (!syncEngine.isConfigured())
+            return err(NOT_CONFIGURED);
+        const { operation, files } = await syncEngine.listConflicts();
+        if (files.length === 0)
+            return ok("No conflicts. Nothing to resolve.");
+        const lines = [
+            `${files.length} conflicted file(s) during a ${operation}.`,
+            `"local" is this machine's version, "remote" is the other machine's.`,
+            "",
+        ];
+        for (const file of files) {
+            lines.push(`${file.path}  (${describeTarget(file.path)})`);
+            if (file.kind === "delete-modify") {
+                lines.push(`  Kind: delete/modify — the ${file.deletedOn} side deleted this document while the other edited it.`);
+            }
+            else if (file.kind === "add-add") {
+                lines.push(`  Kind: add/add — both sides created this document independently; there is no common ancestor.`);
+            }
+            else {
+                // Counting hunks needs the working file, which only exists for content
+                // conflicts (a deleted side leaves nothing on disk).
+                try {
+                    const { hunks } = parseConflicts(syncEngine.readWorkingFile(file.path), operation);
+                    const sections = [...new Set(hunks.map((h) => h.section))];
+                    lines.push(`  Kind: content — ${hunks.length} conflicting hunk(s) in: ${sections.join(", ")}`);
+                }
+                catch {
+                    lines.push(`  Kind: content`);
+                }
+            }
+            lines.push(describeSide("local ", file.local), describeSide("remote", file.remote), "");
+        }
+        lines.push(`Next: get_conflict_hunks to see just the disagreeing passages, resolve_conflict_hunks to decide hunk by hunk,`, `or resolve_sync_conflict to keep one whole side for every file at once.`);
+        return ok(lines.join("\n"));
+    }
+    catch (e) {
+        return err(`Error listing conflicts: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+const GetHunksArgs = z.object({
+    path: z.string(),
+    hunks: z.array(z.number().int().positive()).optional(),
+    max_chars_per_side: z.number().int().positive().max(20000).default(1200),
+});
+export async function getConflictHunks(syncEngine, args) {
+    try {
+        if (!syncEngine.isConfigured())
+            return err(NOT_CONFIGURED);
+        const v = GetHunksArgs.parse(args);
+        const operation = await syncEngine.operationInProgress();
+        const { hunks } = parseConflicts(syncEngine.readWorkingFile(v.path), operation);
+        if (hunks.length === 0)
+            return ok(`No conflict markers in "${v.path}".`);
+        const wanted = v.hunks?.length ? hunks.filter((h) => v.hunks.includes(h.index)) : hunks;
+        if (wanted.length === 0)
+            return ok(`None of the requested hunks exist in "${v.path}" (it has ${hunks.length}).`);
+        const lines = [`${v.path} — ${wanted.length} of ${hunks.length} hunk(s), during a ${operation}.`, ""];
+        for (const hunk of wanted) {
+            const scope = hunk.inFrontmatter ? " [frontmatter — \"both\" is not available, it would duplicate a key]" : "";
+            lines.push(`Hunk ${hunk.index} — section "${hunk.section}" (line ${hunk.line})${scope}`);
+            if (hunk.base)
+                lines.push(`  [base — what both sides started from]`, preview(hunk.base, v.max_chars_per_side));
+            lines.push(`  [local — this machine]`, preview(hunk.local, v.max_chars_per_side));
+            lines.push(`  [remote — the other machine]`, preview(hunk.remote, v.max_chars_per_side));
+            lines.push("");
+        }
+        lines.push(`Resolve with resolve_conflict_hunks: take "local", "remote", "both", "none" (drop it), or "custom" with your own text.`);
+        return ok(lines.join("\n"));
+    }
+    catch (e) {
+        return err(`Error reading conflict hunks: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+const ResolveHunksArgs = z.object({
+    path: z.string(),
+    decisions: z
+        .array(z.object({
+        hunk: z.number().int().positive(),
+        take: z.enum(["local", "remote", "both", "none", "custom"]),
+        content: z.string().optional(),
+    }))
+        .min(1),
+});
+export async function resolveConflictHunks(syncEngine, args) {
+    try {
+        if (!syncEngine.isConfigured())
+            return err(NOT_CONFIGURED);
+        const v = ResolveHunksArgs.parse(args);
+        const missingContent = v.decisions.filter((d) => d.take === "custom" && d.content === undefined);
+        if (missingContent.length > 0) {
+            return err(`Hunk(s) ${missingContent.map((d) => d.hunk).join(", ")} use take "custom" but no content was provided.`);
+        }
+        const operation = await syncEngine.operationInProgress();
+        const decisions = v.decisions.map((d) => d.take === "custom" ? { index: d.hunk, take: "custom", content: d.content } : { index: d.hunk, take: d.take });
+        const original = syncEngine.readWorkingFile(v.path);
+        if (!hasConflictMarkers(original)) {
+            return err(`"${v.path}" has no conflict markers — there is nothing to resolve hunk by hunk.`);
+        }
+        // Concatenating both sides of a frontmatter hunk repeats the key it holds,
+        // which makes the YAML unparseable for every reader of the document.
+        const { hunks } = parseConflicts(original, operation);
+        const badBoth = v.decisions.filter((d) => d.take === "both" && hunks.find((h) => h.index === d.hunk)?.inFrontmatter);
+        if (badBoth.length > 0) {
+            return err(`Hunk(s) ${badBoth.map((d) => d.hunk).join(", ")} concern frontmatter, where "both" would duplicate a key and break the YAML. ` +
+                `Use "local", "remote", or "custom" with the single value you want.`);
+        }
+        // A hoisted frontmatter block lives in the body but describes YAML keys.
+        // Applying its chosen side literally would paste "title: X" into the prose
+        // and leave the real frontmatter untouched, so those hunks are dropped from
+        // the body and their values folded back into the frontmatter instead.
+        const frontmatterUpdates = {};
+        const effective = decisions.map((decision) => {
+            const hunk = hunks.find((h) => h.index === decision.index);
+            if (!hunk?.hoisted)
+                return decision;
+            const chosen = decision.take === "local" ? hunk.local
+                : decision.take === "remote" ? hunk.remote
+                    : decision.take === "custom" ? decision.content.split(/\r?\n/)
+                        : [];
+            if (chosen.length > 0) {
+                try {
+                    const asYaml = ["---", ...chosen, "---", ""].join("\n");
+                    Object.assign(frontmatterUpdates, matter(asYaml).data);
+                }
+                catch {
+                    // Not parseable as YAML - leave the frontmatter alone rather than
+                    // corrupting it; the caller still sees the block disappear.
+                }
+            }
+            return { index: decision.index, take: "none" };
+        });
+        const result = applyResolutions(original, operation, effective);
+        if (Object.keys(frontmatterUpdates).length > 0) {
+            try {
+                const parsed = matter(result.text);
+                result.text = matter.stringify(parsed.content, { ...parsed.data, ...frontmatterUpdates });
+            }
+            catch {
+                // Frontmatter still holds markers of its own; it will be rewritten
+                // once those hunks are resolved too.
+            }
+        }
+        // The invariant is checked against the resulting text rather than the hunk
+        // bookkeeping: staging a file that still holds markers tells git the
+        // conflict is settled and lets them be committed as documentation content.
+        const settled = !hasConflictMarkers(result.text);
+        await syncEngine.writeResolvedFile(v.path, result.text, settled);
+        const lines = [`Resolved ${result.applied.length} hunk(s) in "${v.path}".`];
+        if (result.unknown.length > 0) {
+            lines.push(`Ignored — no such hunk: ${result.unknown.join(", ")}.`);
+        }
+        if (!settled) {
+            lines.push(`${result.remaining} hunk(s) still conflicted; the file is left unstaged until every hunk is decided.`, `Run get_conflict_hunks again — the remaining hunks have been renumbered.`);
+            return ok(lines.join("\n"));
+        }
+        lines.push(`File fully resolved and staged.`);
+        const finish = await syncEngine.continueOperation();
+        if (finish.remaining.length > 0) {
+            lines.push(``, `Still conflicted elsewhere (${finish.remaining.length}):`, `  - ${finish.remaining.join("\n  - ")}`);
+        }
+        else if (finish.done && finish.operation !== "none") {
+            lines.push(``, `The ${finish.operation} is complete. Run push_docs to publish.`);
+        }
+        else if (finish.error) {
+            lines.push(``, `The ${finish.operation} could not be completed: ${finish.error}`);
+        }
+        return ok(lines.join("\n"));
+    }
+    catch (e) {
+        return err(`Error resolving hunks: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}