@imenam/mcp-documentor 1.0.84 → 1.0.86

package/dist/src/core/migrate-code-sources.js

@@ -0,0 +1,157 @@
+import { createLogger } from "@imenam/mcp-gui-interface";
+import { parseRepoSpec } from "./github-code-api.js";
+import { hasCodeSourceConfig, writeCodeSourceConfig } from "./project-settings.js";
+const logger = createLogger("MigrateCodeSources");
+const REPO_VAR = "MCP_DOCUMENTOR_CODE_REPO";
+const BRANCH_VAR = "MCP_DOCUMENTOR_CODE_BRANCH";
+const ROOTS_VAR = "MCP_DOCUMENTOR_CODE_ROOTS";
+const ROOT_VAR = "MCP_DOCUMENTOR_CODE_ROOT";
+const short = (name) => name.replace(/^MCP_DOCUMENTOR_/, "");
+function readVar(name) {
+    return process.env[name]?.trim() || undefined;
+}
+/** Entries of a JSON map variable, keeping non-empty string values only. */
+function readJsonMap(name, raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${name} looks like a JSON map but could not be parsed`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${name} is not a JSON object`);
+    }
+    return Object.entries(parsed)
+        .filter((entry) => typeof entry[1] === "string" && entry[1].trim() !== "")
+        .map(([project, value]) => [project, value.trim()]);
+}
+/** The (project, spec) pairs MCP_DOCUMENTOR_CODE_REPO declares: one spec for all, or a JSON map. */
+function readRepoSpecs(raw, projects) {
+    if (!raw.startsWith("{"))
+        return projects.map((project) => [project, raw]);
+    return readJsonMap(REPO_VAR, raw);
+}
+/**
+ * MCP_DOCUMENTOR_CODE_ROOT seeds the default code root of a data directory that has none — the
+ * setup writes it with the repository's folder. Once a default root is stored, the variable is
+ * not read again: a different value is only logged.
+ */
+function seedDefaultCodeRoot(localState) {
+    const envRoot = readVar(ROOT_VAR);
+    if (!envRoot)
+        return undefined;
+    const stored = localState.getCodeRoots().default;
+    if (stored === undefined) {
+        localState.setDefaultCodeRoot(envRoot);
+        logger.info(`Default code root set from ${ROOT_VAR}: ${envRoot}`);
+        return { kind: "code-root", status: "imported", detail: `Default code root · ${envRoot}`, from: short(ROOT_VAR) };
+    }
+    if (stored !== envRoot) {
+        logger.info(`${ROOT_VAR} (${envRoot}) is ignored: the default code root of this machine is ${stored}.`);
+    }
+    return undefined;
+}
+function migrateRepos(storageEngine, projects, entries) {
+    const repoRaw = readVar(REPO_VAR);
+    if (!repoRaw)
+        return;
+    const defaultBranch = readVar(BRANCH_VAR);
+    let specs = [];
+    try {
+        specs = readRepoSpecs(repoRaw, projects);
+    }
+    catch (err) {
+        entries.push({ kind: "github", status: "error", detail: `Not imported — ${err.message}`, from: short(REPO_VAR) });
+    }
+    for (const [project, spec] of specs) {
+        if (!projects.includes(project)) {
+            entries.push({ project, kind: "github", status: "skipped", detail: "Not imported — no such project", from: short(REPO_VAR) });
+            continue;
+        }
+        const projectDir = storageEngine.getProjectDir(project);
+        if (hasCodeSourceConfig(projectDir)) {
+            entries.push({ project, kind: "github", status: "skipped", detail: "Already configured — kept as is", from: short(REPO_VAR) });
+            continue;
+        }
+        if (spec.toLowerCase() === "local") {
+            writeCodeSourceConfig(projectDir, { kind: "local" });
+            entries.push({ project, kind: "local", status: "imported", detail: "Local working copy", from: `${short(REPO_VAR)} "local"` });
+            continue;
+        }
+        let config;
+        let from = short(REPO_VAR);
+        try {
+            const parsed = parseRepoSpec(spec);
+            const branch = parsed.ref ?? defaultBranch;
+            if (!parsed.ref && defaultBranch)
+                from += ` + ${short(BRANCH_VAR)}`;
+            config = { kind: "github", repo: `${parsed.owner}/${parsed.repo}`, ...(branch && { branch }) };
+        }
+        catch (err) {
+            entries.push({ project, kind: "github", status: "error", detail: `Not imported — ${err.message}`, from });
+            continue;
+        }
+        writeCodeSourceConfig(projectDir, config);
+        entries.push({ project, kind: "github", status: "imported", detail: `${config.repo} · ${config.branch ?? "default branch"}`, from });
+    }
+}
+function migrateCodeRoots(localState, projects, entries) {
+    const rootsRaw = readVar(ROOTS_VAR);
+    if (!rootsRaw)
+        return;
+    let roots = [];
+    try {
+        roots = readJsonMap(ROOTS_VAR, rootsRaw);
+    }
+    catch (err) {
+        entries.push({ kind: "code-root", status: "error", detail: `Not imported — ${err.message}`, from: short(ROOTS_VAR) });
+    }
+    const existing = localState.getCodeRoots().byProject;
+    for (const [project, root] of roots) {
+        if (!projects.includes(project)) {
+            entries.push({ project, kind: "code-root", status: "skipped", detail: "Not imported — no such project", from: short(ROOTS_VAR) });
+        }
+        else if (existing[project] !== undefined) {
+            entries.push({ project, kind: "code-root", status: "skipped", detail: "Code root already set — kept as is", from: short(ROOTS_VAR) });
+        }
+        else {
+            localState.setProjectCodeRoot(project, root);
+            entries.push({ project, kind: "code-root", status: "imported", detail: `Code root · ${root}`, from: short(ROOTS_VAR) });
+        }
+    }
+}
+/**
+ * Moves the code-source environment variables into the project settings and the machine-local
+ * code roots, once per machine.
+ *
+ *  - MCP_DOCUMENTOR_CODE_REPO (+ MCP_DOCUMENTOR_CODE_BRANCH for specs without "#branch") becomes
+ *    the code source of each project it names. A project that already has a code source — written
+ *    by another machine and pulled — keeps it.
+ *  - MCP_DOCUMENTOR_CODE_ROOTS becomes the code root of each project it names, on this machine.
+ *  - MCP_DOCUMENTOR_CODE_ROOT seeds the default code root (see `seedDefaultCodeRoot`); it is not
+ *    one of the variables to remove.
+ *
+ * The outcome is recorded as a report in the local state; the GUI shows it until acknowledged.
+ * Once recorded, the migrated variables are never read again: their presence is only logged.
+ */
+export function migrateCodeSources(storageEngine, localState) {
+    const seeded = seedDefaultCodeRoot(localState);
+    const present = [REPO_VAR, BRANCH_VAR, ROOTS_VAR].filter((name) => readVar(name) !== undefined);
+    if (present.length === 0)
+        return;
+    if (localState.getMigrationReport()) {
+        logger.warn(`${present.join(", ")} ${present.length > 1 ? "are" : "is"} set but no longer read — code sources and code roots ` +
+            `are configured per project in the GUI. Remove ${present.length > 1 ? "them" : "it"} from the MCP configuration.`);
+        return;
+    }
+    const projects = storageEngine.getConfig().projects;
+    const entries = [];
+    migrateRepos(storageEngine, projects, entries);
+    migrateCodeRoots(localState, projects, entries);
+    if (seeded)
+        entries.push(seeded);
+    localState.setMigrationReport({ migratedAt: new Date().toISOString(), entries, variables: present, seen: false });
+    logger.info(`Code sources migrated from ${present.join(", ")}: ${entries.filter((e) => e.status === "imported").length} imported, ` +
+        `${entries.filter((e) => e.status !== "imported").length} not imported. These variables are no longer read.`);
+}

package/dist/src/core/path-resolver.d.ts

@@ -1,20 +1,40 @@
-/** Test-only: clears the memoised env snapshot so a changed env is re-read. */
-export declare function resetCodeRootsCache(): void;
-/** The configured code root for a project, or undefined if none applies. */
+/**
+ * Resolves tracked-file paths between two representations:
+ *
+ *  - **stored**   — what we persist in a doc's `tracked_files[].path`. Portable
+ *    across machines: relative to the project's "code root" and using forward
+ *    slashes. Absolute paths may still appear (files located outside any code
+ *    root) and are handled transparently.
+ *  - **absolute** — a real filesystem path on the current machine, used for any
+ *    `fs`/`git` access.
+ *
+ * The code root is machine-local — each machine clones its repos wherever it
+ * wants — so it is read from the machine-local state (a default root, and
+ * per-project roots), through the provider installed with `setCodeRootProvider`.
+ *
+ * Without a code root, paths are stored absolute and only absolute stored paths
+ * can be resolved.
+ */
+/** The code root that applies to a project on this machine, or undefined. */
+export type CodeRootProvider = (project: string) => string | undefined;
+export declare function setCodeRootProvider(value: CodeRootProvider): void;
+/** The code root that applies to a project on this machine, or undefined if none is set. */
 export declare function getCodeRoot(project: string): string | undefined;
 /**
  * Converts an input path (typically the absolute path supplied by an agent)
  * into the portable form persisted in a doc.
  *
- * Falls back to an absolute path — with a warning — when there is no code root,
- * or when the file lives outside the root (including a different Windows drive).
+ * Keeps an absolute path — with a warning — when there is no code root, or when
+ * the file lives outside the root (including a different Windows drive).
  */
 export declare function toStoredPath(inputPath: string, project: string): string;
 /**
- * Resolves a stored path to an absolute filesystem path on this machine.
+ * Resolves a stored path against a given code root:
  *
- *  - absolute stored path (legacy / fallback)  → returned as-is
- *  - relative stored path + configured root     → joined with the root
- *  - relative stored path + no root configured  → undefined (unverifiable here)
+ *  - absolute stored path                 → returned as-is
+ *  - relative stored path + a root        → joined with the root
+ *  - relative stored path + no root       → undefined (unverifiable here)
  */
+export declare function resolveAgainstRoot(stored: string, root: string | undefined): string | undefined;
+/** Resolves a stored path to an absolute filesystem path on this machine. */
 export declare function toAbsolutePath(stored: string, project: string): string | undefined;

package/dist/src/core/path-resolver.js

@@ -1,42 +1,15 @@
 import path from "path";
 import { createLogger } from "@imenam/mcp-gui-interface";
 const logger = createLogger("PathResolver");
-let cached;
-function loadCodeRoots() {
-    if (cached)
-        return cached;
-    const defaultRoot = process.env.MCP_DOCUMENTOR_CODE_ROOT?.trim() || undefined;
-    let byProject = {};
-    const rawMap = process.env.MCP_DOCUMENTOR_CODE_ROOTS?.trim();
-    if (rawMap) {
-        try {
-            const parsed = JSON.parse(rawMap);
-            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                for (const [proj, root] of Object.entries(parsed)) {
-                    if (typeof root === "string" && root.trim() !== "") {
-                        byProject[proj] = root.trim();
-                    }
-                }
-            }
-            else {
-                logger.warn("MCP_DOCUMENTOR_CODE_ROOTS is not a JSON object, ignoring it");
-            }
-        }
-        catch {
-            logger.warn("Failed to parse MCP_DOCUMENTOR_CODE_ROOTS as JSON, ignoring it");
-        }
-    }
-    cached = { default: defaultRoot, byProject };
-    return cached;
-}
-/** Test-only: clears the memoised env snapshot so a changed env is re-read. */
-export function resetCodeRootsCache() {
-    cached = undefined;
+let provider;
+export function setCodeRootProvider(value) {
+    provider = value;
 }
-/** The configured code root for a project, or undefined if none applies. */
+/** The code root that applies to a project on this machine, or undefined if none is set. */
 export function getCodeRoot(project) {
-    const roots = loadCodeRoots();
-    return roots.byProject[project] ?? roots.default;
+    if (!provider)
+        throw new Error("code roots are read before setCodeRootProvider was called");
+    return provider(project);
 }
 function toForwardSlashes(p) {
     return p.split(path.sep).join("/");
@@ -45,8 +18,8 @@ function toForwardSlashes(p) {
  * Converts an input path (typically the absolute path supplied by an agent)
  * into the portable form persisted in a doc.
  *
- * Falls back to an absolute path — with a warning — when there is no code root,
- * or when the file lives outside the root (including a different Windows drive).
+ * Keeps an absolute path — with a warning — when there is no code root, or when
+ * the file lives outside the root (including a different Windows drive).
  */
 export function toStoredPath(inputPath, project) {
     const abs = path.resolve(process.cwd(), inputPath);
@@ -64,19 +37,22 @@ export function toStoredPath(inputPath, project) {
     return toForwardSlashes(rel);
 }
 /**
- * Resolves a stored path to an absolute filesystem path on this machine.
+ * Resolves a stored path against a given code root:
  *
- *  - absolute stored path (legacy / fallback)  → returned as-is
- *  - relative stored path + configured root     → joined with the root
- *  - relative stored path + no root configured  → undefined (unverifiable here)
+ *  - absolute stored path                 → returned as-is
+ *  - relative stored path + a root        → joined with the root
+ *  - relative stored path + no root       → undefined (unverifiable here)
  */
-export function toAbsolutePath(stored, project) {
+export function resolveAgainstRoot(stored, root) {
     if (path.isAbsolute(stored)) {
         return stored;
     }
-    const root = getCodeRoot(project);
     if (!root) {
         return undefined;
     }
     return path.resolve(root, stored);
 }
+/** Resolves a stored path to an absolute filesystem path on this machine. */
+export function toAbsolutePath(stored, project) {
+    return resolveAgainstRoot(stored, getCodeRoot(project));
+}

package/dist/src/core/project-settings.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+/**
+ * Where a project's source code is read from.
+ *
+ *  - `local`  — the working copy on this machine, resolved through the code roots.
+ *  - `github` — one branch of one repository, read over the GitHub API. `branch` undefined means
+ *               the repository's default branch.
+ */
+export declare const CodeSourceConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"local">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"github">;
+    repo: z.ZodString;
+    branch: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "kind">;
+export type CodeSourceConfig = z.infer<typeof CodeSourceConfigSchema>;
+/** Whether the project has a code source written in its settings. */
+export declare function hasCodeSourceConfig(projectDir: string): boolean;
+/** The project's code source. Throws when the settings file exists but cannot be read. */
+export declare function readCodeSourceConfig(projectDir: string): CodeSourceConfig;
+export declare function writeCodeSourceConfig(projectDir: string, config: CodeSourceConfig): void;

package/dist/src/core/project-settings.js

@@ -0,0 +1,63 @@
+import fs from "fs";
+import path from "path";
+import { z } from "zod";
+/**
+ * Where a project's source code is read from.
+ *
+ *  - `local`  — the working copy on this machine, resolved through the code roots.
+ *  - `github` — one branch of one repository, read over the GitHub API. `branch` undefined means
+ *               the repository's default branch.
+ */
+export const CodeSourceConfigSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("local") }),
+    z.object({
+        kind: z.literal("github"),
+        repo: z.string().regex(/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/, 'expected "owner/repo"'),
+        branch: z.string().min(1).optional(),
+    }),
+]);
+const ProjectSettingsSchema = z.object({
+    codeSource: CodeSourceConfigSchema.optional(),
+});
+/**
+ * Per-project settings, in `projects/<project>/project.json`. The file lives next to the docs, so
+ * it is versioned and synchronised with them: every machine reads the same code source.
+ */
+function settingsPath(projectDir) {
+    return path.join(projectDir, "project.json");
+}
+/** A project without settings, or without a code source in them, reads its local working copy. */
+const DEFAULT_CODE_SOURCE = { kind: "local" };
+function readSettings(projectDir) {
+    const file = settingsPath(projectDir);
+    if (!fs.existsSync(file))
+        return {};
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, "utf-8"));
+    }
+    catch {
+        throw new Error(`${file} is not valid JSON`);
+    }
+    const parsed = ProjectSettingsSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`${file} is invalid: ${parsed.error.issues.map((i) => `${i.path.join(".")} ${i.message}`).join("; ")}`);
+    }
+    return parsed.data;
+}
+/** Whether the project has a code source written in its settings. */
+export function hasCodeSourceConfig(projectDir) {
+    return readSettings(projectDir).codeSource !== undefined;
+}
+/** The project's code source. Throws when the settings file exists but cannot be read. */
+export function readCodeSourceConfig(projectDir) {
+    return readSettings(projectDir).codeSource ?? DEFAULT_CODE_SOURCE;
+}
+export function writeCodeSourceConfig(projectDir, config) {
+    const validated = CodeSourceConfigSchema.parse(config);
+    const file = settingsPath(projectDir);
+    const settings = fs.existsSync(file) ? readSettings(projectDir) : {};
+    settings.codeSource = validated;
+    fs.mkdirSync(projectDir, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}

package/dist/src/gui-worker.js

@@ -2,7 +2,7 @@ import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
-import { ProxyClient } from "@imenam/mcp-gui-interface";
+import { GUI_LISTEN_HOST, ProxyClient, honoGuiGuard } from "@imenam/mcp-gui-interface";
 import { IPCMessageSchema } from "../shared/schemas/doc.schema.js";
 import { isReadOnly } from "../shared/read-only.js";
 import path from "path";
@@ -125,6 +125,7 @@ async function findSystemBrowser() {
 let localPort = 0;
 let guiPublicUrl = '';
 const app = new Hono();
+app.use("*", honoGuiGuard());
 let proxyClient = null;
 const sseControllers = new Set();
 const pendingRequests = new Map();
@@ -196,7 +197,15 @@ function setupIpcErrorHandlers() {
             });
             return;
         }
-        if (msg && (msg.type === "INITIAL_STATE" || msg.type === "CONFIG_UPDATED" || msg.type === "BUNDLES_UPDATED")) {
+        const BROADCAST_TYPES = [
+            "INITIAL_STATE",
+            "CONFIG_UPDATED",
+            "BUNDLES_UPDATED",
+            "PROJECTS_CHANGED",
+            "DOCS_CHANGED",
+            "CODE_SOURCES_CHANGED",
+        ];
+        if (msg && BROADCAST_TYPES.includes(msg.type)) {
             for (const controller of sseControllers) {
                 try {
                     controller.writeSSE({ data: JSON.stringify(msg), event: "message" });
@@ -216,6 +225,8 @@ const READ_ONLY_WRITE_ROUTES = [
     { method: "POST", prefix: "/api/images" },
     { method: "POST", prefix: "/api/configurations/apply" },
     { method: "POST", prefix: "/api/sync" },
+    { method: "POST", prefix: "/api/code-sources/apply" },
+    { method: "POST", prefix: "/api/code-roots/apply" },
 ];
 app.use("*", async (c, next) => {
     if (isReadOnly()) {
@@ -358,6 +369,64 @@ app.post("/api/sync", async (c) => {
         return c.json({ error: result.error }, 500);
     return c.json(result.data);
 });
+// --- Code sources ---
+/** Relays one IPC request and answers with its data, or with its error and `errorStatus`. */
+async function relay(c, type, data, timeout, errorStatus = 500) {
+    const result = await ipcRequest(type, data, timeout);
+    if (result.error)
+        return c.json({ error: result.error }, errorStatus);
+    return c.json(result.data);
+}
+async function readJson(c) {
+    try {
+        return await c.req.json();
+    }
+    catch {
+        return {};
+    }
+}
+// GitHub projects are checked against their branch: one API round trip each.
+app.get("/api/code-sources", (c) => relay(c, "LIST_CODE_SOURCES", {}, 30000));
+app.post("/api/code-sources/inspect", async (c) => {
+    const { repo, branch } = await readJson(c);
+    if (!repo)
+        return c.json({ error: "repo is required" }, 400);
+    return relay(c, "INSPECT_REPOSITORY", { repo, branch }, 30000);
+});
+// Reads every tracked file of the project at the previewed source.
+// `codeRoot`: omitted keeps the project's root, "" means the machine default, else the project's own.
+app.post("/api/code-sources/preview", async (c) => {
+    const { project, config, codeRoot } = await readJson(c);
+    if (!project || !config)
+        return c.json({ error: "project and config are required" }, 400);
+    return relay(c, "PREVIEW_CODE_SOURCE", { project, config, codeRoot }, 120000, 400);
+});
+app.post("/api/code-sources/apply", async (c) => {
+    const { project, config, codeRoot } = await readJson(c);
+    if (!project || !config)
+        return c.json({ error: "project and config are required" }, 400);
+    return relay(c, "SAVE_CODE_SOURCE", { project, config, codeRoot }, 10000, 400);
+});
+app.get("/api/code-roots", (c) => relay(c, "GET_CODE_ROOTS", {}, 5000));
+app.post("/api/code-sources/search", async (c) => {
+    const { query } = await readJson(c);
+    return relay(c, "SEARCH_REPOSITORIES", { query: query ?? "" }, 15000);
+});
+app.post("/api/code-roots/inspect", async (c) => {
+    const { path: root } = await readJson(c);
+    return relay(c, "INSPECT_CODE_ROOT", { path: root ?? "" }, 5000);
+});
+// Without a project, sets the machine default root. An empty path removes the root.
+app.post("/api/code-roots/apply", async (c) => {
+    const { path: root, project } = await readJson(c);
+    if (typeof root !== "string")
+        return c.json({ error: "path is required" }, 400);
+    return relay(c, "SET_CODE_ROOT", { path: root, project }, 5000, 400);
+});
+// The token is read from MCP_DOCUMENTOR_CODE_TOKEN only: the GUI shows its status, never sets it.
+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));
 app.get("/api/projects", async (c) => {
     const result = await ipcRequest("LIST_PROJECTS");
     if (result.error)
@@ -757,7 +826,7 @@ app.get("/*", (c, next) => {
  */
 function listen(port, publicUrl, isProxied) {
     logger.info(`Starting Hono server on port ${port}...`);
-    const serverInstance = serve({ fetch: app.fetch, port, hostname: "0.0.0.0" }, (info) => {
+    const serverInstance = serve({ fetch: app.fetch, port, hostname: GUI_LISTEN_HOST }, (info) => {
         logger.info(`Dashboard server listening on port ${info.port}`);
         safeSend(IPCMessageSchema.parse({
             type: "READY",