@imenam/mcp-documentor 1.0.72 → 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/conflict-inspector.d.ts

@@ -20,6 +20,19 @@ export interface ConflictHunk {
     remote: string[];
     /** Common ancestor, present only when the markers were written in diff3 style. */
     base?: string[];
+    /**
+     * The hunk concerns frontmatter, either because it sits inside the YAML block
+     * or because the doc merge driver hoisted a frontmatter disagreement to the
+     * top of the body. Keeping both sides of one of these would duplicate a key,
+     * so that choice is refused rather than silently producing broken YAML.
+     */
+    inFrontmatter: boolean;
+    /**
+     * The hunk is the block the doc merge driver hoisted out of the frontmatter.
+     * Its sides are `key: value` lines that belong back in the YAML, not in the
+     * body where the markers physically sit.
+     */
+    hoisted: boolean;
 }
 export interface ParsedFile {
     lines: string[];

package/dist/src/core/conflict-inspector.js

@@ -34,6 +34,19 @@ export function hasConflictMarkers(text) {
 function sidesFor(operation, first, second) {
     return operation === "rebase" ? { local: second, remote: first } : { local: first, remote: second };
 }
+/**
+ * Line range of the YAML frontmatter block, if the file opens with one.
+ * Returns null when there is none.
+ */
+function frontmatterRange(lines) {
+    if (lines.length === 0 || lines[0].trim() !== "---")
+        return null;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === "---")
+            return { start: 0, end: i };
+    }
+    return null;
+}
 function sectionFor(lines, hunkStart) {
     for (let i = hunkStart - 1; i >= 0; i--) {
         const match = lines[i].match(HEADING);
@@ -45,6 +58,7 @@ function sectionFor(lines, hunkStart) {
 /** Splits a conflicted file into hunks. Handles both diff3 and plain markers. */
 export function parseConflicts(text, operation) {
     const lines = splitLines(text);
+    const frontmatter = frontmatterRange(lines);
     const hunks = [];
     for (let i = 0; i < lines.length; i++) {
         if (!START.test(lines[i]))
@@ -56,6 +70,7 @@ export function parseConflicts(text, operation) {
         let sawBase = false;
         let closed = false;
         let j = i + 1;
+        const label = lines[i].match(START)?.[1] ?? "";
         for (; j < lines.length; j++) {
             const line = lines[j];
             if (BASE.test(line)) {
@@ -84,6 +99,8 @@ export function parseConflicts(text, operation) {
             local,
             remote,
             ...(sawBase ? { base } : {}),
+            inFrontmatter: label.includes("frontmatter") || (frontmatter !== null && i >= frontmatter.start && i <= frontmatter.end),
+            hoisted: label.includes("frontmatter"),
         });
         i = j;
     }

package/dist/src/core/git-sync.d.ts

@@ -44,13 +44,11 @@ export type PullResult = {
 } | {
     status: "updated";
     changed: string[];
-} | {
-    status: "diverged";
-    ahead: number;
-    behind: number;
+    autoCommitted?: boolean;
 } | {
     status: "conflict";
     conflicted: string[];
+    autoCommitted?: boolean;
 };
 export declare class SyncEngine {
     private storage;
@@ -88,6 +86,15 @@ export declare class SyncEngine {
      */
     pull(): Promise<PullResult>;
     private diffNames;
+    /**
+     * Stages and commits whatever the working tree holds. Committing is what makes
+     * local edits safe to rebase over, so both push and pull go through here
+     * rather than asking the caller to tidy up first.
+     *
+     * .gitignore (written by ensureRepo) excludes all derived and machine-local
+     * state, so `add -A` only ever stages versioned files.
+     */
+    private commitLocalChanges;
     /** Stages versioned files, commits if there is anything to commit, and pushes. */
     push(message?: string): Promise<{
         pushed: boolean;

package/dist/src/core/git-sync.js

@@ -205,20 +205,23 @@ export class SyncEngine {
         }
         // Ensure upstream tracking so status ahead/behind is meaningful.
         await this.git.branch(["--set-upstream-to", `origin/${cfg.branch}`, cfg.branch]).catch(() => { });
-        const status = await this.git.status();
-        if (status.behind === 0)
+        let status = await this.git.status();
+        if (status.behind === 0 && status.files.length === 0)
             return { status: "up-to-date" };
-        // Uncommitted local changes block a safe merge — never risk clobbering them.
-        // Surface as diverged so the user commits/pushes (or stashes) first.
-        if (status.files.length > 0) {
-            return { status: "diverged", ahead: status.ahead, behind: status.behind };
-        }
+        // Uncommitted local edits cannot be rebased over, and reporting the
+        // divergence instead used to strand the caller: the pull asked for a push,
+        // which the remote rejected and which asked for a pull. Committing them
+        // resolves it - the edits become a commit the rebase can replay, nothing is
+        // published, and nothing can be clobbered.
+        const autoCommitted = status.files.length > 0 ? await this.commitLocalChanges() : false;
+        if (autoCommitted)
+            status = await this.git.status();
         const before = await this.git.revparse(["HEAD"]).catch(() => "");
         // Pure behind → fast-forward.
         if (status.ahead === 0) {
             await this.git.merge(["--ff-only", `origin/${cfg.branch}`]);
             const after = await this.git.revparse(["HEAD"]).catch(() => "");
-            return { status: "updated", changed: await this.diffNames(before, after) };
+            return { status: "updated", changed: await this.diffNames(before, after), autoCommitted };
         }
         // Diverged with a clean tree → replay local commits on top of the remote. A
         // conflict stops the rebase with both versions preserved in the index, so it
@@ -229,17 +232,35 @@ export class SyncEngine {
         catch {
             const after = await this.git.status();
             if (after.conflicted.length > 0)
-                return { status: "conflict", conflicted: after.conflicted };
+                return { status: "conflict", conflicted: after.conflicted, autoCommitted };
             throw new Error("Rebase failed without recorded conflicts. Inspect the data directory, or run `git rebase --abort` there to get back to the previous state.");
         }
         const rebased = await this.git.revparse(["HEAD"]).catch(() => "");
-        return { status: "updated", changed: await this.diffNames(before, rebased) };
+        return { status: "updated", changed: await this.diffNames(before, rebased), autoCommitted };
     }
     async diffNames(before, after) {
         if (!before || !after || before === after)
             return [];
         return (await this.git.raw(["diff", "--name-only", before, after])).split("\n").filter(Boolean);
     }
+    /**
+     * Stages and commits whatever the working tree holds. Committing is what makes
+     * local edits safe to rebase over, so both push and pull go through here
+     * rather than asking the caller to tidy up first.
+     *
+     * .gitignore (written by ensureRepo) excludes all derived and machine-local
+     * state, so `add -A` only ever stages versioned files.
+     */
+    async commitLocalChanges(message) {
+        await this.git.add(["-A"]);
+        const status = await this.git.status();
+        const hasWork = status.staged.length > 0 || status.created.length > 0 || status.deleted.length > 0 || status.modified.length > 0;
+        if (!hasWork)
+            return false;
+        const machine = process.env.COMPUTERNAME || process.env.HOSTNAME || "unknown-machine";
+        await this.git.commit(message?.trim() || `docs sync from ${machine} · ${new Date().toISOString()}`);
+        return true;
+    }
     /** Stages versioned files, commits if there is anything to commit, and pushes. */
     async push(message) {
         const cfg = this.requireConfig();
@@ -252,24 +273,14 @@ export class SyncEngine {
             throw new Error(`A ${operation === "none" ? "conflict" : operation} is still unresolved (${pending.conflicted.length} conflicted file(s)). ` +
                 "Resolve it with resolve_sync_conflict before pushing, otherwise the conflict markers would be committed as documentation content.");
         }
-        // .gitignore (written by ensureRepo) excludes all derived/local state,
-        // so -A safely stages only versioned files (projects/, config.json, .gitignore).
-        await this.git.add(["-A"]);
-        const status = await this.git.status();
-        let committed = false;
-        if (status.staged.length > 0 || status.created.length > 0 || status.deleted.length > 0 || status.modified.length > 0) {
-            const machine = process.env.COMPUTERNAME || process.env.HOSTNAME || "unknown-machine";
-            const msg = message?.trim() || `docs sync from ${machine} · ${new Date().toISOString()}`;
-            await this.git.commit(msg);
-            committed = true;
-        }
+        const committed = await this.commitLocalChanges(message);
         try {
             await this.git.push(["-u", "origin", `HEAD:${cfg.branch}`]);
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
             if (/fetch first|non-fast-forward|\[rejected\]/i.test(msg)) {
-                throw new Error("Push rejected: the remote has commits you don't have locally. Run pull_docs to integrate them, then push again.");
+                throw new Error("Push rejected: the remote has commits you don't have locally. Run sync_docs, which integrates them and pushes in one step.");
             }
             throw e;
         }

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);