@imenam/mcp-documentor 1.0.91 → 1.0.92

package/README.md

@@ -12,7 +12,7 @@ Connect it to Cursor, Claude Desktop, or any MCP-compatible agent to let your AI
 - **Track a branch, not a checkout** — point a project at a GitHub branch from its settings in the GUI and freshness is measured against *published* code: switching branches or editing without committing no longer makes docs look stale, and a server with no copy of the codebase (an MCP gateway) can still verify them
 - **Semantic search** — find relevant docs by meaning (requires an OpenAI API key)
 - **Multi-project support** — organize docs into separate projects; every MCP tool names the project it targets, and the GUI's project selector is a per-browser view preference
-- **GUI** — built-in web interface, either behind the proxy (`PROXY_URL`) or served directly on a local port (`APP_PORT`); with neither, the GUI worker is not started. Navigation runs from an icon rail on the left: the current project's badge (click to switch projects or create one), then Documentation, Search (`Ctrl/⌘ + K`, current or all projects), Outdated, Recent, Export bundles and Logs, with Sync and Settings at the bottom. Each destination fills the panel next to the rail; the panel's hide button, or a second click on the active icon, folds it away. Drag the panel's right edge to resize it (double-click resets the width); the browser remembers the width. The details panel on the right of a document (`Ctrl/⌘ + \`) is open by default from 1280 px wide; showing or hiding it by hand is remembered across reloads until the window crosses that width. Badges show the outdated docs, pending commits and the day's failed GitHub calls
+- **GUI** — built-in web interface, either behind the proxy (`PROXY_URL`) or served directly on a local port (`APP_PORT`); with neither, the GUI worker is not started. Navigation runs from an icon rail on the left: the current project's badge (click to switch projects or create one), then Documentation, Search (`Ctrl/⌘ + K`, current or all projects), Outdated, Recent, Export bundles and Logs, with Sync and Settings at the bottom. Each destination fills the panel next to the rail; the panel's hide button, or a second click on the active icon, folds it away. Drag the panel's right edge to resize it (double-click resets the width); the browser remembers the width. The details panel on the right of a document (`Ctrl/⌘ + \`) is open by default from 1280 px wide; showing or hiding it by hand is remembered across reloads until the window crosses that width. Badges show the outdated docs, pending commits and the day's failed GitHub calls. Each open tab polls `GET /api/changes` every 3 seconds and every request is answered immediately: no connection stays open, so many tabs can share the proxy's origin, and changes made by the agent show up within 3 seconds. After a GUI worker restart, or when it has fallen more than 200 changes behind, the tab reloads the server state (`GET /api/initial-state`) and the list of the project it shows
 - **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
@@ -320,7 +320,7 @@ Everything else is content-addressed: a commit's tree is cached by its sha for t
 
 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.
 
-There is no server-side "active project": every MCP tool call names its project, and the GUI's selector only changes what that browser displays (kept in the URL and in `localStorage`). A legacy `currentProject` left in `config.json` is dropped on first read. GitHub sync settings live in environment variables, not on disk.
+There is no server-side "active project": every MCP tool call names its project, and the GUI's selector only changes what that browser displays (kept in the URL and in `localStorage`). The open and closed folders of each project's navigation tree are also kept in `localStorage`, so a reload restores them. A legacy `currentProject` left in `config.json` is dropped on first read. GitHub sync settings live in environment variables, not on disk.
 
 ## License
 

package/dist/src/gui-worker.js

@@ -1,7 +1,6 @@
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { Hono } from "hono";
-import { streamSSE } from "hono/streaming";
 import { GUI_LISTEN_HOST, ProxyClient, honoGuiGuard } from "@imenam/mcp-gui-interface";
 import { IPCMessageSchema } from "../shared/schemas/doc.schema.js";
 import { isReadOnly } from "../shared/read-only.js";
@@ -9,6 +8,7 @@ import path from "path";
 import fs from "fs";
 import { execFile, spawn } from "child_process";
 import { Readable } from "stream";
+import { randomUUID } from "crypto";
 import { promisify } from "util";
 const execFileAsync = promisify(execFile);
 import { fileURLToPath } from "url";
@@ -129,7 +129,6 @@ let guiPublicUrl = '';
 const app = new Hono();
 app.use("*", honoGuiGuard());
 let proxyClient = null;
-const sseControllers = new Set();
 const pendingRequests = new Map();
 function safeSend(message) {
     if (process.send && process.connected) {
@@ -171,6 +170,27 @@ function ipcRequest(type, data, timeout = 5000) {
         }
     });
 }
+/** Message types the master pushes to every GUI, journaled for `/api/changes`. */
+const BROADCAST_TYPES = [
+    "INITIAL_STATE",
+    "CONFIG_UPDATED",
+    "BUNDLES_UPDATED",
+    "PROJECTS_CHANGED",
+    "DOCS_CHANGED",
+    "CODE_SOURCES_CHANGED",
+];
+/** Number of pushed messages kept for clients catching up. */
+const CHANGE_JOURNAL_SIZE = 200;
+/** Identifies this worker run: a client holding another epoch has missed everything since. */
+const workerEpoch = randomUUID();
+let changeSeq = 0;
+const changeJournal = [];
+function recordChange(message) {
+    changeSeq += 1;
+    changeJournal.push({ seq: changeSeq, message });
+    if (changeJournal.length > CHANGE_JOURNAL_SIZE)
+        changeJournal.shift();
+}
 function setupIpcErrorHandlers() {
     process.on("error", (err) => {
         if (err.code === "ERR_IPC_CHANNEL_CLOSED")
@@ -179,7 +199,7 @@ function setupIpcErrorHandlers() {
     });
     process.on("disconnect", () => {
         logger.warn("IPC disconnected from MCP master (parent closed the channel or process exited). " +
-            "GUI worker will exit; EventSource clients will show Disconnected.");
+            "GUI worker will exit.");
         process.exit(0);
     });
     process.on("message", (msg) => {
@@ -199,24 +219,8 @@ function setupIpcErrorHandlers() {
             });
             return;
         }
-        const BROADCAST_TYPES = [
-            "INITIAL_STATE",
-            "CONFIG_UPDATED",
-            "BUNDLES_UPDATED",
-            "PROJECTS_CHANGED",
-            "DOCS_CHANGED",
-            "CODE_SOURCES_CHANGED",
-        ];
-        if (msg && BROADCAST_TYPES.includes(msg.type)) {
-            for (const controller of sseControllers) {
-                try {
-                    controller.writeSSE({ data: JSON.stringify(msg), event: "message" });
-                }
-                catch {
-                    sseControllers.delete(controller);
-                }
-            }
-        }
+        if (msg && BROADCAST_TYPES.includes(msg.type))
+            recordChange(msg);
     });
 }
 // --- HTTP Routes ---
@@ -251,54 +255,34 @@ app.get("/proxy/health", (c) => {
         timestamp: new Date().toISOString(),
     });
 });
-app.get("/api/events", (c) => {
-    return streamSSE(c, async (stream) => {
-        const clientId = Math.random().toString(36).slice(2, 11);
-        const openedAt = Date.now();
-        sseControllers.add(stream);
-        logger.info(`SSE /api/events: client connected (id=${clientId})`);
-        stream.onAbort(() => {
-            sseControllers.delete(stream);
-            logger.warn(`SSE /api/events: stream aborted (id=${clientId}, durationMs=${Date.now() - openedAt}). ` +
-                "Typical causes: user navigated away, proxy closed idle connection, or network drop. " +
-                "Browser will retry EventSource and may log client-diagnostics with readyState.");
-        });
-        const initialSent = safeSend({ type: "GET_INITIAL_STATE", timestamp: new Date().toISOString() });
-        if (!initialSent) {
-            logger.warn(`SSE /api/events: GET_INITIAL_STATE not sent to master (id=${clientId}). ` +
-                `IPC unavailable: process.connected=${process.connected}, process.send=${typeof process.send}. ` +
-                "Dashboard will stay Disconnected until IPC to the MCP process works.");
-        }
-        try {
-            await stream.writeSSE({ data: "connected", event: "ping" });
-        }
-        catch (err) {
-            logger.warn(`SSE /api/events: initial writeSSE failed (id=${clientId}): ${err?.message ?? err}`);
-            sseControllers.delete(stream);
-            return;
-        }
-        while (true) {
-            await stream.sleep(30000);
-            try {
-                await stream.writeSSE({ data: "ping", event: "ping" });
-            }
-            catch (err) {
-                logger.warn(`SSE /api/events: keepalive ping failed (id=${clientId}): ${err?.message ?? err}`);
-                sseControllers.delete(stream);
-                break;
-            }
-        }
+// Answers immediately with the pushed messages after `since`, or `reset: true` when the
+// client must reload the whole state: no cursor, another worker run, or messages dropped.
+app.get("/api/changes", (c) => {
+    const since = c.req.query("since");
+    const epoch = c.req.query("epoch");
+    if (since !== undefined && !/^\d+$/.test(since)) {
+        return c.json({ error: `since must be a non-negative integer, got "${since}"` }, 400);
+    }
+    const reset = { epoch: workerEpoch, seq: changeSeq, reset: true };
+    if (since === undefined || epoch !== workerEpoch)
+        return c.json(reset);
+    const from = Number(since);
+    const oldestKept = changeJournal.length > 0 ? changeJournal[0].seq : changeSeq + 1;
+    if (from > changeSeq || from < oldestKept - 1)
+        return c.json(reset);
+    return c.json({
+        epoch: workerEpoch,
+        seq: changeSeq,
+        reset: false,
+        events: changeJournal.filter((entry) => entry.seq > from).map((entry) => entry.message),
     });
 });
-app.post("/api/client-diagnostics", async (c) => {
-    try {
-        const body = await c.req.json();
-        logger.warn(`Client diagnostics (SSE/EventSource): ${JSON.stringify(body)}`);
-    }
-    catch (e) {
-        logger.warn(`Client diagnostics: invalid JSON body (${e?.message ?? e})`);
-    }
-    return c.json({ ok: true });
+// Server-side state a client loads on start and after each reset.
+app.get("/api/initial-state", async (c) => {
+    const result = await ipcRequest("GET_INITIAL_STATE");
+    if (result.error)
+        return c.json({ error: result.error }, 500);
+    return c.json(result.data);
 });
 app.get("/api/configurations", async (c) => {
     const configRes = await ipcRequest("GET_CONFIG");
@@ -700,7 +684,7 @@ app.get("/api/export-zip/:id", async (c) => {
             docId = ref;
         }
         else {
-            zip.file(`${ref}.md`, `# [Unqualified doc reference: ${ref} — no project given]
+            zip.file(`${ref}.md`, `# [Unqualified doc reference: ${ref} — no project given]
 `);
             continue;
         }

package/dist/src/index.js

@@ -120,7 +120,6 @@ let guiLauncher;
 let guiStatus = "disabled";
 let guiUrl = null;
 let guiStartWaiter = null;
-const sseControllers = new Set();
 function broadcastToGUI(message) {
     const child = guiLauncher.getProcess();
     if (child?.connected) {
@@ -359,6 +358,14 @@ async function handleGetInitialState(msg) {
     }
     catch (err) {
         logger.error(`Failed to get initial state: ${err.message}`);
+        if (msg.correlationId) {
+            broadcastToGUI({
+                type: "INITIAL_STATE",
+                correlationId: msg.correlationId,
+                error: err.message,
+                timestamp: new Date().toISOString(),
+            });
+        }
     }
 }
 async function handleGetConfig(msg) {

package/gui/dist/assets/{arc-VljQAUvA.js → arc-BbedxJ3W.js}

@@ -1 +1 @@
-import{a0 as ln,a1 as an,a2 as y,a3 as tn,a4 as H,a5 as q,a6 as _,a7 as un,a8 as rn,a9 as L,aa as o,ab as B,ac as sn,ad as on,ae as fn}from"./index-C8LVeAsA.js";function cn(l){return l.innerRadius}function yn(l){return l.outerRadius}function gn(l){return l.startAngle}function dn(l){return l.endAngle}function mn(l){return l&&l.padAngle}function pn(l,h,I,D,v,A,C,a){var O=I-l,i=D-h,n=C-v,d=a-A,u=d*O-n*i;if(!(u*u<y))return u=(n*(h-A)-d*(l-v))/u,[l+u*O,h+u*i]}function W(l,h,I,D,v,A,C){var a=l-I,O=h-D,i=(C?A:-A)/L(a*a+O*O),n=i*O,d=-i*a,u=l+n,s=h+d,f=I+n,c=D+d,F=(u+f)/2,t=(s+c)/2,m=f-u,g=c-s,R=m*m+g*g,T=v-A,P=u*c-f*s,S=(g<0?-1:1)*L(fn(0,T*T*R-P*P)),j=(P*g-m*S)/R,z=(-P*m-g*S)/R,w=(P*g+m*S)/R,p=(-P*m+g*S)/R,x=j-F,e=z-t,r=w-F,G=p-t;return x*x+e*e>r*r+G*G&&(j=w,z=p),{cx:j,cy:z,x01:-n,y01:-d,x11:j*(v/T-1),y11:z*(v/T-1)}}function hn(){var l=cn,h=yn,I=B(0),D=null,v=gn,A=dn,C=mn,a=null,O=ln(i);function i(){var n,d,u=+l.apply(this,arguments),s=+h.apply(this,arguments),f=v.apply(this,arguments)-an,c=A.apply(this,arguments)-an,F=un(c-f),t=c>f;if(a||(a=n=O()),s<u&&(d=s,s=u,u=d),!(s>y))a.moveTo(0,0);else if(F>tn-y)a.moveTo(s*H(f),s*q(f)),a.arc(0,0,s,f,c,!t),u>y&&(a.moveTo(u*H(c),u*q(c)),a.arc(0,0,u,c,f,t));else{var m=f,g=c,R=f,T=c,P=F,S=F,j=C.apply(this,arguments)/2,z=j>y&&(D?+D.apply(this,arguments):L(u*u+s*s)),w=_(un(s-u)/2,+I.apply(this,arguments)),p=w,x=w,e,r;if(z>y){var G=sn(z/u*q(j)),M=sn(z/s*q(j));(P-=G*2)>y?(G*=t?1:-1,R+=G,T-=G):(P=0,R=T=(f+c)/2),(S-=M*2)>y?(M*=t?1:-1,m+=M,g-=M):(S=0,m=g=(f+c)/2)}var J=s*H(m),K=s*q(m),N=u*H(T),Q=u*q(T);if(w>y){var U=s*H(g),V=s*q(g),X=u*H(R),Y=u*q(R),E;if(F<rn)if(E=pn(J,K,X,Y,U,V,N,Q)){var Z=J-E[0],$=K-E[1],b=U-E[0],k=V-E[1],nn=1/q(on((Z*b+$*k)/(L(Z*Z+$*$)*L(b*b+k*k)))/2),en=L(E[0]*E[0]+E[1]*E[1]);p=_(w,(u-en)/(nn-1)),x=_(w,(s-en)/(nn+1))}else p=x=0}S>y?x>y?(e=W(X,Y,J,K,s,x,t),r=W(U,V,N,Q,s,x,t),a.moveTo(e.cx+e.x01,e.cy+e.y01),x<w?a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,s,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),!t),a.arc(r.cx,r.cy,x,o(r.y11,r.x11),o(r.y01,r.x01),!t))):(a.moveTo(J,K),a.arc(0,0,s,m,g,!t)):a.moveTo(J,K),!(u>y)||!(P>y)?a.lineTo(N,Q):p>y?(e=W(N,Q,U,V,u,-p,t),r=W(J,K,X,Y,u,-p,t),a.lineTo(e.cx+e.x01,e.cy+e.y01),p<w?a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,u,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),t),a.arc(r.cx,r.cy,p,o(r.y11,r.x11),o(r.y01,r.x01),!t))):a.arc(0,0,u,T,R,t)}if(a.closePath(),n)return a=null,n+""||null}return i.centroid=function(){var n=(+l.apply(this,arguments)+ +h.apply(this,arguments))/2,d=(+v.apply(this,arguments)+ +A.apply(this,arguments))/2-rn/2;return[H(d)*n,q(d)*n]},i.innerRadius=function(n){return arguments.length?(l=typeof n=="function"?n:B(+n),i):l},i.outerRadius=function(n){return arguments.length?(h=typeof n=="function"?n:B(+n),i):h},i.cornerRadius=function(n){return arguments.length?(I=typeof n=="function"?n:B(+n),i):I},i.padRadius=function(n){return arguments.length?(D=n==null?null:typeof n=="function"?n:B(+n),i):D},i.startAngle=function(n){return arguments.length?(v=typeof n=="function"?n:B(+n),i):v},i.endAngle=function(n){return arguments.length?(A=typeof n=="function"?n:B(+n),i):A},i.padAngle=function(n){return arguments.length?(C=typeof n=="function"?n:B(+n),i):C},i.context=function(n){return arguments.length?(a=n??null,i):a},i}export{hn as d};
+import{a0 as ln,a1 as an,a2 as y,a3 as tn,a4 as H,a5 as q,a6 as _,a7 as un,a8 as rn,a9 as L,aa as o,ab as B,ac as sn,ad as on,ae as fn}from"./index-CrG0yj-K.js";function cn(l){return l.innerRadius}function yn(l){return l.outerRadius}function gn(l){return l.startAngle}function dn(l){return l.endAngle}function mn(l){return l&&l.padAngle}function pn(l,h,I,D,v,A,C,a){var O=I-l,i=D-h,n=C-v,d=a-A,u=d*O-n*i;if(!(u*u<y))return u=(n*(h-A)-d*(l-v))/u,[l+u*O,h+u*i]}function W(l,h,I,D,v,A,C){var a=l-I,O=h-D,i=(C?A:-A)/L(a*a+O*O),n=i*O,d=-i*a,u=l+n,s=h+d,f=I+n,c=D+d,F=(u+f)/2,t=(s+c)/2,m=f-u,g=c-s,R=m*m+g*g,T=v-A,P=u*c-f*s,S=(g<0?-1:1)*L(fn(0,T*T*R-P*P)),j=(P*g-m*S)/R,z=(-P*m-g*S)/R,w=(P*g+m*S)/R,p=(-P*m+g*S)/R,x=j-F,e=z-t,r=w-F,G=p-t;return x*x+e*e>r*r+G*G&&(j=w,z=p),{cx:j,cy:z,x01:-n,y01:-d,x11:j*(v/T-1),y11:z*(v/T-1)}}function hn(){var l=cn,h=yn,I=B(0),D=null,v=gn,A=dn,C=mn,a=null,O=ln(i);function i(){var n,d,u=+l.apply(this,arguments),s=+h.apply(this,arguments),f=v.apply(this,arguments)-an,c=A.apply(this,arguments)-an,F=un(c-f),t=c>f;if(a||(a=n=O()),s<u&&(d=s,s=u,u=d),!(s>y))a.moveTo(0,0);else if(F>tn-y)a.moveTo(s*H(f),s*q(f)),a.arc(0,0,s,f,c,!t),u>y&&(a.moveTo(u*H(c),u*q(c)),a.arc(0,0,u,c,f,t));else{var m=f,g=c,R=f,T=c,P=F,S=F,j=C.apply(this,arguments)/2,z=j>y&&(D?+D.apply(this,arguments):L(u*u+s*s)),w=_(un(s-u)/2,+I.apply(this,arguments)),p=w,x=w,e,r;if(z>y){var G=sn(z/u*q(j)),M=sn(z/s*q(j));(P-=G*2)>y?(G*=t?1:-1,R+=G,T-=G):(P=0,R=T=(f+c)/2),(S-=M*2)>y?(M*=t?1:-1,m+=M,g-=M):(S=0,m=g=(f+c)/2)}var J=s*H(m),K=s*q(m),N=u*H(T),Q=u*q(T);if(w>y){var U=s*H(g),V=s*q(g),X=u*H(R),Y=u*q(R),E;if(F<rn)if(E=pn(J,K,X,Y,U,V,N,Q)){var Z=J-E[0],$=K-E[1],b=U-E[0],k=V-E[1],nn=1/q(on((Z*b+$*k)/(L(Z*Z+$*$)*L(b*b+k*k)))/2),en=L(E[0]*E[0]+E[1]*E[1]);p=_(w,(u-en)/(nn-1)),x=_(w,(s-en)/(nn+1))}else p=x=0}S>y?x>y?(e=W(X,Y,J,K,s,x,t),r=W(U,V,N,Q,s,x,t),a.moveTo(e.cx+e.x01,e.cy+e.y01),x<w?a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,s,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),!t),a.arc(r.cx,r.cy,x,o(r.y11,r.x11),o(r.y01,r.x01),!t))):(a.moveTo(J,K),a.arc(0,0,s,m,g,!t)):a.moveTo(J,K),!(u>y)||!(P>y)?a.lineTo(N,Q):p>y?(e=W(N,Q,U,V,u,-p,t),r=W(J,K,X,Y,u,-p,t),a.lineTo(e.cx+e.x01,e.cy+e.y01),p<w?a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,u,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),t),a.arc(r.cx,r.cy,p,o(r.y11,r.x11),o(r.y01,r.x01),!t))):a.arc(0,0,u,T,R,t)}if(a.closePath(),n)return a=null,n+""||null}return i.centroid=function(){var n=(+l.apply(this,arguments)+ +h.apply(this,arguments))/2,d=(+v.apply(this,arguments)+ +A.apply(this,arguments))/2-rn/2;return[H(d)*n,q(d)*n]},i.innerRadius=function(n){return arguments.length?(l=typeof n=="function"?n:B(+n),i):l},i.outerRadius=function(n){return arguments.length?(h=typeof n=="function"?n:B(+n),i):h},i.cornerRadius=function(n){return arguments.length?(I=typeof n=="function"?n:B(+n),i):I},i.padRadius=function(n){return arguments.length?(D=n==null?null:typeof n=="function"?n:B(+n),i):D},i.startAngle=function(n){return arguments.length?(v=typeof n=="function"?n:B(+n),i):v},i.endAngle=function(n){return arguments.length?(A=typeof n=="function"?n:B(+n),i):A},i.padAngle=function(n){return arguments.length?(C=typeof n=="function"?n:B(+n),i):C},i.context=function(n){return arguments.length?(a=n??null,i):a},i}export{hn as d};