@imenam/mcp-documentor 1.0.84 → 1.0.86

package/dist/shared/read-only.js

@@ -11,4 +11,5 @@ export const WRITE_TOOLS = new Set([
     // Sync: pull_docs and sync_status stay allowed (read-only consumer machines
     // still pull updates); these mutate local/remote state and are blocked.
     "push_docs", "sync_docs", "resolve_sync_conflict",
+    "set_code_source", "set_code_root",
 ]);

package/dist/src/cli/setup-mcp.js

@@ -58,7 +58,7 @@ const GENERATED_VARS = [
     ["APP_PATH", "chemin de montage de la GUI derrière le proxy"],
     ["MCP_DATA_DIR", "répertoire de données (défaut : celui du package)"],
     ["MCP_LOG_DIR", "répertoire des logs"],
-    ["MCP_DOCUMENTOR_CODE_ROOT", "racine du code (pré-remplie avec le répertoire courant)"],
+    ["MCP_DOCUMENTOR_CODE_ROOT", "racine du code par défaut (pré-remplie avec le répertoire courant), reprise au premier démarrage puis réglable dans la GUI"],
     ["MCP_DOCUMENTOR_OPENAI_API_KEY", "clé OpenAI (active search_docs)"],
     ["MCP_DOCUMENTOR_OPENAI_MODEL", "modèle d'embedding"],
     ["MCP_DOCUMENTOR_SYNC_REMOTE", "URL HTTPS du repo privé de sync GitHub"],
@@ -66,10 +66,7 @@ const GENERATED_VARS = [
     ["MCP_DOCUMENTOR_SYNC_TOKEN", "PAT GitHub fine-grained pour la sync"],
 ];
 const OPTIONAL_VARS = [
-    ["MCP_DOCUMENTOR_CODE_ROOTS", 'code roots par projet, ex: {"my-proj":"/srv/my-proj"}'],
-    ["MCP_DOCUMENTOR_CODE_REPO", 'repo GitHub suivi au lieu de la copie locale : "owner/repo#main", ou une map JSON par projet {"my-proj":"owner/repo#main","legacy":"local"}'],
-    ["MCP_DOCUMENTOR_CODE_BRANCH", "branche suivie quand le repo n'a pas de suffixe #branche"],
-    ["MCP_DOCUMENTOR_CODE_TOKEN", "PAT GitHub pour lire le code (défaut : MCP_DOCUMENTOR_SYNC_TOKEN)"],
+    ["MCP_DOCUMENTOR_CODE_TOKEN", "PAT GitHub pour lire le code des projets suivis sur GitHub (réglable uniquement ici)"],
     ["READ_ONLY", "1/true pour désactiver toutes les écritures"],
     ["SYNC_PULL_ON_START", "false pour désactiver le pull au démarrage"],
 ];

package/dist/src/core/code-source.d.ts

@@ -1,31 +1,23 @@
 import type { TrackedSection } from "../../shared/schemas/doc.schema.js";
 import { type FileContent } from "./section-tracker.js";
-import { GitHubCodeApi } from "./github-code-api.js";
+import { GitHubCodeApi, type RepoSpec } from "./github-code-api.js";
+import type { CodeSourceConfig } from "./project-settings.js";
 /**
  * Where a project's source code is read from when checking or snapshotting documentation.
  *
  * Two backends:
  *
- *  - **local** — the working copy on this machine, resolved through the code roots. This is the
- *    original behaviour and stays the default: it sees uncommitted work, and it sees whichever
- *    branch happens to be checked out.
+ *  - **local** — the working copy on this machine, resolved through the code roots. It sees
+ *    uncommitted work, and whichever branch happens to be checked out.
  *  - **github** — one branch of one repository, read over the GitHub API. The documentation then
- *    tracks *published* code: switching branches locally, or editing without committing, no longer
- *    makes docs look stale, and a server that has no copy of the codebase at all (an MCP gateway)
+ *    tracks *published* code: switching branches locally, or editing without committing, does not
+ *    make docs look stale, and a server that has no copy of the codebase at all (an MCP gateway)
  *    can still verify freshness.
  *
- * A project uses the GitHub backend only when a repository is configured for it. With no
- * repository set, everything behaves exactly as before.
- *
- *   MCP_DOCUMENTOR_CODE_REPO      the repository to read code from, in either of two shapes:
- *                                 a single spec — "owner/repo", a GitHub URL, with an optional
- *                                 "#branch" suffix — applied to every project, or a JSON map of
- *                                 per-project specs, e.g.
- *                                 {"web":"Imena/web#main","legacy":"local"}
- *                                 — the value "local" opts a project back out to its working copy
- *   MCP_DOCUMENTOR_CODE_BRANCH    branch used when a repository carries no "#branch" suffix
- *                                 (default: the repository's own default branch)
- *   MCP_DOCUMENTOR_CODE_TOKEN     GitHub token; falls back to MCP_DOCUMENTOR_SYNC_TOKEN
+ * Each project's choice is read from its settings (see `project-settings`) and the GitHub token
+ * from the machine-local state, both through the provider installed with `setCodeSourceProvider`.
+ * Sources are memoised per project; `invalidateCodeSources` drops them when a setting changes, so
+ * the next operation reads the new configuration.
  */
 /** One file as it exists at the source. */
 export interface SourceFile {
@@ -38,7 +30,7 @@ export interface SourceFile {
     blobId?: string;
 }
 export interface CodeSource {
-    readonly kind: "local" | "github";
+    readonly kind: "local" | "github" | "unavailable";
     /** Short description of where this source reads from, for reports and error messages. */
     readonly label: string;
     /**
@@ -56,9 +48,28 @@ export interface CodeSource {
     /** Converts a path supplied by an agent into the portable form persisted in a doc. */
     toStoredPath(inputPath: string): Promise<string>;
 }
-/** Test-only / config-reload: drops the memoised environment snapshot and every cached source. */
-export declare function resetCodeSourceCache(): void;
-/** The code source a project reads from. Memoised — the configuration is environment-fixed. */
+/** Where the code sources read their configuration. */
+export interface CodeSourceProvider {
+    /** The project's code source setting. Throws when the settings cannot be read. */
+    codeSourceConfig(project: string): CodeSourceConfig;
+    /** The GitHub token used to read repositories, if one is set. */
+    githubToken(): string | undefined;
+}
+export declare function setCodeSourceProvider(value: CodeSourceProvider): void;
+/** The GitHub token used to read repositories, if one is set. */
+export declare function getGitHubToken(): string | undefined;
+/** Drops the memoised source of one project, or of every project and every GitHub client. */
+export declare function invalidateCodeSources(project?: string): void;
+/** The GitHub repository spec a configuration reads, or undefined for the local working copy. */
+export declare function toRepoSpec(config: CodeSourceConfig): RepoSpec | undefined;
+/**
+ * Builds the source a configuration describes, without memoising it. Used to preview a setting
+ * before it is saved; `codeRoot` then pins the root a local source resolves paths against.
+ */
+export declare function createCodeSource(project: string, config: CodeSourceConfig, codeRoot?: {
+    root: string | undefined;
+}): CodeSource;
+/** The code source a project reads from. Memoised until `invalidateCodeSources`. */
 export declare function getCodeSource(project: string): CodeSource;
 /**
  * Where each tracked section of a file currently sits, as 1-indexed line ranges — `undefined`

package/dist/src/core/code-source.js

@@ -2,21 +2,30 @@ import fs from "fs";
 import path from "path";
 import { createLogger } from "@imenam/mcp-gui-interface";
 import { bytesToFileContent, findAndHashSection } from "./section-tracker.js";
-import { getCodeRoot, toAbsolutePath, toStoredPath as toStoredPathLocal } from "./path-resolver.js";
-import { GitHubCodeApi, parseRepoSpec, formatRepoSpec } from "./github-code-api.js";
+import { getCodeRoot, resolveAgainstRoot, toStoredPath as toStoredPathLocal } from "./path-resolver.js";
+import { GitHubCodeApi, formatRepoSpec } from "./github-code-api.js";
 const logger = createLogger("CodeSource");
 class LocalCodeSource {
     project;
+    fixedRoot;
     kind = "local";
-    constructor(project) {
+    /**
+     * `fixedRoot` pins the code root instead of reading the project's current one — used to preview
+     * a root before it is saved.
+     */
+    constructor(project, fixedRoot) {
         this.project = project;
+        this.fixedRoot = fixedRoot;
+    }
+    get root() {
+        return this.fixedRoot ? this.fixedRoot.root : getCodeRoot(this.project);
     }
     get label() {
-        const root = getCodeRoot(this.project);
+        const root = this.root;
         return root ? `local working copy (${root})` : "local working copy";
     }
     async read(storedPath) {
-        const absolutePath = toAbsolutePath(storedPath, this.project);
+        const absolutePath = resolveAgainstRoot(storedPath, this.root);
         if (!absolutePath || !fs.existsSync(absolutePath))
             return undefined;
         return {
@@ -31,10 +40,10 @@ class LocalCodeSource {
     async toStoredPath(inputPath) {
         // A relative input means "relative to the project's code root" — the same convention used
         // when a stored path is read back. Never the server's cwd.
-        const absolute = toAbsolutePath(inputPath, this.project);
+        const absolute = resolveAgainstRoot(inputPath, this.root);
         if (!absolute) {
-            throw new Error(`the path is relative but no code root is configured for project "${this.project}". ` +
-                `Provide an absolute path or set MCP_DOCUMENTOR_CODE_ROOT.`);
+            throw new Error(`the path is relative but no code root is set for project "${this.project}" on this machine. ` +
+                `Provide an absolute path, or set a code root with set_code_root or in the project settings.`);
         }
         return toStoredPathLocal(absolute, this.project);
     }
@@ -80,7 +89,7 @@ class GitHubCodeSource {
         if (!repoPath) {
             throw new Error(`Cannot map "${inputPath}" to a path inside ${this.api.label}. ` +
                 `Provide the path relative to the repository root, or set a code root for project "${this.project}" ` +
-                `(MCP_DOCUMENTOR_CODE_ROOT / MCP_DOCUMENTOR_CODE_ROOTS) so absolute paths can be stripped down to it.`);
+                `(set_code_root, or the project settings) so absolute paths can be stripped down to it.`);
         }
         return repoPath;
     }
@@ -124,81 +133,95 @@ class GitHubCodeSource {
         return best;
     }
 }
-let settings;
-const sourcesByProject = new Map();
-const apisByRepo = new Map();
-function loadSettings() {
-    if (settings)
-        return settings;
-    // One setting, two shapes. A repository is not a shared parent the way a code root is — it
-    // names exactly one codebase — so an instance serving several projects needs one spec per
-    // project, while a single-project or monorepo instance needs just the spec. A leading "{"
-    // tells the two apart unambiguously, since no repository spec starts with one.
-    const raw = process.env.MCP_DOCUMENTOR_CODE_REPO?.trim() || undefined;
-    const byProject = {};
-    let defaultSpec;
-    if (raw?.startsWith("{")) {
-        try {
-            const parsed = JSON.parse(raw);
-            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                for (const [proj, spec] of Object.entries(parsed)) {
-                    if (typeof spec === "string" && spec.trim() !== "")
-                        byProject[proj] = spec.trim();
-                }
-            }
-            else {
-                logger.warn("MCP_DOCUMENTOR_CODE_REPO is not a JSON object, ignoring it");
-            }
-        }
-        catch {
-            logger.warn("MCP_DOCUMENTOR_CODE_REPO looks like a JSON map but could not be parsed, ignoring it");
-        }
+/**
+ * A project whose settings cannot be read. Every access fails with the reason, so freshness
+ * reports the project as unverifiable and names what to fix.
+ */
+class UnavailableCodeSource {
+    reason;
+    kind = "unavailable";
+    constructor(reason) {
+        this.reason = reason;
+    }
+    get label() {
+        return "unavailable code source";
+    }
+    async read() {
+        throw new Error(this.reason);
+    }
+    async contentId() {
+        throw new Error(this.reason);
     }
-    else {
-        defaultSpec = raw;
+    async toStoredPath() {
+        throw new Error(this.reason);
     }
-    settings = {
-        defaultSpec,
-        byProject,
-        defaultBranch: process.env.MCP_DOCUMENTOR_CODE_BRANCH?.trim() || undefined,
-        token: process.env.MCP_DOCUMENTOR_CODE_TOKEN?.trim() || process.env.MCP_DOCUMENTOR_SYNC_TOKEN?.trim() || undefined,
-    };
-    return settings;
 }
-/** Test-only / config-reload: drops the memoised environment snapshot and every cached source. */
-export function resetCodeSourceCache() {
-    settings = undefined;
+let provider;
+const sourcesByProject = new Map();
+const apisByRepo = new Map();
+export function setCodeSourceProvider(value) {
+    provider = value;
+    invalidateCodeSources();
+}
+function requireProvider() {
+    if (!provider)
+        throw new Error("code sources are read before setCodeSourceProvider was called");
+    return provider;
+}
+/** The GitHub token used to read repositories, if one is set. */
+export function getGitHubToken() {
+    return requireProvider().githubToken();
+}
+/** Drops the memoised source of one project, or of every project and every GitHub client. */
+export function invalidateCodeSources(project) {
+    if (project !== undefined) {
+        sourcesByProject.delete(project);
+        return;
+    }
     sourcesByProject.clear();
     apisByRepo.clear();
 }
-function buildSource(project) {
-    const config = loadSettings();
-    const raw = config.byProject[project] ?? config.defaultSpec;
-    if (!raw || raw.toLowerCase() === "local")
-        return new LocalCodeSource(project);
-    let spec;
-    try {
-        spec = parseRepoSpec(raw);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        logger.warn(`Code repository for project "${project}" is unusable, falling back to the local working copy: ${message}`);
-        return new LocalCodeSource(project);
-    }
-    if (!spec.ref && config.defaultBranch)
-        spec = { ...spec, ref: config.defaultBranch };
+/** The GitHub repository spec a configuration reads, or undefined for the local working copy. */
+export function toRepoSpec(config) {
+    if (config.kind !== "github")
+        return undefined;
+    const [owner, repo] = config.repo.split("/");
+    return { owner, repo, ref: config.branch };
+}
+/**
+ * Builds the source a configuration describes, without memoising it. Used to preview a setting
+ * before it is saved; `codeRoot` then pins the root a local source resolves paths against.
+ */
+export function createCodeSource(project, config, codeRoot) {
+    const spec = toRepoSpec(config);
+    if (!spec)
+        return new LocalCodeSource(project, codeRoot);
     // One API client per (repo, ref): its tree and blob caches are then shared by every project
     // pointing at the same branch.
     const key = formatRepoSpec(spec);
     let api = apisByRepo.get(key);
     if (!api) {
-        api = new GitHubCodeApi(spec, config.token);
+        api = new GitHubCodeApi(spec, requireProvider().githubToken());
         apisByRepo.set(key, api);
-        logger.info(`Project "${project}" reads its code from GitHub ${key}`);
     }
     return new GitHubCodeSource(api, project);
 }
-/** The code source a project reads from. Memoised — the configuration is environment-fixed. */
+function buildSource(project) {
+    let config;
+    try {
+        config = requireProvider().codeSourceConfig(project);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.error(`Code source of project "${project}" cannot be read: ${message}`);
+        return new UnavailableCodeSource(message);
+    }
+    const source = createCodeSource(project, config);
+    if (source.kind === "github")
+        logger.info(`Project "${project}" reads its code from ${source.label}`);
+    return source;
+}
+/** The code source a project reads from. Memoised until `invalidateCodeSources`. */
 export function getCodeSource(project) {
     let source = sourcesByProject.get(project);
     if (!source) {

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

@@ -24,6 +24,34 @@ export declare class GitHubApiError extends Error {
     readonly status?: number | undefined;
     constructor(message: string, status?: number | undefined);
 }
+export interface RepositoryInfo {
+    fullName: string;
+    private: boolean;
+    defaultBranch: string;
+}
+export interface BranchHead {
+    sha: string;
+    message: string;
+    date: string;
+}
+/** Visibility and default branch of a repository. */
+export declare function getRepositoryInfo(owner: string, repo: string, token: string | undefined): Promise<RepositoryInfo>;
+/** Branch names of a repository, in GitHub's order. */
+export declare function listBranches(owner: string, repo: string, token: string | undefined): Promise<string[]>;
+/** The commit a branch points at, with its first message line. */
+export declare function getBranchHead(owner: string, repo: string, branch: string, token: string | undefined): Promise<BranchHead>;
+/** Login of the account a token belongs to. */
+export declare function getTokenLogin(token: string): Promise<string>;
+export interface RepositorySearchResult {
+    fullName: string;
+    private: boolean;
+    description: string;
+}
+/**
+ * Repositories whose name matches `term`, best matches first. "owner/name" narrows the search to
+ * that owner. With a token, private repositories the token can see are included.
+ */
+export declare function searchRepositories(term: string, token: string | undefined, limit: number): Promise<RepositorySearchResult[]>;
 /**
  * Read-only access to a repository's file tree over the GitHub API.
  *

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

@@ -39,6 +39,96 @@ export class GitHubApiError extends Error {
         this.name = "GitHubApiError";
     }
 }
+/**
+ * One GET against the GitHub REST API. `label` names what was asked for in error messages.
+ * 404 and 422 both mean "nothing at that address": 422 is what a valid repository returns for a
+ * ref that does not exist.
+ */
+async function githubRequest(apiPath, token, label) {
+    const headers = {
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": "mcp-documentor",
+    };
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    let response;
+    try {
+        response = await fetch(`${API_BASE}${apiPath}`, { headers });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new GitHubApiError(`network error contacting GitHub (${message})`);
+    }
+    if (response.status === 404 || response.status === 422) {
+        throw new GitHubApiError(`not found: ${label} (repository, branch or path missing — or the token cannot see this repository)`, response.status);
+    }
+    if (response.status === 401 || response.status === 403) {
+        const rateLimited = response.headers.get("x-ratelimit-remaining") === "0";
+        throw new GitHubApiError(rateLimited
+            ? `GitHub API rate limit exhausted for ${label}`
+            : `access denied to ${label} — check the GitHub token in the project settings`, response.status);
+    }
+    if (!response.ok) {
+        throw new GitHubApiError(`GitHub API returned ${response.status} for ${apiPath}`, response.status);
+    }
+    return response.json();
+}
+/** Visibility and default branch of a repository. */
+export async function getRepositoryInfo(owner, repo, token) {
+    const data = await githubRequest(`/repos/${owner}/${repo}`, token, `${owner}/${repo}`);
+    return {
+        fullName: data.full_name,
+        private: !!data.private,
+        defaultBranch: data.default_branch,
+    };
+}
+/** Upper bound on listed branches: ten pages of a hundred. */
+const MAX_BRANCH_PAGES = 10;
+/** Branch names of a repository, in GitHub's order. */
+export async function listBranches(owner, repo, token) {
+    const names = [];
+    for (let page = 1; page <= MAX_BRANCH_PAGES; page++) {
+        const batch = await githubRequest(`/repos/${owner}/${repo}/branches?per_page=100&page=${page}`, token, `${owner}/${repo}`);
+        if (!Array.isArray(batch))
+            break;
+        for (const branch of batch)
+            names.push(branch.name);
+        if (batch.length < 100)
+            break;
+    }
+    return names;
+}
+/** The commit a branch points at, with its first message line. */
+export async function getBranchHead(owner, repo, branch, token) {
+    const commit = await githubRequest(`/repos/${owner}/${repo}/commits/${encodeURIComponent(branch)}`, token, `${owner}/${repo}@${branch}`);
+    return {
+        sha: commit.sha,
+        message: String(commit.commit?.message ?? "").split("\n")[0],
+        date: commit.commit?.committer?.date ?? commit.commit?.author?.date ?? "",
+    };
+}
+/** Login of the account a token belongs to. */
+export async function getTokenLogin(token) {
+    const user = await githubRequest("/user", token, "the authenticated user");
+    return user.login;
+}
+/**
+ * Repositories whose name matches `term`, best matches first. "owner/name" narrows the search to
+ * that owner. With a token, private repositories the token can see are included.
+ */
+export async function searchRepositories(term, token, limit) {
+    const slash = term.indexOf("/");
+    const owner = slash >= 0 ? term.slice(0, slash).trim() : "";
+    const name = slash >= 0 ? term.slice(slash + 1).trim() : term.trim();
+    const qualifiers = [name, "in:name", ...(owner ? [`user:${owner}`] : [])].filter(Boolean).join(" ");
+    const data = await githubRequest(`/search/repositories?q=${encodeURIComponent(qualifiers)}&per_page=${limit}`, token, `repositories matching "${term}"`);
+    return (data.items ?? []).map((item) => ({
+        fullName: item.full_name,
+        private: !!item.private,
+        description: item.description ?? "",
+    }));
+}
 /**
  * Read-only access to a repository's file tree over the GitHub API.
  *
@@ -68,37 +158,8 @@ export class GitHubCodeApi {
     get label() {
         return formatRepoSpec(this.spec);
     }
-    async request(path) {
-        const headers = {
-            Accept: "application/vnd.github+json",
-            "X-GitHub-Api-Version": "2022-11-28",
-            "User-Agent": "mcp-documentor",
-        };
-        if (this.token)
-            headers.Authorization = `Bearer ${this.token}`;
-        let response;
-        try {
-            response = await fetch(`${API_BASE}${path}`, { headers });
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            throw new GitHubApiError(`network error contacting GitHub (${message})`);
-        }
-        // 422 is what a valid repository returns for a ref that does not exist, so a mistyped
-        // branch lands here rather than on 404 — both mean "nothing to read at that address".
-        if (response.status === 404 || response.status === 422) {
-            throw new GitHubApiError(`not found: ${this.label} (repository, branch or path missing — or the token cannot see this repository)`, response.status);
-        }
-        if (response.status === 401 || response.status === 403) {
-            const rateLimited = response.headers.get("x-ratelimit-remaining") === "0";
-            throw new GitHubApiError(rateLimited
-                ? `GitHub API rate limit exhausted for ${this.label}`
-                : `access denied to ${this.label} — check MCP_DOCUMENTOR_CODE_TOKEN / MCP_DOCUMENTOR_SYNC_TOKEN`, response.status);
-        }
-        if (!response.ok) {
-            throw new GitHubApiError(`GitHub API returned ${response.status} for ${path}`, response.status);
-        }
-        return response.json();
+    request(path) {
+        return githubRequest(path, this.token, this.label);
     }
     /**
      * The commit the configured ref points at right now.

package/dist/src/core/local-state.d.ts

@@ -0,0 +1,49 @@
+/** What a migration report entry describes, which sets how the GUI shows it. */
+export type CodeSourceMigrationKind = "github" | "local" | "code-root";
+/** One line of the code-source migration report: what a project became, and from which variables. */
+export interface CodeSourceMigrationEntry {
+    /** Project name, or undefined for the machine-wide default code root. */
+    project?: string;
+    kind: CodeSourceMigrationKind;
+    status: "imported" | "skipped" | "error";
+    /** What the project is configured as now, or why nothing was imported. */
+    detail: string;
+    /** Environment variables the entry was read from, without the MCP_DOCUMENTOR_ prefix. */
+    from: string;
+}
+export interface CodeSourceMigrationReport {
+    migratedAt: string;
+    entries: CodeSourceMigrationEntry[];
+    /** Variables found in the environment, which the server no longer reads. */
+    variables: string[];
+    /** Set once the user has acknowledged the report in the GUI. */
+    seen: boolean;
+}
+/** Code roots of this machine: a default one, and per-project overrides. */
+export interface CodeRoots {
+    default?: string;
+    byProject: Record<string, string>;
+}
+/**
+ * Machine-local state, in `<data dir>/local-state.json`. The sync repository's .gitignore excludes
+ * this file, so what it holds never leaves the machine: the code roots — where this machine keeps
+ * each project's repository — and the report of the one-time migration of the code-source
+ * environment variables.
+ */
+export declare class LocalState {
+    private readonly dataDir;
+    constructor(dataDir: string);
+    private get filePath();
+    private read;
+    private write;
+    getCodeRoots(): CodeRoots;
+    /** The project's own root, else the machine default. */
+    getCodeRoot(project: string): string | undefined;
+    /** Sets the machine default root, or removes it when `root` is undefined. */
+    setDefaultCodeRoot(root: string | undefined): void;
+    /** Sets a project's own root, or removes it — the project then uses the default — when undefined. */
+    setProjectCodeRoot(project: string, root: string | undefined): void;
+    getMigrationReport(): CodeSourceMigrationReport | undefined;
+    setMigrationReport(report: CodeSourceMigrationReport): void;
+    markMigrationReportSeen(): void;
+}

package/dist/src/core/local-state.js

@@ -0,0 +1,78 @@
+import fs from "fs";
+import path from "path";
+/**
+ * Machine-local state, in `<data dir>/local-state.json`. The sync repository's .gitignore excludes
+ * this file, so what it holds never leaves the machine: the code roots — where this machine keeps
+ * each project's repository — and the report of the one-time migration of the code-source
+ * environment variables.
+ */
+export class LocalState {
+    dataDir;
+    constructor(dataDir) {
+        this.dataDir = dataDir;
+    }
+    get filePath() {
+        return path.join(this.dataDir, "local-state.json");
+    }
+    read() {
+        if (!fs.existsSync(this.filePath))
+            return {};
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.filePath, "utf-8"));
+            return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+        }
+        catch {
+            throw new Error(`${this.filePath} is not valid JSON — fix or delete it.`);
+        }
+    }
+    write(state) {
+        fs.mkdirSync(this.dataDir, { recursive: true });
+        fs.writeFileSync(this.filePath, JSON.stringify(state, null, 2), "utf-8");
+    }
+    getCodeRoots() {
+        const roots = this.read().codeRoots;
+        return { default: roots?.default, byProject: { ...(roots?.byProject ?? {}) } };
+    }
+    /** The project's own root, else the machine default. */
+    getCodeRoot(project) {
+        const roots = this.getCodeRoots();
+        return roots.byProject[project] ?? roots.default;
+    }
+    /** Sets the machine default root, or removes it when `root` is undefined. */
+    setDefaultCodeRoot(root) {
+        const state = this.read();
+        const roots = { byProject: {}, ...state.codeRoots };
+        if (root)
+            roots.default = root;
+        else
+            delete roots.default;
+        state.codeRoots = roots;
+        this.write(state);
+    }
+    /** Sets a project's own root, or removes it — the project then uses the default — when undefined. */
+    setProjectCodeRoot(project, root) {
+        const state = this.read();
+        const byProject = { ...(state.codeRoots?.byProject ?? {}) };
+        if (root)
+            byProject[project] = root;
+        else
+            delete byProject[project];
+        state.codeRoots = { ...state.codeRoots, byProject };
+        this.write(state);
+    }
+    getMigrationReport() {
+        return this.read().codeSourceMigration;
+    }
+    setMigrationReport(report) {
+        const state = this.read();
+        state.codeSourceMigration = report;
+        this.write(state);
+    }
+    markMigrationReportSeen() {
+        const state = this.read();
+        if (!state.codeSourceMigration)
+            return;
+        state.codeSourceMigration.seen = true;
+        this.write(state);
+    }
+}

package/dist/src/core/migrate-code-sources.d.ts

@@ -0,0 +1,17 @@
+import type { StorageEngine } from "./storage-engine.js";
+import type { LocalState } from "./local-state.js";
+/**
+ * Moves the code-source environment variables into the project settings and the machine-local
+ * code roots, once per machine.
+ *
+ *  - MCP_DOCUMENTOR_CODE_REPO (+ MCP_DOCUMENTOR_CODE_BRANCH for specs without "#branch") becomes
+ *    the code source of each project it names. A project that already has a code source — written
+ *    by another machine and pulled — keeps it.
+ *  - MCP_DOCUMENTOR_CODE_ROOTS becomes the code root of each project it names, on this machine.
+ *  - MCP_DOCUMENTOR_CODE_ROOT seeds the default code root (see `seedDefaultCodeRoot`); it is not
+ *    one of the variables to remove.
+ *
+ * The outcome is recorded as a report in the local state; the GUI shows it until acknowledged.
+ * Once recorded, the migrated variables are never read again: their presence is only logged.
+ */
+export declare function migrateCodeSources(storageEngine: StorageEngine, localState: LocalState): void;