@imenam/mcp-documentor 1.0.86 → 1.0.88

package/dist/src/core/github-log.js

@@ -0,0 +1,64 @@
+import { AsyncLocalStorage } from "async_hooks";
+import fs from "fs";
+import path from "path";
+import { createLogger } from "@imenam/mcp-gui-interface";
+const logger = createLogger("GitHub");
+export const GITHUB_LOG_FILE = "github.log";
+const triggerStorage = new AsyncLocalStorage();
+/** Runs `fn` with `trigger` recorded as the cause of every GitHub call it makes. */
+export function runTriggeredBy(trigger, fn) {
+    return triggerStorage.run(trigger, fn);
+}
+function currentTrigger() {
+    return triggerStorage.getStore() ?? "server";
+}
+let stream = null;
+/** Opens github.log in `logDir` for appending. */
+export function initGitHubLog(logDir) {
+    fs.mkdirSync(logDir, { recursive: true });
+    const file = path.join(logDir, GITHUB_LOG_FILE);
+    stream = fs.createWriteStream(file, { flags: "a", encoding: "utf8" });
+    stream.on("error", (err) => {
+        stream = null;
+        logger.error(`Cannot write ${file}, GitHub calls are no longer recorded there: ${err.message}`);
+    });
+}
+/** Masks credentials embedded in URLs or tokens quoted verbatim. */
+export function redactSecrets(text, secrets = []) {
+    let out = text.replace(/(https?:\/\/)[^@\s/]+@/gi, "$1***@");
+    for (const secret of secrets) {
+        if (secret)
+            out = out.split(secret).join("***");
+    }
+    return out;
+}
+/** "owner/repo" for a GitHub URL, the host and path for any other remote. */
+export function describeRemote(remoteUrl) {
+    const cleaned = redactSecrets(remoteUrl).replace(/^https?:\/\/(\*\*\*@)?/i, "").replace(/^git@/i, "").replace(/\.git$/i, "");
+    const github = cleaned.match(/^github\.com[/:](.+)$/i);
+    return github ? github[1] : cleaned.replace(":", "/");
+}
+/** Appends one call to github.log and mirrors it in server.log. */
+export function recordGitHubCall(call) {
+    const entry = {
+        ts: new Date().toISOString(),
+        kind: call.kind,
+        action: call.action,
+        command: call.command,
+        repo: call.repo,
+        trigger: currentTrigger(),
+        ok: call.ok,
+        status: call.status,
+        durationMs: call.durationMs,
+        ...(call.error ? { error: call.error } : {}),
+        ...(call.rateLimit ? { rateLimit: call.rateLimit } : {}),
+    };
+    stream?.write(`${JSON.stringify(entry)}\n`);
+    const summary = `${entry.command} · ${entry.status} · ${entry.durationMs} ms · ${entry.trigger}`;
+    if (entry.ok)
+        logger.info(summary);
+    else if (entry.status === "404" || entry.status === "422")
+        logger.warn(`${summary} · ${entry.error ?? ""}`);
+    else
+        logger.error(`${summary} · ${entry.error ?? ""}`);
+}

package/dist/src/core/log-reader.d.ts

@@ -0,0 +1,47 @@
+import { type GitHubLogEntry } from "./github-log.js";
+export declare const SERVER_LOG_FILE = "server.log";
+export declare const LOG_SOURCES: {
+    readonly server: "server.log";
+    readonly github: "github.log";
+};
+export type LogSourceId = keyof typeof LOG_SOURCES;
+export declare function isLogSource(id: string): id is LogSourceId;
+export interface LogFileInfo {
+    id: LogSourceId;
+    file: string;
+    path: string;
+    exists: boolean;
+    size: number;
+    mtime: string | null;
+}
+/** One line of server.log, with the lines that followed it without a timestamp of their own. */
+export interface ServerLogEntry {
+    ts: string;
+    pid: number;
+    process: string;
+    level: "DEBUG" | "INFO" | "WARN" | "ERROR";
+    scope: string;
+    message: string;
+    continuation: string[];
+}
+export interface GitHubLogLine extends GitHubLogEntry {
+    raw: string;
+}
+/** A window on the end of a log file. `partial` is true when older lines lie before it. */
+export interface LogWindow<T> {
+    file: LogFileInfo;
+    partial: boolean;
+    entries: T[];
+    /** Lines that could not be parsed, left out of `entries`. */
+    unreadable: number;
+}
+export declare function logFileInfo(logDir: string, id: LogSourceId): LogFileInfo;
+/**
+ * Parses server.log lines as written by the shared logger:
+ *   [ISO date] [PID n] [process] [LEVEL] [scope] message
+ * Text printed straight to the console carries no level nor scope: it is read as INFO from
+ * "console". A line without the date prefix continues the entry above it (stack traces).
+ */
+export declare function readServerLog(logDir: string): LogWindow<ServerLogEntry>;
+/** Parses github.log: one JSON object per line. */
+export declare function readGitHubLog(logDir: string): LogWindow<GitHubLogLine>;

package/dist/src/core/log-reader.js

@@ -0,0 +1,106 @@
+import fs from "fs";
+import path from "path";
+import { GITHUB_LOG_FILE } from "./github-log.js";
+export const SERVER_LOG_FILE = "server.log";
+export const LOG_SOURCES = {
+    server: SERVER_LOG_FILE,
+    github: GITHUB_LOG_FILE,
+};
+export function isLogSource(id) {
+    return Object.prototype.hasOwnProperty.call(LOG_SOURCES, id);
+}
+/** Bytes read from the end of each file: the most recent part, which is what the viewer shows. */
+const TAIL_BYTES = {
+    server: 4 * 1024 * 1024,
+    github: 8 * 1024 * 1024,
+};
+export function logFileInfo(logDir, id) {
+    const filePath = path.join(logDir, LOG_SOURCES[id]);
+    const stat = fs.existsSync(filePath) ? fs.statSync(filePath) : null;
+    return {
+        id,
+        file: LOG_SOURCES[id],
+        path: filePath,
+        exists: !!stat,
+        size: stat?.size ?? 0,
+        mtime: stat ? stat.mtime.toISOString() : null,
+    };
+}
+/** The last `maxBytes` of a file, starting on a whole line. */
+function readTail(filePath, size, maxBytes) {
+    const start = Math.max(0, size - maxBytes);
+    const length = size - start;
+    const buffer = Buffer.alloc(length);
+    const fd = fs.openSync(filePath, "r");
+    try {
+        fs.readSync(fd, buffer, 0, length, start);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    let text = buffer.toString("utf8");
+    if (start > 0)
+        text = text.slice(text.indexOf("\n") + 1);
+    return { text, partial: start > 0 };
+}
+const LINE_PREFIX = /^\[(\d{4}-\d{2}-\d{2}T[^\]]+)\] \[PID (\d+)\] \[([^\]]+)\] (.*)$/;
+const LEVEL_AND_SCOPE = /^\[(DEBUG|INFO|WARN|ERROR)\] \[([^\]]+)\] ?(.*)$/;
+/**
+ * Parses server.log lines as written by the shared logger:
+ *   [ISO date] [PID n] [process] [LEVEL] [scope] message
+ * Text printed straight to the console carries no level nor scope: it is read as INFO from
+ * "console". A line without the date prefix continues the entry above it (stack traces).
+ */
+export function readServerLog(logDir) {
+    const file = logFileInfo(logDir, "server");
+    if (!file.exists)
+        return { file, partial: false, entries: [], unreadable: 0 };
+    const { text, partial } = readTail(file.path, file.size, TAIL_BYTES.server);
+    const entries = [];
+    let unreadable = 0;
+    for (const line of text.split(/\r?\n/)) {
+        if (!line)
+            continue;
+        const prefix = line.match(LINE_PREFIX);
+        if (!prefix) {
+            const previous = entries[entries.length - 1];
+            if (previous)
+                previous.continuation.push(line);
+            else
+                unreadable++;
+            continue;
+        }
+        const [, ts, pid, processLabel, rest] = prefix;
+        const tagged = rest.match(LEVEL_AND_SCOPE);
+        entries.push({
+            ts,
+            pid: Number(pid),
+            process: processLabel,
+            level: tagged ? tagged[1] : "INFO",
+            scope: tagged ? tagged[2] : "console",
+            message: tagged ? tagged[3] : rest,
+            continuation: [],
+        });
+    }
+    return { file, partial, entries, unreadable };
+}
+/** Parses github.log: one JSON object per line. */
+export function readGitHubLog(logDir) {
+    const file = logFileInfo(logDir, "github");
+    if (!file.exists)
+        return { file, partial: false, entries: [], unreadable: 0 };
+    const { text, partial } = readTail(file.path, file.size, TAIL_BYTES.github);
+    const entries = [];
+    let unreadable = 0;
+    for (const line of text.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            entries.push({ ...JSON.parse(line), raw: line });
+        }
+        catch {
+            unreadable++;
+        }
+    }
+    return { file, partial, entries, unreadable };
+}

package/dist/src/core/storage-engine.d.ts

@@ -42,6 +42,12 @@ export declare class StorageEngine {
     /** Reads sync settings from environment variables (admin-controlled, not agent-settable). */
     getSyncConfig(): SyncConfig | undefined;
     ensureProject(project: string): void;
+    /**
+     * Removes a project that holds nothing but its settings file. Any other file —
+     * doc, asset or otherwise — makes it refuse, listing what it found.
+     */
+    deleteProject(project: string): void;
+    private walkFiles;
     private walkMdFiles;
     private docIdToFilePath;
     private cleanEmptyDirs;
@@ -58,9 +64,28 @@ export declare class StorageEngine {
      */
     listDocsDetailed(project: string): Promise<DocListing[]>;
     deleteDoc(id: string, project: string): Promise<boolean>;
-    moveDoc(oldId: string, newId: string, project: string): Promise<boolean>;
+    /** Known project names, longest first, so a name is never matched as the prefix of a longer one. */
+    private projectsLongestFirst;
+    /**
+     * Matches every `doc://` URL: group 1 is the project of a qualified reference (project names
+     * may contain spaces), undefined for a bare one; group 2 is the doc id.
+     */
+    private docUrlRegex;
+    /** Splits a `related_docs` entry into its project, when qualified with a known one, and its id. */
+    private parseDocRef;
+    /**
+     * Moves a doc to `newId` in `newProject`. Across projects, the moved doc's own references are
+     * rewritten so they keep their target: bare ones are qualified with the source project, and any
+     * reference into the target project becomes bare. The history records a delete in the source
+     * project and a create in the target.
+     */
+    moveDoc(oldId: string, project: string, newId: string, newProject: string): Promise<boolean>;
     getBundles(): ExportBundle[];
     saveBundles(bundles: ExportBundle[]): void;
-    rewriteLinks(oldId: string, newId: string, project: string): Promise<string[]>;
+    /**
+     * Rewrites every reference to `project:oldId` so it points at `newProject:newId`: bare inside
+     * `newProject`, qualified everywhere else.
+     */
+    rewriteLinks(oldId: string, project: string, newId: string, newProject: string): Promise<string[]>;
 }
 export {};

package/dist/src/core/storage-engine.js

@@ -91,6 +91,39 @@ export class StorageEngine {
         }
         logger.info(`Project "${project}" ensured at ${projectDir}`);
     }
+    /**
+     * Removes a project that holds nothing but its settings file. Any other file —
+     * doc, asset or otherwise — makes it refuse, listing what it found.
+     */
+    deleteProject(project) {
+        const projectDir = this.getProjectDir(project);
+        const contents = this.walkFiles(projectDir)
+            .map((file) => path.relative(projectDir, file).split(path.sep).join("/"))
+            .filter((rel) => rel !== "project.json");
+        if (contents.length > 0) {
+            const shown = contents.slice(0, 20).map((rel) => `  - ${rel}`).join("\n");
+            const more = contents.length > 20 ? `\n  … and ${contents.length - 20} more` : "";
+            throw new Error(`Project "${project}" is not empty (${contents.length} file(s)) — nothing deleted. Move or delete its content first:\n${shown}${more}`);
+        }
+        fs.rmSync(projectDir, { recursive: true, force: true });
+        const config = this.getConfig();
+        config.projects = config.projects.filter((p) => p !== project);
+        this.saveConfig(config);
+        logger.info(`Project "${project}" deleted`);
+    }
+    walkFiles(dir) {
+        if (!fs.existsSync(dir))
+            return [];
+        const results = [];
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                results.push(...this.walkFiles(fullPath));
+            else
+                results.push(fullPath);
+        }
+        return results;
+    }
     walkMdFiles(dir) {
         if (!fs.existsSync(dir))
             return [];
@@ -227,24 +260,63 @@ export class StorageEngine {
         logger.info(`Doc deleted: ${filePath}`);
         return true;
     }
-    async moveDoc(oldId, newId, project) {
+    /** Known project names, longest first, so a name is never matched as the prefix of a longer one. */
+    projectsLongestFirst() {
+        return [...this.getConfig().projects].sort((a, b) => b.length - a.length);
+    }
+    /**
+     * Matches every `doc://` URL: group 1 is the project of a qualified reference (project names
+     * may contain spaces), undefined for a bare one; group 2 is the doc id.
+     */
+    docUrlRegex() {
+        const projects = this.projectsLongestFirst().map(escapeRegex).join("|");
+        const qualifier = projects ? `(?:(${projects}):)?` : "()?";
+        return new RegExp(`doc://${qualifier}([^):#\\s]+)(?=[)#\\s]|$)`, "g");
+    }
+    /** Splits a `related_docs` entry into its project, when qualified with a known one, and its id. */
+    parseDocRef(ref) {
+        const project = this.projectsLongestFirst().find((p) => ref.startsWith(`${p}:`));
+        return project ? { project, id: ref.slice(project.length + 1) } : { id: ref };
+    }
+    /**
+     * Moves a doc to `newId` in `newProject`. Across projects, the moved doc's own references are
+     * rewritten so they keep their target: bare ones are qualified with the source project, and any
+     * reference into the target project becomes bare. The history records a delete in the source
+     * project and a create in the target.
+     */
+    async moveDoc(oldId, project, newId, newProject) {
         const projectDir = this.getProjectDir(project);
         const oldFilePath = this.docIdToFilePath(oldId, projectDir);
         if (!fs.existsSync(oldFilePath))
             return false;
-        const newFilePath = this.docIdToFilePath(newId, projectDir);
+        const newProjectDir = this.getProjectDir(newProject);
+        const newFilePath = this.docIdToFilePath(newId, newProjectDir);
         if (fs.existsSync(newFilePath)) {
-            throw new Error(`A document already exists at path "${newId}".`);
+            throw new Error(`A document already exists at path "${newId}" in project "${newProject}".`);
         }
         const doc = await this.getDoc(oldId, project);
         if (!doc)
             return false;
+        const crossProject = newProject !== project;
+        if (crossProject) {
+            this.historyStore?.record(project, doc, "delete");
+            const relocate = (ref) => {
+                const target = ref.project ?? project;
+                return target === newProject ? ref.id : `${target}:${ref.id}`;
+            };
+            doc.content = doc.content.replace(this.docUrlRegex(), (_match, refProject, id) => `doc://${relocate({ project: refProject, id })}`);
+            doc.related_docs = doc.related_docs.map((ref) => {
+                const parsed = this.parseDocRef(ref);
+                // A qualifier naming no known project is left as is: it cannot be resolved either way.
+                return !parsed.project && ref.includes(":") ? ref : relocate(parsed);
+            });
+        }
         const newParts = newId.split("/");
         doc.id = newId;
         doc.folder = newParts.length > 1 ? newParts.slice(0, -1).join("/") : undefined;
         doc.updatedAt = new Date().toISOString();
         fs.mkdirSync(path.dirname(newFilePath), { recursive: true });
-        await this.saveDoc(doc, project, "update");
+        await this.saveDoc(doc, newProject, crossProject ? "create" : "update");
         fs.unlinkSync(oldFilePath);
         this.cleanEmptyDirs(path.dirname(oldFilePath), projectDir);
         logger.info(`Doc moved: ${oldFilePath} → ${newFilePath}`);
@@ -265,67 +337,71 @@ export class StorageEngine {
         const p = path.join(this.getDataDir(), "export-bundles.json");
         fs.writeFileSync(p, JSON.stringify(bundles, null, 2), "utf-8");
     }
-    async rewriteLinks(oldId, newId, project) {
+    /**
+     * Rewrites every reference to `project:oldId` so it points at `newProject:newId`: bare inside
+     * `newProject`, qualified everywhere else.
+     */
+    async rewriteLinks(oldId, project, newId, newProject) {
         const config = this.getConfig();
         const proj = project;
+        const crossProject = newProject !== proj;
+        const targetFrom = (docProject) => (docProject === newProject ? newId : `${newProject}:${newId}`);
+        const boundary = "(?=[)#\\s]|$)";
+        const qualifiedOld = new RegExp(`doc://${escapeRegex(proj)}:${escapeRegex(oldId)}${boundary}`, "g");
         const updated = [];
-        // Within the same project: rewrite same-project refs and explicit self-cross-project refs
+        // Within the source project: rewrite bare refs and explicit self-cross-project refs
         const sameProjDocs = await this.listDocs(proj);
         for (const summary of sameProjDocs) {
-            if (summary.id === newId)
+            if (!crossProject && summary.id === newId)
                 continue;
             const doc = await this.getDoc(summary.id, proj);
             if (!doc)
                 continue;
+            const target = targetFrom(proj);
             let changed = false;
-            let newContent = doc.content.replace(new RegExp(`doc://${escapeRegex(oldId)}`, "g"), `doc://${newId}`);
-            // Also rewrite explicit self cross-project refs (doc://proj:oldId → doc://proj:newId)
-            newContent = newContent.replace(new RegExp(`doc://${escapeRegex(proj)}:${escapeRegex(oldId)}`, "g"), `doc://${proj}:${newId}`);
+            const newContent = doc.content
+                .replace(new RegExp(`doc://${escapeRegex(oldId)}${boundary}`, "g"), `doc://${target}`)
+                .replace(qualifiedOld, `doc://${target}`);
             if (newContent !== doc.content) {
                 doc.content = newContent;
                 changed = true;
             }
-            const newRelated = doc.related_docs.map((ref) => {
-                if (ref === oldId) {
-                    changed = true;
-                    return newId;
-                }
-                if (ref === `${proj}:${oldId}`) {
+            doc.related_docs = doc.related_docs.map((ref) => {
+                if (ref === oldId || ref === `${proj}:${oldId}`) {
                     changed = true;
-                    return `${proj}:${newId}`;
+                    return target;
                 }
                 return ref;
             });
-            doc.related_docs = newRelated;
             if (changed) {
                 doc.updatedAt = new Date().toISOString();
                 await this.saveDoc(doc, proj);
                 updated.push(summary.id);
             }
         }
-        // In other projects: rewrite cross-project refs pointing to this project
+        // In other projects: rewrite cross-project refs pointing to the source project
         for (const otherProj of config.projects) {
             if (otherProj === proj)
                 continue;
             const otherDocs = await this.listDocs(otherProj);
+            const target = targetFrom(otherProj);
             for (const summary of otherDocs) {
                 const doc = await this.getDoc(summary.id, otherProj);
                 if (!doc)
                     continue;
                 let changed = false;
-                const newContent = doc.content.replace(new RegExp(`doc://${escapeRegex(proj)}:${escapeRegex(oldId)}`, "g"), `doc://${proj}:${newId}`);
+                const newContent = doc.content.replace(qualifiedOld, `doc://${target}`);
                 if (newContent !== doc.content) {
                     doc.content = newContent;
                     changed = true;
                 }
-                const newRelated = doc.related_docs.map((ref) => {
+                doc.related_docs = doc.related_docs.map((ref) => {
                     if (ref === `${proj}:${oldId}`) {
                         changed = true;
-                        return `${proj}:${newId}`;
+                        return target;
                     }
                     return ref;
                 });
-                doc.related_docs = newRelated;
                 if (changed) {
                     doc.updatedAt = new Date().toISOString();
                     await this.saveDoc(doc, otherProj);

package/dist/src/gui-worker.js

@@ -7,12 +7,14 @@ import { IPCMessageSchema } from "../shared/schemas/doc.schema.js";
 import { isReadOnly } from "../shared/read-only.js";
 import path from "path";
 import fs from "fs";
-import { execFile } from "child_process";
+import { execFile, spawn } from "child_process";
+import { Readable } from "stream";
 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 matter from "gray-matter";
 import JSZip from "jszip";
 import puppeteer from "puppeteer-core";
@@ -427,6 +429,61 @@ 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));
+// --- Logs ---
+// Read straight from the log directory: both processes write there, and reading needs no IPC.
+const logDir = resolveLogDir(rootDir);
+app.get("/api/logs", (c) => c.json({ dir: logDir, files: [logFileInfo(logDir, "server"), logFileInfo(logDir, "github")] }));
+// `knownSize` and `knownMtime` echo the file state the client already holds: when the file has
+// not changed, nothing is re-read.
+app.get("/api/logs/:source", (c) => {
+    const source = c.req.param("source");
+    if (!isLogSource(source))
+        return c.json({ error: `Unknown log "${source}"` }, 404);
+    const info = logFileInfo(logDir, source);
+    if (c.req.query("knownSize") === String(info.size) && c.req.query("knownMtime") === (info.mtime ?? "")) {
+        return c.json({ unchanged: true, file: info });
+    }
+    try {
+        return c.json(source === "server" ? readServerLog(logDir) : readGitHubLog(logDir));
+    }
+    catch (err) {
+        return c.json({ error: `Cannot read ${info.path}: ${err.message}` }, 500);
+    }
+});
+app.get("/api/logs/:source/download", (c) => {
+    const source = c.req.param("source");
+    if (!isLogSource(source))
+        return c.json({ error: `Unknown log "${source}"` }, 404);
+    const info = logFileInfo(logDir, source);
+    if (!info.exists)
+        return c.json({ error: `${info.path} does not exist yet` }, 404);
+    const body = Readable.toWeb(fs.createReadStream(info.path));
+    return new Response(body, {
+        headers: {
+            "Content-Type": "text/plain; charset=utf-8",
+            "Content-Length": String(info.size),
+            "Content-Disposition": `attachment; filename="${info.file}"`,
+        },
+    });
+});
+// Opens the log directory in the file manager of the machine running the server.
+app.post("/api/logs/open-folder", async (c) => {
+    const command = process.platform === "win32" ? "explorer" : process.platform === "darwin" ? "open" : "xdg-open";
+    try {
+        await new Promise((resolve, reject) => {
+            const child = spawn(command, [logDir], { detached: true, stdio: "ignore" });
+            child.once("error", reject);
+            child.once("spawn", () => {
+                child.unref();
+                resolve();
+            });
+        });
+        return c.json({ ok: true });
+    }
+    catch (err) {
+        return c.json({ error: `Cannot open ${logDir} with ${command}: ${err.message}` }, 500);
+    }
+});
 app.get("/api/projects", async (c) => {
     const result = await ipcRequest("LIST_PROJECTS");
     if (result.error)