@imenam/mcp-documentor 1.0.56 → 1.0.58

package/dist/src/tools/refresh-file-snapshot.js

@@ -2,6 +2,7 @@ import fs from "fs";
 import { RefreshFileSnapshotArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFileHash } from "./check-freshness.js";
 import { relocateAndRefreshSection } from "../core/section-tracker.js";
+import { toAbsolutePath, toStoredPath } from "../core/path-resolver.js";
 export async function refreshFileSnapshot(storageEngine, historyStore, args) {
     try {
         const validated = RefreshFileSnapshotArgsSchema.parse(args);
@@ -17,24 +18,26 @@ export async function refreshFileSnapshot(storageEngine, historyStore, args) {
             const missing = [];
             const skipped = [];
             const anchorsLost = [];
-            // Normalize to forward slashes and lowercase for case-insensitive comparison on Windows
-            // (e.g. stored 'c:\...' vs provided 'C:\...'). file_paths must be absolute paths.
+            // Normalize to forward slashes and lowercase for case-insensitive comparison
+            // on Windows. Agent-supplied file_paths are absolute; map them to the stored
+            // (portable) form so they match tracked.path regardless of representation.
             const norm = (p) => p.replace(/\\/g, "/").toLowerCase();
-            const resolvedFilePaths = validated.file_paths?.map(norm);
+            const resolvedFilePaths = validated.file_paths?.map((p) => norm(toStoredPath(p, resolvedProject)));
             for (const tracked of doc.tracked_files) {
                 if (resolvedFilePaths && !resolvedFilePaths.includes(norm(tracked.path))) {
                     skipped.push(tracked.path);
                     continue;
                 }
-                if (!fs.existsSync(tracked.path)) {
+                const absolutePath = toAbsolutePath(tracked.path, resolvedProject);
+                if (!absolutePath || !fs.existsSync(absolutePath)) {
                     missing.push(tracked.path);
                     continue;
                 }
-                tracked.lastModifiedAt = fs.statSync(tracked.path).mtime.toISOString();
+                tracked.lastModifiedAt = fs.statSync(absolutePath).mtime.toISOString();
                 if (tracked.sections && tracked.sections.length > 0) {
                     let hasLostAnchors = false;
                     const refreshedSections = tracked.sections.map((section) => {
-                        const result = relocateAndRefreshSection(tracked.path, section);
+                        const result = relocateAndRefreshSection(absolutePath, section);
                         if (!result.found)
                             hasLostAnchors = true;
                         return result.found ? result.refreshed : section;
@@ -48,7 +51,7 @@ export async function refreshFileSnapshot(storageEngine, historyStore, args) {
                     }
                 }
                 else {
-                    tracked.contentHash = computeFileHash(tracked.path);
+                    tracked.contentHash = computeFileHash(absolutePath);
                     refreshed.push(tracked.path);
                 }
             }

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

@@ -0,0 +1,17 @@
+import type { SyncEngine } from "../core/git-sync.js";
+import type { StorageEngine } from "../core/storage-engine.js";
+import type { EmbeddingEngine } from "../core/embedding-engine.js";
+import type { EmbeddingStore } from "../core/embedding-store.js";
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+};
+export declare function syncStatus(syncEngine: SyncEngine): Promise<ToolResult>;
+export declare function pullDocs(syncEngine: SyncEngine, storageEngine: StorageEngine, embeddingEngine: EmbeddingEngine, embeddingStore: EmbeddingStore): Promise<ToolResult>;
+export declare function pushDocs(syncEngine: SyncEngine, args: unknown): Promise<ToolResult>;
+export declare function syncDocs(syncEngine: SyncEngine, storageEngine: StorageEngine, embeddingEngine: EmbeddingEngine, embeddingStore: EmbeddingStore, args: unknown): Promise<ToolResult>;
+export declare function resolveSyncConflict(syncEngine: SyncEngine, args: unknown): Promise<ToolResult>;
+export {};

package/dist/src/tools/sync.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { reindexEmbeddings } from "./reindex-embeddings.js";
+function ok(text) {
+    return { content: [{ type: "text", text }] };
+}
+function err(text) {
+    return { 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.";
+export async function syncStatus(syncEngine) {
+    try {
+        if (!syncEngine.isConfigured())
+            return ok(NOT_CONFIGURED);
+        const s = await syncEngine.status();
+        const lines = [
+            `Branch: ${s.branch}`,
+            `Ahead: ${s.ahead} commit(s) · Behind: ${s.behind} commit(s)`,
+            s.conflicted.length > 0 ? `Conflicted files (${s.conflicted.length}):\n  - ${s.conflicted.join("\n  - ")}` : "No conflicts.",
+            s.dirty.length > 0 ? `Uncommitted changes (${s.dirty.length}):\n  - ${s.dirty.join("\n  - ")}` : "Working tree clean.",
+        ];
+        return ok(lines.join("\n"));
+    }
+    catch (e) {
+        return err(`Error getting sync status: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+function describePull(res) {
+    switch (res.status) {
+        case "up-to-date":
+            return "Already up to date — nothing to pull.";
+        case "updated":
+            return `Pulled ${res.changed.length} changed file(s):\n  - ${res.changed.join("\n  - ")}`;
+        case "diverged":
+            return `You have uncommitted local changes while the remote has ${res.behind} new commit(s). No changes applied — your local data is intact. Run push_docs to commit and publish your changes, then pull again to merge.`;
+        case "conflict":
+            return `Merge conflict in ${res.conflicted.length} file(s):\n  - ${res.conflicted.join("\n  - ")}\nEdit these markdown files to resolve, or use resolve_sync_conflict, then push_docs.`;
+    }
+}
+/** Reindex embeddings for new docs after a successful merge. Best-effort. */
+async function reindexAfterPull(res, storageEngine, embeddingEngine, embeddingStore) {
+    if (res.status !== "updated" || res.changed.length === 0)
+        return "";
+    if (!embeddingEngine.isConfigured())
+        return "\n(Embeddings not reindexed: OpenAI key not configured.)";
+    try {
+        await reindexEmbeddings(storageEngine, embeddingEngine, embeddingStore, {});
+        return "\nEmbeddings reindexed for new documents.";
+    }
+    catch (e) {
+        return `\n(Embedding reindex failed: ${e instanceof Error ? e.message : String(e)})`;
+    }
+}
+export async function pullDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore) {
+    try {
+        if (!syncEngine.isConfigured())
+            return err(NOT_CONFIGURED);
+        const res = await syncEngine.pull();
+        const reindexNote = await reindexAfterPull(res, storageEngine, embeddingEngine, embeddingStore);
+        return ok(describePull(res) + reindexNote);
+    }
+    catch (e) {
+        return err(`Error pulling docs: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+const PushDocsArgs = z.object({ message: z.string().optional() });
+export async function pushDocs(syncEngine, args) {
+    try {
+        if (!syncEngine.isConfigured())
+            return err(NOT_CONFIGURED);
+        const v = PushDocsArgs.parse(args);
+        const res = await syncEngine.push(v.message);
+        return ok(res.message);
+    }
+    catch (e) {
+        return err(`Error pushing docs: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+export async function syncDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore, args) {
+    try {
+        if (!syncEngine.isConfigured())
+            return err(NOT_CONFIGURED);
+        const v = PushDocsArgs.parse(args);
+        const pull = await syncEngine.pull();
+        const reindexNote = await reindexAfterPull(pull, storageEngine, embeddingEngine, embeddingStore);
+        // Don't push over a divergence/conflict — surface it so the user can resolve first.
+        if (pull.status === "diverged" || pull.status === "conflict") {
+            return ok(`Pull step:\n${describePull(pull)}${reindexNote}\n\nPush skipped until the above is resolved.`);
+        }
+        const push = await syncEngine.push(v.message);
+        return ok(`Pull step: ${describePull(pull)}${reindexNote}\n\nPush step: ${push.message}`);
+    }
+    catch (e) {
+        return err(`Error syncing docs: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+const ResolveConflictArgs = z.object({
+    strategy: z.enum(["mine", "theirs"]),
+    paths: z.array(z.string()).optional(),
+});
+export async function resolveSyncConflict(syncEngine, args) {
+    try {
+        if (!syncEngine.isConfigured())
+            return err(NOT_CONFIGURED);
+        const v = ResolveConflictArgs.parse(args);
+        const resolved = await syncEngine.resolveConflict(v.strategy, v.paths);
+        if (resolved.length === 0)
+            return ok("No conflicted files to resolve.");
+        return ok(`Resolved ${resolved.length} file(s) keeping "${v.strategy}":\n  - ${resolved.join("\n  - ")}\nReview and run push_docs to finalize.`);
+    }
+    catch (e) {
+        return err(`Error resolving conflict: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}

package/dist/src/tools/update-doc.js

@@ -28,10 +28,10 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
             doc.tracked_files = snapshotTrackedFiles([
                 ...validated.tracked_files,
                 ...additionalTrackedFiles,
-            ]);
+            ], resolvedProject);
         }
         else {
-            doc.tracked_files = mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles);
+            doc.tracked_files = mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles, resolvedProject);
         }
         if (validated.tags !== undefined) {
             doc.tags = validated.tags;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.56";
+export declare const APP_VERSION = "1.0.58";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated version file - do not edit manually
-export const APP_VERSION = '1.0.56';
+export const APP_VERSION = '1.0.58';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-documentor",
-  "version": "1.0.56",
+  "version": "1.0.58",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
@@ -35,12 +35,14 @@
     "jszip": "^3.10.1",
     "openai": "^6.25.0",
     "puppeteer-core": "^25.0.4",
+    "simple-git": "^3.36.0",
     "zod": "^4.3.6"
   },
   "type": "module",
   "bin": {
     "mcp-documentor": "dist/src/index.js",
-    "mcp-documentor-migrate": "scripts/migrate-links.js"
+    "mcp-documentor-migrate": "scripts/migrate-links.js",
+    "mcp-documentor-migrate-paths": "scripts/migrate-paths-to-relative.js"
   },
   "files": [
     "dist",

package/scripts/migrate-paths-to-relative.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * migrate-paths-to-relative.js
+ *
+ * One-shot migration that rewrites the absolute paths stored in each doc's
+ * `tracked_files[].path` into the portable, code-root-relative form introduced
+ * alongside GitHub documentation sync. Portable paths let an agent running on a
+ * different machine (where the codebase lives at a different absolute location)
+ * resolve tracked files correctly.
+ *
+ * Resolution reuses the compiled path-resolver (dist/) so it behaves exactly
+ * like the running server — RUN `npm run build` FIRST.
+ *
+ * The conversion is driven by the same environment variables as the server:
+ *   MCP_DOCUMENTOR_CODE_ROOT    default code root
+ *   MCP_DOCUMENTOR_CODE_ROOTS   JSON map of per-project overrides
+ *
+ * A tracked file whose absolute path is NOT under the project's code root is
+ * left absolute and reported, so nothing is silently broken.
+ *
+ * The data dir is resolved like the server: --data-dir flag, else MCP_DATA_DIR,
+ * else <package>/data. The MCP_DATA_DIR fallback is what makes npx usable.
+ *
+ * Usage (from a clone):
+ *   node scripts/migrate-paths-to-relative.js [--dry-run] [--data-dir <dir>]
+ *
+ * Usage (npx install — no clone):
+ *   MCP_DOCUMENTOR_CODE_ROOT="<repos root>" MCP_DATA_DIR="<your data dir>" \
+ *     npx -p @imenam/mcp-documentor mcp-documentor-migrate-paths --dry-run
+ *
+ * This migration is a ONE-TIME operation: run it once on the machine where the
+ * stored absolute paths are valid, publish the result (sync_docs / push_docs),
+ * and every other machine just pulls and sets its own MCP_DOCUMENTOR_CODE_ROOT.
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import matter from "gray-matter";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.join(__dirname, "..");
+
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+
+// Data dir resolution mirrors the server (StorageEngine.getDataDir):
+//   --data-dir flag  >  MCP_DATA_DIR env  >  <package>/data fallback.
+// The env fallback is what makes `npx` work: the data lives in the user's
+// MCP_DATA_DIR, not inside the npx package cache.
+const dataDirArgIdx = args.indexOf("--data-dir");
+const dataDir =
+  dataDirArgIdx !== -1 && args[dataDirArgIdx + 1]
+    ? args[dataDirArgIdx + 1]
+    : process.env.MCP_DATA_DIR && process.env.MCP_DATA_DIR.trim() !== ""
+      ? process.env.MCP_DATA_DIR.trim()
+      : path.join(rootDir, "data");
+
+// ---------------------------------------------------------------------------
+// Reuse the compiled resolver so migration matches runtime behaviour exactly.
+// ---------------------------------------------------------------------------
+
+const resolverPath = path.join(rootDir, "dist", "src", "core", "path-resolver.js");
+if (!fs.existsSync(resolverPath)) {
+  console.error(`[ERROR] Compiled resolver not found at: ${resolverPath}`);
+  console.error("        Run `npm run build` before this migration.");
+  process.exit(1);
+}
+const { getCodeRoot, toStoredPath } = await import(pathToFileURL(resolverPath).href);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function walkMdFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkMdFiles(fullPath));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+function filePathToDocId(filePath, projectDir) {
+  return path.relative(projectDir, filePath).replace(/\.md$/, "").split(path.sep).join("/");
+}
+
+// ---------------------------------------------------------------------------
+// Load config
+// ---------------------------------------------------------------------------
+
+const configPath = path.join(dataDir, "config.json");
+if (!fs.existsSync(configPath)) {
+  console.error(`[ERROR] config.json not found at: ${configPath}`);
+  console.error("        Make sure --data-dir points to the right directory.");
+  process.exit(1);
+}
+
+const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+const projects = config.projects ?? ["default"];
+
+console.log(`${dryRun ? "[DRY RUN] " : ""}migrate-paths-to-relative`);
+console.log(`Data dir : ${dataDir}`);
+console.log(`Projects : ${projects.length}`);
+console.log("");
+
+// ---------------------------------------------------------------------------
+// Migrate
+// ---------------------------------------------------------------------------
+
+let totalDocsChanged = 0;
+let totalConverted = 0;
+let totalLeftAbsolute = 0;
+const projectsWithoutRoot = [];
+
+for (const project of projects) {
+  const root = getCodeRoot(project);
+  if (!root) {
+    projectsWithoutRoot.push(project);
+    continue;
+  }
+
+  const projectDir = path.join(dataDir, "projects", project);
+  const files = walkMdFiles(projectDir);
+  if (files.length === 0) continue;
+
+  const docChanges = [];
+
+  for (const filePath of files) {
+    const fullId = filePathToDocId(filePath, projectDir);
+    const parsed = matter(fs.readFileSync(filePath, "utf-8"));
+    const tracked = parsed.data.tracked_files;
+    if (!Array.isArray(tracked) || tracked.length === 0) continue;
+
+    let docChanged = false;
+    for (const tf of tracked) {
+      if (!tf || typeof tf.path !== "string") continue;
+      if (!path.isAbsolute(tf.path)) continue; // already relative
+
+      const stored = toStoredPath(tf.path, project);
+      if (path.isAbsolute(stored)) {
+        // Outside the root (or different drive) — resolver kept it absolute.
+        totalLeftAbsolute++;
+        docChanges.push(`  [${fullId}] KEPT ABSOLUTE (outside root): ${tf.path}`);
+        continue;
+      }
+
+      docChanges.push(`  [${fullId}] "${tf.path}"  →  "${stored}"`);
+      tf.path = stored;
+      docChanged = true;
+      totalConverted++;
+    }
+
+    if (docChanged) {
+      totalDocsChanged++;
+      if (!dryRun) {
+        fs.writeFileSync(filePath, matter.stringify(parsed.content, parsed.data), "utf-8");
+      }
+    }
+  }
+
+  if (docChanges.length > 0) {
+    console.log(`### Project: ${project}  (root: ${root})`);
+    docChanges.forEach((c) => console.log(c));
+    console.log("");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+console.log("─".repeat(60));
+console.log(`Paths converted to relative : ${totalConverted}`);
+console.log(`Paths kept absolute         : ${totalLeftAbsolute}  ← outside the code root`);
+console.log(`Docs modified               : ${totalDocsChanged}`);
+if (projectsWithoutRoot.length > 0) {
+  console.log("");
+  console.log(`Projects skipped (no code root configured): ${projectsWithoutRoot.length}`);
+  console.log(`  ${projectsWithoutRoot.join(", ")}`);
+  console.log("  → set MCP_DOCUMENTOR_CODE_ROOT or add them to MCP_DOCUMENTOR_CODE_ROOTS to migrate them.");
+}
+
+if (dryRun) {
+  console.log("");
+  console.log("[DRY RUN] No files were modified. Run without --dry-run to apply.");
+}