@imenam/mcp-documentor 1.0.87 → 1.0.89

package/README.md

@@ -119,13 +119,15 @@ that work on a whole project (`list_docs`, `get_doc_tree`, `check_freshness` wit
 | `list_docs` | List docs with staleness indicators (optionally filter by project) |
 | `get_doc_tree` | Return folder/doc structure for a project (or all projects) |
 | `update_doc` | Fully replace content and/or metadata (`project` required; prefer `patch_doc` for small edits) |
-| `patch_doc` | Search-and-replace a fragment of a doc’s content (`project` required) |
-| `move_doc` | Change a doc’s path (`new_path`) and/or project (`new_project`); links are rewritten across all projects (`project` required) |
+| `patch_doc` | Search-and-replace a fragment of a doc’s content; the text must occur once unless `replace_all` is set (`project` required) |
+| `move_doc` | Change a doc’s path (`new_path`) and/or project (`new_project`); links are rewritten across all projects, bare within their own project (`project` required) |
 | `delete_doc` | Permanently delete a documentation entry (`project` required) |
+| `create_project` | Create an empty project, optionally with its code source (`code_source`, as `set_code_source`) |
+| `delete_project` | Delete a project; refused while it holds any doc, image or other file besides its settings |
 | `search_docs` | Semantic search over docs (natural language; requires OpenAI) |
 | `check_freshness` | Staleness for one doc (`project` required) or a full project scan |
 | `refresh_file_snapshot` | Mark tracked files as up-to-date without editing the doc (`project` required) |
-| `git_diff_doc` | Git diff for tracked files vs snapshot baseline (`project` required) |
+| `git_diff_doc` | Diff of changed tracked files between their snapshot content and the current one (`project` required) |
 | `check_links` | Validate `related_docs`, `doc://` links, and `#heading` anchors (`project` required) |
 | `list_projects` | List all documentation projects |
 | `upload_image` | Upload an image from a local file path to a project's assets (`project` required); returns the markdown link to insert |
@@ -291,7 +293,7 @@ The GUI then shows a report of what each project became and which entries were n
 | Sees uncommitted edits | yes | no — only what is pushed |
 | Affected by `git checkout` | yes | no |
 | Needs the codebase on the server | yes | no |
-| `git_diff_doc` baseline | last commit before the snapshot date | the exact commit the snapshot was taken at |
+| `git_diff_doc` baseline | the commit the snapshot was taken at, else the last one before its date | the blob the snapshot was taken from, else its commit, else the last one before its date |
 
 Every report names the source it used (`Code source: GitHub you/my-repo@main`), so a verdict is never ambiguous. If the source cannot be reached — network, auth, rate limit — the status is `unverifiable` with the reason attached, **never** `stale`.
 
@@ -302,7 +304,7 @@ Stored tracked-file paths are already relative to the code root, and a code root
 - Hashes are computed on line-ending-normalised content, so a snapshot taken from a CRLF checkout still matches the LF blob in the repository. Hashes stored by earlier versions are still recognised.
 - Absolute paths sent by an agent are reduced by the code root when one is configured, and otherwise matched against the repository tree by their longest unambiguous suffix (a bare filename is only accepted when the repository holds exactly one file by that name).
 
-Docs snapshotted before the switch carry no source commit: `check_freshness` works immediately, while `git_diff_doc` will ask for one `refresh_file_snapshot` to anchor them on the branch.
+Docs snapshotted before the switch carry no source commit: `check_freshness` works immediately, and `git_diff_doc` falls back on the last commit before the snapshot date. Whatever its origin, a baseline is checked against the hash stored at the snapshot; when it does not match — typically after a rebase that rewrote commit dates — the diff is reported impossible, and one `refresh_file_snapshot` anchors the file on its blob, which survives rebases.
 
 ### API usage
 
@@ -310,7 +312,9 @@ Freshness is **never computed in the background** — only when something asks f
 
 Within one such request, the branch head is resolved **once** and every tracked file is compared against that same commit — no mixed verdict if someone pushes mid-scan. The next request resolves it again, so a push is visible immediately: there is no staleness window to configure.
 
-Everything else is content-addressed and therefore cached for the life of the process: a commit's tree by its sha, a file's bytes by its blob sha. Each tracked file also records the blob sha it was snapshotted at, so an unchanged file is proven untouched without being downloaded at all. A full scan of an unchanged repository costs about two API calls — not one per file.
+Resolving the branch head is a conditional request: while the branch has not moved, GitHub answers `304 Not Modified`, which does not count against the rate limit of an authenticated token.
+
+Everything else is content-addressed: a commit's tree is cached by its sha for the life of the process, and a file's bytes by their blob sha on disk, in `<data dir>/blob-cache/` (machine-local, excluded from sync) — each version of a file is downloaded once per machine, across restarts. Each tracked file also records the blob sha it was snapshotted at, so an unchanged file is proven untouched without being downloaded at all. A full scan of an unchanged repository costs about two API calls — not one per file.
 
 ## Data Storage
 

package/dist/shared/read-only.js

@@ -5,7 +5,7 @@ export function isReadOnly() {
 }
 /** Outils MCP qui créent / modifient / suppriment de la donnée. */
 export const WRITE_TOOLS = new Set([
-    "create_doc", "update_doc", "patch_doc", "move_doc", "delete_doc",
+    "create_doc", "update_doc", "patch_doc", "move_doc", "delete_doc", "create_project", "delete_project",
     "restore_doc_version", "refresh_file_snapshot", "reindex_embeddings",
     "prepare_export_bundle", "delete_export_bundle", "upload_image",
     // Sync: pull_docs and sync_status stay allowed (read-only consumer machines

package/dist/shared/schemas/doc.schema.d.ts

@@ -178,6 +178,7 @@ export declare const GetDocMetadataArgsSchema: z.ZodObject<{
     project: z.ZodString;
 }, z.core.$strip>;
 export declare const PatchDocArgsSchema: z.ZodObject<{
+    replace_all: z.ZodOptional<z.ZodBoolean>;
     replacement_file_path: z.ZodOptional<z.ZodString>;
     replacement_file_content: z.ZodOptional<z.ZodString>;
     replacement_draft: z.ZodOptional<z.ZodString>;

package/dist/shared/schemas/doc.schema.js

@@ -166,6 +166,7 @@ export const PatchDocArgsSchema = z.object({
     ...textSourceFields("search", "the search text"),
     replacement: z.string().optional().describe("Text to replace it with"),
     ...textSourceFields("replacement", "the replacement"),
+    replace_all: z.boolean().optional().describe("Replace every occurrence. Without it, a search text that occurs more than once is refused."),
 }).refine(d => d.search !== undefined || d.search_file_path !== undefined || d.search_file_content !== undefined || d.search_draft !== undefined, {
     message: "One of search, search_file_path or search_draft is required",
 }).refine(d => d.replacement !== undefined || d.replacement_file_path !== undefined || d.replacement_file_content !== undefined || d.replacement_draft !== undefined, {

package/dist/src/core/blob-store.d.ts

@@ -0,0 +1,5 @@
+export declare function setBlobStoreDir(dir: string): void;
+/** A stored blob, or undefined when it is not on disk. An entry that does not hash to its sha is dropped. */
+export declare function readStoredBlob(sha: string): Buffer | undefined;
+/** Stores a blob. Written to a temporary file then renamed, so a reader never sees a partial one. */
+export declare function storeBlob(sha: string, bytes: Buffer): void;

package/dist/src/core/blob-store.js

@@ -0,0 +1,49 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { createLogger } from "@imenam/mcp-gui-interface";
+const logger = createLogger("BlobStore");
+/**
+ * Git blobs downloaded from GitHub, kept on disk by sha. A blob's content is fixed by its sha, so
+ * an entry never goes stale: each version of a file is downloaded once per machine, whatever the
+ * number of restarts. Entries are checked against their sha when read.
+ */
+let storeDir;
+export function setBlobStoreDir(dir) {
+    storeDir = dir;
+}
+function blobPath(sha) {
+    if (!storeDir || !/^[0-9a-f]{40}$/.test(sha))
+        return undefined;
+    return path.join(storeDir, sha.slice(0, 2), sha);
+}
+/** The git blob sha of some bytes. */
+function gitBlobSha(bytes) {
+    return crypto.createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex");
+}
+/** A stored blob, or undefined when it is not on disk. An entry that does not hash to its sha is dropped. */
+export function readStoredBlob(sha) {
+    const file = blobPath(sha);
+    if (!file || !fs.existsSync(file))
+        return undefined;
+    const bytes = fs.readFileSync(file);
+    if (gitBlobSha(bytes) === sha)
+        return bytes;
+    logger.warn(`Stored blob ${sha.slice(0, 7)} does not match its sha; removing it`);
+    fs.rmSync(file, { force: true });
+    return undefined;
+}
+/** Stores a blob. Written to a temporary file then renamed, so a reader never sees a partial one. */
+export function storeBlob(sha, bytes) {
+    const file = blobPath(sha);
+    if (!file)
+        return;
+    if (gitBlobSha(bytes) !== sha) {
+        logger.warn(`Downloaded content of blob ${sha.slice(0, 7)} does not match its sha; not storing it`);
+        return;
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, bytes);
+    fs.renameSync(temp, file);
+}

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

@@ -48,6 +48,36 @@ export interface CodeSource {
     /** Converts a path supplied by an agent into the portable form persisted in a doc. */
     toStoredPath(inputPath: string): Promise<string>;
 }
+export declare class GitHubCodeSource implements CodeSource {
+    readonly api: GitHubCodeApi;
+    private readonly project;
+    readonly kind: "github";
+    /** Agent-supplied path → repo-relative path, per source. Repo layouts barely move. */
+    private readonly repoPathCache;
+    constructor(api: GitHubCodeApi, project: string);
+    get label(): string;
+    read(storedPath: string): Promise<SourceFile | undefined>;
+    /** The blob sha from the commit's tree — already fetched for the whole repository in one call. */
+    contentId(storedPath: string): Promise<string | undefined>;
+    /**
+     * A blob's content by its sha. A blob outlives the commits that referenced it, rebases included.
+     * `repoPath` names the file in github.log.
+     */
+    readBlob(blobSha: string, repoPath?: string): Promise<FileContent>;
+    /** A stored path's content at a given commit, or undefined when the file does not exist there. */
+    readAt(storedPath: string, commitSha: string): Promise<FileContent | undefined>;
+    toStoredPath(inputPath: string): Promise<string>;
+    /**
+     * Maps a path onto the repository layout.
+     *
+     * A relative path is already repo-relative. An absolute one — what an agent working on a local
+     * clone naturally sends — is reduced by the configured code root when there is one, and
+     * otherwise matched against the repository tree by its longest unambiguous path suffix, so the
+     * feature works without forcing every machine to declare a root.
+     */
+    private toRepoPath;
+    private computeRepoPath;
+}
 /** Where the code sources read their configuration. */
 export interface CodeSourceProvider {
     /** The project's code source setting. Throws when the settings cannot be read. */
@@ -86,5 +116,7 @@ export declare function locateTrackedSections(project: string, storedPath: strin
  * it simply matches nothing, which is the right outcome for a filter.
  */
 export declare function toStoredPathForMatching(project: string, inputPath: string): Promise<string>;
+/** A project's source when it reads a GitHub branch, undefined when it reads the local working copy. */
+export declare function getGitHubSource(project: string): GitHubCodeSource | undefined;
 /** The GitHub client behind a project's source, or undefined when it reads the local working copy. */
 export declare function getGitHubApi(project: string): GitHubCodeApi | undefined;

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

@@ -49,7 +49,7 @@ class LocalCodeSource {
     }
 }
 const toForwardSlashes = (p) => p.split("\\").join("/");
-class GitHubCodeSource {
+export class GitHubCodeSource {
     api;
     project;
     kind = "github";
@@ -71,7 +71,7 @@ class GitHubCodeSource {
         if (!blobSha)
             return undefined;
         return {
-            content: bytesToFileContent(await this.api.getBlob(blobSha)),
+            content: bytesToFileContent(await this.api.getBlob(blobSha, repoPath)),
             lastModifiedAt: commitDate,
             revision: commitSha,
             blobId: blobSha,
@@ -83,6 +83,21 @@ class GitHubCodeSource {
         const repoPath = await this.toRepoPath(storedPath, commitSha);
         return repoPath ? this.api.getBlobSha(commitSha, repoPath) : undefined;
     }
+    /**
+     * A blob's content by its sha. A blob outlives the commits that referenced it, rebases included.
+     * `repoPath` names the file in github.log.
+     */
+    async readBlob(blobSha, repoPath) {
+        return bytesToFileContent(await this.api.getBlob(blobSha, repoPath));
+    }
+    /** A stored path's content at a given commit, or undefined when the file does not exist there. */
+    async readAt(storedPath, commitSha) {
+        const repoPath = await this.toRepoPath(storedPath, commitSha);
+        if (!repoPath)
+            return undefined;
+        const blobSha = await this.api.getBlobSha(commitSha, repoPath);
+        return blobSha ? this.readBlob(blobSha, repoPath) : undefined;
+    }
     async toStoredPath(inputPath) {
         const { commitSha } = await this.api.resolveRef();
         const repoPath = await this.toRepoPath(inputPath, commitSha);
@@ -264,8 +279,12 @@ export async function toStoredPathForMatching(project, inputPath) {
         return toForwardSlashes(inputPath);
     }
 }
+/** A project's source when it reads a GitHub branch, undefined when it reads the local working copy. */
+export function getGitHubSource(project) {
+    const source = getCodeSource(project);
+    return source instanceof GitHubCodeSource ? source : undefined;
+}
 /** The GitHub client behind a project's source, or undefined when it reads the local working copy. */
 export function getGitHubApi(project) {
-    const source = getCodeSource(project);
-    return source instanceof GitHubCodeSource ? source.api : undefined;
+    return getGitHubSource(project)?.api;
 }

package/dist/src/core/git-sync.d.ts

@@ -61,6 +61,11 @@ export declare class SyncEngine {
      * ever stored in .git/config (which git never commits), never versioned.
      */
     private authedUrl;
+    /**
+     * Runs one git command that reaches the remote and records it in github.log. Error messages
+     * are recorded with the token masked: git quotes the authenticated URL in some of them.
+     */
+    private remoteGit;
     private requireConfig;
     /**
      * Registers the structured merge drivers in .git/config, which git never

package/dist/src/core/git-sync.js

@@ -4,6 +4,7 @@ import path from "path";
 import { fileURLToPath } from "url";
 import { simpleGit } from "simple-git";
 import { createLogger } from "@imenam/mcp-gui-interface";
+import { describeRemote, recordGitHubCall, redactSecrets } from "./github-log.js";
 const logger = createLogger("GitSync");
 const GITIGNORE_CONTENT = [
     "# Derived / machine-local state — never synced",
@@ -20,6 +21,7 @@ const GITIGNORE_CONTENT = [
     "errors-tmp-files/",
     "export-bundles.json",
     "local-state.json",
+    "blob-cache/",
     "",
 ].join("\n");
 /**
@@ -72,6 +74,31 @@ export class SyncEngine {
             return cfg.remoteUrl;
         }
     }
+    /**
+     * Runs one git command that reaches the remote and records it in github.log. Error messages
+     * are recorded with the token masked: git quotes the authenticated URL in some of them.
+     */
+    async remoteGit(cfg, action, command, run) {
+        const startedAt = Date.now();
+        const call = { kind: "git", action, command, repo: describeRemote(cfg.remoteUrl) };
+        try {
+            const result = await run();
+            recordGitHubCall({ ...call, ok: true, status: "ok", durationMs: Date.now() - startedAt });
+            return result;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const rejected = /fetch first|non-fast-forward|\[rejected\]/i.test(message);
+            recordGitHubCall({
+                ...call,
+                ok: false,
+                status: rejected ? "rejected" : "failed",
+                durationMs: Date.now() - startedAt,
+                error: redactSecrets(message, [cfg.token]).trim(),
+            });
+            throw err;
+        }
+    }
     requireConfig() {
         const cfg = this.storage.getSyncConfig();
         if (!cfg?.remoteUrl) {
@@ -117,10 +144,21 @@ export class SyncEngine {
     async ensureRepo() {
         const cfg = this.requireConfig();
         const authed = this.authedUrl(cfg);
+        // Entries a newer server added are appended to an existing file, so machine-local state it
+        // introduces is never staged in a repo initialized before it.
         const gitignorePath = path.join(this.dataDir, ".gitignore");
         if (!fs.existsSync(gitignorePath)) {
             fs.writeFileSync(gitignorePath, GITIGNORE_CONTENT, "utf-8");
         }
+        else {
+            const current = fs.readFileSync(gitignorePath, "utf-8");
+            const present = new Set(current.split(/\r?\n/).map((line) => line.trim()));
+            const missing = GITIGNORE_CONTENT.split("\n").filter((line) => line && !line.startsWith("#") && !present.has(line));
+            if (missing.length > 0) {
+                const separator = current === "" || current.endsWith("\n") ? "" : "\n";
+                fs.writeFileSync(gitignorePath, `${current}${separator}${missing.join("\n")}\n`, "utf-8");
+            }
+        }
         // Rewritten when it drifts, so an upgraded server updates the routing of
         // repos that were initialized by an older version.
         const attributesPath = path.join(this.dataDir, ".gitattributes");
@@ -185,7 +223,7 @@ export class SyncEngine {
             const pending = await this.git.status();
             return { status: "conflict", conflicted: pending.conflicted };
         }
-        await this.git.fetch("origin", cfg.branch);
+        await this.remoteGit(cfg, "Fetch the docs repository", `git fetch origin ${cfg.branch}`, () => this.git.fetch("origin", cfg.branch));
         const remoteRef = `refs/remotes/origin/${cfg.branch}`;
         // No remote branch yet (fresh repo) — nothing to pull.
         const hasRemote = await this.git
@@ -274,8 +312,9 @@ export class SyncEngine {
                 "Resolve it with resolve_sync_conflict before pushing, otherwise the conflict markers would be committed as documentation content.");
         }
         const committed = await this.commitLocalChanges(message);
+        const unpushed = (await this.git.status()).ahead;
         try {
-            await this.git.push(["-u", "origin", `HEAD:${cfg.branch}`]);
+            await this.remoteGit(cfg, unpushed > 0 ? `Push ${unpushed} local doc commit${unpushed > 1 ? "s" : ""}` : "Push the docs branch", `git push -u origin HEAD:${cfg.branch}`, () => this.git.push(["-u", "origin", `HEAD:${cfg.branch}`]));
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);

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

@@ -59,8 +59,8 @@ export declare function searchRepositories(term: string, token: string | undefin
  *   - the commit a ref points at — the only time-varying one, so it is resolved once per
  *     operation and never carried across them (see `code-operation`);
  *   - that commit's tree (path → blob sha) — immutable, cached per commit;
- *   - a blob's bytes — immutable, cached per blob sha, so a file that survives a commit
- *     untouched is never downloaded twice.
+ *   - a blob's bytes — immutable, cached per blob sha in memory and on disk (see `blob-store`),
+ *     so a given version of a file is downloaded once per machine.
  *
  * One instance per (repo, ref) pair; instances are shared across projects by `code-source`.
  */
@@ -78,7 +78,8 @@ export declare class GitHubCodeApi {
      * The commit the configured ref points at right now.
      *
      * Resolved afresh for each operation — so a push is visible to the very next call — but only
-     * once within it, however many files that operation ends up reading.
+     * once within it, however many files that operation ends up reading. The request is conditional:
+     * while the branch has not moved, GitHub answers 304 and the call costs no rate limit.
      */
     resolveRef(): Promise<ResolvedRef>;
     /**
@@ -101,15 +102,10 @@ export declare class GitHubCodeApi {
     isTreeTruncated(commitSha: string): boolean;
     /** Blob sha for one path at one commit, or undefined if the file does not exist there. */
     getBlobSha(commitSha: string, repoPath: string): Promise<string | undefined>;
-    /** A blob's bytes. Blobs are immutable, so this is cached for the life of the process. */
-    getBlob(blobSha: string): Promise<Buffer>;
     /**
-     * Unified diff of every file that changed between two commits, keyed by path.
-     *
-     * One call covers a whole doc, so `git_diff_doc` groups its tracked files by the commit they
-     * were snapshotted at rather than asking per file. GitHub caps the response at 300 files;
-     * paths beyond that are simply absent from the map.
+     * A blob's bytes, read from the blob store when this machine already downloaded them.
+     * `filePath` names the file in github.log.
      */
-    comparePatches(baseSha: string, headSha: string): Promise<Map<string, string>>;
+    getBlob(blobSha: string, filePath?: string): Promise<Buffer>;
 }
 export {};

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

@@ -1,5 +1,7 @@
 import { createLogger } from "@imenam/mcp-gui-interface";
 import { oncePerOperation } from "./code-operation.js";
+import { recordGitHubCall, redactSecrets } from "./github-log.js";
+import { readStoredBlob, storeBlob } from "./blob-store.js";
 const logger = createLogger("GitHubCodeApi");
 const API_BASE = "https://api.github.com";
 export function formatRepoSpec(spec) {
@@ -39,12 +41,22 @@ export class GitHubApiError extends Error {
         this.name = "GitHubApiError";
     }
 }
+/** Last answer to each revalidated path, under the token it was read with. */
+const revalidated = new Map();
+function readRateLimit(response) {
+    const remaining = Number(response.headers.get("x-ratelimit-remaining"));
+    const limit = Number(response.headers.get("x-ratelimit-limit"));
+    const reset = Number(response.headers.get("x-ratelimit-reset"));
+    if (!Number.isFinite(remaining) || !Number.isFinite(limit) || !limit)
+        return undefined;
+    return { remaining, limit, reset: Number.isFinite(reset) ? new Date(reset * 1000).toISOString() : "" };
+}
 /**
- * One GET against the GitHub REST API. `label` names what was asked for in error messages.
+ * One GET against the GitHub REST API, recorded in github.log whatever its outcome.
  * 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) {
+async function githubRequest(apiPath, token, purpose) {
     const headers = {
         Accept: "application/vnd.github+json",
         "X-GitHub-Api-Version": "2022-11-28",
@@ -52,31 +64,70 @@ async function githubRequest(apiPath, token, label) {
     };
     if (token)
         headers.Authorization = `Bearer ${token}`;
+    const cacheKey = `${token ?? ""} ${apiPath}`;
+    const previous = purpose.revalidate ? revalidated.get(cacheKey) : undefined;
+    if (previous)
+        headers["If-None-Match"] = previous.etag;
+    const { label } = purpose;
+    const startedAt = Date.now();
+    const record = (status, ok, error, rateLimit) => recordGitHubCall({
+        kind: "api",
+        action: purpose.action,
+        command: `GET ${apiPath}`,
+        repo: purpose.repo,
+        ok,
+        status,
+        durationMs: Date.now() - startedAt,
+        error: error && redactSecrets(error, [token]),
+        rateLimit,
+    });
     let response;
     try {
         response = await fetch(`${API_BASE}${apiPath}`, { headers });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        record("network error", false, message);
         throw new GitHubApiError(`network error contacting GitHub (${message})`);
     }
+    const rateLimit = readRateLimit(response);
+    const status = String(response.status);
+    if (response.status === 304 && previous) {
+        record(status, true, undefined, rateLimit);
+        return previous.body;
+    }
     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);
+        const message = `not found: ${label} (repository, branch or path missing — or the token cannot see this repository)`;
+        record(status, false, message, rateLimit);
+        throw new GitHubApiError(message, response.status);
     }
     if (response.status === 401 || response.status === 403) {
         const rateLimited = response.headers.get("x-ratelimit-remaining") === "0";
-        throw new GitHubApiError(rateLimited
+        const message = rateLimited
             ? `GitHub API rate limit exhausted for ${label}`
-            : `access denied to ${label} — check the GitHub token in the project settings`, response.status);
+            : `access denied to ${label} — check the GitHub token in the project settings`;
+        record(status, false, message, rateLimit);
+        throw new GitHubApiError(message, response.status);
     }
     if (!response.ok) {
-        throw new GitHubApiError(`GitHub API returned ${response.status} for ${apiPath}`, response.status);
+        const message = `GitHub API returned ${response.status} for ${apiPath}`;
+        record(status, false, message, rateLimit);
+        throw new GitHubApiError(message, response.status);
     }
-    return response.json();
+    record(status, true, undefined, rateLimit);
+    const body = await response.json();
+    const etag = response.headers.get("etag");
+    if (purpose.revalidate && etag)
+        revalidated.set(cacheKey, { etag, body });
+    return body;
 }
 /** Visibility and default branch of a repository. */
 export async function getRepositoryInfo(owner, repo, token) {
-    const data = await githubRequest(`/repos/${owner}/${repo}`, token, `${owner}/${repo}`);
+    const data = await githubRequest(`/repos/${owner}/${repo}`, token, {
+        label: `${owner}/${repo}`,
+        action: "Read the repository details",
+        repo: `${owner}/${repo}`,
+    });
     return {
         fullName: data.full_name,
         private: !!data.private,
@@ -89,7 +140,7 @@ const MAX_BRANCH_PAGES = 10;
 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}`);
+        const batch = await githubRequest(`/repos/${owner}/${repo}/branches?per_page=100&page=${page}`, token, { label: `${owner}/${repo}`, action: `List the repository branches (page ${page})`, repo: `${owner}/${repo}` });
         if (!Array.isArray(batch))
             break;
         for (const branch of batch)
@@ -101,7 +152,7 @@ export async function listBranches(owner, repo, token) {
 }
 /** 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}`);
+    const commit = await githubRequest(`/repos/${owner}/${repo}/commits/${encodeURIComponent(branch)}`, token, { label: `${owner}/${repo}@${branch}`, action: `Read the head commit of ${branch}`, repo: `${owner}/${repo}`, revalidate: true });
     return {
         sha: commit.sha,
         message: String(commit.commit?.message ?? "").split("\n")[0],
@@ -110,7 +161,11 @@ export async function getBranchHead(owner, repo, branch, token) {
 }
 /** Login of the account a token belongs to. */
 export async function getTokenLogin(token) {
-    const user = await githubRequest("/user", token, "the authenticated user");
+    const user = await githubRequest("/user", token, {
+        label: "the authenticated user",
+        action: "Identify the account the token belongs to",
+        repo: null,
+    });
     return user.login;
 }
 /**
@@ -122,7 +177,7 @@ export async function searchRepositories(term, token, limit) {
     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}"`);
+    const data = await githubRequest(`/search/repositories?q=${encodeURIComponent(qualifiers)}&per_page=${limit}`, token, { label: `repositories matching "${term}"`, action: `Search repositories matching "${term}"`, repo: null });
     return (data.items ?? []).map((item) => ({
         fullName: item.full_name,
         private: !!item.private,
@@ -136,8 +191,8 @@ export async function searchRepositories(term, token, limit) {
  *   - the commit a ref points at — the only time-varying one, so it is resolved once per
  *     operation and never carried across them (see `code-operation`);
  *   - that commit's tree (path → blob sha) — immutable, cached per commit;
- *   - a blob's bytes — immutable, cached per blob sha, so a file that survives a commit
- *     untouched is never downloaded twice.
+ *   - a blob's bytes — immutable, cached per blob sha in memory and on disk (see `blob-store`),
+ *     so a given version of a file is downloaded once per machine.
  *
  * One instance per (repo, ref) pair; instances are shared across projects by `code-source`.
  */
@@ -158,19 +213,25 @@ export class GitHubCodeApi {
     get label() {
         return formatRepoSpec(this.spec);
     }
-    request(path) {
-        return githubRequest(path, this.token, this.label);
+    request(path, action, revalidate = false) {
+        return githubRequest(path, this.token, {
+            label: this.label,
+            action,
+            repo: `${this.spec.owner}/${this.spec.repo}`,
+            revalidate,
+        });
     }
     /**
      * The commit the configured ref points at right now.
      *
      * Resolved afresh for each operation — so a push is visible to the very next call — but only
-     * once within it, however many files that operation ends up reading.
+     * once within it, however many files that operation ends up reading. The request is conditional:
+     * while the branch has not moved, GitHub answers 304 and the call costs no rate limit.
      */
     resolveRef() {
         return oncePerOperation(`ref:${this.label}`, async () => {
             const ref = this.spec.ref ?? "HEAD";
-            const commit = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/commits/${encodeURIComponent(ref)}`);
+            const commit = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/commits/${encodeURIComponent(ref)}`, `Resolve ${ref} to its current commit`, true);
             logger.debug(`${this.label} is at ${String(commit.sha).slice(0, 7)}`);
             return {
                 commitSha: commit.sha,
@@ -190,7 +251,7 @@ export class GitHubCodeApi {
         return this.cached(this.commitByDate, isoDate, async () => {
             const ref = this.spec.ref ?? "HEAD";
             const commits = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/commits` +
-                `?sha=${encodeURIComponent(ref)}&until=${encodeURIComponent(isoDate)}&per_page=1`);
+                `?sha=${encodeURIComponent(ref)}&until=${encodeURIComponent(isoDate)}&per_page=1`, `Find the last commit on ${ref} at or before ${isoDate}`);
             const sha = Array.isArray(commits) && typeof commits[0]?.sha === "string" ? commits[0].sha : undefined;
             logger.debug(`${this.label}: commit at or before ${isoDate} is ${sha ? sha.slice(0, 7) : "none"}`);
             return sha;
@@ -199,7 +260,7 @@ export class GitHubCodeApi {
     /** path → blob sha for every file in the commit's tree. A commit's tree never changes. */
     getTree(commitSha) {
         return this.cached(this.treeByCommit, commitSha, async () => {
-            const tree = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/git/trees/${commitSha}?recursive=1`);
+            const tree = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/git/trees/${commitSha}?recursive=1`, `List the files of commit ${commitSha.slice(0, 7)}`);
             const map = new Map();
             for (const entry of tree.tree ?? []) {
                 if (entry.type === "blob")
@@ -240,7 +301,7 @@ export class GitHubCodeApi {
         if (known || !this.isTreeTruncated(commitSha))
             return known;
         try {
-            const contents = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/contents/${encodeURI(repoPath)}?ref=${commitSha}`);
+            const contents = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/contents/${encodeURI(repoPath)}?ref=${commitSha}`, `Look up ${repoPath} at ${commitSha.slice(0, 7)}`);
             return typeof contents?.sha === "string" ? contents.sha : undefined;
         }
         catch (err) {
@@ -249,27 +310,19 @@ export class GitHubCodeApi {
             throw err;
         }
     }
-    /** A blob's bytes. Blobs are immutable, so this is cached for the life of the process. */
-    getBlob(blobSha) {
-        return this.cached(this.blobCache, blobSha, async () => {
-            const blob = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/git/blobs/${blobSha}`);
-            return Buffer.from(blob.content ?? "", blob.encoding === "base64" ? "base64" : "utf-8");
-        });
-    }
     /**
-     * Unified diff of every file that changed between two commits, keyed by path.
-     *
-     * One call covers a whole doc, so `git_diff_doc` groups its tracked files by the commit they
-     * were snapshotted at rather than asking per file. GitHub caps the response at 300 files;
-     * paths beyond that are simply absent from the map.
+     * A blob's bytes, read from the blob store when this machine already downloaded them.
+     * `filePath` names the file in github.log.
      */
-    async comparePatches(baseSha, headSha) {
-        const comparison = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/compare/${baseSha}...${headSha}`);
-        const patches = new Map();
-        for (const file of comparison.files ?? []) {
-            if (typeof file.patch === "string")
-                patches.set(file.filename, file.patch);
-        }
-        return patches;
+    getBlob(blobSha, filePath) {
+        return this.cached(this.blobCache, blobSha, async () => {
+            const stored = readStoredBlob(blobSha);
+            if (stored)
+                return stored;
+            const blob = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/git/blobs/${blobSha}`, filePath ? `Download ${filePath}` : `Download blob ${blobSha.slice(0, 7)}`);
+            const bytes = Buffer.from(blob.content ?? "", blob.encoding === "base64" ? "base64" : "utf-8");
+            storeBlob(blobSha, bytes);
+            return bytes;
+        });
     }
 }