@imenam/mcp-documentor 1.0.23

package/dist/src/tools/check-freshness.d.ts

@@ -0,0 +1,18 @@
+import type { TrackedFile, FreshnessReport } from "../../shared/schemas/doc.schema.js";
+import type { StorageEngine } from "../core/storage-engine.js";
+export declare function computeFileHash(absolutePath: string): string;
+export declare function computeFreshness(trackedFiles: TrackedFile[]): FreshnessReport;
+export declare function formatFreshnessReport(title: string, report: FreshnessReport): string;
+export declare function checkFreshness(storageEngine: StorageEngine, args: unknown): Promise<{
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/src/tools/check-freshness.js

@@ -0,0 +1,167 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { CheckFreshnessArgsSchema } from "../../shared/schemas/doc.schema.js";
+export function computeFileHash(absolutePath) {
+    return crypto.createHash("sha256").update(fs.readFileSync(absolutePath)).digest("hex");
+}
+export function computeFreshness(trackedFiles) {
+    if (!trackedFiles || trackedFiles.length === 0) {
+        return { status: "no_tracking", modified: [], missing: [], unchanged: [], total: 0 };
+    }
+    const modified = [];
+    const missing = [];
+    const unchanged = [];
+    for (const tracked of trackedFiles) {
+        const absolutePath = path.resolve(process.cwd(), tracked.path);
+        if (!fs.existsSync(absolutePath)) {
+            missing.push(tracked.path);
+            continue;
+        }
+        if (tracked.contentHash) {
+            const currentHash = computeFileHash(absolutePath);
+            if (currentHash !== tracked.contentHash) {
+                modified.push(tracked.path);
+            }
+            else {
+                unchanged.push(tracked.path);
+            }
+        }
+        else {
+            const currentMtime = fs.statSync(absolutePath).mtime.getTime();
+            const storedMtime = new Date(tracked.lastModifiedAt).getTime();
+            const STALENESS_TOLERANCE_MS = 2000;
+            if (currentMtime > storedMtime + STALENESS_TOLERANCE_MS) {
+                modified.push(tracked.path);
+            }
+            else {
+                unchanged.push(tracked.path);
+            }
+        }
+    }
+    const isStale = modified.length > 0 || missing.length > 0;
+    return {
+        status: isStale ? "stale" : "up_to_date",
+        modified,
+        missing,
+        unchanged,
+        total: trackedFiles.length,
+    };
+}
+export function formatFreshnessReport(title, report) {
+    if (report.status === "no_tracking") {
+        return `No tracked files for "${title}". Use tracked_files when creating or updating the doc to enable staleness detection.`;
+    }
+    let text = report.status === "stale"
+        ? `STALE: "${title}" — tracked files have changed since the documentation was last updated.\n`
+        : `UP TO DATE: "${title}" — no tracked files have been modified.\n`;
+    text += `\nSummary: ${report.modified.length} modified, ${report.missing.length} missing, ${report.unchanged.length} unchanged out of ${report.total} tracked file(s).`;
+    if (report.modified.length > 0) {
+        text += `\n\nModified files:\n${report.modified.map((f) => `  - ${f}`).join("\n")}`;
+    }
+    if (report.missing.length > 0) {
+        text += `\n\nMissing files:\n${report.missing.map((f) => `  - ${f}`).join("\n")}`;
+    }
+    return text;
+}
+export async function checkFreshness(storageEngine, args) {
+    try {
+        const validated = CheckFreshnessArgsSchema.parse(args);
+        if (validated.path) {
+            const resolved = await storageEngine.resolveDoc(validated.path);
+            if (!resolved) {
+                return { isError: true, content: [{ type: "text", text: `Documentation entry "${validated.path}" not found in any project.` }] };
+            }
+            const { doc } = resolved;
+            const report = computeFreshness(doc.tracked_files);
+            return { content: [{ type: "text", text: formatFreshnessReport(doc.title, report) }] };
+        }
+        if (validated.project) {
+            const summaries = await storageEngine.listDocs(validated.project);
+            if (summaries.length === 0) {
+                return { content: [{ type: "text", text: `No documentation entries found in project "${validated.project}".` }] };
+            }
+            const stale = [];
+            const noTracking = [];
+            let upToDate = 0;
+            for (const summary of summaries) {
+                const doc = await storageEngine.getDoc(summary.id, validated.project);
+                if (!doc)
+                    continue;
+                const report = computeFreshness(doc.tracked_files);
+                if (report.status === "no_tracking") {
+                    noTracking.push(doc.title);
+                }
+                else if (report.status === "stale") {
+                    const details = [
+                        ...report.modified.map((f) => `    • modified: ${f}`),
+                        ...report.missing.map((f) => `    • missing: ${f}`),
+                    ].join("\n");
+                    stale.push(`  - **${doc.title}** [${doc.id}]\n${details}`);
+                }
+                else {
+                    upToDate++;
+                }
+            }
+            let text = `# Freshness report — project "${validated.project}"\n\n`;
+            text += `${summaries.length} doc(s) scanned: **${stale.length} stale**, ${upToDate} up to date, ${noTracking.length} untracked.\n`;
+            if (stale.length > 0) {
+                text += `\n## Stale docs\n\n${stale.join("\n\n")}`;
+            }
+            if (noTracking.length > 0) {
+                text += `\n\n## Untracked docs (no staleness detection)\n${noTracking.map((t) => `  - ${t}`).join("\n")}`;
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        // No id, no project → scan all projects
+        const config = storageEngine.getConfig();
+        const allProjects = config.projects;
+        const projectBlocks = [];
+        let totalDocs = 0;
+        let totalStale = 0;
+        for (const proj of allProjects) {
+            const summaries = await storageEngine.listDocs(proj);
+            const stale = [];
+            const noTracking = [];
+            let upToDate = 0;
+            for (const summary of summaries) {
+                const doc = await storageEngine.getDoc(summary.id, proj);
+                if (!doc)
+                    continue;
+                const report = computeFreshness(doc.tracked_files);
+                if (report.status === "no_tracking") {
+                    noTracking.push(doc.title);
+                }
+                else if (report.status === "stale") {
+                    const details = [
+                        ...report.modified.map((f) => `    • modified: ${f}`),
+                        ...report.missing.map((f) => `    • missing: ${f}`),
+                    ].join("\n");
+                    stale.push(`  - **${doc.title}** [${doc.id}]\n${details}`);
+                }
+                else {
+                    upToDate++;
+                }
+            }
+            totalDocs += summaries.length;
+            totalStale += stale.length;
+            let block = `## ${proj}\n\n`;
+            block += `${summaries.length} doc(s): **${stale.length} stale**, ${upToDate} up to date, ${noTracking.length} untracked.`;
+            if (stale.length > 0) {
+                block += `\n\n### Stale docs\n\n${stale.join("\n\n")}`;
+            }
+            if (noTracking.length > 0) {
+                block += `\n\n### Untracked docs\n${noTracking.map((t) => `  - ${t}`).join("\n")}`;
+            }
+            projectBlocks.push(block);
+        }
+        let text = `# Freshness report — all projects (${allProjects.length})\n\n`;
+        text += `Total: ${totalDocs} doc(s) across all projects, **${totalStale} stale**.\n\n`;
+        text += projectBlocks.join("\n\n---\n\n");
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Error checking freshness: ${message}` }] };
+    }
+}

package/dist/src/tools/check-links.d.ts

@@ -0,0 +1,14 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+export declare function checkLinks(storageEngine: StorageEngine, args: unknown): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/src/tools/check-links.js

@@ -0,0 +1,99 @@
+import GithubSlugger from "github-slugger";
+import { CheckLinksArgsSchema } from "../../shared/schemas/doc.schema.js";
+function getValidAnchors(content) {
+    const slugger = new GithubSlugger();
+    const headingRegex = /^#{1,6}\s+(.+)$/gm;
+    const anchors = new Set();
+    let match;
+    while ((match = headingRegex.exec(content)) !== null) {
+        anchors.add(slugger.slug(match[1].trim()));
+    }
+    return anchors;
+}
+function extractAnchorLinks(content) {
+    const linkRegex = /\[[^\]]*\]\(#([^)]+)\)/g;
+    const anchors = [];
+    let match;
+    while ((match = linkRegex.exec(content)) !== null) {
+        anchors.push(match[1]);
+    }
+    return anchors;
+}
+function extractDocLinks(content) {
+    const linkRegex = /\[[^\]]*\]\(doc:\/\/([^)]+)\)/g;
+    const ids = [];
+    let match;
+    while ((match = linkRegex.exec(content)) !== null) {
+        ids.push(match[1]);
+    }
+    return ids;
+}
+export async function checkLinks(storageEngine, args) {
+    try {
+        const validated = CheckLinksArgsSchema.parse(args);
+        const config = storageEngine.getConfig();
+        const project = validated.project ?? config.currentProject;
+        const docs = await storageEngine.listDocs(project);
+        const validIds = new Set(docs.map((d) => d.id));
+        const brokenRefs = [];
+        const brokenDocLinks = [];
+        const brokenAnchors = [];
+        for (const summary of docs) {
+            const doc = await storageEngine.getDoc(summary.id, project);
+            if (!doc)
+                continue;
+            for (const ref of doc.related_docs ?? []) {
+                if (!validIds.has(ref)) {
+                    brokenRefs.push({ sourceId: summary.id, brokenId: ref });
+                }
+            }
+            for (const targetId of extractDocLinks(doc.content)) {
+                if (!validIds.has(targetId)) {
+                    brokenDocLinks.push({ sourceId: summary.id, targetId });
+                }
+            }
+            const anchorLinks = extractAnchorLinks(doc.content);
+            if (anchorLinks.length > 0) {
+                const validAnchors = getValidAnchors(doc.content);
+                for (const anchor of anchorLinks) {
+                    if (!validAnchors.has(anchor)) {
+                        brokenAnchors.push({ sourceId: summary.id, anchor });
+                    }
+                }
+            }
+        }
+        const totalBroken = brokenRefs.length + brokenDocLinks.length + brokenAnchors.length;
+        if (totalBroken === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `✓ No broken links found in project "${project}" (${docs.length} docs checked).`,
+                    },
+                ],
+            };
+        }
+        const lines = [];
+        for (const b of brokenRefs) {
+            lines.push(`  [related_doc] ${b.sourceId} → ${b.brokenId} (doc not found)`);
+        }
+        for (const b of brokenDocLinks) {
+            lines.push(`  [doc://]      ${b.sourceId} → doc://${b.targetId} (doc not found)`);
+        }
+        for (const b of brokenAnchors) {
+            lines.push(`  [anchor]      ${b.sourceId} → #${b.anchor} (heading not found)`);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Found ${totalBroken} broken link(s) in project "${project}" (${docs.length} docs checked):\n${lines.join("\n")}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Error checking links: ${message}` }] };
+    }
+}

package/dist/src/tools/create-doc.d.ts

@@ -0,0 +1,15 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+import type { EmbeddingEngine } from "../core/embedding-engine.js";
+export declare function createDoc(storageEngine: StorageEngine, embeddingEngine: EmbeddingEngine, args: unknown): Promise<{
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/src/tools/create-doc.js

@@ -0,0 +1,78 @@
+import fs from "fs";
+import path from "path";
+import { CreateDocArgsSchema } from "../../shared/schemas/doc.schema.js";
+import { computeFileHash } from "./check-freshness.js";
+function slugify(title) {
+    return title
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+function snapshotTrackedFiles(filePaths) {
+    const tracked = [];
+    for (const fp of filePaths) {
+        const absolutePath = path.resolve(process.cwd(), fp);
+        let mtime = new Date().toISOString();
+        let contentHash;
+        if (fs.existsSync(absolutePath)) {
+            mtime = fs.statSync(absolutePath).mtime.toISOString();
+            contentHash = computeFileHash(absolutePath);
+        }
+        tracked.push({ path: absolutePath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
+    }
+    return tracked;
+}
+export async function createDoc(storageEngine, embeddingEngine, args) {
+    try {
+        const validated = CreateDocArgsSchema.parse(args);
+        const { project } = (args ?? {});
+        const slug = slugify(validated.title);
+        const id = validated.folder ? `${validated.folder}/${slug}` : slug;
+        const now = new Date().toISOString();
+        const existing = await storageEngine.getDoc(id, project);
+        if (existing) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `A documentation entry with path "${id}" already exists. Use update_doc to modify it.` }],
+            };
+        }
+        if (project) {
+            storageEngine.ensureProject(project);
+        }
+        const trackedFiles = validated.tracked_files ? snapshotTrackedFiles(validated.tracked_files) : [];
+        const folder = validated.folder;
+        const doc = {
+            id,
+            title: validated.title,
+            content: validated.content,
+            tracked_files: trackedFiles,
+            tags: validated.tags ?? [],
+            folder,
+            related_docs: validated.related_docs ?? [],
+            createdAt: now,
+            updatedAt: now,
+        };
+        const resolvedProject = project ?? storageEngine.getConfig().currentProject;
+        await storageEngine.saveDoc(doc, resolvedProject);
+        if (embeddingEngine.isConfigured()) {
+            const embedding = await embeddingEngine.generateEmbedding(validated.content);
+            if (embedding) {
+                await embeddingEngine.saveEmbedding(id, embedding, resolvedProject);
+            }
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Documentation entry "${validated.title}" created successfully with path "${id}".\nFolder: ${validated.folder || "none"}\nTracked files: ${trackedFiles.length}\nTags: ${(validated.tags ?? []).join(", ") || "none"}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Error creating doc: ${message}` }] };
+    }
+}

package/dist/src/tools/delete-doc.d.ts

@@ -0,0 +1,15 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+import type { EmbeddingEngine } from "../core/embedding-engine.js";
+export declare function deleteDoc(storageEngine: StorageEngine, embeddingEngine: EmbeddingEngine, args: unknown): Promise<{
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/src/tools/delete-doc.js

@@ -0,0 +1,18 @@
+export async function deleteDoc(storageEngine, embeddingEngine, args) {
+    try {
+        const { path: docPath } = args;
+        const resolved = await storageEngine.resolveDoc(docPath);
+        if (!resolved) {
+            return { isError: true, content: [{ type: "text", text: `Documentation entry "${docPath}" not found in any project.` }] };
+        }
+        await storageEngine.deleteDoc(resolved.doc.id, resolved.project);
+        await embeddingEngine.removeEmbedding(resolved.doc.id, resolved.project);
+        return {
+            content: [{ type: "text", text: `Documentation entry "${docPath}" deleted from project "${resolved.project}".` }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Error deleting doc: ${message}` }] };
+    }
+}

package/dist/src/tools/get-doc-metadata.d.ts

@@ -0,0 +1,14 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+export declare function getDocMetadata(storageEngine: StorageEngine, args: unknown): Promise<{
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/src/tools/get-doc-metadata.js

@@ -0,0 +1,40 @@
+import { GetDocMetadataArgsSchema } from "../../shared/schemas/doc.schema.js";
+import { computeFreshness } from "./check-freshness.js";
+export async function getDocMetadata(storageEngine, args) {
+    try {
+        const validated = GetDocMetadataArgsSchema.parse(args);
+        const resolved = await storageEngine.resolveDoc(validated.path);
+        if (!resolved) {
+            return { isError: true, content: [{ type: "text", text: `Documentation entry "${validated.path}" not found in any project.` }] };
+        }
+        const { doc } = resolved;
+        const report = computeFreshness(doc.tracked_files);
+        const fileStatusIcon = (filePath) => {
+            if (report.modified.includes(filePath))
+                return "✗ modified";
+            if (report.missing.includes(filePath))
+                return "✗ missing";
+            return "✓ up to date";
+        };
+        let text = `**Path:** ${doc.id}\n`;
+        text += `**Title:** ${doc.title}\n`;
+        text += `**Tags:** ${doc.tags.length > 0 ? doc.tags.join(", ") : "none"}\n`;
+        text += `**Created:** ${doc.createdAt}\n`;
+        text += `**Updated:** ${doc.updatedAt}\n`;
+        text += `**Freshness:** ${report.status}\n`;
+        if (doc.tracked_files.length > 0) {
+            text += `\nTracked files (${doc.tracked_files.length} total):\n`;
+            text += doc.tracked_files
+                .map((f) => `  ${fileStatusIcon(f.path)} — ${f.path}\n  Snapshot: ${f.lastModifiedAt}`)
+                .join("\n");
+        }
+        else {
+            text += "\nNo tracked files.";
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Error getting metadata: ${message}` }] };
+    }
+}

package/dist/src/tools/get-doc-tree.d.ts

@@ -0,0 +1,14 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+export declare function getDocTree(storageEngine: StorageEngine, args?: unknown): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/src/tools/get-doc-tree.js

@@ -0,0 +1,64 @@
+function getOrCreateFolder(nodes, name, fullPath) {
+    const existing = nodes.find((n) => n.type === "folder" && n.name === name);
+    if (existing)
+        return existing;
+    const newFolder = { type: "folder", name, path: fullPath, children: [] };
+    nodes.push(newFolder);
+    return newFolder;
+}
+function insertDoc(roots, folderPath, title, id) {
+    if (!folderPath) {
+        roots.push({ type: "doc", title, id });
+        return;
+    }
+    const segments = folderPath.split("/");
+    let currentLevel = roots;
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        const fullPath = segments.slice(0, i + 1).join("/");
+        const folder = getOrCreateFolder(currentLevel, segment, fullPath);
+        currentLevel = folder.children;
+    }
+    currentLevel.push({ type: "doc", title, id });
+}
+function sortNodes(nodes) {
+    return [...nodes].sort((a, b) => {
+        if (a.type !== b.type)
+            return a.type === "folder" ? -1 : 1;
+        const nameA = a.type === "folder" ? a.name : a.title;
+        const nameB = b.type === "folder" ? b.name : b.title;
+        return nameA.localeCompare(nameB);
+    }).map((node) => node.type === "folder"
+        ? { ...node, children: sortNodes(node.children) }
+        : node);
+}
+function buildTree(summaries) {
+    const roots = [];
+    for (const s of summaries) {
+        insertDoc(roots, s.folder, s.title, s.id);
+    }
+    return sortNodes(roots);
+}
+export async function getDocTree(storageEngine, args) {
+    try {
+        const { project } = (args ?? {});
+        const config = storageEngine.getConfig();
+        const projectsToList = project ? [project] : config.projects;
+        const result = [];
+        for (const proj of projectsToList) {
+            const summaries = await storageEngine.listDocs(proj);
+            result.push({
+                project: proj,
+                doc_count: summaries.length,
+                tree: buildTree(summaries),
+            });
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Error building doc tree: ${message}` }] };
+    }
+}

package/dist/src/tools/get-doc.d.ts

@@ -0,0 +1,14 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+export declare function getDoc(storageEngine: StorageEngine, args: unknown): Promise<{
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/src/tools/get-doc.js

@@ -0,0 +1,55 @@
+import { GetDocArgsSchema } from "../../shared/schemas/doc.schema.js";
+import { computeFreshness } from "./check-freshness.js";
+export async function getDoc(storageEngine, args) {
+    try {
+        const validated = GetDocArgsSchema.parse(args);
+        const resolved = await storageEngine.resolveDoc(validated.path);
+        if (!resolved) {
+            return { isError: true, content: [{ type: "text", text: `Documentation entry "${validated.path}" not found in any project.` }] };
+        }
+        const { doc, project: resolvedProject } = resolved;
+        const trackedFilesText = doc.tracked_files.length > 0
+            ? doc.tracked_files.map((f) => `  - ${f.path} (snapshot: ${f.lastModifiedAt})`).join("\n")
+            : "  (none)";
+        const freshnessReport = computeFreshness(doc.tracked_files);
+        const stalenessBanner = freshnessReport.status === "stale"
+            ? [
+                `> [!WARNING]`,
+                `> **Cette documentation est potentiellement obsolète.**`,
+                `> Les fichiers suivants ont été modifiés depuis la dernière mise à jour de ce document :`,
+                ...[
+                    ...freshnessReport.modified.map((f) => `> - \`${f}\` *(modifié)*`),
+                    ...freshnessReport.missing.map((f) => `> - \`${f}\` *(introuvable)*`),
+                ],
+                `>`,
+                `> Vérifiez si le contenu ci-dessous est toujours valide. Si nécessaire, utilisez \`git_diff_doc\` pour voir les changements, puis mettez à jour la documentation avec \`patch_doc\` ou \`update_doc\`.`,
+                ``,
+            ].join("\n")
+            : "";
+        const text = [
+            stalenessBanner,
+            `# ${doc.title}`,
+            ``,
+            `**ID:** ${doc.id}`,
+            `**Project:** ${resolvedProject}`,
+            `**Tags:** ${doc.tags.join(", ") || "none"}`,
+            `**Created:** ${doc.createdAt}`,
+            `**Updated:** ${doc.updatedAt}`,
+            ``,
+            `## Tracked Files`,
+            trackedFilesText,
+            ``,
+            `## Content`,
+            ``,
+            doc.content,
+            ``,
+            `---`,
+            `> **Agent instruction:** To modify this document, ALWAYS prefer \`patch_doc\` (targeted search-and-replace) over \`update_doc\` (full rewrite). Only use \`update_doc\` when the changes are so extensive that a patch is impractical. Using \`patch_doc\` preserves document integrity and avoids accidental data loss.`,
+        ].join("\n");
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Error getting doc: ${message}` }] };
+    }
+}

package/dist/src/tools/git-diff-doc.d.ts

@@ -0,0 +1,14 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+export declare function gitDiffDoc(storageEngine: StorageEngine, args: unknown): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;