@imenam/mcp-documentor 1.0.94 → 1.0.96

package/README.md

@@ -11,7 +11,7 @@ Connect it to Cursor, Claude Desktop, or any MCP-compatible agent to let your AI
 - **Portable code references** — tracked-file paths are stored relative to a code root set per machine and per project (GUI or `set_code_root`), so synced docs resolve their source files on any machine regardless of where the repos live
 - **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
+- **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, with a search field that filters the list by name
 - **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, Publications 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. On wide screens the whole interface is capped at 1600 px and centred. 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
@@ -139,6 +139,9 @@ that work on a whole project (`list_docs`, `get_doc_tree`, `check_freshness` wit
 | `get_code_source` | Show each project's code source (local working copy or GitHub branch) and its code root on this machine |
 | `set_code_source` | Make a project read its local working copy or one branch of a GitHub repository (checked before saving) |
 | `set_code_root` | Set the code root of a project, or the machine default, on this machine |
+| `list_comments` | List readers' comments on published documents (`project` required; one doc with `path`; `status`: `all`, `unread` or `detached`) |
+| `mark_comments_read` | Mark comments of a published doc as read, or unread with `read: false`; every comment of the doc when `ids` is omitted (`project` required) |
+| `delete_comments` | Delete comments of a published doc, replies included (`project` required) |
 
 ## Images in documents
 
@@ -175,9 +178,28 @@ A document can be shared, read-only, with anyone who holds its link — no accou
 - **Unpublish** — revokes the link after a confirmation: it answers 404 at once. Publishing again creates a new link.
 - **Publications page** — the globe of the rail lists every published document of the current project: version note, publication date, state (*Up to date*, *Changed · v12 → v14*, or *Document removed*), with Update, copy, open and Unpublish on each row. *Changed* keeps only the publications that lag behind their document.
 
-What the reader sees is the viewer's rendering (code highlighting, Mermaid, tables, images) without any action. The page shows the document alone — title, publication date, version and note — and nothing about where it comes from: no project name, no header bar. An *On this page* table of contents of the document's headings sits on the right and follows the scroll; it is hidden below 1024 px wide. Web links stay active and open in a new tab; links to other documents become plain text; in-page anchors work. Images uploaded to the project are copied into the snapshot when it is frozen, so the page never changes until the publication is updated.
+What the reader sees is the viewer's rendering (code highlighting, Mermaid, tables, images) without any action. The page shows the document alone — title, publication date, version and note — and nothing about where it comes from: no project name, no header bar. A **Contents** button lists the document's headings. Web links stay active and open in a new tab; links to other documents become plain text; in-page anchors work. Images uploaded to the project are copied into the snapshot when it is frozen, so the page never changes until the publication is updated.
 
-**The link** is a *capability URL*: its last segment is a 32-byte random token, and holding it is the only authorization. The page is served under `public/<token>/` next to the GUI, or under `/_pub/<route of the GUI>/<token>/` behind the mcp-gateway-manager hub, which relays that prefix without a session. Every public response carries `X-Robots-Tag: noindex, nofollow, noarchive` and `Referrer-Policy: no-referrer` (the token never leaks to the sites the reader opens), and the page has a strict Content-Security-Policy. The page embeds the frozen document: it makes no API call.
+### Comments
+
+Readers can comment on a published document, without an account:
+
+- **Commenting** — a click on a word selects it, a drag selects a passage (over several lines if needed); a **Comment** button appears above it. The form takes an optional name, remembered by the browser, and the comment (Ctrl/⌘ + Enter sends it). Readers can reply to a comment.
+- **In the margins** — each comment is a card next to its passage, in the margin on the passage's side (left half of the text: left margin), linked to it by a line; the passage is highlighted. Cards that would overlap are pushed down. From 1080 to 1400 px wide every card goes to the right margin; below 1080 px, a click on a highlighted passage opens its comment in a panel at the bottom of the screen. The **N comments** button hides or shows them all.
+- **Limits** — 20 comments per publication, replies included, and 2,000 characters per comment. A deleted comment frees its place; a comment marked as read does not. Behind the hub, a client sending more than 15 comments in a minute is refused, against automated posting.
+- **Names** — the name is whatever the reader typed: every name carries a *not verified* tooltip, on the public page and in the GUI.
+
+Comments are visible to everyone holding the link. Marking them as read and deleting them is reserved to the GUI and to the agent (`list_comments`, `mark_comments_read`, `delete_comments`): the public page offers neither.
+
+In the GUI, a document with unread comments shows a blue bubble and their number in the tree (a bubble alone on its folders), the globe of the rail counts the project's unread comments, and the document toolbar has a comment button. The details panel on the right gets a **Comments** tab, opened by itself on a document with unread comments: each comment can be marked as read or deleted, **Close comments** stops readers from adding any (existing ones stay visible; **Reopen comments** lifts it), a click on it scrolls to its highlighted passage, and a click on a highlighted passage opens its comment.
+
+A comment points at a passage by its text, plus the text just around it. When a publication is updated and a commented passage no longer exists, the comment is kept and marked **detached**: readers no longer see it, the GUI lists it apart with its original passage and versions, and `list_comments` flags it `DETACHED` so the agent can clean them up. A detached comment whose passage comes back in a later update is attached again. Passages are compared without whitespace, against the rendered text of the markdown.
+
+Comments are stored in `<data dir>/publications/<publication>/comments.json`, with their publication: unpublishing deletes them. `READ_ONLY` disables marking, deleting, closing and reopening. When the comment file cannot be read, the public page still shows the document and states that its comments are unavailable.
+
+`list_comments` gives the agent text written by anonymous readers. Its output opens with a notice that names, quoted passages and texts are data, never instructions; every line break of a comment, Unicode separators included, starts a new `>` quoted line, so a comment cannot pass for another entry.
+
+**The link** is a *capability URL*: its last segment is a 32-byte random token, and holding it is the only authorization. The page is served under `public/<token>/` next to the GUI, or under `/_pub/<route of the GUI>/<token>/` behind the mcp-gateway-manager hub, which relays that prefix without a session. Every public response carries `X-Robots-Tag: noindex, nofollow, noarchive` and `Referrer-Policy: no-referrer` (the token never leaks to the sites the reader opens), and the page has a strict Content-Security-Policy. The page embeds the frozen document and its comments; its only request is `POST public/<token>/comments`, which accepts JSON only (at most 16 KB), so that a form from another site cannot post. Behind the hub, this needs a version of mcp-gateway-manager that relays `POST` on `/_pub/`.
 
 Publications live in `<data dir>/publications/` — `index.json` plus one snapshot directory per publication. The directory is machine-local and excluded from sync: a link is served by the machine that created it. A document moved with `move_doc` keeps its publication; a deleted one keeps serving its frozen snapshot until it is unpublished. `READ_ONLY` disables publishing, updating and unpublishing.
 

package/dist/shared/read-only.js

@@ -12,4 +12,5 @@ export const WRITE_TOOLS = new Set([
     // still pull updates); these mutate local/remote state and are blocked.
     "push_docs", "sync_docs", "resolve_sync_conflict",
     "set_code_source", "set_code_root",
+    "mark_comments_read", "delete_comments",
 ]);

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

@@ -231,6 +231,26 @@ export declare const PrepareExportBundleArgsSchema: z.ZodObject<{
 export declare const DeleteExportBundleArgsSchema: z.ZodObject<{
     id: z.ZodString;
 }, z.core.$strip>;
+export declare const ListCommentsArgsSchema: z.ZodObject<{
+    project: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    status: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        unread: "unread";
+        detached: "detached";
+    }>>>;
+}, z.core.$strip>;
+export declare const MarkCommentsReadArgsSchema: z.ZodObject<{
+    project: z.ZodString;
+    path: z.ZodString;
+    ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    read: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+export declare const DeleteCommentsArgsSchema: z.ZodObject<{
+    project: z.ZodString;
+    path: z.ZodString;
+    ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
 export declare const IPCMessageSchema: z.ZodObject<{
     type: z.ZodString;
     correlationId: z.ZodOptional<z.ZodString>;

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

@@ -215,6 +215,26 @@ export const PrepareExportBundleArgsSchema = z.object({
 export const DeleteExportBundleArgsSchema = z.object({
     id: z.string().describe("Bundle identifier to delete (slug)"),
 });
+export const ListCommentsArgsSchema = z.object({
+    project: requiredProject("the comment lookup"),
+    path: z.string().optional().describe("Published document whose comments are listed. Every published document of the project if omitted."),
+    status: z
+        .enum(["all", "unread", "detached"])
+        .optional()
+        .default("all")
+        .describe("'unread': not yet marked as read. 'detached': their passage disappeared when the publication was updated."),
+});
+export const MarkCommentsReadArgsSchema = z.object({
+    project: requiredProject("the update"),
+    path: z.string().describe("Published document the comments belong to"),
+    ids: z.array(z.string()).min(1).optional().describe("Comments to mark, as listed by list_comments. Every comment of the document if omitted."),
+    read: z.boolean().optional().default(true).describe("false marks them as unread again"),
+});
+export const DeleteCommentsArgsSchema = z.object({
+    project: requiredProject("the deletion"),
+    path: z.string().describe("Published document the comments belong to"),
+    ids: z.array(z.string()).min(1).describe("Comments to delete, as listed by list_comments. Deleting a comment deletes its replies."),
+});
 export const IPCMessageSchema = z.object({
     type: z.string(),
     correlationId: z.string().optional(),

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

@@ -0,0 +1,87 @@
+/**
+ * Comments left by readers of a public link, in `<data dir>/publications/<publication id>/comments.json`.
+ * They live with their publication: unpublishing deletes them.
+ *
+ * A comment is anchored to a passage of the published text by a quote selector — the passage
+ * itself plus the text just before and after it. Replies carry no anchor: they belong to the
+ * thread of their root comment. When a publication is updated and its passage no longer exists,
+ * the comment is kept and marked detached.
+ */
+/** Passage a comment points at, as text of the rendered document. */
+export interface CommentAnchor {
+    exact: string;
+    /** Text just before the passage, to tell apart two identical passages. */
+    prefix: string;
+    /** Text just after the passage. */
+    suffix: string;
+}
+export interface CommentDetachment {
+    at: string;
+    /** Version the comment was anchored in. */
+    fromVersion: number | null;
+    /** Version published without its passage. */
+    toVersion: number | null;
+}
+export interface PublicationComment {
+    id: string;
+    /** Root comment of the thread, null for a root comment. */
+    parentId: string | null;
+    /** Null for a reply. */
+    anchor: CommentAnchor | null;
+    /** Name given by the reader, "" when none was given. */
+    author: string;
+    body: string;
+    createdAt: string;
+    /** Publication version the comment was written on. */
+    version: number | null;
+    /** Marked as read by the documentation owner. */
+    read: boolean;
+    /** Set when the passage disappeared from the published version. Replies follow their root. */
+    detached: CommentDetachment | null;
+}
+/** What the public page shows of a comment. */
+export interface PublicComment {
+    id: string;
+    parentId: string | null;
+    anchor: CommentAnchor | null;
+    author: string;
+    body: string;
+    createdAt: string;
+}
+export interface NewCommentInput {
+    parentId?: unknown;
+    anchor?: unknown;
+    author?: unknown;
+    body?: unknown;
+}
+/** Comments a publication accepts, replies included. */
+export declare const MAX_COMMENTS = 20;
+export declare const MAX_BODY_LENGTH = 2000;
+export declare const MAX_AUTHOR_LENGTH = 80;
+export declare const MAX_QUOTE_LENGTH = 500;
+export declare const MAX_CONTEXT_LENGTH = 64;
+/** A request a reader can correct (400), or a limit the publication reached (409). */
+export declare class CommentInputError extends Error {
+    readonly status: 400 | 409;
+    constructor(message: string, status?: 400 | 409);
+}
+export declare function toPublicComment(comment: PublicationComment): PublicComment;
+export declare class CommentStore {
+    private readonly dataDir;
+    constructor(dataDir: string);
+    private filePath;
+    list(publicationId: string): PublicationComment[];
+    /** Comments the public page shows: detached ones have no passage to sit next to. */
+    listPublic(publicationId: string): PublicComment[];
+    add(publicationId: string, version: number | null, input: NewCommentInput): PublicationComment;
+    /** Marks comments as read or unread; returns how many changed. */
+    setRead(publicationId: string, ids: string[] | null, read: boolean): number;
+    /** Deletes comments, and the replies of the root comments deleted; returns how many were removed. */
+    delete(publicationId: string, ids: string[]): number;
+    /**
+     * Checks every root comment against the text of a newly published version: a comment whose
+     * passage is gone becomes detached, one whose passage is back is attached again.
+     */
+    reanchor(publicationId: string, publishedText: string, version: number | null): number;
+    private write;
+}

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

@@ -0,0 +1,189 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { compactText } from "./markdown-text.js";
+/** Comments a publication accepts, replies included. */
+export const MAX_COMMENTS = 20;
+export const MAX_BODY_LENGTH = 2000;
+export const MAX_AUTHOR_LENGTH = 80;
+export const MAX_QUOTE_LENGTH = 500;
+export const MAX_CONTEXT_LENGTH = 64;
+/** A request a reader can correct (400), or a limit the publication reached (409). */
+export class CommentInputError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.status = status;
+    }
+}
+function requireString(value, field) {
+    if (typeof value !== "string")
+        throw new CommentInputError(`${field} must be a string`);
+    return value;
+}
+function optionalString(value, field) {
+    if (value === undefined || value === null)
+        return "";
+    return requireString(value, field);
+}
+function collapseWhitespace(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function parseAnchor(value) {
+    if (!value || typeof value !== "object")
+        throw new CommentInputError("anchor is required");
+    const raw = value;
+    const exact = collapseWhitespace(requireString(raw.exact, "anchor.exact"));
+    if (compactText(exact) === "")
+        throw new CommentInputError("anchor.exact is empty");
+    if (exact.length > MAX_QUOTE_LENGTH) {
+        throw new CommentInputError(`The selected passage is limited to ${MAX_QUOTE_LENGTH} characters`);
+    }
+    const prefix = collapseWhitespace(optionalString(raw.prefix, "anchor.prefix")).slice(-MAX_CONTEXT_LENGTH);
+    const suffix = collapseWhitespace(optionalString(raw.suffix, "anchor.suffix")).slice(0, MAX_CONTEXT_LENGTH);
+    return { exact, prefix, suffix };
+}
+export function toPublicComment(comment) {
+    return {
+        id: comment.id,
+        parentId: comment.parentId,
+        anchor: comment.anchor,
+        author: comment.author,
+        body: comment.body,
+        createdAt: comment.createdAt,
+    };
+}
+/** Root comment of a thread, or the comment itself when it is a root. */
+function rootOf(comments, comment) {
+    return comment.parentId ? comments.find((c) => c.id === comment.parentId) ?? comment : comment;
+}
+export class CommentStore {
+    dataDir;
+    constructor(dataDir) {
+        this.dataDir = dataDir;
+    }
+    filePath(publicationId) {
+        return path.join(this.dataDir, "publications", publicationId, "comments.json");
+    }
+    list(publicationId) {
+        const file = this.filePath(publicationId);
+        if (!fs.existsSync(file))
+            return [];
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+            if (!Array.isArray(parsed))
+                throw new Error("not an array");
+            return parsed;
+        }
+        catch (err) {
+            throw new Error(`${file} is not a valid comment file (${err.message}) — fix or delete it.`);
+        }
+    }
+    /** Comments the public page shows: detached ones have no passage to sit next to. */
+    listPublic(publicationId) {
+        const comments = this.list(publicationId);
+        return comments.filter((c) => !rootOf(comments, c).detached).map(toPublicComment);
+    }
+    add(publicationId, version, input) {
+        const comments = this.list(publicationId);
+        if (comments.length >= MAX_COMMENTS) {
+            throw new CommentInputError(`This document accepts no more comments (limit: ${MAX_COMMENTS})`, 409);
+        }
+        const body = requireString(input.body, "body").trim();
+        if (body === "")
+            throw new CommentInputError("The comment is empty");
+        if (body.length > MAX_BODY_LENGTH) {
+            throw new CommentInputError(`A comment is limited to ${MAX_BODY_LENGTH} characters`);
+        }
+        const author = collapseWhitespace(optionalString(input.author, "author"));
+        if (author.length > MAX_AUTHOR_LENGTH) {
+            throw new CommentInputError(`A name is limited to ${MAX_AUTHOR_LENGTH} characters`);
+        }
+        let parentId = null;
+        let anchor = null;
+        if (input.parentId !== undefined && input.parentId !== null) {
+            const parent = comments.find((c) => c.id === requireString(input.parentId, "parentId"));
+            const root = parent ? rootOf(comments, parent) : undefined;
+            if (!root || root.detached)
+                throw new CommentInputError("The comment answered no longer exists");
+            parentId = root.id;
+        }
+        else {
+            anchor = parseAnchor(input.anchor);
+        }
+        const comment = {
+            id: crypto.randomBytes(8).toString("hex"),
+            parentId,
+            anchor,
+            author,
+            body,
+            createdAt: new Date().toISOString(),
+            version,
+            read: false,
+            detached: null,
+        };
+        this.write(publicationId, [...comments, comment]);
+        return comment;
+    }
+    /** Marks comments as read or unread; returns how many changed. */
+    setRead(publicationId, ids, read) {
+        const comments = this.list(publicationId);
+        const wanted = ids ? new Set(ids) : null;
+        let changed = 0;
+        const next = comments.map((c) => {
+            if ((wanted && !wanted.has(c.id)) || c.read === read)
+                return c;
+            changed++;
+            return { ...c, read };
+        });
+        if (changed > 0)
+            this.write(publicationId, next);
+        return changed;
+    }
+    /** Deletes comments, and the replies of the root comments deleted; returns how many were removed. */
+    delete(publicationId, ids) {
+        const comments = this.list(publicationId);
+        const removed = new Set(ids.filter((id) => comments.some((c) => c.id === id)));
+        for (const c of comments)
+            if (c.parentId && removed.has(c.parentId))
+                removed.add(c.id);
+        if (removed.size === 0)
+            return 0;
+        this.write(publicationId, comments.filter((c) => !removed.has(c.id)));
+        return removed.size;
+    }
+    /**
+     * Checks every root comment against the text of a newly published version: a comment whose
+     * passage is gone becomes detached, one whose passage is back is attached again.
+     */
+    reanchor(publicationId, publishedText, version) {
+        const comments = this.list(publicationId);
+        const text = compactText(publishedText);
+        const now = new Date().toISOString();
+        let changed = 0;
+        const next = comments.map((c) => {
+            if (!c.anchor)
+                return c;
+            const found = text.includes(compactText(c.anchor.exact));
+            if (found && c.detached) {
+                changed++;
+                return { ...c, detached: null };
+            }
+            if (!found && !c.detached) {
+                changed++;
+                return { ...c, detached: { at: now, fromVersion: c.version, toVersion: version } };
+            }
+            return c;
+        });
+        if (changed > 0)
+            this.write(publicationId, next);
+        return changed;
+    }
+    write(publicationId, comments) {
+        const file = this.filePath(publicationId);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const temp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(temp, JSON.stringify(comments, null, 2), "utf-8");
+        fs.renameSync(temp, file);
+    }
+}

package/dist/src/core/markdown-text.d.ts

@@ -0,0 +1,7 @@
+/** Text a reader sees once the markdown is rendered: markup removed, code kept. */
+export declare function markdownText(content: string): string;
+/**
+ * Text with every whitespace removed. Rendered text and markdown text differ in the whitespace
+ * between blocks; comparing without it makes a passage found in one found in the other.
+ */
+export declare function compactText(text: string): string;

package/dist/src/core/markdown-text.js

@@ -0,0 +1,16 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmFromMarkdown } from "mdast-util-gfm";
+import { gfm } from "micromark-extension-gfm";
+import { toString } from "mdast-util-to-string";
+/** Text a reader sees once the markdown is rendered: markup removed, code kept. */
+export function markdownText(content) {
+    const tree = fromMarkdown(content, { extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()] });
+    return toString(tree, { includeImageAlt: false });
+}
+/**
+ * Text with every whitespace removed. Rendered text and markdown text differ in the whitespace
+ * between blocks; comparing without it makes a passage found in one found in the other.
+ */
+export function compactText(text) {
+    return text.replace(/\s+/g, "");
+}

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

@@ -28,6 +28,8 @@ export interface Publication {
     createdAt: string;
     /** When the current snapshot was frozen. */
     publishedAt: string;
+    /** True when readers can no longer add comments; absent or false when they can. */
+    commentsClosed?: boolean;
 }
 /** Content and images of a document at the moment it is frozen. */
 export interface FreezeInput {
@@ -66,6 +68,8 @@ export declare class PublicationStore {
     update(id: string, input: FreezeInput): Publication;
     /** Revokes the link: the publication and its snapshots are deleted. */
     unpublish(id: string): Publication;
+    /** Opens or closes the publication to new comments. Existing comments stay visible. */
+    setCommentsClosed(id: string, closed: boolean): 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;

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

@@ -137,6 +137,12 @@ export class PublicationStore {
         fs.rmSync(path.join(this.rootDir, id), { recursive: true, force: true });
         return publication;
     }
+    /** Opens or closes the publication to new comments. Existing comments stay visible. */
+    setCommentsClosed(id, closed) {
+        const publication = { ...this.require(id), commentsClosed: closed };
+        this.writeIndex(this.list().map((p) => (p.id === id ? publication : p)));
+        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();

package/dist/src/gui-worker.js

@@ -16,6 +16,7 @@ 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 { CommentStore, MAX_AUTHOR_LENGTH, MAX_BODY_LENGTH, MAX_COMMENTS, MAX_QUOTE_LENGTH, } from "./core/comment-store.js";
 import matter from "gray-matter";
 import JSZip from "jszip";
 import puppeteer from "puppeteer-core";
@@ -180,6 +181,7 @@ const BROADCAST_TYPES = [
     "DOCS_CHANGED",
     "CODE_SOURCES_CHANGED",
     "PUBLICATIONS_CHANGED",
+    "COMMENTS_CHANGED",
 ];
 /** Number of pushed messages kept for clients catching up. */
 const CHANGE_JOURNAL_SIZE = 200;
@@ -237,6 +239,7 @@ const READ_ONLY_WRITE_ROUTES = [
     { method: "POST", prefix: "/api/code-roots/apply" },
     { method: "POST", prefix: "/api/publications" },
     { method: "DELETE", prefix: "/api/publications" },
+    { method: "POST", prefix: "/api/comments/" },
 ];
 app.use("*", async (c, next) => {
     if (isReadOnly()) {
@@ -431,11 +434,36 @@ app.post("/api/publications/:publicationId/update", async (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));
+// --- Comments ---
+// Written by the master; the GUI reads them per document and as counts for the badges.
+app.get("/api/comments/summary", (c) => relay(c, "COMMENTS_SUMMARY", { project: c.req.query("project") }, 15000));
+app.get("/api/comments", (c) => relay(c, "LIST_DOC_COMMENTS", { project: c.req.query("project"), docId: c.req.query("doc") }, 15000, 400));
+app.post("/api/comments/read", async (c) => {
+    const { publicationId, ids, read } = await readJson(c);
+    return relay(c, "SET_COMMENTS_READ", { publicationId, ids, read }, 15000, 400);
+});
+app.post("/api/comments/delete", async (c) => {
+    const { publicationId, ids } = await readJson(c);
+    return relay(c, "DELETE_COMMENTS", { publicationId, ids }, 15000, 400);
+});
+app.post("/api/comments/closed", async (c) => {
+    const { publicationId, closed } = await readJson(c);
+    return relay(c, "SET_COMMENTS_CLOSED", { publicationId, closed }, 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);
+const commentStore = new CommentStore(dataDir);
+/** Largest comment request a public page may send. */
+const MAX_COMMENT_REQUEST_BYTES = 16 * 1024;
+const COMMENT_LIMITS = {
+    comments: MAX_COMMENTS,
+    body: MAX_BODY_LENGTH,
+    author: MAX_AUTHOR_LENGTH,
+    quote: MAX_QUOTE_LENGTH,
+};
 /** Tokens are 32 random bytes in base64url. */
 const PUBLIC_TOKEN = /^[A-Za-z0-9_-]{43}$/;
 const PUBLIC_HEADERS = {
@@ -477,9 +505,54 @@ function jsonForScript(value) {
 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" });
+/**
+ * Comments shown on a public page. An unreadable comment file is reported as `comments: null`:
+ * the page then states that its comments are unavailable, and the document stays readable.
+ */
+function publicCommentsOf(publicationId) {
+    try {
+        return { comments: commentStore.listPublic(publicationId), commentsUsed: commentStore.list(publicationId).length };
+    }
+    catch (err) {
+        logger.error(`Comments of publication ${publicationId} are unavailable: ${err.message}`);
+        return { comments: null, commentsUsed: 0 };
+    }
+}
+function publicJson(value, status = 200) {
+    return publicResponse(JSON.stringify(value), status, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-store",
+    });
+}
+/**
+ * `POST /public/<token>/comments`: a reader's comment, JSON only. A cross-site form cannot send
+ * JSON without a preflight this server never answers, so only the page itself can post.
+ */
+async function postPublicComment(c, publicationId) {
+    const type = String(c.req.header("content-type") ?? "").toLowerCase();
+    if (!type.startsWith("application/json"))
+        return publicJson({ error: "Comments are sent as JSON" }, 415);
+    const raw = await c.req.text();
+    if (Buffer.byteLength(raw) > MAX_COMMENT_REQUEST_BYTES)
+        return publicJson({ error: "Request too large" }, 413);
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        return publicJson({ error: "Invalid JSON" }, 400);
+    }
+    const result = await ipcRequest("ADD_PUBLIC_COMMENT", { publicationId, input }, 15000);
+    if (result.error)
+        return publicJson({ error: "The comment could not be saved" }, 500);
+    if (result.data?.rejected)
+        return publicJson({ error: result.data.rejected.message }, result.data.rejected.status);
+    return publicJson({ comments: result.data.comments, used: result.data.used });
+}
+app.all("/public/*", async (c) => {
+    const method = c.req.method;
+    if (method !== "GET" && method !== "HEAD" && method !== "POST") {
+        return publicResponse("Method not allowed", 405, { Allow: "GET, HEAD, POST", "Cache-Control": "no-store" });
     }
     let segments;
     try {
@@ -494,6 +567,11 @@ app.all("/public/*", (c) => {
     const publication = publicationStore.findByToken(token);
     if (!publication)
         return publicNotFound();
+    if (method === "POST") {
+        if (tail.length === 1 && tail[0] === "comments")
+            return postPublicComment(c, publication.id);
+        return publicResponse("Method not allowed", 405, { Allow: "GET, HEAD", "Cache-Control": "no-store" });
+    }
     // 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" });
@@ -509,11 +587,15 @@ app.all("/public/*", (c) => {
             note: publication.note,
             publishedAt: publication.publishedAt,
             content: publicationStore.readContent(publication),
+            ...publicCommentsOf(publication.id),
+            commentsClosed: publication.commentsClosed === true,
+            commentLimits: COMMENT_LIMITS,
         };
+        // Replacer functions: a `$` pattern in the title or in a comment must stay literal.
         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>`);
+            .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",