@imenam/mcp-documentor 1.0.71 → 1.0.74

package/dist/src/core/conflict-inspector.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Reads and rewrites git conflict markers so the agent can resolve a document
+ * hunk by hunk without ever loading the document itself.
+ *
+ * Sides are named "local" and "remote" throughout, never git's ours/theirs:
+ * those two swap meaning between a merge and a rebase, and the whole point of
+ * this layer is that the caller never has to know which one is running.
+ */
+/** Direct marker check, independent of hunk parsing - the invariant before staging. */
+export declare function hasConflictMarkers(text: string): boolean;
+export type HunkSide = "local" | "remote";
+export interface ConflictHunk {
+    /** 1-based index within the file; the id the caller resolves against. */
+    index: number;
+    /** Nearest markdown heading above the hunk, for locating it without reading the doc. */
+    section: string;
+    /** 1-based line where the hunk's opening marker sits. */
+    line: number;
+    local: string[];
+    remote: string[];
+    /** Common ancestor, present only when the markers were written in diff3 style. */
+    base?: string[];
+    /**
+     * The hunk concerns frontmatter, either because it sits inside the YAML block
+     * or because the doc merge driver hoisted a frontmatter disagreement to the
+     * top of the body. Keeping both sides of one of these would duplicate a key,
+     * so that choice is refused rather than silently producing broken YAML.
+     */
+    inFrontmatter: boolean;
+    /**
+     * The hunk is the block the doc merge driver hoisted out of the frontmatter.
+     * Its sides are `key: value` lines that belong back in the YAML, not in the
+     * body where the markers physically sit.
+     */
+    hoisted: boolean;
+}
+export interface ParsedFile {
+    lines: string[];
+    hunks: ConflictHunk[];
+}
+/** Splits a conflicted file into hunks. Handles both diff3 and plain markers. */
+export declare function parseConflicts(text: string, operation: "merge" | "rebase" | "none"): ParsedFile;
+export type Decision = {
+    index: number;
+    take: "local" | "remote" | "both" | "none";
+} | {
+    index: number;
+    take: "custom";
+    content: string;
+};
+/**
+ * Rewrites the file with the chosen resolution for each listed hunk. Hunks with
+ * no decision keep their markers, so a partial resolution is safe: the file
+ * stays conflicted until every hunk has been decided.
+ */
+export declare function applyResolutions(text: string, operation: "merge" | "rebase" | "none", decisions: Decision[]): {
+    text: string;
+    applied: number[];
+    unknown: number[];
+    remaining: number;
+};
+/** Truncates a side to a character budget, saying how much was withheld. */
+export declare function preview(side: string[], maxChars: number): string;

package/dist/src/core/conflict-inspector.js

@@ -0,0 +1,157 @@
+/**
+ * Reads and rewrites git conflict markers so the agent can resolve a document
+ * hunk by hunk without ever loading the document itself.
+ *
+ * Sides are named "local" and "remote" throughout, never git's ours/theirs:
+ * those two swap meaning between a merge and a rebase, and the whole point of
+ * this layer is that the caller never has to know which one is running.
+ */
+const START = /^<{7}(?: (.*))?$/;
+const BASE = /^\|{7}(?: (.*))?$/;
+const SEPARATOR = /^={7}$/;
+const END = /^>{7}(?: (.*))?$/;
+const HEADING = /^(#{1,6})\s+(.*)$/;
+/**
+ * git checks documents out with the platform's line endings, so a working-tree
+ * file on Windows is CRLF even though the driver wrote LF. Splitting on "\n"
+ * alone would leave a trailing CR on every line and no marker would ever match.
+ */
+function splitLines(text) {
+    return text.split(/\r?\n/);
+}
+function lineEnding(text) {
+    return /\r\n/.test(text) ? "\r\n" : "\n";
+}
+/** Direct marker check, independent of hunk parsing - the invariant before staging. */
+export function hasConflictMarkers(text) {
+    return splitLines(text).some((line) => START.test(line) || SEPARATOR.test(line) || END.test(line));
+}
+/**
+ * Maps a marker block onto absolute sides. In the file, the first block is
+ * always git's "ours": the branch being merged into for a merge, but the
+ * upstream being replayed onto for a rebase.
+ */
+function sidesFor(operation, first, second) {
+    return operation === "rebase" ? { local: second, remote: first } : { local: first, remote: second };
+}
+/**
+ * Line range of the YAML frontmatter block, if the file opens with one.
+ * Returns null when there is none.
+ */
+function frontmatterRange(lines) {
+    if (lines.length === 0 || lines[0].trim() !== "---")
+        return null;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === "---")
+            return { start: 0, end: i };
+    }
+    return null;
+}
+function sectionFor(lines, hunkStart) {
+    for (let i = hunkStart - 1; i >= 0; i--) {
+        const match = lines[i].match(HEADING);
+        if (match)
+            return match[2].trim();
+    }
+    return "(document root)";
+}
+/** Splits a conflicted file into hunks. Handles both diff3 and plain markers. */
+export function parseConflicts(text, operation) {
+    const lines = splitLines(text);
+    const frontmatter = frontmatterRange(lines);
+    const hunks = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (!START.test(lines[i]))
+            continue;
+        const first = [];
+        const base = [];
+        const second = [];
+        let target = first;
+        let sawBase = false;
+        let closed = false;
+        let j = i + 1;
+        const label = lines[i].match(START)?.[1] ?? "";
+        for (; j < lines.length; j++) {
+            const line = lines[j];
+            if (BASE.test(line)) {
+                sawBase = true;
+                target = base;
+            }
+            else if (SEPARATOR.test(line)) {
+                target = second;
+            }
+            else if (END.test(line)) {
+                closed = true;
+                break;
+            }
+            else {
+                target.push(line);
+            }
+        }
+        // An unterminated marker is malformed input, not a hunk — leave it alone.
+        if (!closed)
+            continue;
+        const { local, remote } = sidesFor(operation, first, second);
+        hunks.push({
+            index: hunks.length + 1,
+            section: sectionFor(lines, i),
+            line: i + 1,
+            local,
+            remote,
+            ...(sawBase ? { base } : {}),
+            inFrontmatter: label.includes("frontmatter") || (frontmatter !== null && i >= frontmatter.start && i <= frontmatter.end),
+            hoisted: label.includes("frontmatter"),
+        });
+        i = j;
+    }
+    return { lines, hunks };
+}
+/**
+ * Rewrites the file with the chosen resolution for each listed hunk. Hunks with
+ * no decision keep their markers, so a partial resolution is safe: the file
+ * stays conflicted until every hunk has been decided.
+ */
+export function applyResolutions(text, operation, decisions) {
+    const { lines, hunks } = parseConflicts(text, operation);
+    const byIndex = new Map(decisions.map((d) => [d.index, d]));
+    const unknown = decisions.map((d) => d.index).filter((i) => !hunks.some((h) => h.index === i));
+    const applied = [];
+    const out = [];
+    let cursor = 0;
+    for (const hunk of hunks) {
+        const start = hunk.line - 1;
+        // Re-find the closing marker: hunk bodies are stored without their markers.
+        let end = start;
+        while (end < lines.length && !END.test(lines[end]))
+            end++;
+        out.push(...lines.slice(cursor, start));
+        const decision = byIndex.get(hunk.index);
+        if (!decision) {
+            out.push(...lines.slice(start, end + 1));
+        }
+        else {
+            applied.push(hunk.index);
+            if (decision.take === "local")
+                out.push(...hunk.local);
+            else if (decision.take === "remote")
+                out.push(...hunk.remote);
+            else if (decision.take === "both")
+                out.push(...hunk.local, ...hunk.remote);
+            else if (decision.take === "custom")
+                out.push(...splitLines(decision.content));
+            // "none" drops the hunk entirely.
+        }
+        cursor = end + 1;
+    }
+    out.push(...lines.slice(cursor));
+    return { text: out.join(lineEnding(text)), applied, unknown, remaining: hunks.length - applied.length };
+}
+/** Truncates a side to a character budget, saying how much was withheld. */
+export function preview(side, maxChars) {
+    const text = side.join("\n");
+    if (text.length <= maxChars)
+        return text;
+    const kept = text.slice(0, maxChars);
+    const hiddenLines = text.slice(maxChars).split("\n").length;
+    return `${kept}\n… [${hiddenLines} more line(s), ${text.length - maxChars} chars withheld]`;
+}

package/dist/src/core/git-sync.d.ts

@@ -1,6 +1,39 @@
 import type { StorageEngine } from "./storage-engine.js";
+/**
+ * A merge and a rebase both leave conflicts in the index, but they invert the
+ * meaning of "ours" and "theirs" - so every side-picking decision has to know
+ * which one is running.
+ */
+export type SyncOperation = "merge" | "rebase" | "none";
+/** Which side of a conflict to keep, in terms that stay true under both operations. */
+export type ConflictSide = "local" | "remote";
+/** Who last touched a conflicted file on one side, for reporting without reading it. */
+export interface ConflictAuthor {
+    author: string;
+    date: string;
+    /** Commit subject; push() puts the machine name in it. */
+    subject: string;
+}
+export interface ConflictedFile {
+    /** Path relative to the data directory. */
+    path: string;
+    kind: "content" | "delete-modify" | "add-add";
+    /** For delete-modify: the side that deleted the file. */
+    deletedOn?: ConflictSide;
+    local?: ConflictAuthor;
+    remote?: ConflictAuthor;
+}
+export interface ContinueResult {
+    operation: SyncOperation;
+    done: boolean;
+    /** Files still conflicted - a rebase stops once per replayed commit. */
+    remaining: string[];
+    /** Set only when the operation neither completed nor left a conflict to explain why. */
+    error?: string;
+}
 export interface SyncStatus {
     branch: string;
+    operation: SyncOperation;
     ahead: number;
     behind: number;
     dirty: string[];
@@ -11,13 +44,11 @@ export type PullResult = {
 } | {
     status: "updated";
     changed: string[];
-} | {
-    status: "diverged";
-    ahead: number;
-    behind: number;
+    autoCommitted?: boolean;
 } | {
     status: "conflict";
     conflicted: string[];
+    autoCommitted?: boolean;
 };
 export declare class SyncEngine {
     private storage;
@@ -31,6 +62,13 @@ export declare class SyncEngine {
      */
     private authedUrl;
     private requireConfig;
+    /**
+     * 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.
+     */
+    private ensureMergeDrivers;
     /**
      * 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),
@@ -40,17 +78,84 @@ export declare class SyncEngine {
     ensureRepo(): Promise<void>;
     status(): Promise<SyncStatus>;
     /**
-     * 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.
      */
     pull(): Promise<PullResult>;
     private diffNames;
+    /**
+     * 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.
+     */
+    private commitLocalChanges;
     /** Stages versioned files, commits if there is anything to commit, and pushes. */
     push(message?: string): Promise<{
         pushed: boolean;
         committed: boolean;
         message: string;
     }>;
-    /** Bulk-resolve conflicts by taking one side, then stage the resolved files. */
-    resolveConflict(strategy: "mine" | "theirs", paths?: string[]): Promise<string[]>;
+    /**
+     * 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.
+     */
+    operationInProgress(): Promise<SyncOperation>;
+    /** Index stages recorded for a conflicted path: 1 = base, 2 = ours, 3 = theirs. */
+    private conflictStages;
+    /**
+     * 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.
+     */
+    continueOperation(): Promise<ContinueResult>;
+    /**
+     * 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.
+     */
+    private gitDirect;
+    /**
+     * 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.
+     */
+    private sideRefs;
+    private lastCommitFor;
+    /**
+     * 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.
+     */
+    listConflicts(): Promise<{
+        operation: SyncOperation;
+        files: ConflictedFile[];
+    }>;
+    /** Reads a conflicted file from the working tree, refusing to escape the data dir. */
+    readWorkingFile(relativePath: string): string;
+    /** Writes a resolved file back and stages it when nothing is left conflicted in it. */
+    writeResolvedFile(relativePath: string, content: string, stage: boolean): Promise<void>;
+    /**
+     * 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.
+     */
+    resolveConflict(side: ConflictSide, paths?: string[]): Promise<{
+        resolved: string[];
+        operation: SyncOperation;
+    }>;
 }