@imenam/mcp-documentor 1.0.74 → 1.0.76

package/dist/src/cli/setup-mcp.js

@@ -4,8 +4,9 @@ const SERVER_NAME = "mcp-documentor";
 const PACKAGE_NAME = "@imenam/mcp-documentor";
 /**
  * Valeurs volontairement vides : chaque variable est inactive tant qu'elle n'est
- * pas remplie (PROXY_URL vide = GUI désactivée, clé vide = pas d'embeddings),
- * donc le fichier généré est utilisable tel quel, jamais à moitié cassé.
+ * pas remplie (PROXY_URL et APP_PORT vides = GUI désactivée, clé vide = pas
+ * d'embeddings), donc le fichier généré est utilisable tel quel, jamais à
+ * moitié cassé.
  */
 /** Slashes POSIX : évite les backslashes échappés dans le JSON, et Node les accepte sous Windows. */
 function toPosixPath(dir) {
@@ -23,14 +24,18 @@ function toDisplayName(folder) {
         .map(capitalize)
         .join(" ");
 }
-function buildServerEntry(codeRoot) {
+function buildServerEntry(codeRoot, exposure) {
     // Le nom du dossier courant sert de base aux identifiants d'affichage côté proxy.
     const folder = path.basename(codeRoot) || "documentor";
+    // Un port explicite désactive le placeholder proxy : les deux variables ne
+    // doivent jamais être renseignées ensemble, PROXY_URL primant au runtime.
+    const proxyUrl = exposure.appPort !== undefined ? "" : exposure.proxyUrl ?? "http://localhost:";
     return {
         command: "npx",
         args: ["-y", PACKAGE_NAME],
         env: {
-            PROXY_URL: "http://localhost:",
+            PROXY_URL: proxyUrl,
+            APP_PORT: exposure.appPort !== undefined ? String(exposure.appPort) : "",
             APP_GROUP: capitalize(folder),
             APP_NAME: `Documentor ${toDisplayName(folder)}`,
             APP_PATH: `/documentor-${folder}`,
@@ -47,6 +52,7 @@ function buildServerEntry(codeRoot) {
 }
 const GENERATED_VARS = [
     ["PROXY_URL", "URL du proxy pour exposer la GUI (compléter le port)"],
+    ["APP_PORT", "port local si aucun proxy — la GUI est servie sur http://localhost:<port>"],
     ["APP_GROUP", "groupe d'affichage dans le dashboard du proxy"],
     ["APP_NAME", "nom affiché de la GUI dans le dashboard du proxy"],
     ["APP_PATH", "chemin de montage de la GUI derrière le proxy"],
@@ -64,7 +70,53 @@ const OPTIONAL_VARS = [
     ["READ_ONLY", "1/true pour désactiver toutes les écritures"],
     ["SYNC_PULL_ON_START", "false pour désactiver le pull au démarrage"],
 ];
-export function runSetupMcp({ cwd, force }) {
+/** Lit `--flag=valeur` (tirets ou underscores acceptés). */
+function readFlag(argv, name) {
+    const prefixes = [`--${name}=`, `--${name.replace(/_/g, "-")}=`];
+    for (const arg of argv) {
+        const prefix = prefixes.find((p) => arg.startsWith(p));
+        if (prefix)
+            return arg.slice(prefix.length).trim();
+    }
+    return undefined;
+}
+/**
+ * Traduit `--proxy_url=` / `--app_port=` en mode d'exposition de la GUI.
+ * Les deux ensemble sont refusés : au runtime PROXY_URL primerait toujours,
+ * donc un fichier portant les deux serait silencieusement trompeur.
+ */
+export function parseGuiExposure(argv) {
+    const rawProxyUrl = readFlag(argv, "proxy_url");
+    const rawAppPort = readFlag(argv, "app_port");
+    if (rawProxyUrl !== undefined && rawAppPort !== undefined) {
+        return { error: "--proxy_url et --app_port sont exclusifs : la GUI passe par le proxy, ou écoute sur un port local." };
+    }
+    if (rawProxyUrl !== undefined) {
+        if (rawProxyUrl === "")
+            return { error: "--proxy_url attend une URL, ex : --proxy_url=http://localhost:3000" };
+        let parsed;
+        try {
+            parsed = new URL(rawProxyUrl);
+        }
+        catch {
+            return { error: `--proxy_url invalide : "${rawProxyUrl}" n'est pas une URL absolue (ex : http://localhost:3000).` };
+        }
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            return { error: `--proxy_url invalide : protocole "${parsed.protocol}" non supporté (http ou https attendu).` };
+        }
+        // Une barre finale casserait la concaténation PROXY_URL + APP_PATH.
+        return { exposure: { proxyUrl: rawProxyUrl.replace(/\/+$/, "") } };
+    }
+    if (rawAppPort !== undefined) {
+        const port = Number(rawAppPort);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            return { error: `--app_port invalide : "${rawAppPort}" n'est pas un entier entre 1 et 65535.` };
+        }
+        return { exposure: { appPort: port } };
+    }
+    return { exposure: {} };
+}
+export function runSetupMcp({ cwd, force, exposure = {} }) {
     const target = path.join(cwd, ".mcp.json");
     let config = {};
     const exists = fs.existsSync(target);
@@ -94,11 +146,17 @@ export function runSetupMcp({ cwd, force }) {
         console.error("Relancez avec --force pour écraser cette entrée (les autres serveurs sont préservés).");
         return 1;
     }
-    config.mcpServers[SERVER_NAME] = buildServerEntry(cwd);
+    config.mcpServers[SERVER_NAME] = buildServerEntry(cwd, exposure);
     fs.writeFileSync(target, JSON.stringify(config, null, 2) + "\n", "utf-8");
     const action = alreadyPresent ? "remplacée" : exists ? "ajoutée" : "créée";
     console.log(`Configuration ${SERVER_NAME} ${action} dans ${target}`);
     console.log("");
+    if (exposure.appPort !== undefined) {
+        console.log(`GUI en accès direct : http://localhost:${exposure.appPort} (sans proxy).`);
+    }
+    else if (exposure.proxyUrl !== undefined) {
+        console.log(`GUI exposée via le proxy ${exposure.proxyUrl}.`);
+    }
     console.log('À compléter dans le champ "env" :');
     for (const [name, description] of GENERATED_VARS) {
         console.log(`  ${name.padEnd(30)} ${description}`);
@@ -110,5 +168,6 @@ export function runSetupMcp({ cwd, force }) {
     }
     console.log("");
     console.log("Une variable laissée vide est simplement inactive.");
+    console.log("PROXY_URL et APP_PORT s'excluent : PROXY_URL prime si les deux sont renseignés.");
     return 0;
 }

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

@@ -1,7 +1,6 @@
 import type { DocEntry, DocSummary, ExportBundle } from "../../shared/schemas/doc.schema.js";
 import type { HistoryStore } from "./history-store.js";
 interface GlobalConfig {
-    currentProject: string;
     projects: string[];
     foldersMigrated?: boolean;
 }
@@ -22,16 +21,16 @@ export declare class StorageEngine {
     constructor(rootDir: string);
     setHistoryStore(store: HistoryStore): void;
     getDataDir(): string;
-    getProjectDir(project?: string): string;
+    /**
+     * There is no "current project" fallback: every caller names the project it
+     * targets. The UI's project selector is a client-side view preference only.
+     */
+    getProjectDir(project: string): string;
     private getConfigPath;
-    private getLocalStatePath;
-    private readLocalState;
-    private writeLocalState;
     /**
-     * Returns the merged config. The shared part (projects list, migration flags)
-     * comes from config.json (versioned), while currentProject is a machine-local
-     * preference sourced from local-state.json (gitignored). Legacy config.json
-     * files that still embed currentProject are migrated transparently.
+     * Reads config.json (versioned): the project list and migration flags.
+     * A legacy currentProject key is stripped on read — project selection is a
+     * per-client UI concern and is no longer server state.
      */
     getConfig(): GlobalConfig;
     saveConfig(config: GlobalConfig): void;
@@ -41,13 +40,13 @@ export declare class StorageEngine {
     private walkMdFiles;
     private docIdToFilePath;
     private cleanEmptyDirs;
-    saveDoc(doc: DocEntry, project?: string, changeType?: "create" | "update" | "patch"): Promise<void>;
-    getDoc(id: string, project?: string): Promise<DocEntry | null>;
-    listDocs(project?: string): Promise<DocSummary[]>;
-    deleteDoc(id: string, project?: string): Promise<boolean>;
-    moveDoc(oldId: string, newId: string, project?: string): Promise<boolean>;
+    saveDoc(doc: DocEntry, project: string, changeType?: "create" | "update" | "patch"): Promise<void>;
+    getDoc(id: string, project: string): Promise<DocEntry | null>;
+    listDocs(project: string): Promise<DocSummary[]>;
+    deleteDoc(id: string, project: string): Promise<boolean>;
+    moveDoc(oldId: string, newId: string, project: string): Promise<boolean>;
     getBundles(): ExportBundle[];
     saveBundles(bundles: ExportBundle[]): void;
-    rewriteLinks(oldId: string, newId: string, project?: string): Promise<string[]>;
+    rewriteLinks(oldId: string, newId: string, project: string): Promise<string[]>;
 }
 export {};

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

@@ -19,39 +19,20 @@ export class StorageEngine {
         const envDir = process.env.MCP_DATA_DIR;
         return envDir && envDir.trim() !== "" ? envDir : path.join(this.rootDir, ".docs-data");
     }
+    /**
+     * There is no "current project" fallback: every caller names the project it
+     * targets. The UI's project selector is a client-side view preference only.
+     */
     getProjectDir(project) {
-        const config = this.getConfig();
-        const proj = project ?? config.currentProject;
-        return path.join(this.getDataDir(), "projects", proj);
+        return path.join(this.getDataDir(), "projects", project);
     }
     getConfigPath() {
         return path.join(this.getDataDir(), "config.json");
     }
-    getLocalStatePath() {
-        return path.join(this.getDataDir(), "local-state.json");
-    }
-    readLocalState() {
-        const p = this.getLocalStatePath();
-        if (fs.existsSync(p)) {
-            try {
-                return JSON.parse(fs.readFileSync(p, "utf-8"));
-            }
-            catch {
-                logger.warn("Failed to parse local-state.json, using defaults");
-            }
-        }
-        return {};
-    }
-    writeLocalState(state) {
-        const p = this.getLocalStatePath();
-        fs.mkdirSync(path.dirname(p), { recursive: true });
-        fs.writeFileSync(p, JSON.stringify(state, null, 2), "utf-8");
-    }
     /**
-     * Returns the merged config. The shared part (projects list, migration flags)
-     * comes from config.json (versioned), while currentProject is a machine-local
-     * preference sourced from local-state.json (gitignored). Legacy config.json
-     * files that still embed currentProject are migrated transparently.
+     * Reads config.json (versioned): the project list and migration flags.
+     * A legacy currentProject key is stripped on read — project selection is a
+     * per-client UI concern and is no longer server state.
      */
     getConfig() {
         const configPath = this.getConfigPath();
@@ -64,35 +45,20 @@ export class StorageEngine {
                 logger.warn("Failed to parse config.json, using defaults");
             }
         }
-        const local = this.readLocalState();
-        const projects = shared.projects ?? ["default"];
-        // Migrate a legacy currentProject embedded in config.json into local-state.
-        if (shared.currentProject !== undefined && local.currentProject === undefined) {
-            local.currentProject = shared.currentProject;
-            this.writeLocalState(local);
+        if (shared.currentProject !== undefined) {
             delete shared.currentProject;
             fs.writeFileSync(configPath, JSON.stringify(shared, null, 2), "utf-8");
-            logger.info("Migrated currentProject from config.json to local-state.json");
+            logger.info("Dropped obsolete currentProject from config.json");
         }
         return {
-            currentProject: local.currentProject ?? projects[0] ?? "default",
-            projects,
+            projects: shared.projects ?? ["default"],
             foldersMigrated: shared.foldersMigrated,
         };
     }
     saveConfig(config) {
-        // Shared, versioned part → config.json (currentProject is intentionally excluded).
         const configPath = this.getConfigPath();
-        const shared = {
-            projects: config.projects,
-            foldersMigrated: config.foldersMigrated,
-        };
         fs.mkdirSync(path.dirname(configPath), { recursive: true });
-        fs.writeFileSync(configPath, JSON.stringify(shared, null, 2), "utf-8");
-        // Machine-local part → local-state.json.
-        const local = this.readLocalState();
-        local.currentProject = config.currentProject;
-        this.writeLocalState(local);
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
     }
     /** Reads sync settings from environment variables (admin-controlled, not agent-settable). */
     getSyncConfig() {
@@ -146,8 +112,7 @@ export class StorageEngine {
         }
     }
     async saveDoc(doc, project, changeType = "update") {
-        const config = this.getConfig();
-        const proj = project ?? config.currentProject;
+        const proj = project;
         const projectDir = this.getProjectDir(project);
         const targetPath = this.docIdToFilePath(doc.id, projectDir);
         fs.mkdirSync(path.dirname(targetPath), { recursive: true });
@@ -220,8 +185,7 @@ export class StorageEngine {
     // existed in several. Doc-targeted callers must name their project and go through
     // getDoc(id, project) — see core/project-scope.ts.
     async deleteDoc(id, project) {
-        const config = this.getConfig();
-        const proj = project ?? config.currentProject;
+        const proj = project;
         const projectDir = this.getProjectDir(project);
         const filePath = this.docIdToFilePath(id, projectDir);
         if (!fs.existsSync(filePath))
@@ -277,7 +241,7 @@ export class StorageEngine {
     }
     async rewriteLinks(oldId, newId, project) {
         const config = this.getConfig();
-        const proj = project ?? config.currentProject;
+        const proj = project;
         const updated = [];
         // Within the same project: rewrite same-project refs and explicit self-cross-project refs
         const sameProjDocs = await this.listDocs(proj);

package/dist/src/gui-worker.js

@@ -32,6 +32,22 @@ const dataDir = process.env.MCP_DATA_DIR?.trim() || path.join(rootDir, ".docs-da
 const staticRoot = path.join(rootDir, "gui/dist");
 const absoluteStaticRoot = path.resolve(staticRoot);
 const configuredAppPath = process.env.APP_PATH || "/documentor-gui";
+function resolveGuiMode() {
+    const proxyUrl = process.env.PROXY_URL?.trim();
+    if (proxyUrl)
+        return { kind: "proxy", proxyUrl };
+    const rawPort = process.env.APP_PORT?.trim();
+    if (!rawPort) {
+        return { kind: "disabled", reason: "PROXY_URL et APP_PORT non définis" };
+    }
+    const port = Number(rawPort);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        return { kind: "disabled", reason: `APP_PORT invalide (${rawPort}) — attendu : entier entre 1 et 65535` };
+    }
+    return { kind: "standalone", port };
+}
+const guiMode = resolveGuiMode();
+const isStandalone = guiMode.kind === "standalone";
 setupLogging({ processLabel: "mcp-documentor:GUI", logDir: resolveLogDir(rootDir) });
 const logger = createLogger("mcp-documentor:GUI");
 process.on("uncaughtException", (err) => {
@@ -208,7 +224,7 @@ app.get("/proxy/health", (c) => {
     const memory = process.memoryUsage();
     return c.json({
         status: "ok",
-        proxy: proxyClient ? proxyClient.getStatus() : process.env.PROXY_URL ? "error" : "standalone",
+        proxy: proxyClient ? proxyClient.getStatus() : isStandalone ? "standalone" : "error",
         uptime: process.uptime(),
         memory: { rss: memory.rss, heapUsed: memory.heapUsed },
         ipc: process.connected ? "connected" : "disconnected",
@@ -343,22 +359,29 @@ app.get("/api/projects", async (c) => {
 });
 app.get("/api/folders", async (c) => {
     const project = c.req.query("project");
-    const result = await ipcRequest("LIST_FOLDERS", project ? { project } : {});
+    if (!project)
+        return c.json({ error: "project query param is required" }, 400);
+    const result = await ipcRequest("LIST_FOLDERS", { project });
     if (result.error)
         return c.json({ error: result.error }, 500);
     return c.json(result.data);
 });
-app.put("/api/project", async (c) => {
+// Creates an empty project. Selecting a project is a client-side concern:
+// the server holds no active project.
+app.post("/api/projects", async (c) => {
     const { project } = await c.req.json();
     if (!project)
         return c.json({ error: "project is required" }, 400);
-    const result = await ipcRequest("UPDATE_PROJECT", { project });
+    const result = await ipcRequest("CREATE_PROJECT", { project });
     if (result.error)
         return c.json({ error: result.error }, 500);
     return c.json(result.data);
 });
 app.get("/api/docs", async (c) => {
-    const result = await ipcRequest("LIST_DOCS");
+    const project = c.req.query("project");
+    if (!project)
+        return c.json({ error: "project query param is required" }, 400);
+    const result = await ipcRequest("LIST_DOCS", { project });
     if (result.error)
         return c.json({ error: result.error }, 500);
     return c.json(result.data);
@@ -475,10 +498,13 @@ app.get("/api/history-version/*", async (c) => {
     return c.json(result.data);
 });
 app.post("/api/search", async (c) => {
-    const { query, top_k, all_projects } = await c.req.json();
+    const { query, top_k, all_projects, project } = await c.req.json();
     if (!query)
         return c.json({ error: "query is required" }, 400);
-    const result = await ipcRequest("SEARCH_DOCS", { query, top_k: top_k || 5, all_projects: !!all_projects });
+    if (!all_projects && !project) {
+        return c.json({ error: "project is required unless all_projects is set" }, 400);
+    }
+    const result = await ipcRequest("SEARCH_DOCS", { query, top_k: top_k || 5, all_projects: !!all_projects, project });
     if (result.error)
         return c.json({ error: result.error }, 500);
     return c.json(result.data);
@@ -522,14 +548,9 @@ app.get("/api/export-zip/:id", async (c) => {
     const bundle = bundles.find((b) => b.id === id);
     if (!bundle)
         return c.json({ error: "Bundle not found" }, 404);
-    let currentProject = "default";
-    try {
-        const configPath = path.join(dataDir, "config.json");
-        if (fs.existsSync(configPath)) {
-            currentProject = JSON.parse(fs.readFileSync(configPath, "utf-8")).currentProject ?? "default";
-        }
-    }
-    catch { /* use default */ }
+    // Legacy bundles may hold bare doc ids; they are resolved against the project
+    // the caller is viewing. Fully qualified "project:doc-id" refs ignore it.
+    const fallbackProject = c.req.query("project");
     const flat = c.req.query('flat') === '1';
     const includeHeaders = c.req.query('headers') === '1';
     const zip = new JSZip();
@@ -541,10 +562,15 @@ app.get("/api/export-zip/:id", async (c) => {
             project = ref.slice(0, colonIdx);
             docId = ref.slice(colonIdx + 1);
         }
-        else {
-            project = currentProject;
+        else if (fallbackProject) {
+            project = fallbackProject;
             docId = ref;
         }
+        else {
+            zip.file(`${ref}.md`, `# [Unqualified doc reference: ${ref} — no project given]
+`);
+            continue;
+        }
         const docFilePath = path.join(dataDir, "projects", project, ...docId.split("/")) + ".md";
         let content;
         if (!fs.existsSync(docFilePath)) {
@@ -704,8 +730,9 @@ app.get("/*", (c, next) => {
         const indexPath = path.join(absoluteStaticRoot, "index.html");
         if (fs.existsSync(indexPath)) {
             // ?__pdf=1 : accès direct depuis Puppeteer — pas de préfixe proxy dans <base href>
+            // En mode standalone la GUI est déjà servie à la racine : même règle.
             const isPdfRender = c.req.query('__pdf') === '1';
-            const baseHref = isPdfRender ? '/' : getHtmlBaseHref(configuredAppPath);
+            const baseHref = isStandalone || isPdfRender ? '/' : getHtmlBaseHref(configuredAppPath);
             const html = fs
                 .readFileSync(indexPath, "utf8")
                 .replace("<head>", `<head>\n    <base href="${baseHref}" />`);
@@ -717,12 +744,54 @@ app.get("/*", (c, next) => {
         return next();
     }
 });
+/**
+ * Lance Hono sur `port` et prévient le master. `publicUrl` est l'URL que
+ * l'utilisateur doit ouvrir : via le proxy, ou directement en localhost.
+ */
+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) => {
+        logger.info(`Dashboard server listening on port ${info.port}`);
+        safeSend(IPCMessageSchema.parse({
+            type: "READY",
+            data: { port: info.port, isProxied, url: publicUrl },
+            timestamp: new Date().toISOString(),
+        }));
+    });
+    serverInstance.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            // Sortie propre (code 0) : le master ne doit pas relancer un worker de plus.
+            logger.error(`Port ${port} already in use — another GUI instance is running.`);
+            safeSend(IPCMessageSchema.parse({
+                type: "ALREADY_RUNNING",
+                data: { url: publicUrl },
+                timestamp: new Date().toISOString(),
+            }));
+            process.exit(0);
+        }
+        logger.error(`Server error: ${err.message}`);
+        process.exit(1);
+    });
+}
+/** Sans proxy : la GUI écoute sur APP_PORT et est servie à la racine. */
+function startStandalone(port) {
+    const publicUrl = `http://localhost:${port}`;
+    logger.info(`Standalone mode (no PROXY_URL): serving GUI on ${publicUrl}`);
+    localPort = port;
+    guiPublicUrl = publicUrl;
+    setupIpcErrorHandlers();
+    listen(port, publicUrl, false);
+}
 async function startServer() {
-    if (!process.env.PROXY_URL) {
-        process.stderr.write('[GUI] PROXY_URL non défini — arrêt.\n');
+    if (guiMode.kind === "disabled") {
+        process.stderr.write(`[GUI] ${guiMode.reason} — arrêt.\n`);
         process.exit(0);
     }
-    const proxyUrl = process.env.PROXY_URL;
+    if (guiMode.kind === "standalone") {
+        startStandalone(guiMode.port);
+        return;
+    }
+    const proxyUrl = guiMode.proxyUrl;
     const appPath = configuredAppPath;
     const appName = process.env.APP_NAME || "MCP Documentor GUI";
     logger.info(`Starting server with proxyUrl=${proxyUrl}`);
@@ -769,19 +838,7 @@ async function startServer() {
     process.on("SIGTERM", cleanupProxy);
     process.on("SIGINT", cleanupProxy);
     setupIpcErrorHandlers();
-    logger.info(`Starting Hono server on port ${finalPort}...`);
-    const serverInstance = serve({ fetch: app.fetch, port: finalPort, hostname: "0.0.0.0" }, (info) => {
-        logger.info(`Dashboard server listening on port ${info.port}`);
-        safeSend(IPCMessageSchema.parse({
-            type: "READY",
-            data: { port: info.port, isProxied: true, url: publicUrl },
-            timestamp: new Date().toISOString(),
-        }));
-    });
-    serverInstance.on("error", (err) => {
-        logger.error(`Server error: ${err.message}`);
-        process.exit(1);
-    });
+    listen(finalPort, publicUrl, true);
 }
 startServer().catch((err) => {
     logger.error(`Failed to start GUI Worker: ${err.message}`);