@imenam/mcp-documentor 1.0.86 → 1.0.88

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 (folder/name) within its project (`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
 

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

@@ -156,8 +156,9 @@ export declare const DeleteDocArgsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const MoveDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
-    new_path: z.ZodString;
+    new_path: z.ZodOptional<z.ZodString>;
     project: z.ZodString;
+    new_project: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const CheckFreshnessArgsSchema: z.ZodObject<{
     path: z.ZodOptional<z.ZodString>;
@@ -177,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

@@ -123,8 +123,19 @@ export const DeleteDocArgsSchema = z.object({
 });
 export const MoveDocArgsSchema = z.object({
     path: z.string().describe("Current path of the documentation entry, e.g. 'backend/auth/authentication'"),
-    new_path: z.string().describe("New path for the documentation entry, e.g. 'backend/v2/authentication'. Changes folder and/or name."),
+    new_path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("New path for the documentation entry, e.g. 'backend/v2/authentication'. Changes folder and/or name. Omitted: the entry keeps its current path, which requires new_project."),
     project: requiredProject("the move"),
+    new_project: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Project the entry is moved to. Omitted: the entry stays in `project`."),
+}).refine((args) => args.new_path !== undefined || args.new_project !== undefined, {
+    message: "Provide new_path, new_project, or both.",
 });
 export const CheckFreshnessArgsSchema = z
     .object({
@@ -155,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/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/embedding-engine.d.ts

@@ -11,7 +11,7 @@ export declare class EmbeddingEngine {
     cosineSimilarity(a: number[], b: number[]): number;
     saveEmbedding(docId: string, embedding: number[], project: string): Promise<void>;
     removeEmbedding(docId: string, project: string): Promise<void>;
-    moveEmbedding(oldDocId: string, newDocId: string, project: string): Promise<void>;
+    moveEmbedding(oldDocId: string, project: string, newDocId: string, newProject: string): Promise<void>;
     search(query: string, project: string, topK: number, getDocContent: (id: string) => Promise<{
         title: string;
         content: string;

package/dist/src/core/embedding-engine.js

@@ -66,9 +66,9 @@ export class EmbeddingEngine {
         this.store.remove(project, docId);
         logger.debug(`Embedding removed for doc "${docId}" in project "${project}"`);
     }
-    async moveEmbedding(oldDocId, newDocId, project) {
-        this.store.move(project, oldDocId, newDocId);
-        logger.debug(`Embedding moved: "${oldDocId}" → "${newDocId}" in project "${project}"`);
+    async moveEmbedding(oldDocId, project, newDocId, newProject) {
+        this.store.move(project, oldDocId, newProject, newDocId);
+        logger.debug(`Embedding moved: "${project}:${oldDocId}" → "${newProject}:${newDocId}"`);
     }
     async search(query, project, topK, getDocContent) {
         return this.searchAcrossProjects(query, [project], topK, async (_proj, docId) => getDocContent(docId));

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

@@ -5,7 +5,7 @@ export declare class EmbeddingStore {
     private getDb;
     save(project: string, docId: string, embedding: number[]): void;
     remove(project: string, docId: string): void;
-    move(project: string, oldDocId: string, newDocId: string): void;
+    move(project: string, oldDocId: string, newProject: string, newDocId: string): void;
     loadAll(project: string): Map<string, number[]>;
     loadAllProjects(projects: string[]): Array<{
         project: string;

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

@@ -65,11 +65,11 @@ export class EmbeddingStore {
             .run(project, docId);
         logger.debug(`Embedding removed: [${project}] ${docId}`);
     }
-    move(project, oldDocId, newDocId) {
+    move(project, oldDocId, newProject, newDocId) {
         this.getDb()
-            .prepare("UPDATE embeddings SET doc_id = ? WHERE project = ? AND doc_id = ?")
-            .run(newDocId, project, oldDocId);
-        logger.debug(`Embedding moved: [${project}] ${oldDocId} → ${newDocId}`);
+            .prepare("UPDATE embeddings SET project = ?, doc_id = ? WHERE project = ? AND doc_id = ?")
+            .run(newProject, newDocId, project, oldDocId);
+        logger.debug(`Embedding moved: [${project}] ${oldDocId} → [${newProject}] ${newDocId}`);
     }
     loadAll(project) {
         const rows = this.getDb()

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",
@@ -72,6 +73,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) {
@@ -185,7 +211,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 +300,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

@@ -101,15 +101,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. Blobs are immutable, so this is cached for the life of the process.
+     * `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,6 @@
 import { createLogger } from "@imenam/mcp-gui-interface";
 import { oncePerOperation } from "./code-operation.js";
+import { recordGitHubCall, redactSecrets } from "./github-log.js";
 const logger = createLogger("GitHubCodeApi");
 const API_BASE = "https://api.github.com";
 export function formatRepoSpec(spec) {
@@ -39,12 +40,20 @@ export class GitHubApiError extends Error {
         this.name = "GitHubApiError";
     }
 }
+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 +61,58 @@ async function githubRequest(apiPath, token, label) {
     };
     if (token)
         headers.Authorization = `Bearer ${token}`;
+    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 === 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);
     }
+    record(status, true, undefined, rateLimit);
     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}`);
+    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 +125,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 +137,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}` });
     return {
         sha: commit.sha,
         message: String(commit.commit?.message ?? "").split("\n")[0],
@@ -110,7 +146,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 +162,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,
@@ -158,8 +198,12 @@ export class GitHubCodeApi {
     get label() {
         return formatRepoSpec(this.spec);
     }
-    request(path) {
-        return githubRequest(path, this.token, this.label);
+    request(path, action) {
+        return githubRequest(path, this.token, {
+            label: this.label,
+            action,
+            repo: `${this.spec.owner}/${this.spec.repo}`,
+        });
     }
     /**
      * The commit the configured ref points at right now.
@@ -170,7 +214,7 @@ export class GitHubCodeApi {
     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`);
             logger.debug(`${this.label} is at ${String(commit.sha).slice(0, 7)}`);
             return {
                 commitSha: commit.sha,
@@ -190,7 +234,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 +243,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 +284,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 +293,14 @@ export class GitHubCodeApi {
             throw err;
         }
     }
-    /** A blob's bytes. Blobs are immutable, so this is cached for the life of the process. */
-    getBlob(blobSha) {
+    /**
+     * A blob's bytes. Blobs are immutable, so this is cached for the life of the process.
+     * `filePath` names the file in github.log.
+     */
+    getBlob(blobSha, filePath) {
         return this.cached(this.blobCache, blobSha, async () => {
-            const blob = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/git/blobs/${blobSha}`);
+            const blob = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/git/blobs/${blobSha}`, filePath ? `Download ${filePath}` : `Download blob ${blobSha.slice(0, 7)}`);
             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.
-     */
-    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;
-    }
 }

package/dist/src/core/github-log.d.ts

@@ -0,0 +1,38 @@
+export declare const GITHUB_LOG_FILE = "github.log";
+/**
+ * One call to GitHub, as written to github.log — one JSON object per line.
+ *
+ *   kind     "git" for a git command reaching the remote, "api" for a REST request
+ *   action   what was done, in plain words
+ *   command  the exact git command or HTTP request
+ *   repo     "owner/repo" the call targets, when it targets one
+ *   trigger  the tool call, GUI request or server step that caused it
+ *   status   HTTP status, or "ok" / "rejected" / "failed" / "network error"
+ */
+export interface GitHubLogEntry {
+    ts: string;
+    kind: "git" | "api";
+    action: string;
+    command: string;
+    repo: string | null;
+    trigger: string;
+    ok: boolean;
+    status: string;
+    durationMs: number;
+    error?: string;
+    rateLimit?: {
+        remaining: number;
+        limit: number;
+        reset: string;
+    };
+}
+/** Runs `fn` with `trigger` recorded as the cause of every GitHub call it makes. */
+export declare function runTriggeredBy<T>(trigger: string, fn: () => T): T;
+/** Opens github.log in `logDir` for appending. */
+export declare function initGitHubLog(logDir: string): void;
+/** Masks credentials embedded in URLs or tokens quoted verbatim. */
+export declare function redactSecrets(text: string, secrets?: Array<string | undefined>): string;
+/** "owner/repo" for a GitHub URL, the host and path for any other remote. */
+export declare function describeRemote(remoteUrl: string): string;
+/** Appends one call to github.log and mirrors it in server.log. */
+export declare function recordGitHubCall(call: Omit<GitHubLogEntry, "ts" | "trigger">): void;