@imenam/mcp-documentor 1.0.87 → 1.0.88

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,18 +64,27 @@ export declare class StorageEngine {
      */
     listDocsDetailed(project: string): Promise<DocListing[]>;
     deleteDoc(id: 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
-     * same-project references (`doc://id`, bare related_docs) are qualified with the
-     * source project so they keep pointing at the same entries; the history records
-     * a delete in the source project and a create in the target.
+     * 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;
     /**
-     * Rewrites every reference to `project:oldId` so it points at `newProject:newId`.
-     * In the source project, bare references become qualified when the doc left it.
+     * 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[]>;
 }

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,11 +260,29 @@ export class StorageEngine {
         logger.info(`Doc deleted: ${filePath}`);
         return true;
     }
+    /** 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);
+    }
     /**
-     * Moves a doc to `newId` in `newProject`. Across projects, the moved doc's own
-     * same-project references (`doc://id`, bare related_docs) are qualified with the
-     * source project so they keep pointing at the same entries; the history records
-     * a delete in the source project and a create in the target.
+     * 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);
@@ -249,8 +300,16 @@ export class StorageEngine {
         const crossProject = newProject !== project;
         if (crossProject) {
             this.historyStore?.record(project, doc, "delete");
-            doc.content = doc.content.replace(/doc:\/\/([^):#\s]+)(?=[)#\s]|$)/g, `doc://${project}:$1`);
-            doc.related_docs = doc.related_docs.map((ref) => (ref.includes(":") ? ref : `${project}:${ref}`));
+            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;
@@ -279,16 +338,16 @@ export class StorageEngine {
         fs.writeFileSync(p, JSON.stringify(bundles, null, 2), "utf-8");
     }
     /**
-     * Rewrites every reference to `project:oldId` so it points at `newProject:newId`.
-     * In the source project, bare references become qualified when the doc left it.
+     * 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 qualifiedTarget = `${newProject}:${newId}`;
-        const bareTarget = crossProject ? qualifiedTarget : newId;
+        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 source project: rewrite bare refs and explicit self-cross-project refs
         const sameProjDocs = await this.listDocs(proj);
@@ -298,25 +357,22 @@ export class StorageEngine {
             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)}${boundary}`, "g"), `doc://${bareTarget}`);
-            newContent = newContent.replace(new RegExp(`doc://${escapeRegex(proj)}:${escapeRegex(oldId)}${boundary}`, "g"), `doc://${qualifiedTarget}`);
+            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 bareTarget;
-                }
-                if (ref === `${proj}:${oldId}`) {
+            doc.related_docs = doc.related_docs.map((ref) => {
+                if (ref === oldId || ref === `${proj}:${oldId}`) {
                     changed = true;
-                    return qualifiedTarget;
+                    return target;
                 }
                 return ref;
             });
-            doc.related_docs = newRelated;
             if (changed) {
                 doc.updatedAt = new Date().toISOString();
                 await this.saveDoc(doc, proj);
@@ -328,24 +384,24 @@ export class StorageEngine {
             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)}${boundary}`, "g"), `doc://${qualifiedTarget}`);
+                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 qualifiedTarget;
+                        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)

package/dist/src/index.js

@@ -9,6 +9,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { APP_VERSION } from "./version.js";
 import { GuiLauncher, createLogger, setupLogging } from "@imenam/mcp-gui-interface";
 import { resolveLogDir } from "./core/log-dir.js";
+import { initGitHubLog, runTriggeredBy } from "./core/github-log.js";
 import { StorageEngine } from "./core/storage-engine.js";
 import { EmbeddingStore } from "./core/embedding-store.js";
 import { EmbeddingEngine } from "./core/embedding-engine.js";
@@ -35,6 +36,8 @@ import { gitDiffDoc } from "./tools/git-diff-doc.js";
 import { checkLinks } from "./tools/check-links.js";
 import { deleteDoc } from "./tools/delete-doc.js";
 import { moveDoc } from "./tools/move-doc.js";
+import { deleteProject } from "./tools/delete-project.js";
+import { createProject } from "./tools/create-project.js";
 import { getDocTree } from "./tools/get-doc-tree.js";
 import { migrateFolders } from "./core/migrate-folders.js";
 import { migrateEmbeddings } from "./core/migrate-embeddings.js";
@@ -79,6 +82,7 @@ function findProjectRoot(startDir) {
 const rootDir = findProjectRoot(__dirname);
 const packageEnvPath = path.join(rootDir, ".env");
 setupLogging({ processLabel: "mcp-documentor", logDir: resolveLogDir(rootDir) });
+initGitHubLog(resolveLogDir(rootDir));
 const logger = createLogger("mcp-documentor");
 function getConfig() {
     if (fs.existsSync(packageEnvPath)) {
@@ -126,9 +130,13 @@ function broadcastToGUI(message) {
         }
     }
 }
-/** Each GUI message is one operation: the branch head it reads is resolved once, and freshly. */
+/**
+ * Each GUI message is one operation: the branch head it reads is resolved once, and freshly.
+ * GitHub calls it makes are attributed to it in github.log.
+ */
 function handleIPCMessage(msg) {
-    return runInCodeOperation(() => dispatchIPCMessage(msg));
+    const trigger = `GUI · ${String(msg?.type ?? "unknown").toLowerCase().replace(/_/g, " ")}`;
+    return runInCodeOperation(() => runTriggeredBy(trigger, () => dispatchIPCMessage(msg)));
 }
 function dispatchIPCMessage(msg) {
     if (msg.type === "ALREADY_RUNNING") {
@@ -1129,14 +1137,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
             name: "move_doc",
-            description: "Move a documentation entry to a new path (changes its folder and/or name) and/or to another project. All existing doc:// links and related_docs references pointing to the old location are automatically rewritten across all projects. When the entry changes project, its own same-project links are qualified with the source project so they keep their target, and its tracked_files are then resolved against the target project's code source. This is the only way to relocate a document — update_doc does not change the location. Provide new_path, new_project, or both.",
+            description: "Move a documentation entry to a new path (changes its folder and/or name) and/or to another project. All existing doc:// links and related_docs references pointing to the old location are automatically rewritten across all projects. When the entry changes project, its own links keep their target: bare ones are qualified with the source project, and those into the target project become bare. Links are always bare within their own project. Its tracked_files are then resolved against the target project's code source. This is the only way to relocate a document — update_doc does not change the location. Provide new_path, new_project, or both.",
             inputSchema: {
                 type: "object",
                 properties: {
                     path: { type: "string", description: "Current path of the documentation entry, e.g. 'backend/authentication'" },
                     new_path: { type: "string", description: "New path for the documentation entry, e.g. 'backend/v2/authentication'. Can change folder, name, or both. Omitted: the entry keeps its current path (new_project is then required)." },
                     project: { type: "string", description: PROJECT_PARAM_DESCRIPTION + " This is the project the entry is moved from." },
-                    new_project: { type: "string", description: "Project the entry is moved to. Must already exist (see list_projects). Omitted: the entry stays in `project`." },
+                    new_project: { type: "string", description: "Project the entry is moved to. Must already exist (see list_projects; create it with create_project). Omitted: the entry stays in `project`." },
                 },
                 required: ["path", "project"],
             },
@@ -1173,6 +1181,38 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 properties: {},
             },
         },
+        {
+            name: "create_project",
+            description: "Create an empty documentation project, optionally with its code source (as set_code_source would set it). A GitHub repository and branch are checked first: if they cannot be found, nothing is created.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: { type: "string", description: "Name of the project to create. Must not exist yet, nor contain '/', '\' or ':'." },
+                    code_source: {
+                        type: "object",
+                        description: "Where the project's code is read from (defaults to the local working copy).",
+                        properties: {
+                            kind: { type: "string", enum: ["local", "github"], description: "'local' reads the working copy, 'github' reads a repository branch" },
+                            repo: { type: "string", description: "Repository when kind is 'github': 'owner/repo' or a GitHub URL" },
+                            branch: { type: "string", description: "Branch when kind is 'github' (defaults to the repository's default branch)" },
+                        },
+                        required: ["kind"],
+                    },
+                },
+                required: ["project"],
+            },
+        },
+        {
+            name: "delete_project",
+            description: "Delete an empty documentation project. Refuses — and lists what remains — while the project holds any doc, image or other file besides its settings: move_doc (with new_project) or delete_doc its entries first. Also forgets this machine's code root for the project.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: { type: "string", description: "Project to delete. Must exist and be empty." },
+                },
+                required: ["project"],
+            },
+        },
         {
             name: "refresh_file_snapshot",
             description: "Mark tracked files as up-to-date by updating their snapshot timestamps. Use when file changes don't affect the documentation. Accepts one or more doc paths.",
@@ -1208,7 +1248,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
             name: "patch_doc",
-            description: "PREFERRED method for modifying documentation. Replaces a specific portion of a documentation entry's content using an exact search-and-replace, without touching the rest of the doc. Always use this instead of update_doc when making partial changes.",
+            description: "PREFERRED method for modifying documentation. Replaces a specific portion of a documentation entry's content using an exact search-and-replace, without touching the rest of the doc. The search text must occur exactly once, unless replace_all is set; the answer gives the number of occurrences replaced. The replacement is inserted verbatim. Always use this instead of update_doc when making partial changes.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1217,6 +1257,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     ...textSourceProperties("search", "the search text"),
                     replacement: { type: "string", description: "Text to replace it with. Supports [copy-from-codebase|/absolute/path/to/file.ts|startLine|endLine] — the tag is replaced at save time by a fenced code block, and the file+range is automatically added to tracked_files. IMPORTANT: always read the source file first to identify the exact line numbers before writing the tag." },
                     ...textSourceProperties("replacement", "the replacement"),
+                    replace_all: { type: "boolean", description: "Replace every occurrence of the search text. Without it, a search text that occurs more than once is refused." },
                     project: { type: "string", description: PROJECT_PARAM_DESCRIPTION },
                 },
                 required: ["path", "project"],
@@ -1224,7 +1265,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
             name: "git_diff_doc",
-            description: "Show the git diff for each tracked file of one or more docs, between their current state and the last commit before the stored snapshot date.",
+            description: "Show, for each changed tracked file of one or more docs, the diff between the content recorded at its last snapshot and its current content at the project's code source. The snapshot content is read from the recorded blob, else from the recorded commit, else from the newest commit at or before the snapshot date; it is checked against the stored hash, and the diff is reported impossible when it does not match.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1521,8 +1562,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     };
 });
 // Each tool call is one operation: the branch head every tracked file is compared against is
-// resolved once for the whole call, and never carried over to the next one.
-server.setRequestHandler(CallToolRequestSchema, (request) => runInCodeOperation(() => handleToolCall(request)));
+// resolved once for the whole call, and never carried over to the next one. GitHub calls it makes
+// are attributed to the tool in github.log.
+server.setRequestHandler(CallToolRequestSchema, (request) => runInCodeOperation(() => runTriggeredBy(request.params.name, () => handleToolCall(request))));
 async function handleToolCall(request) {
     const { name, arguments: args } = request.params;
     if (isReadOnly() && WRITE_TOOLS.has(name)) {
@@ -1555,12 +1597,35 @@ async function handleToolCall(request) {
                             type: "text",
                             text: "set_project no longer exists: there is no active project. " +
                                 "Pass the project explicitly to every tool call (use list_projects to see them). " +
-                                "A project is created on demand by create_doc.",
+                                "Create a project with create_project, or on demand with create_doc.",
                         },
                     ],
                 };
             case "list_projects":
                 return await listProjects(storageEngine);
+            case "create_project": {
+                const result = await createProject(storageEngine, localState, args);
+                if (!result.isError) {
+                    broadcastToGUI({
+                        type: "PROJECTS_CHANGED",
+                        data: { projects: storageEngine.getConfig().projects },
+                        timestamp: new Date().toISOString(),
+                    });
+                    broadcastCodeSourcesChanged(args?.project);
+                }
+                return result;
+            }
+            case "delete_project": {
+                const result = await deleteProject(storageEngine, localState, args);
+                if (!result.isError) {
+                    broadcastToGUI({
+                        type: "PROJECTS_CHANGED",
+                        data: { projects: storageEngine.getConfig().projects },
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+                return result;
+            }
             case "refresh_file_snapshot":
                 return await refreshFileSnapshot(storageEngine, historyStore, args);
             case "get_doc_metadata":
@@ -1685,7 +1750,7 @@ async function syncPullOnStartup() {
 async function main() {
     await migrateFolders(storageEngine);
     await migrateEmbeddings(embeddingStore, storageEngine);
-    await syncPullOnStartup();
+    await runTriggeredBy("startup sync", syncPullOnStartup);
     migrateCodeSources(storageEngine, localState);
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/src/tools/code-sources.d.ts

@@ -88,6 +88,15 @@ export declare function getCodeSourceTool(storageEngine: StorageEngine, localSta
         text: string;
     }[];
 }>;
+/** A code source as an agent describes it. */
+export interface CodeSourceInput {
+    kind?: string;
+    repo?: string;
+    branch?: string;
+}
+/** Turns an agent's description into a configuration, checking a GitHub repository and branch exist. */
+export declare function resolveCodeSourceInput({ kind, repo, branch }: CodeSourceInput): Promise<CodeSourceConfig>;
+export declare function describeCodeSourceConfig(config: CodeSourceConfig): string;
 export declare function setCodeSourceTool(storageEngine: StorageEngine, localState: LocalState, args: unknown): Promise<{
     content: {
         type: string;

package/dist/src/tools/code-sources.js

@@ -221,29 +221,31 @@ export async function getCodeSourceTool(storageEngine, localState, args) {
         `The code source is shared by every machine (synced with the docs); code roots belong to this machine.`;
     return { content: [{ type: "text", text }] };
 }
-export async function setCodeSourceTool(storageEngine, localState, args) {
-    const { project, kind, repo, branch } = (args ?? {});
-    if (!project)
-        throw new Error("project is required");
-    assertKnownProject(storageEngine, project);
-    let config;
-    if (kind === "local") {
-        config = { kind: "local" };
-    }
-    else if (kind === "github") {
+/** Turns an agent's description into a configuration, checking a GitHub repository and branch exist. */
+export async function resolveCodeSourceInput({ kind, repo, branch }) {
+    if (kind === "local")
+        return { kind: "local" };
+    if (kind === "github") {
         if (!repo)
             throw new Error('repo is required when kind is "github"');
         const inspection = await inspectRepository({ repo, branch });
         if (!inspection.ok)
             throw new Error(inspection.error);
-        config = { kind: "github", repo: inspection.repo.fullName, ...(branch && { branch: inspection.branch }) };
-    }
-    else {
-        throw new Error('kind must be "local" or "github"');
+        return { kind: "github", repo: inspection.repo.fullName, ...(branch && { branch: inspection.branch }) };
     }
+    throw new Error('kind must be "local" or "github"');
+}
+export function describeCodeSourceConfig(config) {
+    return config.kind === "github" ? `GitHub ${config.repo} · ${config.branch ?? "default branch"}` : "its local working copy";
+}
+export async function setCodeSourceTool(storageEngine, localState, args) {
+    const { project, ...input } = (args ?? {});
+    if (!project)
+        throw new Error("project is required");
+    assertKnownProject(storageEngine, project);
+    const config = await resolveCodeSourceInput(input);
     saveCodeSource(storageEngine, localState, project, config);
-    const where = config.kind === "github" ? `GitHub ${config.repo} · ${config.branch ?? "default branch"}` : "its local working copy";
-    return { content: [{ type: "text", text: `Project "${project}" now reads its code from ${where}.` }] };
+    return { content: [{ type: "text", text: `Project "${project}" now reads its code from ${describeCodeSourceConfig(config)}.` }] };
 }
 export function setCodeRootTool(storageEngine, localState, args) {
     const { path: root, project } = (args ?? {});