@imenam/mcp-documentor 1.0.80 → 1.0.82

package/dist/src/core/github-code-api.d.ts

@@ -40,6 +40,7 @@ export declare class GitHubCodeApi {
     private readonly spec;
     private readonly token;
     private readonly treeByCommit;
+    private readonly commitByDate;
     private readonly truncatedCommits;
     private readonly blobCache;
     constructor(spec: RepoSpec, token: string | undefined);
@@ -52,6 +53,15 @@ export declare class GitHubCodeApi {
      * once within it, however many files that operation ends up reading.
      */
     resolveRef(): Promise<ResolvedRef>;
+    /**
+     * The newest commit on the configured ref at or before `isoDate`, or undefined if the branch
+     * has no commit that old.
+     *
+     * This is how a snapshot taken before commits were recorded still gets a diff base: the date it
+     * was taken at stands in for the revision it was taken from. History is immutable below the ref's
+     * head, so the answer is cached for the life of the process.
+     */
+    resolveCommitAtDate(isoDate: string): Promise<string | undefined>;
     /** path → blob sha for every file in the commit's tree. A commit's tree never changes. */
     getTree(commitSha: string): Promise<Map<string, string>>;
     /**

package/dist/src/core/github-code-api.js

@@ -58,6 +58,7 @@ export class GitHubCodeApi {
     // at once, and they all need the same tree — and often the same blobs. Caching the promise makes
     // concurrent callers await one request instead of each firing its own.
     treeByCommit = new Map();
+    commitByDate = new Map();
     truncatedCommits = new Set();
     blobCache = new Map();
     constructor(spec, token) {
@@ -116,6 +117,24 @@ export class GitHubCodeApi {
             };
         });
     }
+    /**
+     * The newest commit on the configured ref at or before `isoDate`, or undefined if the branch
+     * has no commit that old.
+     *
+     * This is how a snapshot taken before commits were recorded still gets a diff base: the date it
+     * was taken at stands in for the revision it was taken from. History is immutable below the ref's
+     * head, so the answer is cached for the life of the process.
+     */
+    resolveCommitAtDate(isoDate) {
+        return this.cached(this.commitByDate, isoDate, async () => {
+            const ref = this.spec.ref ?? "HEAD";
+            const commits = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/commits` +
+                `?sha=${encodeURIComponent(ref)}&until=${encodeURIComponent(isoDate)}&per_page=1`);
+            const sha = Array.isArray(commits) && typeof commits[0]?.sha === "string" ? commits[0].sha : undefined;
+            logger.debug(`${this.label}: commit at or before ${isoDate} is ${sha ? sha.slice(0, 7) : "none"}`);
+            return sha;
+        });
+    }
     /** path → blob sha for every file in the commit's tree. A commit's tree never changes. */
     getTree(commitSha) {
         return this.cached(this.treeByCommit, commitSha, async () => {

package/dist/src/index.js

@@ -1251,16 +1251,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
             name: "upload_image",
-            description: "Upload an image to a project's assets from a local file path and get back the markdown link to insert in a document. Returns the URL and a ready-to-use markdown snippet: ![alt](/api/images/{project}/{filename}).",
+            description: "Upload an image to a project's assets from a file on your machine and get back the markdown link to insert in a document. Returns the URL and a ready-to-use markdown snippet: ![alt](/api/images/{project}/{filename}).",
             inputSchema: {
                 type: "object",
                 properties: {
-                    filename: { type: "string", description: "Filename with extension, e.g. 'screenshot.png'" },
-                    filePath: { type: "string", description: "Absolute path to the image file on the server" },
+                    filename: { type: "string", description: "Name the image gets in the project's assets, extension included, e.g. 'screenshot.png'" },
+                    file_path: { type: "string", description: "Absolute path to the image file on the agent machine." },
+                    file_content: { type: "string", description: "Filled in by the mcp-http-gateway relay, never by the agent: the base64 content of the file read on the agent machine." },
+                    file_name: { type: "string", description: "Filled in by the mcp-http-gateway relay, never by the agent: the original name of the file read on the agent machine." },
                     project: { type: "string", description: "Target project whose assets receive the image. REQUIRED — never defaulted to the current project." },
                     alt: { type: "string", description: "Alt text for the markdown image link (optional)" },
                 },
-                required: ["filename", "filePath", "project"],
+                required: ["filename", "file_path", "project"],
             },
         },
         {

package/dist/src/tools/git-diff-doc.js

@@ -46,31 +46,53 @@ function getLocalGitDiff(tracked, project) {
  * Diffs tracked files against the branch they are tracked on, using the commit each snapshot
  * was taken at as the base.
  *
+ * A snapshot with no recorded commit — taken before branch tracking, or from a local working copy —
+ * is anchored on the newest commit at or before its date instead, so it diffs like any other rather
+ * than demanding a refresh first.
+ *
  * Files are grouped by that base commit so one comparison covers every file snapshotted at the
  * same revision — which, for a doc refreshed in one go, means a single API call.
  */
 async function getGitHubDiffs(api, trackedFiles) {
     const diffs = new Map();
     const byBase = new Map();
+    const inferredBases = new Set();
     for (const tracked of trackedFiles) {
-        if (!tracked.sourceRevision) {
-            diffs.set(tracked.path, `  [INFO] No source commit recorded for "${tracked.path}" — this snapshot predates branch tracking, or was taken from a local working copy.\n` +
-                `  → Call refresh_file_snapshot to re-anchor it on ${api.label}, after which diffs become available.`);
-            continue;
+        let base = tracked.sourceRevision;
+        if (!base) {
+            try {
+                base = await api.resolveCommitAtDate(tracked.lastModifiedAt);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                diffs.set(tracked.path, `  [ERROR] No source commit recorded, and the commit at the snapshot date (${tracked.lastModifiedAt}) could not be resolved on ${api.label}: ${message}`);
+                continue;
+            }
+            if (!base) {
+                diffs.set(tracked.path, `  [INFO] No source commit recorded, and ${api.label} has no commit at or before the snapshot date (${tracked.lastModifiedAt}) — nothing to diff against.\n` +
+                    `  → Call refresh_file_snapshot to re-anchor this file on ${api.label}.`);
+                continue;
+            }
+            inferredBases.add(base);
         }
-        const group = byBase.get(tracked.sourceRevision);
+        const group = byBase.get(base);
         if (group)
             group.push(tracked);
         else
-            byBase.set(tracked.sourceRevision, [tracked]);
+            byBase.set(base, [tracked]);
     }
     if (byBase.size === 0)
         return diffs;
     const { commitSha: head } = await api.resolveRef();
     for (const [base, files] of byBase) {
+        // An inferred base is the branch state at the snapshot date, not a commit the snapshot was
+        // provably read from — worth saying, since the diff can then include changes already documented.
+        const note = inferredBases.has(base)
+            ? `  [INFO] Base commit ${base.slice(0, 7)} inferred from the snapshot date (no source commit recorded).\n\n`
+            : "";
         if (base === head) {
             for (const file of files) {
-                diffs.set(file.path, `  [INFO] ${api.label} is still at the snapshot commit ${base.slice(0, 7)} — no changes.`);
+                diffs.set(file.path, `${note}  [INFO] ${api.label} is still at the snapshot commit ${base.slice(0, 7)} — no changes.`);
             }
             continue;
         }
@@ -81,12 +103,12 @@ async function getGitHubDiffs(api, trackedFiles) {
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             for (const file of files)
-                diffs.set(file.path, `  [ERROR] Could not compare ${base.slice(0, 7)}...${head.slice(0, 7)}: ${message}`);
+                diffs.set(file.path, `${note}  [ERROR] Could not compare ${base.slice(0, 7)}...${head.slice(0, 7)}: ${message}`);
             continue;
         }
         for (const file of files) {
             const patch = patches.get(file.path);
-            diffs.set(file.path, patch ?? `  [INFO] No changes to this file between ${base.slice(0, 7)} and ${head.slice(0, 7)}.`);
+            diffs.set(file.path, note + (patch ?? `  [INFO] No changes to this file between ${base.slice(0, 7)} and ${head.slice(0, 7)}.`));
         }
     }
     return diffs;

package/dist/src/tools/upload-image.js

@@ -3,7 +3,9 @@ import path from "path";
 import { z } from "zod";
 const UploadImageArgsSchema = z.object({
     filename: z.string().min(1),
-    filePath: z.string(),
+    file_path: z.string().optional(),
+    file_content: z.string().optional(),
+    file_name: z.string().optional(),
     project: z
         .string()
         .min(1)
@@ -35,16 +37,29 @@ export async function uploadImage(storageEngine, args) {
                 content: [{ type: "text", text: `Project "${project}" does not exist. Known projects: ${knownProjects.join(", ")}.` }],
             };
         }
-        if (!fs.existsSync(validated.filePath)) {
-            return {
-                isError: true,
-                content: [{ type: "text", text: `File not found: ${validated.filePath}` }],
-            };
+        // Le relais du gateway a posé le contenu : il a lu le fichier sur la machine de
+        // l'agent, dont ce serveur ne voit pas le disque. Sans contenu, les deux machines
+        // n'en font qu'une et on lit le chemin directement.
+        let data;
+        if (validated.file_content) {
+            data = Buffer.from(validated.file_content.replace(/^data:[^;,]*;base64,/, ""), "base64");
+        }
+        else {
+            if (!validated.file_path) {
+                return { isError: true, content: [{ type: "text", text: "file_path is required." }] };
+            }
+            if (!fs.existsSync(validated.file_path)) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `File not found: ${validated.file_path}` }],
+                };
+            }
+            data = fs.readFileSync(validated.file_path);
         }
         const assetsDir = path.join(storageEngine.getDataDir(), "projects", project, "assets");
         fs.mkdirSync(assetsDir, { recursive: true });
         const finalName = resolveFilename(assetsDir, validated.filename);
-        fs.copyFileSync(validated.filePath, path.join(assetsDir, finalName));
+        fs.writeFileSync(path.join(assetsDir, finalName), data);
         const url = `/api/images/${encodeURIComponent(project)}/${encodeURIComponent(finalName)}`;
         const alt = validated.alt ?? "";
         const markdownLink = `![${alt}](${url})`;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.80";
+export declare const APP_VERSION = "1.0.82";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated version file - do not edit manually
-export const APP_VERSION = '1.0.80';
+export const APP_VERSION = '1.0.82';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-documentor",
-  "version": "1.0.80",
+  "version": "1.0.82",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",

package/gui/README.md

@@ -1,75 +0,0 @@
-# React + TypeScript + Vite
-
-This app is the browser UI for MCP Documentor. Shared MCP/proxy helpers live in the Node package `@imenam/mcp-gui-interface` (used from the repo root server and `gui-worker`, not from this Vite bundle).
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## React Compiler
-
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
-
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```