@imenam/mcp-documentor 1.0.62 → 1.0.64

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

@@ -65,6 +65,8 @@ export interface DocSummary {
     updatedAt: string;
     tags: string[];
     isStale: boolean;
+    /** True when tracked entries have no snapshot and freshness cannot be computed. */
+    isBroken?: boolean;
     folder?: string;
 }
 export interface DocMatch {
@@ -81,11 +83,13 @@ export declare const FreshnessReportSchema: z.ZodObject<{
         stale: "stale";
         no_tracking: "no_tracking";
         unverifiable: "unverifiable";
+        broken: "broken";
     }>;
     modified: z.ZodArray<z.ZodString>;
     missing: z.ZodArray<z.ZodString>;
     unchanged: z.ZodArray<z.ZodString>;
     anchors_lost: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    broken: z.ZodDefault<z.ZodArray<z.ZodString>>;
     total: z.ZodNumber;
 }, z.core.$strip>;
 export type FreshnessReport = z.infer<typeof FreshnessReportSchema>;

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

@@ -36,11 +36,13 @@ export const DocSchema = z.object({
     updatedAt: z.string(),
 });
 export const FreshnessReportSchema = z.object({
-    status: z.enum(["up_to_date", "stale", "no_tracking", "unverifiable"]),
+    status: z.enum(["up_to_date", "stale", "no_tracking", "unverifiable", "broken"]),
     modified: z.array(z.string()),
     missing: z.array(z.string()),
     unchanged: z.array(z.string()),
     anchors_lost: z.array(z.string()).default([]),
+    /** Entries with neither sections nor contentHash (pre hash-based tracking) — cannot be checked until re-tracked. */
+    broken: z.array(z.string()).default([]),
     total: z.number(),
 });
 export const CreateDocArgsSchema = z.object({

package/dist/src/index.js

@@ -81,6 +81,9 @@ storageEngine.setHistoryStore(historyStore);
 const syncEngine = new SyncEngine(storageEngine);
 const server = new Server({ name: "mcp-documentor", version: APP_VERSION }, { capabilities: { tools: {} } });
 let guiLauncher;
+let guiStatus = "disabled";
+let guiUrl = null;
+let guiStartWaiter = null;
 const sseControllers = new Set();
 function broadcastToGUI(message) {
     const child = guiLauncher.getProcess();
@@ -95,9 +98,15 @@ function broadcastToGUI(message) {
 }
 function handleIPCMessage(msg) {
     if (msg.type === "ALREADY_RUNNING") {
+        guiStatus = "already_running";
+        guiUrl = msg.data?.url ?? guiUrl;
+        guiStartWaiter?.({ outcome: "already_running", url: msg.data?.url });
         logger.info(`GUI is already running at: ${msg.data?.url || "unknown URL"}.`);
     }
     else if (msg.type === "READY") {
+        guiStatus = "ready";
+        guiUrl = msg.data?.url ?? null;
+        guiStartWaiter?.({ outcome: "ready", url: msg.data?.url });
         logger.info(`GUI is ready! Access it at: ${msg.data.url}`);
     }
     else if (msg.type === "GET_INITIAL_STATE") {
@@ -159,15 +168,9 @@ async function handleGetInitialState(msg) {
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id); // doc.id is now the full path
             if (full && full.tracked_files.length > 0) {
-                // A doc whose freshness cannot be computed (legacy hash-less entries)
-                // needs attention: surface it as stale rather than crashing the view.
-                try {
-                    const report = computeFreshness(full.tracked_files, config.currentProject);
-                    doc.isStale = report.status === "stale";
-                }
-                catch {
-                    doc.isStale = true;
-                }
+                const report = computeFreshness(full.tracked_files, config.currentProject);
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
             }
         }
         const bundles = storageEngine.getBundles();
@@ -204,13 +207,9 @@ async function handleUpdateProject(msg) {
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
-                try {
-                    const report = computeFreshness(full.tracked_files, project);
-                    doc.isStale = report.status === "stale";
-                }
-                catch {
-                    doc.isStale = true;
-                }
+                const report = computeFreshness(full.tracked_files, project);
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
             }
         }
         broadcastToGUI({
@@ -250,13 +249,9 @@ async function handleListDocs(msg) {
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
-                try {
-                    const report = computeFreshness(full.tracked_files, currentProject);
-                    doc.isStale = report.status === "stale";
-                }
-                catch {
-                    doc.isStale = true;
-                }
+                const report = computeFreshness(full.tracked_files, currentProject);
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
             }
         }
         broadcastToGUI({
@@ -368,15 +363,9 @@ async function handleCreateDocIPC(msg) {
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
-                // A doc whose freshness cannot be computed (legacy hash-less entries)
-                // needs attention: surface it as stale rather than crashing the view.
-                try {
-                    const report = computeFreshness(full.tracked_files, config.currentProject);
-                    doc.isStale = report.status === "stale";
-                }
-                catch {
-                    doc.isStale = true;
-                }
+                const report = computeFreshness(full.tracked_files, config.currentProject);
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
             }
         }
         broadcastToGUI({
@@ -661,13 +650,70 @@ guiLauncher = new GuiLauncher({
         handleIPCMessage(msg);
     },
 });
+function startGuiWorker() {
+    guiStatus = "starting";
+    const child = guiLauncher.start();
+    child.on("exit", () => {
+        // Un start() ultérieur remplace le process courant : seul l'exit du process
+        // actif change l'état. ALREADY_RUNNING = la GUI vit dans une autre instance,
+        // l'exit du worker est alors attendu.
+        if (guiLauncher.getProcess() === child && guiStatus !== "already_running") {
+            guiStatus = "stopped";
+        }
+    });
+    return child;
+}
 function launchGUI() {
     if (!process.env.PROXY_URL) {
         logger.info('[MASTER] PROXY_URL non défini — GUI désactivée.');
+        guiStatus = "disabled";
         return;
     }
     logger.info("Launching GUI worker...");
-    guiLauncher.start();
+    startGuiWorker();
+}
+async function reconnectGui(args) {
+    getConfig(); // relit le .env au cas où PROXY_URL aurait été ajouté après le démarrage
+    if (!process.env.PROXY_URL) {
+        return {
+            content: [{ type: "text", text: "Error: PROXY_URL is not set — the GUI is disabled. Add PROXY_URL to the .env file, then call reconnect_gui again." }],
+            isError: true,
+        };
+    }
+    const child = guiLauncher.getProcess();
+    const alive = !!child && child.exitCode === null && !child.killed;
+    const force = args?.force === true;
+    if (alive && !force) {
+        if (guiStatus === "starting") {
+            return { content: [{ type: "text", text: "GUI worker is already starting (proxy registration in progress). Wait a few seconds, then call reconnect_gui again if needed." }] };
+        }
+        return { content: [{ type: "text", text: `GUI is already registered with the proxy${guiUrl ? ` at ${guiUrl}` : ""}. Nothing to do (use force=true to restart it anyway).` }] };
+    }
+    logger.info(`[MASTER] reconnect_gui: ${alive ? "restarting (force)" : "relaunching"} GUI worker...`);
+    const result = await new Promise((resolve) => {
+        const newChild = startGuiWorker();
+        const onExit = (code) => { cleanup(); resolve({ outcome: "exited", code }); };
+        const timer = setTimeout(() => { cleanup(); resolve({ outcome: "timeout" }); }, 15000);
+        const cleanup = () => { clearTimeout(timer); newChild.off("exit", onExit); guiStartWaiter = null; };
+        guiStartWaiter = (r) => { cleanup(); resolve(r); };
+        newChild.on("exit", onExit);
+    });
+    if (result.outcome === "ready") {
+        return { content: [{ type: "text", text: `GUI reconnected and registered with the proxy. URL: ${result.url}` }] };
+    }
+    if (result.outcome === "already_running") {
+        return { content: [{ type: "text", text: `GUI is already registered by another MCP instance. URL: ${result.url ?? "unknown"}` }] };
+    }
+    if (result.outcome === "exited") {
+        return {
+            content: [{ type: "text", text: `GUI worker exited before completing registration (code=${result.code}). The proxy server is probably still unreachable at ${process.env.PROXY_URL}. Start the proxy server, then call reconnect_gui again.` }],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: "text", text: "GUI worker started but did not confirm proxy registration within 15s. Check the logs (.docs-data/logs), then retry." }],
+        isError: true,
+    };
 }
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     const tools = [
@@ -1103,6 +1149,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 required: ["strategy"],
             },
         },
+        {
+            name: "reconnect_gui",
+            description: "Relaunch the GUI worker and re-register it with the proxy server. Use this when the proxy server was not running when the MCP server started (so the GUI registration failed), to redeploy the GUI without restarting the MCP server. Does nothing if the GUI is already registered, unless force=true.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    force: { type: "boolean", description: "Restart the GUI worker even if it is already running and registered (default: false)" },
+                },
+            },
+        },
     ];
     return {
         tools: isReadOnly() ? tools.filter((t) => !WRITE_TOOLS.has(t.name)) : tools,
@@ -1194,6 +1250,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return await syncDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore, args);
             case "resolve_sync_conflict":
                 return await resolveSyncConflict(syncEngine, args);
+            case "reconnect_gui":
+                return await reconnectGui(args);
             default:
                 throw new Error(`Tool not found: ${name}`);
         }

package/dist/src/tools/check-freshness.js

@@ -8,12 +8,13 @@ export function computeFileHash(absolutePath) {
 }
 export function computeFreshness(trackedFiles, project) {
     if (!trackedFiles || trackedFiles.length === 0) {
-        return { status: "no_tracking", modified: [], missing: [], unchanged: [], anchors_lost: [], total: 0 };
+        return { status: "no_tracking", modified: [], missing: [], unchanged: [], anchors_lost: [], broken: [], total: 0 };
     }
     const modified = [];
     const missing = [];
     const unchanged = [];
     const anchors_lost = [];
+    const broken = [];
     for (const tracked of trackedFiles) {
         // A relative path with no code root configured on this machine is not
         // resolvable here — count it as absent so we end up "unverifiable" rather
@@ -61,8 +62,10 @@ export function computeFreshness(trackedFiles, project) {
         }
         else {
             // Hash comparison is the only freshness system. An entry with neither
-            // sections nor contentHash predates it and cannot be checked.
-            throw new Error(`Tracked file "${tracked.path}" has no contentHash and no sections — it predates hash-based tracking. Call refresh_file_snapshot on this doc to snapshot it, or re-declare it via update_doc.`);
+            // sections nor contentHash predates it and cannot be checked — it is
+            // reported as broken (never checked by any other means) so readers can
+            // still expose the doc and its tracked list to the agent for re-tracking.
+            broken.push(tracked.path);
         }
     }
     // When every tracked file is absent, the source code simply isn't present on
@@ -72,15 +75,18 @@ export function computeFreshness(trackedFiles, project) {
     // change signal (likely deletions) and still counts as stale.
     const allMissing = missing.length === trackedFiles.length;
     if (allMissing) {
-        return { status: "unverifiable", modified, missing, unchanged, anchors_lost, total: trackedFiles.length };
+        return { status: "unverifiable", modified, missing, unchanged, anchors_lost, broken, total: trackedFiles.length };
     }
     const isStale = modified.length > 0 || missing.length > 0 || anchors_lost.length > 0;
+    // Broken tracking outranks everything: no freshness verdict is trustworthy
+    // until the broken entries are re-tracked.
     return {
-        status: isStale ? "stale" : "up_to_date",
+        status: broken.length > 0 ? "broken" : isStale ? "stale" : "up_to_date",
         modified,
         missing,
         unchanged,
         anchors_lost,
+        broken,
         total: trackedFiles.length,
     };
 }
@@ -91,11 +97,23 @@ export function formatFreshnessReport(title, report) {
     if (report.status === "unverifiable") {
         return `UNVERIFIABLE: "${title}" — none of the ${report.total} tracked file(s) are present on this machine, so freshness cannot be checked here. This is expected when the documentation is cloned without its source codebase.`;
     }
-    let text = report.status === "stale"
-        ? `STALE: "${title}" — tracked files have changed since the documentation was last updated.\n`
-        : `UP TO DATE: "${title}" — no tracked files have been modified.\n`;
+    let text;
+    if (report.status === "broken") {
+        text = `BROKEN TRACKING: "${title}" — some tracked entries have no content snapshot and cannot be checked.\n`;
+    }
+    else if (report.status === "stale") {
+        text = `STALE: "${title}" — tracked files have changed since the documentation was last updated.\n`;
+    }
+    else {
+        text = `UP TO DATE: "${title}" — no tracked files have been modified.\n`;
+    }
     const anchorLostCount = report.anchors_lost?.length ?? 0;
-    text += `\nSummary: ${report.modified.length} modified, ${report.missing.length} missing, ${anchorLostCount} with lost anchors, ${report.unchanged.length} unchanged out of ${report.total} tracked file(s).`;
+    const brokenCount = report.broken?.length ?? 0;
+    text += `\nSummary: ${report.modified.length} modified, ${report.missing.length} missing, ${anchorLostCount} with lost anchors, ${brokenCount} with broken tracking, ${report.unchanged.length} unchanged out of ${report.total} tracked file(s).`;
+    if (brokenCount > 0) {
+        text += `\n\n⚠ Files with broken tracking — no snapshot to compare against:\n${report.broken.map((f) => `  - ${f}`).join("\n")}`;
+        text += `\n  → These entries predate hash-based tracking. Re-read the source files and re-declare them in tracked_files via update_doc, or call refresh_file_snapshot if the doc content is still accurate.`;
+    }
     if (report.modified.length > 0) {
         text += `\n\nModified files (call refresh_file_snapshot to acknowledge):\n${report.modified.map((f) => `  - ${f}`).join("\n")}`;
     }
@@ -125,16 +143,12 @@ async function scanProjectFreshness(storageEngine, project) {
         const doc = await storageEngine.getDoc(summary.id, project);
         if (!doc)
             continue;
-        let report;
-        try {
-            report = computeFreshness(doc.tracked_files, project);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            scan.broken.push(`  - **${doc.title}** [${doc.id}]: ${message}`);
-            continue;
+        const report = computeFreshness(doc.tracked_files, project);
+        if (report.status === "broken") {
+            const files = report.broken.map((f) => `    • no snapshot: ${f}`).join("\n");
+            scan.broken.push(`  - **${doc.title}** [${doc.id}]\n${files}`);
         }
-        if (report.status === "no_tracking") {
+        else if (report.status === "no_tracking") {
             scan.noTracking.push(doc.title);
         }
         else if (report.status === "unverifiable") {

package/dist/src/tools/get-doc-metadata.js

@@ -13,6 +13,8 @@ export async function getDocMetadata(storageEngine, args) {
         const { doc, project } = resolved;
         const report = computeFreshness(doc.tracked_files, project);
         const fileStatusIcon = (filePath) => {
+            if (report.broken.includes(filePath))
+                return "⚠ broken tracking (no snapshot — re-declare via update_doc or run refresh_file_snapshot)";
             if (report.modified.includes(filePath))
                 return "✗ modified";
             if (report.missing.includes(filePath))

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

@@ -29,8 +29,20 @@ export async function getDoc(storageEngine, args) {
             }).join("\n")
             : "  (none)";
         const freshnessReport = computeFreshness(doc.tracked_files, resolvedProject);
-        const stalenessBanner = freshnessReport.status === "stale"
-            ? [
+        let stalenessBanner = "";
+        if (freshnessReport.status === "broken") {
+            stalenessBanner = [
+                `> [!WARNING]`,
+                `> **Le suivi de fichiers de cette documentation est cassé.**`,
+                `> Les entrées suivantes n'ont aucun snapshot de contenu et ne peuvent pas être vérifiées :`,
+                ...freshnessReport.broken.map((f) => `> - \`${f}\` *(aucun snapshot)*`),
+                `>`,
+                `> La fraîcheur de ce document est invérifiable tant que ces entrées ne sont pas re-suivies. Relisez les fichiers sources et re-déclarez-les via \`update_doc\` (tracked_files), ou appelez \`refresh_file_snapshot\` si le contenu ci-dessous est encore exact.`,
+                ``,
+            ].join("\n");
+        }
+        else if (freshnessReport.status === "stale") {
+            stalenessBanner = [
                 `> [!WARNING]`,
                 `> **Cette documentation est potentiellement obsolète.**`,
                 `> Les fichiers suivants ont été modifiés depuis la dernière mise à jour de ce document :`,
@@ -41,8 +53,8 @@ export async function getDoc(storageEngine, args) {
                 `>`,
                 `> Vérifiez si le contenu ci-dessous est toujours valide. Si nécessaire, utilisez \`git_diff_doc\` pour voir les changements, puis mettez à jour la documentation avec \`patch_doc\` ou \`update_doc\`.`,
                 ``,
-            ].join("\n")
-            : "";
+            ].join("\n");
+        }
         const text = [
             stalenessBanner,
             `# ${doc.title}`,

package/dist/src/tools/git-diff-doc.js

@@ -62,7 +62,9 @@ export async function gitDiffDoc(storageEngine, args) {
             }
             else {
                 const freshness = computeFreshness(doc.tracked_files, project);
-                const changedPaths = new Set([...freshness.modified, ...freshness.missing]);
+                // Broken entries (no snapshot) can't be hash-compared, but the git diff
+                // is still the best signal the agent has to re-assess them — include them.
+                const changedPaths = new Set([...freshness.modified, ...freshness.missing, ...freshness.broken]);
                 filesToDiff = doc.tracked_files.filter((tf) => changedPaths.has(tf.path));
             }
             if (filesToDiff.length === 0) {

package/dist/src/tools/list-docs.js

@@ -21,7 +21,7 @@ function renderProjectDocs(summaries, totalLabel) {
         if (key)
             lines.push(`\n  📁 ${key}`);
         for (const s of groups.get(key)) {
-            const staleTag = s.isStale ? " [STALE]" : "";
+            const staleTag = s.isBroken ? " [BROKEN TRACKING]" : s.isStale ? " [STALE]" : "";
             const tags = s.tags.length > 0 ? ` (${s.tags.join(", ")})` : "";
             const indent = key ? "    " : "  ";
             lines.push(`${indent}- ${s.title} [${s.id}]${tags}${staleTag} — updated ${s.updatedAt}`);
@@ -43,6 +43,7 @@ export async function listDocs(storageEngine, args) {
                 if (doc && doc.tracked_files.length > 0) {
                     const report = computeFreshness(doc.tracked_files, proj);
                     summary.isStale = report.status === "stale";
+                    summary.isBroken = report.status === "broken";
                 }
             }
             if (summaries.length === 0) {
@@ -61,6 +62,7 @@ export async function listDocs(storageEngine, args) {
                 if (doc && doc.tracked_files.length > 0) {
                     const report = computeFreshness(doc.tracked_files, proj);
                     summary.isStale = report.status === "stale";
+                    summary.isBroken = report.status === "broken";
                 }
             }
             grandTotal += summaries.length;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.62";
+export declare const APP_VERSION = "1.0.64";

package/dist/src/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-documentor",
-  "version": "1.0.62",
+  "version": "1.0.64",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",