@imenam/mcp-documentor 1.0.85 → 1.0.86

package/dist/src/index.js

@@ -20,7 +20,12 @@ import { searchDocs } from "./tools/search-docs.js";
 import { checkFreshness, computeFreshness, DOC_CONCURRENCY } from "./tools/check-freshness.js";
 import { mapWithConcurrency } from "./core/concurrency.js";
 import { findAndHashSection } from "./core/section-tracker.js";
-import { getCodeSource } from "./core/code-source.js";
+import { getCodeSource, invalidateCodeSources, setCodeSourceProvider } from "./core/code-source.js";
+import { readCodeSourceConfig } from "./core/project-settings.js";
+import { LocalState } from "./core/local-state.js";
+import { migrateCodeSources } from "./core/migrate-code-sources.js";
+import { setCodeRootProvider } from "./core/path-resolver.js";
+import { getCodeSourceTool, getGitHubTokenStatus, GITHUB_TOKEN_VAR, inspectCodeRoot, inspectRepository, listCodeSources, previewCodeSource, saveCodeSource, searchRepositoriesForInput, setCodeRoot, setCodeRootTool, setCodeSourceTool, } from "./tools/code-sources.js";
 import { runInCodeOperation } from "./core/code-operation.js";
 import { listProjects } from "./tools/list-projects.js";
 import { refreshFileSnapshot } from "./tools/refresh-file-snapshot.js";
@@ -98,6 +103,12 @@ const historyStore = new HistoryStore();
 historyStore.init(storageEngine.getDataDir());
 storageEngine.setHistoryStore(historyStore);
 const syncEngine = new SyncEngine(storageEngine);
+const localState = new LocalState(storageEngine.getDataDir());
+setCodeRootProvider((project) => localState.getCodeRoot(project));
+setCodeSourceProvider({
+    codeSourceConfig: (project) => readCodeSourceConfig(storageEngine.getProjectDir(project)),
+    githubToken: () => process.env[GITHUB_TOKEN_VAR]?.trim() || undefined,
+});
 const server = new Server({ name: "mcp-documentor", version: APP_VERSION }, { capabilities: { tools: {} } });
 let guiLauncher;
 let guiStatus = "disabled";
@@ -189,6 +200,44 @@ function dispatchIPCMessage(msg) {
     else if (msg.type === "SYNC_DOCS") {
         handleSyncDocsIPC(msg);
     }
+    else if (msg.type === "LIST_CODE_SOURCES") {
+        replyToGUI(msg, "LIST_CODE_SOURCES_RESPONSE", async () => ({ projects: await listCodeSources(storageEngine, localState) }));
+    }
+    else if (msg.type === "INSPECT_REPOSITORY") {
+        replyToGUI(msg, "INSPECT_REPOSITORY_RESPONSE", () => inspectRepository(msg.data ?? {}));
+    }
+    else if (msg.type === "SEARCH_REPOSITORIES") {
+        replyToGUI(msg, "SEARCH_REPOSITORIES_RESPONSE", async () => ({
+            results: await searchRepositoriesForInput(String(msg.data?.query ?? "")),
+        }));
+    }
+    else if (msg.type === "INSPECT_CODE_ROOT") {
+        replyToGUI(msg, "INSPECT_CODE_ROOT_RESPONSE", () => inspectCodeRoot(String(msg.data?.path ?? "")));
+    }
+    else if (msg.type === "PREVIEW_CODE_SOURCE") {
+        replyToGUI(msg, "PREVIEW_CODE_SOURCE_RESPONSE", () => previewCodeSource(storageEngine, localState, requireProjectFromIPC(msg), msg.data?.config, msg.data?.codeRoot));
+    }
+    else if (msg.type === "SAVE_CODE_SOURCE") {
+        handleSaveCodeSource(msg);
+    }
+    else if (msg.type === "GET_CODE_ROOTS") {
+        replyToGUI(msg, "GET_CODE_ROOTS_RESPONSE", () => localState.getCodeRoots());
+    }
+    else if (msg.type === "SET_CODE_ROOT") {
+        handleSetCodeRoot(msg);
+    }
+    else if (msg.type === "GET_GITHUB_TOKEN") {
+        replyToGUI(msg, "GET_GITHUB_TOKEN_RESPONSE", () => getGitHubTokenStatus());
+    }
+    else if (msg.type === "GET_CODE_SOURCE_MIGRATION") {
+        replyToGUI(msg, "GET_CODE_SOURCE_MIGRATION_RESPONSE", () => ({ report: localState.getMigrationReport() ?? null }));
+    }
+    else if (msg.type === "ACK_CODE_SOURCE_MIGRATION") {
+        replyToGUI(msg, "ACK_CODE_SOURCE_MIGRATION_RESPONSE", () => {
+            localState.markMigrationReportSeen();
+            return { success: true };
+        });
+    }
     else {
         logger.debug(`Unhandled message from GUI: ${msg.type}`);
     }
@@ -203,6 +252,54 @@ function requireProjectFromIPC(msg) {
         throw new Error("project is required for this operation");
     return project;
 }
+/** Answers a GUI request with what `compute` returns, or with the error it throws. */
+async function replyToGUI(msg, type, compute) {
+    try {
+        const data = await compute();
+        broadcastToGUI({ type, correlationId: msg.correlationId, data, timestamp: new Date().toISOString() });
+    }
+    catch (err) {
+        broadcastToGUI({ type, correlationId: msg.correlationId, error: err.message, timestamp: new Date().toISOString() });
+    }
+}
+/** Tells every connected GUI that code sources changed, so selectors and freshness are re-read. */
+function broadcastCodeSourcesChanged(project) {
+    broadcastToGUI({
+        type: "CODE_SOURCES_CHANGED",
+        data: { project: project ?? null },
+        timestamp: new Date().toISOString(),
+    });
+}
+function handleSaveCodeSource(msg) {
+    if (isReadOnly()) {
+        replyToGUI(msg, "SAVE_CODE_SOURCE_RESPONSE", () => {
+            throw new Error("READ_ONLY mode: configuration changes disabled");
+        });
+        return;
+    }
+    return replyToGUI(msg, "SAVE_CODE_SOURCE_RESPONSE", () => {
+        const project = requireProjectFromIPC(msg);
+        const config = saveCodeSource(storageEngine, localState, project, msg.data?.config, msg.data?.codeRoot);
+        logger.info(`Code source of project "${project}" set to ${getCodeSource(project).label}`);
+        broadcastCodeSourcesChanged(project);
+        return { config };
+    });
+}
+/** Sets the machine default code root, or a project's own when the message names one. */
+function handleSetCodeRoot(msg) {
+    if (isReadOnly()) {
+        replyToGUI(msg, "SET_CODE_ROOT_RESPONSE", () => {
+            throw new Error("READ_ONLY mode: configuration changes disabled");
+        });
+        return;
+    }
+    return replyToGUI(msg, "SET_CODE_ROOT_RESPONSE", () => {
+        const project = msg.data?.project || undefined;
+        const root = setCodeRoot(storageEngine, localState, String(msg.data?.path ?? ""), project);
+        broadcastCodeSourcesChanged(project);
+        return { path: root ?? null };
+    });
+}
 /** Loads one project's summaries and flags each entry as stale/broken. */
 async function listDocsWithFreshness(project) {
     const listings = await storageEngine.listDocsDetailed(project);
@@ -245,6 +342,7 @@ async function handleGetInitialState(msg) {
                 bundles,
                 readOnly: isReadOnly(),
                 syncEnabled: syncEngine.isConfigured(),
+                codeSourceMigrationPending: localState.getMigrationReport()?.seen === false,
             },
             timestamp: new Date().toISOString(),
         });
@@ -684,9 +782,9 @@ async function handleSyncDocsIPC(msg) {
     }
     try {
         // Reuse the tool so the GUI and the agent get identical pull/push semantics.
-        const result = await syncDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore, {
+        const result = afterSync(await syncDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore, {
             message: msg.data?.message,
-        });
+        }));
         const text = result.content.map((c) => c.text).join("\n");
         if (result.isError) {
             broadcastToGUI({
@@ -1370,6 +1468,42 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 required: ["path", "decisions"],
             },
         },
+        {
+            name: "get_code_source",
+            description: "Show where each project's source code is read from when checking freshness: its local working copy or one branch of a GitHub repository, and the code root that applies on this machine. GitHub sources are checked against their branch, and a project whose repository or branch cannot be found is flagged.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: { type: "string", description: "Project to show (defaults to every project)" },
+                },
+            },
+        },
+        {
+            name: "set_code_source",
+            description: "Set where a project's source code is read from: 'local' (the working copy on this machine, under its code root) or 'github' (one branch of a repository, read over the GitHub API). The repository and branch are checked before saving. The setting is stored with the docs, so every machine reads the same source after a sync. The GitHub token is not settable here: it is read from the MCP_DOCUMENTOR_CODE_TOKEN environment variable only.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: { type: "string", description: "Project to configure. REQUIRED." },
+                    kind: { type: "string", enum: ["local", "github"], description: "'local' reads the working copy, 'github' reads a repository branch" },
+                    repo: { type: "string", description: "Repository when kind is 'github': 'owner/repo' or a GitHub URL" },
+                    branch: { type: "string", description: "Branch when kind is 'github' (defaults to the repository's default branch)" },
+                },
+                required: ["project", "kind"],
+            },
+        },
+        {
+            name: "set_code_root",
+            description: "Set the code root on THIS machine: the folder tracked-file paths are stored relative to, and that the local working copy is read from. With a project, sets that project's own root; without, sets the machine default used by every project that has none. An empty path removes the root (a project then uses the machine default). The folder must exist. Code roots are machine-local and never synced.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Absolute path of the folder, or an empty string to remove the root" },
+                    project: { type: "string", description: "Project whose own root is set (omit to set the machine default)" },
+                },
+                required: ["path"],
+            },
+        },
         {
             name: "reconnect_gui",
             description: "Relaunch the GUI worker and re-register it with the proxy server. Use this when the proxy server was not running when the MCP server started (so the GUI registration failed), to redeploy the GUI without restarting the MCP server. Does nothing if the GUI is already registered, unless force=true.",
@@ -1479,19 +1613,31 @@ async function handleToolCall(request) {
             case "sync_status":
                 return await syncStatus(syncEngine);
             case "pull_docs":
-                return await pullDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore);
+                return afterSync(await pullDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore));
             case "push_docs":
                 return await pushDocs(syncEngine, args);
             case "sync_docs":
-                return await syncDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore, args);
+                return afterSync(await syncDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore, args));
             case "resolve_sync_conflict":
-                return await resolveSyncConflict(syncEngine, args);
+                return afterSync(await resolveSyncConflict(syncEngine, args));
             case "list_conflicts":
                 return await listConflicts(syncEngine);
             case "get_conflict_hunks":
                 return await getConflictHunks(syncEngine, args);
             case "resolve_conflict_hunks":
-                return await resolveConflictHunks(syncEngine, args);
+                return afterSync(await resolveConflictHunks(syncEngine, args));
+            case "get_code_source":
+                return await getCodeSourceTool(storageEngine, localState, args);
+            case "set_code_source": {
+                const result = await setCodeSourceTool(storageEngine, localState, args);
+                broadcastCodeSourcesChanged(args?.project);
+                return result;
+            }
+            case "set_code_root": {
+                const result = setCodeRootTool(storageEngine, localState, args);
+                broadcastCodeSourcesChanged(args?.project);
+                return result;
+            }
             case "reconnect_gui":
                 return await reconnectGui(args);
             default:
@@ -1505,6 +1651,12 @@ async function handleToolCall(request) {
         };
     }
 }
+/** A sync can bring other machines' project settings: code sources are re-read on next use. */
+function afterSync(result) {
+    invalidateCodeSources();
+    broadcastCodeSourcesChanged();
+    return result;
+}
 async function syncPullOnStartup() {
     if (!syncEngine.isConfigured())
         return;
@@ -1533,6 +1685,7 @@ async function main() {
     await migrateFolders(storageEngine);
     await migrateEmbeddings(embeddingStore, storageEngine);
     await syncPullOnStartup();
+    migrateCodeSources(storageEngine, localState);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     logger.info("MCP Server connected and running on stdio");

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

@@ -1,12 +1,13 @@
 import type { TrackedFile, FreshnessReport } from "../../shared/schemas/doc.schema.js";
 import type { StorageEngine } from "../core/storage-engine.js";
+import { type CodeSource } from "../core/code-source.js";
 /**
  * Docs checked at once during a whole-project scan. With FILE_CONCURRENCY this caps in-flight
  * source reads at 32 — enough to hide network latency on a 160-doc project, far below anything
  * GitHub objects to.
  */
 export declare const DOC_CONCURRENCY = 8;
-export declare function computeFreshness(trackedFiles: TrackedFile[], project: string): Promise<FreshnessReport>;
+export declare function computeFreshness(trackedFiles: TrackedFile[], project: string, source?: CodeSource): Promise<FreshnessReport>;
 export declare function formatFreshnessReport(title: string, report: FreshnessReport): string;
 export declare function checkFreshness(storageEngine: StorageEngine, args: unknown): Promise<{
     content: {

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

@@ -48,8 +48,7 @@ async function checkTrackedFile(tracked, source) {
         return { kind: "source_error", message: err instanceof Error ? err.message : String(err) };
     }
 }
-export async function computeFreshness(trackedFiles, project) {
-    const source = getCodeSource(project);
+export async function computeFreshness(trackedFiles, project, source = getCodeSource(project)) {
     const empty = { modified: [], missing: [], unchanged: [], anchors_lost: [], broken: [], source: source.label };
     if (!trackedFiles || trackedFiles.length === 0) {
         return { status: "no_tracking", ...empty, total: 0 };

package/dist/src/tools/code-sources.d.ts

@@ -0,0 +1,102 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+import type { LocalState } from "../core/local-state.js";
+import { type BranchHead, type RepositoryInfo, type RepositorySearchResult } from "../core/github-code-api.js";
+import { type CodeSourceConfig } from "../core/project-settings.js";
+/** The only variable the GitHub token is read from. It is never stored nor settable elsewhere. */
+export declare const GITHUB_TOKEN_VAR = "MCP_DOCUMENTOR_CODE_TOKEN";
+/** One project as the project selector shows it. */
+export interface ProjectCodeSource {
+    project: string;
+    /** Undefined when the project's settings cannot be read — `error` then says why. */
+    config?: CodeSourceConfig;
+    /** The code root that applies to the project on this machine. */
+    codeRoot?: string;
+    /** Whether that root is the project's own, or the machine default. */
+    codeRootOrigin?: "project" | "default";
+    /** The machine default root, shown as what an empty project root falls back to. */
+    defaultCodeRoot?: string;
+    /** Why the source cannot be read right now: unreadable settings, unknown repository or branch… */
+    error?: string;
+}
+/** Every project's code source and code root, with GitHub ones checked against their branch. */
+export declare function listCodeSources(storageEngine: StorageEngine, localState: LocalState): Promise<ProjectCodeSource[]>;
+export type RepositoryInspection = {
+    ok: true;
+    repo: RepositoryInfo;
+    branches: string[];
+    branch: string;
+    head: BranchHead;
+} | {
+    ok: false;
+    field: "repo" | "branch";
+    error: string;
+    repo?: RepositoryInfo;
+    branches?: string[];
+};
+/**
+ * Checks a repository: whether it exists for the configured token, its branches, and the commit
+ * the chosen branch — or the default one — points at.
+ */
+export declare function inspectRepository(input: {
+    repo: string;
+    branch?: string;
+}): Promise<RepositoryInspection>;
+/** Repositories matching what is typed in the repository field — empty below two characters. */
+export declare function searchRepositoriesForInput(term: string): Promise<RepositorySearchResult[]>;
+/** Checks that a code root is an existing folder given as an absolute path. */
+export declare function inspectCodeRoot(root: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** How the project's docs would read against a code source that is not saved yet. */
+export interface CodeSourcePreview {
+    label: string;
+    docs: number;
+    upToDate: number;
+    stale: number;
+    unverifiable: number;
+    broken: number;
+    /** Set when the source itself could not be consulted. */
+    sourceError?: string;
+}
+export declare function previewCodeSource(storageEngine: StorageEngine, localState: LocalState, project: string, rawConfig: unknown, codeRoot?: string): Promise<CodeSourcePreview>;
+/**
+ * Sets a code root on this machine: the project's own one, or the machine default when `project`
+ * is undefined. An empty root removes it — a project then uses the default.
+ */
+export declare function setCodeRoot(storageEngine: StorageEngine, localState: LocalState, root: string, project?: string): string | undefined;
+/**
+ * Saves a project's code source and, when `codeRoot` is given, its code root on this machine (see
+ * `setCodeRoot`). The next operation on that project reads them.
+ */
+export declare function saveCodeSource(storageEngine: StorageEngine, localState: LocalState, project: string, rawConfig: unknown, codeRoot?: string): CodeSourceConfig;
+export interface GitHubTokenStatus {
+    /** The variable the token is read from. */
+    variable: string;
+    configured: boolean;
+    /** Account the token belongs to. */
+    login?: string;
+    /** Why the token was rejected. */
+    error?: string;
+}
+export declare function getGitHubTokenStatus(): Promise<GitHubTokenStatus>;
+export declare function getCodeSourceTool(storageEngine: StorageEngine, localState: LocalState, args: unknown): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;
+export declare function setCodeSourceTool(storageEngine: StorageEngine, localState: LocalState, args: unknown): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;
+export declare function setCodeRootTool(storageEngine: StorageEngine, localState: LocalState, args: unknown): {
+    content: {
+        type: string;
+        text: string;
+    }[];
+};

package/dist/src/tools/code-sources.js

@@ -0,0 +1,260 @@
+import fs from "fs";
+import path from "path";
+import { mapWithConcurrency } from "../core/concurrency.js";
+import { createCodeSource, getGitHubApi, getGitHubToken, invalidateCodeSources } from "../core/code-source.js";
+import { getBranchHead, getRepositoryInfo, getTokenLogin, GitHubApiError, listBranches, parseRepoSpec, searchRepositories, } from "../core/github-code-api.js";
+import { CodeSourceConfigSchema, readCodeSourceConfig, writeCodeSourceConfig, } from "../core/project-settings.js";
+import { computeFreshness, DOC_CONCURRENCY } from "./check-freshness.js";
+/** The only variable the GitHub token is read from. It is never stored nor settable elsewhere. */
+export const GITHUB_TOKEN_VAR = "MCP_DOCUMENTOR_CODE_TOKEN";
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+function assertKnownProject(storageEngine, project) {
+    if (!storageEngine.getConfig().projects.includes(project)) {
+        throw new Error(`Project "${project}" does not exist.`);
+    }
+}
+function describeRoot(localState, project) {
+    const roots = localState.getCodeRoots();
+    const own = roots.byProject[project];
+    if (own !== undefined)
+        return { codeRoot: own, codeRootOrigin: "project", defaultCodeRoot: roots.default };
+    if (roots.default !== undefined)
+        return { codeRoot: roots.default, codeRootOrigin: "default", defaultCodeRoot: roots.default };
+    return {};
+}
+/**
+ * Turns a failed branch lookup into what the user has to fix: the branch when the repository
+ * answers, the repository otherwise. Other failures (network, rate limit) keep their message.
+ */
+async function describeUnreachableSource(config, err) {
+    if (!(err instanceof GitHubApiError) || (err.status !== 404 && err.status !== 422))
+        return errorMessage(err);
+    const [owner, repo] = config.repo.split("/");
+    try {
+        const info = await getRepositoryInfo(owner, repo, getGitHubToken());
+        return `Branch “${config.branch ?? info.defaultBranch}” not found — freshness unavailable`;
+    }
+    catch {
+        return `Repository ${config.repo} not found, or not visible with ${GITHUB_TOKEN_VAR}`;
+    }
+}
+/** Every project's code source and code root, with GitHub ones checked against their branch. */
+export async function listCodeSources(storageEngine, localState) {
+    const projects = storageEngine.getConfig().projects;
+    return mapWithConcurrency(projects, DOC_CONCURRENCY, async (project) => {
+        const root = describeRoot(localState, project);
+        let config;
+        try {
+            config = readCodeSourceConfig(storageEngine.getProjectDir(project));
+        }
+        catch (err) {
+            return { project, ...root, error: errorMessage(err) };
+        }
+        if (config.kind === "local")
+            return { project, config, ...root };
+        try {
+            await getGitHubApi(project)?.resolveRef();
+            return { project, config, ...root };
+        }
+        catch (err) {
+            return { project, config, ...root, error: await describeUnreachableSource(config, err) };
+        }
+    });
+}
+/**
+ * Checks a repository: whether it exists for the configured token, its branches, and the commit
+ * the chosen branch — or the default one — points at.
+ */
+export async function inspectRepository(input) {
+    let owner;
+    let name;
+    let suffixBranch;
+    try {
+        ({ owner, repo: name, ref: suffixBranch } = parseRepoSpec(input.repo));
+    }
+    catch (err) {
+        return { ok: false, field: "repo", error: errorMessage(err) };
+    }
+    const token = getGitHubToken();
+    let repo;
+    let branches;
+    try {
+        [repo, branches] = await Promise.all([getRepositoryInfo(owner, name, token), listBranches(owner, name, token)]);
+    }
+    catch (err) {
+        return { ok: false, field: "repo", error: errorMessage(err) };
+    }
+    const branch = input.branch || suffixBranch || repo.defaultBranch;
+    try {
+        const head = await getBranchHead(owner, name, branch, token);
+        return { ok: true, repo, branches, branch, head };
+    }
+    catch (err) {
+        const missing = err instanceof GitHubApiError && (err.status === 404 || err.status === 422);
+        const error = missing ? `Branch “${branch}” does not exist in ${repo.fullName}` : errorMessage(err);
+        return { ok: false, field: "branch", error, repo, branches };
+    }
+}
+/** Suggestions shown while a repository is typed. */
+const SEARCH_LIMIT = 8;
+/** Repositories matching what is typed in the repository field — empty below two characters. */
+export async function searchRepositoriesForInput(term) {
+    const trimmed = term.trim().replace(/^https?:\/\/github\.com\//i, "").replace(/\.git$/i, "");
+    if (trimmed.replace("/", "").length < 2)
+        return [];
+    return searchRepositories(trimmed, getGitHubToken(), SEARCH_LIMIT);
+}
+/** Checks that a code root is an existing folder given as an absolute path. */
+export function inspectCodeRoot(root) {
+    if (!path.isAbsolute(root))
+        return { ok: false, error: "Expected an absolute path" };
+    try {
+        if (!fs.statSync(root).isDirectory())
+            return { ok: false, error: "Not a folder" };
+    }
+    catch {
+        return { ok: false, error: "Folder not found on this machine" };
+    }
+    return { ok: true };
+}
+/**
+ * The root a project would use with `codeRoot`: undefined keeps the current one, an empty string
+ * means the machine default, anything else is the project's own root.
+ */
+function rootFor(localState, project, codeRoot) {
+    if (codeRoot === undefined)
+        return localState.getCodeRoot(project);
+    return codeRoot.trim() === "" ? localState.getCodeRoots().default : codeRoot.trim();
+}
+export async function previewCodeSource(storageEngine, localState, project, rawConfig, codeRoot) {
+    assertKnownProject(storageEngine, project);
+    const config = CodeSourceConfigSchema.parse(rawConfig);
+    const source = createCodeSource(project, config, { root: rootFor(localState, project, codeRoot) });
+    const listings = (await storageEngine.listDocsDetailed(project)).filter((l) => l.tracked_files.length > 0);
+    const preview = { label: source.label, docs: listings.length, upToDate: 0, stale: 0, unverifiable: 0, broken: 0 };
+    const reports = await mapWithConcurrency(listings, DOC_CONCURRENCY, (listing) => computeFreshness(listing.tracked_files, project, source));
+    for (const report of reports) {
+        if (report.sourceError)
+            preview.sourceError = report.sourceError;
+        if (report.status === "up_to_date")
+            preview.upToDate++;
+        else if (report.status === "stale")
+            preview.stale++;
+        else if (report.status === "broken")
+            preview.broken++;
+        else if (report.status === "unverifiable")
+            preview.unverifiable++;
+    }
+    return preview;
+}
+/**
+ * Sets a code root on this machine: the project's own one, or the machine default when `project`
+ * is undefined. An empty root removes it — a project then uses the default.
+ */
+export function setCodeRoot(storageEngine, localState, root, project) {
+    const trimmed = root.trim();
+    if (trimmed !== "") {
+        const check = inspectCodeRoot(trimmed);
+        if (!check.ok)
+            throw new Error(`Invalid code root "${trimmed}": ${check.error}`);
+    }
+    const value = trimmed === "" ? undefined : path.resolve(trimmed);
+    if (project === undefined) {
+        localState.setDefaultCodeRoot(value);
+        invalidateCodeSources();
+    }
+    else {
+        assertKnownProject(storageEngine, project);
+        localState.setProjectCodeRoot(project, value);
+        invalidateCodeSources(project);
+    }
+    return value;
+}
+/**
+ * Saves a project's code source and, when `codeRoot` is given, its code root on this machine (see
+ * `setCodeRoot`). The next operation on that project reads them.
+ */
+export function saveCodeSource(storageEngine, localState, project, rawConfig, codeRoot) {
+    assertKnownProject(storageEngine, project);
+    const config = CodeSourceConfigSchema.parse(rawConfig);
+    if (codeRoot !== undefined)
+        setCodeRoot(storageEngine, localState, codeRoot, project);
+    writeCodeSourceConfig(storageEngine.getProjectDir(project), config);
+    invalidateCodeSources(project);
+    return config;
+}
+export async function getGitHubTokenStatus() {
+    const token = getGitHubToken();
+    if (!token)
+        return { variable: GITHUB_TOKEN_VAR, configured: false };
+    try {
+        return { variable: GITHUB_TOKEN_VAR, configured: true, login: await getTokenLogin(token) };
+    }
+    catch (err) {
+        return { variable: GITHUB_TOKEN_VAR, configured: true, error: errorMessage(err) };
+    }
+}
+// --- Agent tools ---
+function describeSourceLine(source) {
+    const config = source.config;
+    const head = !config
+        ? "settings unreadable"
+        : config.kind === "github"
+            ? `GitHub ${config.repo} · ${config.branch ?? "default branch"}`
+            : "local working copy";
+    const root = source.codeRoot
+        ? `code root ${source.codeRoot} (${source.codeRootOrigin === "project" ? "project setting" : "machine default"})`
+        : "no code root on this machine";
+    const status = source.error ? ` — ⚠ ${source.error}` : "";
+    return `- **${source.project}**: ${head}; ${root}${status}`;
+}
+export async function getCodeSourceTool(storageEngine, localState, args) {
+    const project = args?.project;
+    if (project)
+        assertKnownProject(storageEngine, project);
+    const all = await listCodeSources(storageEngine, localState);
+    const shown = project ? all.filter((s) => s.project === project) : all;
+    const defaultRoot = localState.getCodeRoots().default;
+    const token = getGitHubToken() ? `${GITHUB_TOKEN_VAR} is set` : `${GITHUB_TOKEN_VAR} is not set (public repositories only)`;
+    const text = `Code sources${project ? ` — project "${project}"` : ""}:\n\n${shown.map(describeSourceLine).join("\n")}\n\n` +
+        `Machine default code root: ${defaultRoot ?? "none"}. GitHub token: ${token}.\n` +
+        `The code source is shared by every machine (synced with the docs); code roots belong to this machine.`;
+    return { content: [{ type: "text", text }] };
+}
+export async function setCodeSourceTool(storageEngine, localState, args) {
+    const { project, kind, repo, branch } = (args ?? {});
+    if (!project)
+        throw new Error("project is required");
+    assertKnownProject(storageEngine, project);
+    let config;
+    if (kind === "local") {
+        config = { kind: "local" };
+    }
+    else if (kind === "github") {
+        if (!repo)
+            throw new Error('repo is required when kind is "github"');
+        const inspection = await inspectRepository({ repo, branch });
+        if (!inspection.ok)
+            throw new Error(inspection.error);
+        config = { kind: "github", repo: inspection.repo.fullName, ...(branch && { branch: inspection.branch }) };
+    }
+    else {
+        throw new Error('kind must be "local" or "github"');
+    }
+    saveCodeSource(storageEngine, localState, project, config);
+    const where = config.kind === "github" ? `GitHub ${config.repo} · ${config.branch ?? "default branch"}` : "its local working copy";
+    return { content: [{ type: "text", text: `Project "${project}" now reads its code from ${where}.` }] };
+}
+export function setCodeRootTool(storageEngine, localState, args) {
+    const { path: root, project } = (args ?? {});
+    if (root === undefined)
+        throw new Error("path is required (an empty string removes the root)");
+    const value = setCodeRoot(storageEngine, localState, root, project);
+    const target = project ? `project "${project}"` : "this machine (default)";
+    const text = value
+        ? `Code root of ${target} set to ${value}.`
+        : project
+            ? `Project "${project}" now uses the machine default code root (${localState.getCodeRoots().default ?? "none"}).`
+            : "Default code root removed on this machine.";
+    return { content: [{ type: "text", text }] };
+}

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.85";
+export declare const APP_VERSION: string;

package/dist/src/version.js

@@ -1,2 +1,16 @@
-// Auto-generated version file - do not edit manually
-export const APP_VERSION = '1.0.85';
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// Lit la version dans le premier package.json trouvé en remontant depuis ce module.
+function readPackageVersion() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    while (!existsSync(path.join(dir, "package.json"))) {
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            throw new Error("package.json introuvable");
+        dir = parent;
+    }
+    const pkg = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8"));
+    return pkg.version;
+}
+export const APP_VERSION = readPackageVersion();