@imenam/mcp-documentor 1.0.91 → 1.0.93

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

@@ -22,6 +22,7 @@ const GITIGNORE_CONTENT = [
     "export-bundles.json",
     "local-state.json",
     "blob-cache/",
+    "publications/",
     "",
 ].join("\n");
 /**

package/dist/src/core/publication-store.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Published documents, in `<data dir>/publications/`. The sync repository's .gitignore excludes the
+ * directory: a publication is served by this machine, and its link only works here.
+ *
+ *   publications/index.json                     every publication
+ *   publications/<id>/<snapshot>/content.md     the frozen content
+ *   publications/<id>/<snapshot>/img/<p>/<f>    the images it references, copied when frozen
+ *
+ * Each freeze writes a new snapshot directory before the index points at it, so a reader always
+ * finds a complete snapshot.
+ */
+export interface Publication {
+    id: string;
+    /** Secret part of the public link. Whoever holds it can read the frozen content. */
+    token: string;
+    project: string;
+    docId: string;
+    /** Title of the document when it was frozen. */
+    title: string;
+    /** History version frozen, or null when the document has no recorded history. */
+    version: number | null;
+    /** Version note, "" when none was given. */
+    note: string;
+    /** Hash of the frozen title and content, compared with the current document. */
+    contentHash: string;
+    /** Snapshot directory under `<id>/`. */
+    snapshot: string;
+    createdAt: string;
+    /** When the current snapshot was frozen. */
+    publishedAt: string;
+}
+/** Content and images of a document at the moment it is frozen. */
+export interface FreezeInput {
+    project: string;
+    docId: string;
+    title: string;
+    content: string;
+    version: number | null;
+    note: string;
+}
+export declare const MAX_NOTE_LENGTH = 500;
+export declare function hashDocContent(title: string, content: string): string;
+/** Project assets referenced by a document, as decoded `{ project, file }` pairs. */
+export declare function referencedImages(content: string): Array<{
+    project: string;
+    file: string;
+}>;
+/** A single path segment that cannot climb out of its directory. */
+export declare function isSafeSegment(segment: string): boolean;
+export declare class PublicationStore {
+    private readonly dataDir;
+    constructor(dataDir: string);
+    private get rootDir();
+    private get indexPath();
+    list(): Publication[];
+    get(id: string): Publication | undefined;
+    findByDoc(project: string, docId: string): Publication | undefined;
+    /** The publication a public link names, compared in constant time. */
+    findByToken(token: string): Publication | undefined;
+    /** Frozen markdown of a publication. */
+    readContent(publication: Publication): string;
+    /** Path of a frozen image, or undefined when the snapshot holds no such image. */
+    imagePath(publication: Publication, project: string, file: string): string | undefined;
+    publish(input: FreezeInput): Publication;
+    /** Freezes the current content under the same link. */
+    update(id: string, input: FreezeInput): Publication;
+    /** Revokes the link: the publication and its snapshots are deleted. */
+    unpublish(id: string): Publication;
+    /** Follows a document to its new place. Returns true when a publication was moved. */
+    moveDoc(project: string, docId: string, newProject: string, newDocId: string): boolean;
+    private require;
+    private snapshotDir;
+    /** Writes a new snapshot directory and returns its name. */
+    private freeze;
+    private writeIndex;
+}

package/dist/src/core/publication-store.js

@@ -0,0 +1,180 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+/** Image URLs a document uses for project assets: `/api/images/<project>/<file>`. */
+const IMAGE_URL = /(?:^|[\s("'/])\/?api\/images\/([^/\s)"'?#]+)\/([^/\s)"'?#]+)/g;
+export const MAX_NOTE_LENGTH = 500;
+export function hashDocContent(title, content) {
+    return crypto.createHash("sha256").update(title).update("\n").update(content).digest("hex");
+}
+/** Project assets referenced by a document, as decoded `{ project, file }` pairs. */
+export function referencedImages(content) {
+    const found = new Map();
+    for (const match of content.matchAll(IMAGE_URL)) {
+        let project;
+        let file;
+        try {
+            project = decodeURIComponent(match[1]);
+            file = decodeURIComponent(match[2]);
+        }
+        catch {
+            continue;
+        }
+        if (!isSafeSegment(project) || !isSafeSegment(file))
+            continue;
+        found.set(`${project}/${file}`, { project, file });
+    }
+    return [...found.values()];
+}
+/** A single path segment that cannot climb out of its directory. */
+export function isSafeSegment(segment) {
+    return segment !== "" && segment !== "." && segment !== ".." && !/[\\/\0]/.test(segment);
+}
+function normalizeNote(note) {
+    if (note === undefined || note === null)
+        return "";
+    if (typeof note !== "string")
+        throw new Error("note must be a string");
+    const trimmed = note.trim();
+    if (trimmed.length > MAX_NOTE_LENGTH) {
+        throw new Error(`note is limited to ${MAX_NOTE_LENGTH} characters`);
+    }
+    return trimmed;
+}
+export class PublicationStore {
+    dataDir;
+    constructor(dataDir) {
+        this.dataDir = dataDir;
+    }
+    get rootDir() {
+        return path.join(this.dataDir, "publications");
+    }
+    get indexPath() {
+        return path.join(this.rootDir, "index.json");
+    }
+    list() {
+        if (!fs.existsSync(this.indexPath))
+            return [];
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.indexPath, "utf-8"));
+            if (!Array.isArray(parsed))
+                throw new Error("not an array");
+            return parsed;
+        }
+        catch (err) {
+            throw new Error(`${this.indexPath} is not a valid publication index (${err.message}) — fix or delete it.`);
+        }
+    }
+    get(id) {
+        return this.list().find((p) => p.id === id);
+    }
+    findByDoc(project, docId) {
+        return this.list().find((p) => p.project === project && p.docId === docId);
+    }
+    /** The publication a public link names, compared in constant time. */
+    findByToken(token) {
+        const given = Buffer.from(token);
+        return this.list().find((p) => {
+            const expected = Buffer.from(p.token);
+            return expected.length === given.length && crypto.timingSafeEqual(expected, given);
+        });
+    }
+    /** Frozen markdown of a publication. */
+    readContent(publication) {
+        return fs.readFileSync(path.join(this.snapshotDir(publication), "content.md"), "utf-8");
+    }
+    /** Path of a frozen image, or undefined when the snapshot holds no such image. */
+    imagePath(publication, project, file) {
+        if (!isSafeSegment(project) || !isSafeSegment(file))
+            return undefined;
+        const filePath = path.join(this.snapshotDir(publication), "img", project, file);
+        return fs.existsSync(filePath) ? filePath : undefined;
+    }
+    publish(input) {
+        if (this.findByDoc(input.project, input.docId)) {
+            throw new Error(`"${input.docId}" is already published in project "${input.project}"`);
+        }
+        const now = new Date().toISOString();
+        const id = crypto.randomBytes(8).toString("hex");
+        const snapshot = this.freeze(id, input);
+        const publication = {
+            id,
+            token: crypto.randomBytes(32).toString("base64url"),
+            project: input.project,
+            docId: input.docId,
+            title: input.title,
+            version: input.version,
+            note: normalizeNote(input.note),
+            contentHash: hashDocContent(input.title, input.content),
+            snapshot,
+            createdAt: now,
+            publishedAt: now,
+        };
+        this.writeIndex([...this.list(), publication]);
+        return publication;
+    }
+    /** Freezes the current content under the same link. */
+    update(id, input) {
+        const previous = this.require(id);
+        const snapshot = this.freeze(id, input);
+        const publication = {
+            ...previous,
+            title: input.title,
+            version: input.version,
+            note: normalizeNote(input.note),
+            contentHash: hashDocContent(input.title, input.content),
+            snapshot,
+            publishedAt: new Date().toISOString(),
+        };
+        this.writeIndex(this.list().map((p) => (p.id === id ? publication : p)));
+        fs.rmSync(path.join(this.rootDir, id, previous.snapshot), { recursive: true, force: true });
+        return publication;
+    }
+    /** Revokes the link: the publication and its snapshots are deleted. */
+    unpublish(id) {
+        const publication = this.require(id);
+        this.writeIndex(this.list().filter((p) => p.id !== id));
+        fs.rmSync(path.join(this.rootDir, id), { recursive: true, force: true });
+        return publication;
+    }
+    /** Follows a document to its new place. Returns true when a publication was moved. */
+    moveDoc(project, docId, newProject, newDocId) {
+        const publications = this.list();
+        const target = publications.find((p) => p.project === project && p.docId === docId);
+        if (!target)
+            return false;
+        this.writeIndex(publications.map((p) => (p === target ? { ...p, project: newProject, docId: newDocId } : p)));
+        return true;
+    }
+    require(id) {
+        const publication = this.get(id);
+        if (!publication)
+            throw new Error(`Publication "${id}" does not exist`);
+        return publication;
+    }
+    snapshotDir(publication) {
+        return path.join(this.rootDir, publication.id, publication.snapshot);
+    }
+    /** Writes a new snapshot directory and returns its name. */
+    freeze(id, input) {
+        const snapshot = `${Date.now().toString(36)}-${crypto.randomBytes(4).toString("hex")}`;
+        const dir = path.join(this.rootDir, id, snapshot);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, "content.md"), input.content, "utf-8");
+        for (const { project, file } of referencedImages(input.content)) {
+            const source = path.join(this.dataDir, "projects", project, "assets", file);
+            if (!fs.existsSync(source))
+                continue;
+            const target = path.join(dir, "img", project, file);
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.copyFileSync(source, target);
+        }
+        return snapshot;
+    }
+    writeIndex(publications) {
+        fs.mkdirSync(this.rootDir, { recursive: true });
+        const temp = `${this.indexPath}.${process.pid}.tmp`;
+        fs.writeFileSync(temp, JSON.stringify(publications, null, 2), "utf-8");
+        fs.renameSync(temp, this.indexPath);
+    }
+}

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,12 +8,14 @@ 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";
 import { createLogger, setupLogging } from "@imenam/mcp-gui-interface";
 import { resolveLogDir } from "./core/log-dir.js";
 import { isLogSource, logFileInfo, readGitHubLog, readServerLog } from "./core/log-reader.js";
+import { isSafeSegment, PublicationStore } from "./core/publication-store.js";
 import matter from "gray-matter";
 import JSZip from "jszip";
 import puppeteer from "puppeteer-core";
@@ -129,7 +130,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 +171,28 @@ 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",
+    "PUBLICATIONS_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 +201,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 +221,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 ---
@@ -229,6 +235,8 @@ const READ_ONLY_WRITE_ROUTES = [
     { method: "POST", prefix: "/api/sync" },
     { method: "POST", prefix: "/api/code-sources/apply" },
     { method: "POST", prefix: "/api/code-roots/apply" },
+    { method: "POST", prefix: "/api/publications" },
+    { method: "DELETE", prefix: "/api/publications" },
 ];
 app.use("*", async (c, next) => {
     if (isReadOnly()) {
@@ -251,54 +259,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");
@@ -429,6 +417,134 @@ app.post("/api/code-roots/apply", async (c) => {
 app.get("/api/github-token", (c) => relay(c, "GET_GITHUB_TOKEN", {}, 15000));
 app.get("/api/code-source-migration", (c) => relay(c, "GET_CODE_SOURCE_MIGRATION", {}, 5000));
 app.post("/api/code-source-migration/ack", (c) => relay(c, "ACK_CODE_SOURCE_MIGRATION", {}, 5000));
+// --- Publications ---
+// Written by the master, which owns the documents and their history.
+app.get("/api/publications", (c) => relay(c, "LIST_PUBLICATIONS", { project: c.req.query("project") }, 15000));
+app.post("/api/publications", async (c) => {
+    const { project, id, note } = await readJson(c);
+    if (!project || !id)
+        return c.json({ error: "project and id are required" }, 400);
+    return relay(c, "PUBLISH_DOC", { project, id, note }, 15000, 400);
+});
+app.post("/api/publications/:publicationId/update", async (c) => {
+    const { note } = await readJson(c);
+    return relay(c, "UPDATE_PUBLICATION", { publicationId: c.req.param("publicationId"), note }, 15000, 400);
+});
+app.delete("/api/publications/:publicationId", (c) => relay(c, "UNPUBLISH_DOC", { publicationId: c.req.param("publicationId") }, 15000, 400));
+// --- Public pages ---
+// `/public/<token>/` serves a frozen document to anyone holding the link, with no session. It is
+// the only route a hub relays without authentication: everything it answers stays under it.
+// Read straight from the publication store, so a page never waits on the master.
+const publicationStore = new PublicationStore(dataDir);
+/** Tokens are 32 random bytes in base64url. */
+const PUBLIC_TOKEN = /^[A-Za-z0-9_-]{43}$/;
+const PUBLIC_HEADERS = {
+    "X-Robots-Tag": "noindex, nofollow, noarchive",
+    "Referrer-Policy": "no-referrer",
+    "X-Content-Type-Options": "nosniff",
+};
+const PUBLIC_PAGE_CSP = [
+    "default-src 'self'",
+    "script-src 'self'",
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data: https:",
+    "font-src 'self' data:",
+    "connect-src 'self'",
+    "object-src 'none'",
+    "base-uri 'none'",
+    "form-action 'none'",
+    "frame-ancestors 'none'",
+].join("; ");
+const ASSET_MIME = {
+    js: "text/javascript; charset=utf-8",
+    css: "text/css; charset=utf-8",
+    svg: "image/svg+xml",
+    png: "image/png",
+    woff: "font/woff",
+    woff2: "font/woff2",
+    ttf: "font/ttf",
+};
+function publicResponse(body, status, headers) {
+    return new Response(body, { status, headers: { ...PUBLIC_HEADERS, ...headers } });
+}
+function publicNotFound() {
+    return publicResponse("Not found", 404, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" });
+}
+/** Safe for the inside of a `<script type="application/json">` element. */
+function jsonForScript(value) {
+    return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+function escapeHtml(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+app.all("/public/*", (c) => {
+    if (c.req.method !== "GET" && c.req.method !== "HEAD") {
+        return publicResponse("Method not allowed", 405, { Allow: "GET, HEAD", "Cache-Control": "no-store" });
+    }
+    let segments;
+    try {
+        segments = new URL(c.req.url).pathname.slice("/public/".length).split("/").map(decodeURIComponent);
+    }
+    catch {
+        return publicNotFound();
+    }
+    const [token, ...tail] = segments;
+    if (!PUBLIC_TOKEN.test(token))
+        return publicNotFound();
+    const publication = publicationStore.findByToken(token);
+    if (!publication)
+        return publicNotFound();
+    // Relative URLs of the page resolve under the token only when its URL ends with a slash.
+    if (tail.length === 0) {
+        return publicResponse(null, 302, { Location: `${encodeURIComponent(token)}/`, "Cache-Control": "no-store" });
+    }
+    if (tail.length === 1 && tail[0] === "") {
+        const shellPath = path.join(absoluteStaticRoot, "public.html");
+        if (!fs.existsSync(shellPath)) {
+            return publicResponse("GUI build not found", 500, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" });
+        }
+        const data = {
+            project: publication.project,
+            title: publication.title,
+            version: publication.version,
+            note: publication.note,
+            publishedAt: publication.publishedAt,
+            content: publicationStore.readContent(publication),
+        };
+        const html = fs
+            .readFileSync(shellPath, "utf8")
+            .replace(/<title>[^<]*<\/title>/, `<title>${escapeHtml(publication.title)}</title>`)
+            .replace("</head>", `  <script id="publication-data" type="application/json">${jsonForScript(data)}</script>\n  </head>`);
+        return publicResponse(html, 200, {
+            "Content-Type": "text/html; charset=utf-8",
+            "Cache-Control": "no-store",
+            "Content-Security-Policy": PUBLIC_PAGE_CSP,
+        });
+    }
+    if (tail.length === 2 && tail[0] === "assets" && isSafeSegment(tail[1])) {
+        const filePath = path.join(absoluteStaticRoot, "assets", tail[1]);
+        if (!fs.existsSync(filePath))
+            return publicNotFound();
+        const ext = path.extname(filePath).toLowerCase().slice(1);
+        return publicResponse(fs.readFileSync(filePath), 200, {
+            "Content-Type": ASSET_MIME[ext] ?? "application/octet-stream",
+            "Cache-Control": "public, max-age=31536000, immutable",
+        });
+    }
+    if (tail.length === 3 && tail[0] === "img") {
+        const filePath = publicationStore.imagePath(publication, tail[1], tail[2]);
+        if (!filePath)
+            return publicNotFound();
+        const ext = path.extname(filePath).toLowerCase().slice(1);
+        return publicResponse(fs.readFileSync(filePath), 200, {
+            "Content-Type": IMAGE_MIME[ext] ?? "application/octet-stream",
+            "Cache-Control": "no-store",
+            // An SVG opened on its own must not run scripts under the hub's origin.
+            "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; sandbox",
+        });
+    }
+    return publicNotFound();
+});
 // --- Logs ---
 // Read straight from the log directory: both processes write there, and reading needs no IPC.
 const logDir = resolveLogDir(rootDir);