@imenam/mcp-documentor 1.0.56 → 1.0.58

package/README.md

@@ -14,6 +14,7 @@ Connect it to Cursor, Claude Desktop, or any MCP-compatible agent to let your AI
 - **Proxy-aware** — integrates with the [proxy-setup](https://github.com/Imena/proxy-setup) for GUI exposure
 - **Links & structure** — `check_links`, `get_doc_tree`, `move_doc`, and `git_diff_doc` for maintenance workflows
 - **Image support** — upload images to a project's assets via `upload_image` (local file path) or directly from the GUI editor; images are stored per-project and rendered inline in the viewer and in PDF exports
+- **GitHub sync** — share your documentation across machines by backing the data directory with a private GitHub repo; the repo/token are fixed by the administrator via environment variables, and the agent can only `pull_docs` / `push_docs` / `sync_docs`
 
 ## Installation
 
@@ -59,6 +60,10 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 | `PROXY_URL` | No | URL of the proxy server to register and launch the GUI |
 | `MCP_DATA_DIR` | No | Overrides the default data directory (see Data storage) |
 | `READ_ONLY` | No | When set to `1`/`true`/`yes`, disables all create/update/delete tools and GUI write actions (read-only mode) |
+| `MCP_DOCUMENTOR_SYNC_REMOTE` | No | HTTPS URL of the private GitHub repo to sync with; enables GitHub sync when set |
+| `MCP_DOCUMENTOR_SYNC_BRANCH` | No | Branch to sync (default: `main`) |
+| `MCP_DOCUMENTOR_SYNC_TOKEN` | No | Fine-grained GitHub PAT used for HTTPS auth (see GitHub sync) |
+| `SYNC_PULL_ON_START` | No | Set to `false` to disable the automatic pull at server startup |
 
 Optional `.env` at the package root (directory containing `package.json` discovered from the installed binary) is loaded when present.
 
@@ -83,6 +88,11 @@ Optional `.env` at the package root (directory containing `package.json` discove
 | `list_projects` | List all documentation projects |
 | `set_project` | Switch the active project **for the GUI only** (not for MCP tools) |
 | `upload_image` | Upload an image from a local file path to a project's assets; returns the markdown link to insert |
+| `sync_status` | Show branch, ahead/behind counts, conflicted files, and uncommitted changes |
+| `pull_docs` | Pull updates from the remote (defensive fast-forward; reindexes new docs) |
+| `push_docs` | Commit local doc changes and push them to the remote |
+| `sync_docs` | Full sync: pull then push (push skipped if the pull reveals a conflict) |
+| `resolve_sync_conflict` | Bulk-resolve merge conflicts by keeping `mine` or `theirs`, then stage |
 
 ## Images in documents
 
@@ -110,10 +120,69 @@ The tool copies the file into `.docs-data/projects/{project}/assets/` and return
 - **URL tab** — paste any external image URL; the markdown link is inserted at the cursor position
 - **Project images gallery** — click any previously uploaded image to re-insert it
 
+## Syncing across machines with GitHub
+
+You can share documentation between several machines by backing the data directory with a **private** GitHub repository. The approach is git-based: only the human-readable markdown, assets, and the shared project list are versioned. Derived state (embeddings) is regenerated locally, and version history stays local to each machine.
+
+### What is and isn't synced
+
+| Synced (versioned) | Local only (gitignored) |
+|---|---|
+| `projects/**` (markdown + assets) | `embeddings.db` (regenerated after pull) |
+| `config.json` (project list) | `history.db` (per-machine version history) |
+| | `local-state.json` (active project) |
+
+### Setup
+
+The sync target is **administrator-controlled**: the repository, branch and token are read from environment variables and **cannot be set or changed by the agent**. The agent can only pull/push against whatever repo you configured.
+
+1. Create an **empty private repo** on GitHub (e.g. `my-docs`).
+2. Create a **fine-grained PAT** scoped to that single repo (Repository permissions → **Contents: Read and write**).
+3. Add the sync environment variables to your MCP client config, per machine:
+
+```jsonc
+{
+  "mcpServers": {
+    "mcp-documentor": {
+      "command": "npx",
+      "args": ["-y", "@imenam/mcp-documentor"],
+      "env": {
+        "MCP_DOCUMENTOR_SYNC_REMOTE": "https://github.com/<you>/my-docs.git",
+        "MCP_DOCUMENTOR_SYNC_BRANCH": "main",            // optional, defaults to "main"
+        "MCP_DOCUMENTOR_SYNC_TOKEN": "github_pat_..."
+      }
+    }
+  }
+}
+```
+
+The token is injected into the `origin` URL inside `.git/config` only (which git never commits) — it is never pushed.
+
+### Daily workflow
+
+- `sync_docs` — pull then push in one step (recommended).
+- `pull_docs` / `push_docs` — granular control.
+- `sync_status` — inspect ahead/behind, conflicts, and uncommitted changes.
+
+By default the server also performs a **defensive pull at startup**: it only fast-forwards a clean working tree and never overwrites local changes (disable with `SYNC_PULL_ON_START=false`). On the first run, a machine with no local data simply clones the remote.
+
+### Conflicts
+
+Because docs are plain markdown, merge conflicts are readable. When `pull_docs` reports a conflict:
+
+- edit the conflicted `.md` files directly (remove the `<<<<<<<` / `>>>>>>>` markers), **or**
+- run `resolve_sync_conflict` with `strategy: "mine"` or `"theirs"` to take one side in bulk,
+
+then run `push_docs` to publish the resolution. If you have **uncommitted** local changes while the remote has moved, the pull reports `diverged` without touching anything — push your changes first, then pull again.
+
+> Read-only machines (`READ_ONLY=1`) can still `pull_docs` and `sync_status`, but `push_docs`, `sync_docs`, and `resolve_sync_conflict` are disabled.
+
 ## Data Storage
 
 By default, data lives under **`.docs-data`** next to the resolved package root (the folder that contains `package.json` for the running install). Set **`MCP_DATA_DIR`** to use another directory. Contents include projects, SQLite/embeddings, and logs under `.docs-data/logs`. This tree is **not** part of the npm package; it is created at runtime.
 
+The active project is a machine-local preference kept in `local-state.json` (gitignored), separate from the shared `config.json`. On first run, a legacy `currentProject` stored in `config.json` is migrated automatically. GitHub sync settings live in environment variables, not on disk.
+
 ## License
 
 ISC

package/dist/shared/read-only.js

@@ -8,4 +8,7 @@ export const WRITE_TOOLS = new Set([
     "create_doc", "update_doc", "patch_doc", "move_doc", "delete_doc",
     "restore_doc_version", "refresh_file_snapshot", "reindex_embeddings",
     "prepare_export_bundle", "delete_export_bundle", "upload_image",
+    // Sync: pull_docs and sync_status stay allowed (read-only consumer machines
+    // still pull updates); these mutate local/remote state and are blocked.
+    "push_docs", "sync_docs", "resolve_sync_conflict",
 ]);

package/dist/shared/schemas/doc.schema.d.ts

@@ -80,6 +80,7 @@ export declare const FreshnessReportSchema: z.ZodObject<{
         up_to_date: "up_to_date";
         stale: "stale";
         no_tracking: "no_tracking";
+        unverifiable: "unverifiable";
     }>;
     modified: z.ZodArray<z.ZodString>;
     missing: z.ZodArray<z.ZodString>;

package/dist/shared/schemas/doc.schema.js

@@ -36,7 +36,7 @@ export const DocSchema = z.object({
     updatedAt: z.string(),
 });
 export const FreshnessReportSchema = z.object({
-    status: z.enum(["up_to_date", "stale", "no_tracking"]),
+    status: z.enum(["up_to_date", "stale", "no_tracking", "unverifiable"]),
     modified: z.array(z.string()),
     missing: z.array(z.string()),
     unchanged: z.array(z.string()),
@@ -47,7 +47,7 @@ export const CreateDocArgsSchema = z.object({
     title: z.string().describe("Title of the documentation entry"),
     content: z.string().optional().describe("Documentation content in markdown"),
     content_file: z.string().optional().describe("Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft."),
-    tracked_files: z.array(TrackedFileInputSchema).optional().describe("Files to track for staleness detection. Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive."),
+    tracked_files: z.array(TrackedFileInputSchema).optional().describe("Files to track for staleness detection. Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths; when MCP_DOCUMENTOR_CODE_ROOT is configured they are stored relative to it so the docs stay portable across machines."),
     tags: z.array(z.string()).optional().describe("Tags for categorization"),
     folder: z.string().optional().describe("Folder path for organization, e.g. 'frontend/components'"),
     related_docs: z.array(z.string()).optional().describe("IDs of related documentation entries"),
@@ -59,7 +59,7 @@ export const UpdateDocArgsSchema = z.object({
     title: z.string().optional().describe("Title of the documentation entry"),
     content: z.string().optional().describe("New content (replaces existing)"),
     content_file: z.string().optional().describe("Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft."),
-    tracked_files: z.array(TrackedFileInputSchema).optional().describe("New list of tracked files (replaces existing). Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive."),
+    tracked_files: z.array(TrackedFileInputSchema).optional().describe("New list of tracked files (replaces existing). Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths; when MCP_DOCUMENTOR_CODE_ROOT is configured they are stored relative to it so the docs stay portable across machines."),
     tags: z.array(z.string()).optional().describe("New tags (replaces existing)"),
     related_docs: z.array(z.string()).optional().describe("Paths of related documentation entries (replaces existing)"),
 });
@@ -80,7 +80,7 @@ export const SearchDocsArgsSchema = z.object({
 });
 export const RefreshFileSnapshotArgsSchema = z.object({
     paths: z.array(z.string()).min(1).describe("Paths of documentation entries to refresh, e.g. ['backend/auth/authentication', 'setup']"),
-    file_paths: z.array(z.string()).optional().describe("Specific tracked file paths to refresh, as absolute paths (refreshes all tracked files if omitted)"),
+    file_paths: z.array(z.string()).optional().describe("Specific tracked files to refresh, as absolute paths (they are matched against the stored paths, relative or absolute). Refreshes all tracked files if omitted."),
 });
 export const GetDocMetadataArgsSchema = z.object({
     path: z.string().describe("Path of the documentation entry, e.g. 'backend/auth/authentication'"),
@@ -101,7 +101,7 @@ export const CheckLinksArgsSchema = z.object({
 });
 export const GitDiffDocArgsSchema = z.object({
     paths: z.array(z.string()).min(1).describe("Paths of documentation entries to diff, e.g. ['backend/auth/authentication']"),
-    file_paths: z.array(z.string()).optional().describe("Specific tracked file paths to diff (all tracked files if omitted)"),
+    file_paths: z.array(z.string()).optional().describe("Specific tracked files to diff, as absolute paths (matched against the stored paths, relative or absolute). All tracked files if omitted."),
 });
 export const SetProjectArgsSchema = z.object({
     project: z.string().describe("Project name to switch to (created if it does not exist)"),

package/dist/src/core/code-ref-resolver.d.ts

@@ -4,11 +4,11 @@ export interface CodeRefResult {
     additionalTrackedFiles: TrackedFileInput[];
 }
 export declare function resolveCodeRefs(content: string): CodeRefResult;
-export declare function snapshotTrackedFiles(inputs: TrackedFileInput[]): TrackedFile[];
+export declare function snapshotTrackedFiles(inputs: TrackedFileInput[], project: string): TrackedFile[];
 /**
  * Merges snapshotted tracked files into an existing list.
  * - If a file is not yet tracked: appended.
  * - If a file is already tracked with sections and the new entry also has sections: sections are merged.
  * - Otherwise (whole-file tracking involved): the existing entry is replaced.
  */
-export declare function mergeTrackedFiles(existing: TrackedFile[], additions: TrackedFileInput[]): TrackedFile[];
+export declare function mergeTrackedFiles(existing: TrackedFile[], additions: TrackedFileInput[], project: string): TrackedFile[];

package/dist/src/core/code-ref-resolver.js

@@ -2,6 +2,7 @@ import crypto from "crypto";
 import fs from "fs";
 import path from "path";
 import { snapshotSection } from "./section-tracker.js";
+import { toStoredPath } from "./path-resolver.js";
 const EXT_TO_LANG = {
     ts: "typescript",
     tsx: "tsx",
@@ -46,18 +47,21 @@ export function resolveCodeRefs(content) {
     });
     return { content: resolved, additionalTrackedFiles };
 }
-export function snapshotTrackedFiles(inputs) {
+export function snapshotTrackedFiles(inputs, project) {
+    // Keyed on the *stored* (portable) path so two inputs pointing at the same
+    // file dedupe regardless of how the agent spelled the path.
     const byPath = new Map();
     for (const input of inputs) {
         const fp = typeof input === "string" ? input : input.path;
         const absolutePath = path.resolve(process.cwd(), fp);
+        const storedPath = toStoredPath(fp, project);
         const mtime = fs.existsSync(absolutePath)
             ? fs.statSync(absolutePath).mtime.toISOString()
             : new Date().toISOString();
         const isWhole = typeof input === "string" || input.lines.length === 0;
-        const existing = byPath.get(absolutePath);
+        const existing = byPath.get(storedPath);
         if (isWhole) {
-            byPath.set(absolutePath, { mtime, lineRanges: [], wholeFile: true });
+            byPath.set(storedPath, { absolutePath, mtime, lineRanges: [], wholeFile: true });
         }
         else if (existing) {
             if (!existing.wholeFile) {
@@ -65,7 +69,8 @@ export function snapshotTrackedFiles(inputs) {
             }
         }
         else {
-            byPath.set(absolutePath, {
+            byPath.set(storedPath, {
+                absolutePath,
                 mtime,
                 lineRanges: [...input.lines],
                 wholeFile: false,
@@ -73,16 +78,16 @@ export function snapshotTrackedFiles(inputs) {
         }
     }
     const tracked = [];
-    for (const [absolutePath, { mtime, lineRanges, wholeFile }] of byPath) {
+    for (const [storedPath, { absolutePath, mtime, lineRanges, wholeFile }] of byPath) {
         if (!wholeFile && lineRanges.length > 0 && fs.existsSync(absolutePath)) {
             const sections = lineRanges
                 .filter(({ start, end }) => start <= end)
                 .map(({ start, end }) => snapshotSection(absolutePath, start, end));
-            tracked.push({ path: absolutePath, lastModifiedAt: mtime, sections });
+            tracked.push({ path: storedPath, lastModifiedAt: mtime, sections });
         }
         else {
             const contentHash = fs.existsSync(absolutePath) ? computeFileHash(absolutePath) : undefined;
-            tracked.push({ path: absolutePath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
+            tracked.push({ path: storedPath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
         }
     }
     return tracked;
@@ -93,10 +98,10 @@ export function snapshotTrackedFiles(inputs) {
  * - If a file is already tracked with sections and the new entry also has sections: sections are merged.
  * - Otherwise (whole-file tracking involved): the existing entry is replaced.
  */
-export function mergeTrackedFiles(existing, additions) {
+export function mergeTrackedFiles(existing, additions, project) {
     if (additions.length === 0)
         return existing;
-    const snapshotted = snapshotTrackedFiles(additions);
+    const snapshotted = snapshotTrackedFiles(additions, project);
     const result = [...existing];
     for (const newTf of snapshotted) {
         const idx = result.findIndex(tf => tf.path === newTf.path);

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

@@ -0,0 +1,56 @@
+import type { StorageEngine } from "./storage-engine.js";
+export interface SyncStatus {
+    branch: string;
+    ahead: number;
+    behind: number;
+    dirty: string[];
+    conflicted: string[];
+}
+export type PullResult = {
+    status: "up-to-date";
+} | {
+    status: "updated";
+    changed: string[];
+} | {
+    status: "diverged";
+    ahead: number;
+    behind: number;
+} | {
+    status: "conflict";
+    conflicted: string[];
+};
+export declare class SyncEngine {
+    private storage;
+    private git;
+    private dataDir;
+    constructor(storage: StorageEngine);
+    isConfigured(): boolean;
+    /**
+     * Builds an authenticated HTTPS URL by injecting the PAT. The result is only
+     * ever stored in .git/config (which git never commits), never versioned.
+     */
+    private authedUrl;
+    private requireConfig;
+    /**
+     * 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),
+     * so normal origin-based fetch/push work and upstream tracking — required for
+     * ahead/behind detection — stays accurate.
+     */
+    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.
+     */
+    pull(): Promise<PullResult>;
+    private diffNames;
+    /** 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[]>;
+}

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

@@ -0,0 +1,215 @@
+import fs from "fs";
+import path from "path";
+import { simpleGit } from "simple-git";
+import { createLogger } from "@imenam/mcp-gui-interface";
+const logger = createLogger("GitSync");
+const GITIGNORE_CONTENT = [
+    "# Derived / machine-local state — never synced",
+    "embeddings.db",
+    "embeddings.db-shm",
+    "embeddings.db-wal",
+    "history.db",
+    "history.db-shm",
+    "history.db-wal",
+    "*.db-shm",
+    "*.db-wal",
+    "logs/",
+    "temps/",
+    "errors-tmp-files/",
+    "export-bundles.json",
+    "local-state.json",
+    "",
+].join("\n");
+export class SyncEngine {
+    storage;
+    git;
+    dataDir;
+    constructor(storage) {
+        this.storage = storage;
+        this.dataDir = storage.getDataDir();
+        fs.mkdirSync(this.dataDir, { recursive: true });
+        this.git = simpleGit(this.dataDir);
+    }
+    isConfigured() {
+        const cfg = this.storage.getSyncConfig();
+        return !!cfg?.remoteUrl;
+    }
+    /**
+     * Builds an authenticated HTTPS URL by injecting the PAT. The result is only
+     * ever stored in .git/config (which git never commits), never versioned.
+     */
+    authedUrl(cfg) {
+        const token = cfg.token;
+        if (!token)
+            return cfg.remoteUrl;
+        try {
+            const u = new URL(cfg.remoteUrl);
+            if (u.protocol !== "https:")
+                return cfg.remoteUrl;
+            u.username = token;
+            u.password = "";
+            return u.toString();
+        }
+        catch {
+            return cfg.remoteUrl;
+        }
+    }
+    requireConfig() {
+        const cfg = this.storage.getSyncConfig();
+        if (!cfg?.remoteUrl) {
+            throw new Error("Sync is not configured. Set MCP_DOCUMENTOR_SYNC_REMOTE (and MCP_DOCUMENTOR_SYNC_TOKEN) in the server environment.");
+        }
+        return cfg;
+    }
+    /**
+     * 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),
+     * so normal origin-based fetch/push work and upstream tracking — required for
+     * ahead/behind detection — stays accurate.
+     */
+    async ensureRepo() {
+        const cfg = this.requireConfig();
+        const authed = this.authedUrl(cfg);
+        const gitignorePath = path.join(this.dataDir, ".gitignore");
+        if (!fs.existsSync(gitignorePath)) {
+            fs.writeFileSync(gitignorePath, GITIGNORE_CONTENT, "utf-8");
+        }
+        if (!fs.existsSync(path.join(this.dataDir, ".git"))) {
+            await this.git.init();
+            logger.info(`Initialized git repo in ${this.dataDir}`);
+        }
+        // (Re)point origin at the authenticated URL.
+        const remotes = await this.git.getRemotes(true);
+        const origin = remotes.find((r) => r.name === "origin");
+        if (!origin) {
+            await this.git.addRemote("origin", authed);
+        }
+        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);
+            }
+        }
+    }
+    async status() {
+        this.requireConfig();
+        const s = await this.git.status();
+        return {
+            branch: s.current ?? "",
+            ahead: s.ahead,
+            behind: s.behind,
+            dirty: s.files.map((f) => f.path),
+            conflicted: s.conflicted,
+        };
+    }
+    /**
+     * Defensive pull: only fast-forwards a clean working tree. Never auto-merges
+     * a divergent history, so local data is never silently overwritten.
+     */
+    async pull() {
+        const cfg = this.requireConfig();
+        await this.ensureRepo();
+        await this.git.fetch("origin", cfg.branch);
+        const remoteRef = `refs/remotes/origin/${cfg.branch}`;
+        // No remote branch yet (fresh repo) — nothing to pull.
+        const hasRemote = await this.git
+            .raw(["rev-parse", "--verify", "--quiet", remoteRef])
+            .then(() => true)
+            .catch(() => false);
+        if (!hasRemote)
+            return { status: "up-to-date" };
+        // Fresh clone: the local branch has no commit yet, so status can't compute
+        // ahead/behind. Materialize the remote branch directly.
+        const hasLocalCommit = await this.git.revparse(["--verify", "HEAD"]).then(() => true).catch(() => false);
+        if (!hasLocalCommit) {
+            await this.git.raw(["reset", "--hard", `origin/${cfg.branch}`]);
+            await this.git.branch(["--set-upstream-to", `origin/${cfg.branch}`, cfg.branch]).catch(() => { });
+            const changed = (await this.git.raw(["ls-tree", "-r", "--name-only", "HEAD"])).split("\n").filter(Boolean);
+            return { status: "updated", changed };
+        }
+        // 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)
+            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 };
+        }
+        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) };
+        }
+        // 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.
+        try {
+            await this.git.merge([`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.");
+        }
+        const merged = await this.git.revparse(["HEAD"]).catch(() => "");
+        return { status: "updated", changed: await this.diffNames(before, merged) };
+    }
+    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 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;
+        }
+        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 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) {
+        this.requireConfig();
+        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 targets;
+    }
+}

package/dist/src/core/path-resolver.d.ts

@@ -0,0 +1,20 @@
+/** Test-only: clears the memoised env snapshot so a changed env is re-read. */
+export declare function resetCodeRootsCache(): void;
+/** The configured code root for a project, or undefined if none applies. */
+export declare function getCodeRoot(project: string): string | undefined;
+/**
+ * Converts an input path (typically the absolute path supplied by an agent)
+ * into the portable form persisted in a doc.
+ *
+ * Falls back to an absolute path — with a warning — when there is no code root,
+ * or when the file lives outside the root (including a different Windows drive).
+ */
+export declare function toStoredPath(inputPath: string, project: string): string;
+/**
+ * Resolves a stored path to an absolute filesystem path on this machine.
+ *
+ *  - absolute stored path (legacy / fallback)  → returned as-is
+ *  - relative stored path + configured root     → joined with the root
+ *  - relative stored path + no root configured  → undefined (unverifiable here)
+ */
+export declare function toAbsolutePath(stored: string, project: string): string | undefined;

package/dist/src/core/path-resolver.js

@@ -0,0 +1,82 @@
+import path from "path";
+import { createLogger } from "@imenam/mcp-gui-interface";
+const logger = createLogger("PathResolver");
+let cached;
+function loadCodeRoots() {
+    if (cached)
+        return cached;
+    const defaultRoot = process.env.MCP_DOCUMENTOR_CODE_ROOT?.trim() || undefined;
+    let byProject = {};
+    const rawMap = process.env.MCP_DOCUMENTOR_CODE_ROOTS?.trim();
+    if (rawMap) {
+        try {
+            const parsed = JSON.parse(rawMap);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                for (const [proj, root] of Object.entries(parsed)) {
+                    if (typeof root === "string" && root.trim() !== "") {
+                        byProject[proj] = root.trim();
+                    }
+                }
+            }
+            else {
+                logger.warn("MCP_DOCUMENTOR_CODE_ROOTS is not a JSON object, ignoring it");
+            }
+        }
+        catch {
+            logger.warn("Failed to parse MCP_DOCUMENTOR_CODE_ROOTS as JSON, ignoring it");
+        }
+    }
+    cached = { default: defaultRoot, byProject };
+    return cached;
+}
+/** Test-only: clears the memoised env snapshot so a changed env is re-read. */
+export function resetCodeRootsCache() {
+    cached = undefined;
+}
+/** The configured code root for a project, or undefined if none applies. */
+export function getCodeRoot(project) {
+    const roots = loadCodeRoots();
+    return roots.byProject[project] ?? roots.default;
+}
+function toForwardSlashes(p) {
+    return p.split(path.sep).join("/");
+}
+/**
+ * Converts an input path (typically the absolute path supplied by an agent)
+ * into the portable form persisted in a doc.
+ *
+ * Falls back to an absolute path — with a warning — when there is no code root,
+ * or when the file lives outside the root (including a different Windows drive).
+ */
+export function toStoredPath(inputPath, project) {
+    const abs = path.resolve(process.cwd(), inputPath);
+    const root = getCodeRoot(project);
+    if (!root) {
+        return toForwardSlashes(abs);
+    }
+    const rel = path.relative(path.resolve(root), abs);
+    // `rel` escaping the root ("../…") or being absolute (different drive on
+    // Windows) means the file is not under the root — keep it absolute.
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+        logger.warn(`tracked file "${abs}" is outside the code root for project "${project}" (${root}); storing as an absolute path`);
+        return toForwardSlashes(abs);
+    }
+    return toForwardSlashes(rel);
+}
+/**
+ * Resolves a stored path to an absolute filesystem path on this machine.
+ *
+ *  - absolute stored path (legacy / fallback)  → returned as-is
+ *  - relative stored path + configured root     → joined with the root
+ *  - relative stored path + no root configured  → undefined (unverifiable here)
+ */
+export function toAbsolutePath(stored, project) {
+    if (path.isAbsolute(stored)) {
+        return stored;
+    }
+    const root = getCodeRoot(project);
+    if (!root) {
+        return undefined;
+    }
+    return path.resolve(root, stored);
+}