@imenam/mcp-documentor 1.0.66 → 1.0.68

package/dist/src/index.js

@@ -8,6 +8,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { APP_VERSION } from "./version.js";
 import { GuiLauncher, createLogger, setupLogging } from "@imenam/mcp-gui-interface";
+import { resolveLogDir } from "./core/log-dir.js";
 import { StorageEngine } from "./core/storage-engine.js";
 import { EmbeddingStore } from "./core/embedding-store.js";
 import { EmbeddingEngine } from "./core/embedding-engine.js";
@@ -45,6 +46,12 @@ import { syncStatus, pullDocs, pushDocs, syncDocs, resolveSyncConflict } from ".
 import { isReadOnly, WRITE_TOOLS } from "../shared/read-only.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+// Les flags CLI sont traités avant toute initialisation (storage, sqlite, logs) :
+// ils s'exécutent dans le répertoire de l'utilisateur, pas dans un serveur MCP.
+if (process.argv.slice(2).includes("--claude-setup-mcp")) {
+    const { runSetupMcp } = await import("./cli/setup-mcp.js");
+    process.exit(runSetupMcp({ cwd: process.cwd(), force: process.argv.slice(2).includes("--force") }));
+}
 function findProjectRoot(startDir) {
     let current = startDir;
     while (current !== path.dirname(current)) {
@@ -57,7 +64,7 @@ function findProjectRoot(startDir) {
 }
 const rootDir = findProjectRoot(__dirname);
 const packageEnvPath = path.join(rootDir, ".env");
-setupLogging({ processLabel: "mcp-documentor", logDir: path.join(rootDir, ".docs-data", "logs") });
+setupLogging({ processLabel: "mcp-documentor", logDir: resolveLogDir(rootDir) });
 const logger = createLogger("mcp-documentor");
 function getConfig() {
     if (fs.existsSync(packageEnvPath)) {
@@ -154,6 +161,9 @@ function handleIPCMessage(msg) {
     else if (msg.type === "UPDATE_DOC") {
         handleUpdateDocIPC(msg);
     }
+    else if (msg.type === "DELETE_DOC") {
+        handleDeleteDocIPC(msg);
+    }
     else if (msg.type === "GET_FILE_SECTION") {
         handleGetFileSection(msg);
     }
@@ -161,6 +171,16 @@ function handleIPCMessage(msg) {
         logger.debug(`Unhandled message from GUI: ${msg.type}`);
     }
 }
+/**
+ * GUI requests that target a specific doc must name their project: the GUI can be
+ * showing project A while an agent switches the server's active project to B.
+ */
+function requireProjectFromIPC(msg) {
+    const project = msg.data?.project;
+    if (!project)
+        throw new Error("project is required for this operation");
+    return project;
+}
 async function handleGetInitialState(msg) {
     try {
         const config = storageEngine.getConfig();
@@ -272,12 +292,13 @@ async function handleListDocs(msg) {
 }
 async function handleGetDoc(msg) {
     try {
-        const resolved = await storageEngine.resolveDoc(msg.data.id ?? msg.data.path);
+        const project = requireProjectFromIPC(msg);
+        const doc = await storageEngine.getDoc(msg.data.id ?? msg.data.path, project);
         broadcastToGUI({
             type: "GET_DOC_RESPONSE",
             correlationId: msg.correlationId,
-            data: resolved ? { doc: resolved.doc } : null,
-            error: resolved ? undefined : "Doc not found",
+            data: doc ? { doc } : null,
+            error: doc ? undefined : `Doc not found in project "${project}"`,
             timestamp: new Date().toISOString(),
         });
     }
@@ -330,15 +351,16 @@ async function handleCreateDocIPC(msg) {
         return;
     }
     try {
-        const { title, content, folder, tags, project } = msg.data ?? {};
+        const { title, content, folder, tags } = msg.data ?? {};
         if (!title || !content)
             throw new Error("title and content are required");
+        const project = requireProjectFromIPC(msg);
         const result = await createDoc(storageEngine, embeddingEngine, {
             title,
             content,
+            project,
             ...(folder && { folder }),
             ...(tags && { tags }),
-            ...(project && { project }),
         });
         if (result.isError) {
             const text = result.content[0]?.type === "text" ? result.content[0].text : "Create failed";
@@ -396,6 +418,7 @@ async function handleUpdateDocIPC(msg) {
     try {
         const result = await updateDoc(storageEngine, embeddingEngine, {
             path: msg.data.id,
+            project: requireProjectFromIPC(msg),
             content: msg.data.content,
             ...(msg.data.title !== undefined && { title: msg.data.title }),
         });
@@ -426,16 +449,72 @@ async function handleUpdateDocIPC(msg) {
         });
     }
 }
+async function handleDeleteDocIPC(msg) {
+    if (isReadOnly()) {
+        broadcastToGUI({
+            type: "DELETE_DOC_RESPONSE",
+            correlationId: msg.correlationId,
+            error: "READ_ONLY mode: deletion disabled",
+            timestamp: new Date().toISOString(),
+        });
+        return;
+    }
+    try {
+        const project = requireProjectFromIPC(msg);
+        const result = await deleteDoc(storageEngine, embeddingEngine, { path: msg.data.id, project });
+        if (result.isError) {
+            const text = result.content[0]?.type === "text" ? result.content[0].text : "Delete failed";
+            broadcastToGUI({
+                type: "DELETE_DOC_RESPONSE",
+                correlationId: msg.correlationId,
+                error: text,
+                timestamp: new Date().toISOString(),
+            });
+            return;
+        }
+        const message = result.content[0]?.type === "text" ? result.content[0].text : undefined;
+        broadcastToGUI({
+            type: "DELETE_DOC_RESPONSE",
+            correlationId: msg.correlationId,
+            data: { success: true, message },
+            timestamp: new Date().toISOString(),
+        });
+        const config = storageEngine.getConfig();
+        const docs = await storageEngine.listDocs();
+        for (const doc of docs) {
+            const full = await storageEngine.getDoc(doc.id);
+            if (full && full.tracked_files.length > 0) {
+                const report = computeFreshness(full.tracked_files, config.currentProject);
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
+            }
+        }
+        broadcastToGUI({
+            type: "INITIAL_STATE",
+            data: { config, docs, projects: config.projects },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        broadcastToGUI({
+            type: "DELETE_DOC_RESPONSE",
+            correlationId: msg.correlationId,
+            error: err.message,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
 async function handleGetFileSection(msg) {
     try {
         const { docId, filePath } = msg.data;
-        const resolved = await storageEngine.resolveDoc(docId);
-        if (!resolved)
-            throw new Error("Doc not found");
-        const trackedFile = resolved.doc.tracked_files.find((f) => f.path === filePath);
+        const project = requireProjectFromIPC(msg);
+        const doc = await storageEngine.getDoc(docId, project);
+        if (!doc)
+            throw new Error(`Doc not found in project "${project}"`);
+        const trackedFile = doc.tracked_files.find((f) => f.path === filePath);
         if (!trackedFile || !trackedFile.sections?.length)
             throw new Error("No sections for this file");
-        const absolutePath = toAbsolutePath(trackedFile.path, resolved.project);
+        const absolutePath = toAbsolutePath(trackedFile.path, project);
         if (!absolutePath)
             throw new Error("Cannot resolve file on this machine (no code root configured)");
         const fileLines = fs.readFileSync(absolutePath, "utf-8").split("\n");
@@ -468,18 +547,18 @@ async function handleGetFileSection(msg) {
 }
 async function handleCheckFreshness(msg) {
     try {
-        const resolved = await storageEngine.resolveDoc(msg.data.id ?? msg.data.path);
-        const doc = resolved?.doc;
+        const project = requireProjectFromIPC(msg);
+        const doc = await storageEngine.getDoc(msg.data.id ?? msg.data.path, project);
         if (!doc) {
             broadcastToGUI({
                 type: "CHECK_FRESHNESS_RESPONSE",
                 correlationId: msg.correlationId,
-                error: "Doc not found",
+                error: `Doc not found in project "${project}"`,
                 timestamp: new Date().toISOString(),
             });
             return;
         }
-        const report = computeFreshness(doc.tracked_files, resolved.project);
+        const report = computeFreshness(doc.tracked_files, project);
         broadcastToGUI({
             type: "CHECK_FRESHNESS_RESPONSE",
             correlationId: msg.correlationId,
@@ -536,7 +615,10 @@ async function handleSearchDocs(msg) {
 }
 async function handleGitDiff(msg) {
     try {
-        const result = await gitDiffDoc(storageEngine, { paths: [msg.data.id ?? msg.data.path] });
+        const result = await gitDiffDoc(storageEngine, {
+            paths: [msg.data.id ?? msg.data.path],
+            project: requireProjectFromIPC(msg),
+        });
         const text = result.content[0]?.text ?? "";
         broadcastToGUI({
             type: "GIT_DIFF_RESPONSE",
@@ -599,8 +681,7 @@ async function handleUpdateConfig(msg) {
 async function handleGetDocHistory(msg) {
     try {
         const id = msg.data?.id ?? msg.data?.path;
-        const config = storageEngine.getConfig();
-        const project = msg.data?.project ?? config.currentProject;
+        const project = requireProjectFromIPC(msg);
         const versions = historyStore.listVersions(project, id);
         broadcastToGUI({
             type: "GET_DOC_HISTORY_RESPONSE",
@@ -622,8 +703,7 @@ async function handleGetDocVersionIPC(msg) {
     try {
         const id = msg.data?.id ?? msg.data?.path;
         const version = msg.data?.version;
-        const config = storageEngine.getConfig();
-        const project = msg.data?.project ?? config.currentProject;
+        const project = requireProjectFromIPC(msg);
         const entry = historyStore.getVersion(project, id, version);
         broadcastToGUI({
             type: "GET_DOC_VERSION_RESPONSE",
@@ -711,11 +791,12 @@ async function reconnectGui(args) {
         };
     }
     return {
-        content: [{ type: "text", text: "GUI worker started but did not confirm proxy registration within 15s. Check the logs (.docs-data/logs), then retry." }],
+        content: [{ type: "text", text: `GUI worker started but did not confirm proxy registration within 15s. Check the logs (${resolveLogDir(rootDir)}), then retry.` }],
         isError: true,
     };
 }
 server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const PROJECT_PARAM_DESCRIPTION = "Project the documentation entry belongs to. REQUIRED — never guessed, and never defaulted to the current project. Use list_projects or get_doc_tree if you are unsure which project holds the entry.";
     const tools = [
         {
             name: "create_doc",
@@ -767,20 +848,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         items: { type: "string" },
                         description: "IDs of related documentation entries",
                     },
-                    project: { type: "string", description: "Project to create the doc in (defaults to current project if omitted). If the project name does not exist yet, it will be created automatically." },
+                    project: { type: "string", description: "Project to create the doc in. REQUIRED — never defaulted to the current project. If the project name does not exist yet, it will be created automatically." },
                 },
-                required: ["title"],
+                required: ["title", "project"],
             },
         },
         {
             name: "get_doc",
-            description: "Retrieve a documentation entry by its path, including full content, tracked files, and metadata.",
+            description: "Retrieve a documentation entry by its path, including full content, tracked files, and metadata. The project is required — lookups are never resolved across projects.",
             inputSchema: {
                 type: "object",
                 properties: {
                     path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication' or 'authentication' for root docs" },
+                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION },
                 },
-                required: ["path"],
+                required: ["path", "project"],
             },
         },
         {
@@ -846,8 +928,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         items: { type: "string" },
                         description: "Paths of related documentation entries (replaces existing), e.g. ['backend/auth/authentication']",
                     },
+                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION },
                 },
-                required: ["path"],
+                required: ["path", "project"],
             },
         },
         {
@@ -858,8 +941,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 properties: {
                     path: { type: "string", description: "Current path of the documentation entry, e.g. 'backend/authentication'" },
                     new_path: { type: "string", description: "New path for the documentation entry, e.g. 'backend/v2/authentication'. Can change folder, name, or both." },
+                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION + " The doc stays in this project — move_doc never moves an entry across projects." },
                 },
-                required: ["path", "new_path"],
+                required: ["path", "new_path", "project"],
             },
         },
         {
@@ -881,7 +965,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 type: "object",
                 properties: {
                     path: { type: "string", description: "Path of a single documentation entry to check, e.g. 'backend/auth/authentication'. If omitted, scans all docs in the project." },
-                    project: { type: "string", description: "Project to scan (scans all projects if omitted). Only used when path is omitted." },
+                    project: { type: "string", description: "Project to work in. REQUIRED whenever path is provided — the freshness of a single entry is never resolved across projects. When path is omitted, it selects the project to scan (all projects if omitted too)." },
                 },
                 required: [],
             },
@@ -921,8 +1005,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         items: { type: "string" },
                         description: "Specific tracked file paths to refresh (all tracked files if omitted)",
                     },
+                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION + " Every entry in paths must belong to it — call once per project otherwise." },
                 },
-                required: ["paths"],
+                required: ["paths", "project"],
             },
         },
         {
@@ -932,8 +1017,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 type: "object",
                 properties: {
                     path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
+                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION },
                 },
-                required: ["path"],
+                required: ["path", "project"],
             },
         },
         {
@@ -947,8 +1033,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     search_file: { type: "string", description: "Absolute path to a text file whose content will be used as the search text. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
                     replacement: { type: "string", description: "Text to replace it with. Supports [copy-from-codebase|/absolute/path/to/file.ts|startLine|endLine] — the tag is replaced at save time by a fenced code block, and the file+range is automatically added to tracked_files. IMPORTANT: always read the source file first to identify the exact line numbers before writing the tag." },
                     replacement_file: { type: "string", description: "Absolute path to a text file whose content will be used as the replacement. Use this to reuse a previously persisted draft (path is returned in the error message when a previous call failed)." },
+                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION },
                 },
-                required: ["path", "search"],
+                required: ["path", "search", "project"],
             },
         },
         {
@@ -967,8 +1054,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         items: { type: "string" },
                         description: "Specific tracked file paths to diff (all tracked files if omitted)",
                     },
+                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION + " Every entry in paths must belong to it — call once per project otherwise." },
                 },
-                required: ["paths"],
+                required: ["paths", "project"],
             },
         },
         {
@@ -984,13 +1072,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
             name: "delete_doc",
-            description: "Permanently delete a documentation entry. Works across all projects — no need to set the active project first.",
+            description: "Permanently delete a documentation entry from an explicitly named project. The project is MANDATORY: deletion is never resolved across projects, so an entry that exists under the same path in several projects can never be deleted by mistake. Use list_projects / get_doc_tree first if you are unsure which project holds the entry.",
             inputSchema: {
                 type: "object",
                 properties: {
                     path: { type: "string", description: "Path of the documentation entry to delete, e.g. 'backend/auth/authentication'" },
+                    project: {
+                        type: "string",
+                        description: "Project the documentation entry belongs to. Required — never guessed, and never defaulted to the current project.",
+                    },
                 },
-                required: ["path"],
+                required: ["path", "project"],
             },
         },
         {
@@ -1010,9 +1102,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 type: "object",
                 properties: {
                     path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
-                    project: { type: "string", description: "Project to look in (defaults to current project)" },
+                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION },
                 },
-                required: ["path"],
+                required: ["path", "project"],
             },
         },
         {
@@ -1023,9 +1115,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 properties: {
                     path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
                     version: { type: "number", description: "Version number to retrieve" },
-                    project: { type: "string", description: "Project to look in (defaults to current project)" },
+                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION },
                 },
-                required: ["path", "version"],
+                required: ["path", "version", "project"],
             },
         },
         {
@@ -1036,9 +1128,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 properties: {
                     path: { type: "string", description: "Path of the documentation entry, e.g. 'backend/auth/authentication'" },
                     version: { type: "number", description: "Version number to restore" },
-                    project: { type: "string", description: "Project to look in (defaults to current project)" },
+                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION },
                 },
-                required: ["path", "version"],
+                required: ["path", "version", "project"],
             },
         },
         {
@@ -1064,7 +1156,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     docs: {
                         type: "array",
                         items: { type: "string" },
-                        description: "Doc references to include: 'project:doc-id' for cross-project, or 'doc-id' for current project",
+                        description: "Doc references to include, each fully qualified as 'project:doc-id'. The project prefix is REQUIRED — a bare 'doc-id' is rejected so a bundle can never pick up another project's entry.",
                     },
                     description: { type: "string", description: "Short description of the bundle (optional)" },
                 },
@@ -1090,10 +1182,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 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" },
-                    project: { type: "string", description: "Target project (defaults to current project)" },
+                    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"],
+                required: ["filename", "filePath", "project"],
             },
         },
         {

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

@@ -4,15 +4,15 @@ export declare function computeFileHash(absolutePath: string): string;
 export declare function computeFreshness(trackedFiles: TrackedFile[], project: string): 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;
     }[];
+    isError?: undefined;
 } | {
+    isError: boolean;
     content: {
         type: string;
         text: string;
     }[];
-    isError?: undefined;
 }>;

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

@@ -3,6 +3,7 @@ import fs from "fs";
 import { CheckFreshnessArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { findAndHashSection } from "../core/section-tracker.js";
 import { toAbsolutePath } from "../core/path-resolver.js";
+import { resolveDocInProject, isScopeError, scopeErrorResult } from "../core/project-scope.js";
 export function computeFileHash(absolutePath) {
     return crypto.createHash("sha256").update(fs.readFileSync(absolutePath)).digest("hex");
 }
@@ -192,13 +193,13 @@ 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, project } = resolved;
-            const report = computeFreshness(doc.tracked_files, project);
-            return { content: [{ type: "text", text: formatFreshnessReport(doc.title, report) }] };
+            // The schema guarantees project is present alongside path.
+            const project = validated.project;
+            const resolved = await resolveDocInProject(storageEngine, validated.path, project, "freshness check");
+            if (isScopeError(resolved))
+                return scopeErrorResult(resolved);
+            const report = computeFreshness(resolved.doc.tracked_files, project);
+            return { content: [{ type: "text", text: formatFreshnessReport(resolved.doc.title, report) }] };
         }
         if (validated.project) {
             const scan = await scanProjectFreshness(storageEngine, validated.project);

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

@@ -13,7 +13,7 @@ export function slugify(title) {
 export async function createDoc(storageEngine, embeddingEngine, args) {
     try {
         const validated = CreateDocArgsSchema.parse(args);
-        const { project } = (args ?? {});
+        const { project } = validated;
         const rawContent = validated.content_file
             ? fs.readFileSync(validated.content_file, "utf-8")
             : validated.content;
@@ -25,13 +25,11 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
         if (existing) {
             return {
                 isError: true,
-                content: [{ type: "text", text: `A documentation entry with path "${id}" already exists. Use update_doc to modify it.` }],
+                content: [{ type: "text", text: `A documentation entry with path "${id}" already exists in project "${project}". Use update_doc to modify it.` }],
             };
         }
-        if (project) {
-            storageEngine.ensureProject(project);
-        }
-        const resolvedProject = project ?? storageEngine.getConfig().currentProject;
+        storageEngine.ensureProject(project);
+        const resolvedProject = project;
         const allTrackedInputs = [
             ...(validated.tracked_files ?? []),
             ...additionalTrackedFiles,

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

@@ -1,14 +1,21 @@
+import { DeleteDocArgsSchema } from "../../shared/schemas/doc.schema.js";
+import { resolveDocInProject, isScopeError, scopeErrorResult } from "../core/project-scope.js";
 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.` }] };
+        const { path: docPath, project } = DeleteDocArgsSchema.parse(args);
+        const resolved = await resolveDocInProject(storageEngine, docPath, project, "deletion");
+        if (isScopeError(resolved))
+            return scopeErrorResult(resolved);
+        const deleted = await storageEngine.deleteDoc(resolved.doc.id, project);
+        if (!deleted) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Failed to delete "${docPath}" from project "${project}".` }],
+            };
         }
-        await storageEngine.deleteDoc(resolved.doc.id, resolved.project);
-        await embeddingEngine.removeEmbedding(resolved.doc.id, resolved.project);
+        await embeddingEngine.removeEmbedding(resolved.doc.id, project);
         return {
-            content: [{ type: "text", text: `Documentation entry "${docPath}" deleted from project "${resolved.project}".` }],
+            content: [{ type: "text", text: `Documentation entry "${docPath}" deleted from project "${project}".` }],
         };
     }
     catch (err) {

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

@@ -1,14 +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;
     }[];
+    isError?: undefined;
 } | {
+    isError: boolean;
     content: {
         type: string;
         text: string;
     }[];
-    isError?: undefined;
 }>;

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

@@ -3,14 +3,15 @@ import { GetDocMetadataArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFreshness } from "./check-freshness.js";
 import { findAndHashSection } from "../core/section-tracker.js";
 import { toAbsolutePath } from "../core/path-resolver.js";
+import { resolveDocInProject, isScopeError, scopeErrorResult } from "../core/project-scope.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, project } = resolved;
+        const resolved = await resolveDocInProject(storageEngine, validated.path, validated.project, "lookup");
+        if (isScopeError(resolved))
+            return scopeErrorResult(resolved);
+        const { doc } = resolved;
+        const project = validated.project;
         const report = computeFreshness(doc.tracked_files, project);
         const fileStatusIcon = (filePath) => {
             if (report.broken.includes(filePath))

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

@@ -1,9 +1,12 @@
 import { GetDocVersionArgsSchema } from "../../shared/schemas/doc.schema.js";
+import { assertProject, scopeErrorResult } from "../core/project-scope.js";
 export async function getDocVersion(historyStore, storageEngine, args) {
     try {
         const validated = GetDocVersionArgsSchema.parse(args);
-        const config = storageEngine.getConfig();
-        const project = validated.project ?? config.currentProject;
+        const project = validated.project;
+        const projectError = assertProject(storageEngine, project);
+        if (projectError)
+            return scopeErrorResult(projectError);
         const entry = historyStore.getVersion(project, validated.path, validated.version);
         if (!entry) {
             return {

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

@@ -1,14 +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;
     }[];
+    isError?: undefined;
 } | {
+    isError: boolean;
     content: {
         type: string;
         text: string;
     }[];
-    isError?: undefined;
 }>;

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

@@ -3,14 +3,15 @@ import { GetDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFreshness } from "./check-freshness.js";
 import { findAndHashSection } from "../core/section-tracker.js";
 import { toAbsolutePath } from "../core/path-resolver.js";
+import { resolveDocInProject, isScopeError, scopeErrorResult } from "../core/project-scope.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 resolved = await resolveDocInProject(storageEngine, validated.path, validated.project, "lookup");
+        if (isScopeError(resolved))
+            return scopeErrorResult(resolved);
+        const { doc } = resolved;
+        const resolvedProject = validated.project;
         const trackedFilesText = doc.tracked_files.length > 0
             ? doc.tracked_files.map((f) => {
                 if (f.sections && f.sections.length > 0) {