@nimbus-dev/connectors 0.6.0 → 0.8.0

package/connectors/github/src/tools.ts

@@ -1,10 +1,23 @@
 import { z } from "zod";
+import {
+  assertCombinedSize,
+  assertCommitFiles,
+  COMMIT_MAX_COMBINED_BYTES,
+  COMMIT_MAX_FILES,
+  commitFilePathSchema,
+  commitFilesSchema,
+  fullShaSchema,
+  notOverwritable,
+} from "../../../shared/commit-files.ts";
 import {
   type ConsentServer,
+  createPrepareToolRegistrar,
   createWriteToolRegistrar,
   type WriteToolConfig,
 } from "../../../shared/consent-kit.ts";
+import { type GithubFileRead, readGithubFilesAt } from "../../../shared/github-files.ts";
 import {
+  commitRefCandidates,
   ghFetch,
   ghQueryPath,
   ghRepoPath,
@@ -17,6 +30,7 @@ import {
   createRegisterSimpleTool,
   createZodToolRegistrar,
   mcpJsonResult as jsonResult,
+  mcpJsonResultIfOk,
   requireProcessEnv,
   type ZodObjectSchema,
 } from "../../../shared/mcp-tool-kit.ts";
@@ -44,11 +58,15 @@ export const GITHUB_TOOL_NAMES = [
   "github_ci_run_get",
   "github_branch_delete",
   "github_ref_get",
+  "github_commit_get",
   "github_branch_create",
   "github_pr_create",
   "github_pr_update",
   "github_tag_create",
   "github_commit_push",
+  "github_files_get",
+  "github_commit_prepare",
+  "github_file_commit",
 ] as const;
 
 export function registerGithubTools(
@@ -68,6 +86,16 @@ export function registerGithubTools(
     scopeKinds: ["repo"],
   });
 
+  /**
+   * Prepare tools (shared/prepare-tool-ids.ts) read the state a write is bound to, for the gateway to
+   * call BEFORE the write's approval prompt; they are neither reads nor writes to the kit.
+   */
+  const registerPrepareTool = createPrepareToolRegistrar(server, {
+    connector: "github",
+    scopeEnv: "NIMBUS_MCP_GITHUB_WRITE_SCOPE",
+    scopeKinds: ["repo"],
+  });
+
   /** Standard GitHub tool, read or write: token → ghFetch(buildPath[, buildInit]) → mcpJsonResultIfOk("GitHub"). */
   const githubRest = { tokenEnv: "GITHUB_PAT", serviceLabel: "GitHub", fetch: ghFetch } as const;
   const registerGithubTool = makeRestToolRegistrar({ registrar: reg, ...githubRest });
@@ -174,15 +202,20 @@ export function registerGithubTools(
     pullNumber: z.number().int().min(1),
     mergeMethod: z.enum(["merge", "squash", "rebase"]).optional(),
     commitTitle: z.string().max(500).optional(),
+    // Lowercase hex only: the sha is sent as given and compared by GitHub, and the preview shows it.
+    sha: z
+      .string()
+      .regex(/^[0-9a-f]{40}$/, "a full 40-character lowercase hex commit sha")
+      .optional(),
   });
 
-  registerGithubWriteTool(
+  registerWriteTool(
     "github_pr_merge",
-    { mutates: "github.pr.merge", recoverable: true },
-    "Merge a pull request.",
+    { mutates: "github.pr.merge", recoverable: true, scopeTargetOf: repoScope },
+    "Merge a pull request. If sha (40 lowercase hex) is given it is sent as the API's sha parameter, the head SHA the pull request must match, and GitHub refuses the merge with a 409 when the head has moved (https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request).",
     githubPrMergeSchema,
-    (parsed) => `${ghRepoPath(parsed.owner, parsed.repo)}/pulls/${String(parsed.pullNumber)}/merge`,
-    (parsed) => {
+    async (parsed) => {
+      const token = requireProcessEnv("GITHUB_PAT");
       const body: Record<string, string> = {};
       if (parsed.mergeMethod !== undefined) {
         body["merge_method"] = parsed.mergeMethod;
@@ -190,7 +223,22 @@ export function registerGithubTools(
       if (parsed.commitTitle !== undefined && parsed.commitTitle !== "") {
         body["commit_title"] = parsed.commitTitle;
       }
-      return jsonInit("PUT", body);
+      if (parsed.sha !== undefined) {
+        body["sha"] = parsed.sha;
+      }
+      const res = await ghFetch(
+        token,
+        `${ghRepoPath(parsed.owner, parsed.repo)}/pulls/${String(parsed.pullNumber)}/merge`,
+        jsonInit("PUT", body),
+      );
+      // The merge endpoint documents 409 as "Conflict if sha was provided and pull request head did
+      // not match". Without a sha a 409 is not that, so it keeps the generic error.
+      if (res.status === 409 && parsed.sha !== undefined) {
+        throw new Error(
+          `GitHub 409: the pull request head is no longer the approved ${parsed.sha}; nothing was merged. GitHub said: ${res.text.slice(0, 200)}`,
+        );
+      }
+      return mcpJsonResultIfOk("GitHub", res);
     },
   );
 
@@ -360,6 +408,67 @@ export function registerGithubTools(
     },
   );
 
+  /** `owner/repo` as one string: exactly two safe slugs. */
+  const repoFullSchema = z.string().refine((v) => {
+    const parts = v.split("/");
+    return parts.length === 2 && parts.every(isSafeGhSlug);
+  }, "not an owner/repo name");
+
+  const COMMIT_MESSAGE_LINE_MAX = 200;
+
+  /** The first line of a commit message, clipped to 200 characters (code points, not UTF-16 halves). */
+  function firstLine(message: unknown): string {
+    const line = typeof message === "string" ? (message.split("\n")[0] ?? "").trimEnd() : "";
+    return [...line].slice(0, COMMIT_MESSAGE_LINE_MAX).join("");
+  }
+
+  /**
+   * Only what a tag's preview needs of `GET /commits/{ref}`
+   * (https://docs.github.com/en/rest/commits/commits#get-a-commit): the sha, the first line of the
+   * message, the author's name and date, and the parents' shas. The file list and diff are dropped.
+   */
+  function projectCommit(raw: unknown): Record<string, unknown> {
+    const c = raw as {
+      sha?: unknown;
+      commit?: { message?: unknown; author?: { name?: unknown; date?: unknown } };
+      parents?: unknown;
+    } | null;
+    if (c === null || typeof c.sha !== "string") throw new Error("GitHub returned no commit");
+    const parents = Array.isArray(c.parents)
+      ? c.parents
+          .map((p) => (p as { sha?: unknown } | null)?.sha)
+          .filter((s): s is string => typeof s === "string")
+      : [];
+    return {
+      sha: c.sha,
+      message: firstLine(c.commit?.message),
+      authorName: c.commit?.author?.name,
+      authorDate: c.commit?.author?.date,
+      parents,
+    };
+  }
+
+  reg(
+    "github_commit_get",
+    "Get one commit by sha, branch or tag: {sha, message (first line, at most 200 characters), authorName, authorDate, parents:[sha]}. The before-state of github_tag_create. A bare name is tried as a branch, then a tag; an unknown ref is 'commit not found'.",
+    z.object({ repoFull: repoFullSchema, ref: gitRefSchema }),
+    async (parsed) => {
+      const token = requireProcessEnv("GITHUB_PAT");
+      const [owner = "", repo = ""] = parsed.repoFull.split("/");
+      for (const name of commitRefCandidates(parsed.ref)) {
+        const segments = name.split("/").map(encodeURIComponent).join("/");
+        const res = await ghFetch(token, `${ghRepoPath(owner, repo)}/commits/${segments}`); // NOSONAR S9382: candidates are tried in order and the first hit wins.
+        // A missing ref is a 404, or a 422 "No commit found for SHA" (the commits endpoint's reply
+        // for a name it cannot resolve); a 422 with any other message is a real error.
+        if (res.status === 404 || (res.status === 422 && /no commit found/i.test(res.text)))
+          continue;
+        if (!res.ok) throw new Error(`GitHub ${String(res.status)}: ${res.text.slice(0, 300)}`);
+        return jsonResult(projectCommit(res.json));
+      }
+      throw new Error("commit not found");
+    },
+  );
+
   const githubBranchCreateSchema = repoSlugArgs.extend({
     branch: gitRefSchema,
     fromRef: gitRefSchema,
@@ -488,4 +597,187 @@ export function registerGithubTools(
         }),
       ),
   );
+
+  // -------------------------------------------------------------------------------------------
+  // Multi-file commit: github_files_get (read), github_commit_prepare (prepare), github_file_commit
+  // -------------------------------------------------------------------------------------------
+
+  /** The commit a branch points at now. A bare name is NOT tried as a tag: the commit lands on a branch. */
+  async function branchHead(
+    token: string,
+    p: { owner: string; repo: string; branch: string },
+  ): Promise<string> {
+    return (await resolveCommitSha(token, p.owner, p.repo, `heads/${p.branch}`)).sha;
+  }
+
+  /** What a read tool reports for one file; `content` only for text. */
+  function fileView(f: GithubFileRead): Record<string, unknown> {
+    if (!f.exists) return { path: f.path, exists: false };
+    const base = { path: f.path, exists: true, mode: f.mode, sha: f.sha, size: f.size };
+    if (f.kind === "text") return { ...base, content: f.content };
+    return { ...base, withheld: f.kind };
+  }
+
+  const READ_LIMIT = COMMIT_MAX_COMBINED_BYTES;
+
+  reg(
+    "github_files_get",
+    'Read up to 50 files at a branch, tag or commit: {ref, headSha, files:[{path, exists, mode, sha, size, content}]}. A binary, symlink, submodule or over-192-KiB file is reported with its sha and `withheld` instead of content, and the content of all the files together is capped at 192 KiB: the first file that does not fit, and every file after it, is reported with `withheld: "budget"` and no content.',
+    repoSlugArgs.extend({
+      ref: gitRefSchema,
+      paths: z.array(commitFilePathSchema).min(1).max(50),
+    }),
+    async (parsed) => {
+      const token = requireProcessEnv("GITHUB_PAT");
+      const { sha } = await resolveCommitSha(token, parsed.owner, parsed.repo, parsed.ref);
+      const { files } = await readGithubFilesAt(
+        token,
+        parsed.owner,
+        parsed.repo,
+        sha,
+        parsed.paths,
+        { withContent: true, maxReadBytes: READ_LIMIT, totalBudget: READ_LIMIT },
+      );
+      return jsonResult({ ref: parsed.ref, headSha: sha, files: files.map(fileView) });
+    },
+  );
+
+  const githubCommitInputSchema = repoSlugArgs.extend({
+    branch: gitRefSchema,
+    files: commitFilesSchema,
+  });
+
+  registerPrepareTool(
+    "github_commit_prepare",
+    { scopeTargetOf: repoScope },
+    `Read the state a github_file_commit is bound to: the branch head and, for each file, whether it exists, its mode, blob sha and current content. Refuses (no truncation) a commit that touches more than ${String(COMMIT_MAX_FILES)} files or whose old and new content together exceed 192 KiB, and any existing file that is not a text file. Takes the commit's own owner, repo, branch and files.`,
+    githubCommitInputSchema,
+    async (parsed) => {
+      assertCommitFiles(parsed.files);
+      const token = requireProcessEnv("GITHUB_PAT");
+      const head = await branchHead(token, parsed);
+      const { files: read } = await readGithubFilesAt(
+        token,
+        parsed.owner,
+        parsed.repo,
+        head,
+        parsed.files.map((f) => f.path),
+        { withContent: true, maxReadBytes: READ_LIMIT },
+      );
+      let oldBytes = 0;
+      const files = read.map((f) => {
+        if (!f.exists) return { path: f.path, exists: false, mode: "100644" };
+        if (f.kind !== "text") throw notOverwritable(f.path);
+        oldBytes += f.size;
+        return { path: f.path, exists: true, mode: f.mode, oldSha: f.sha, oldContent: f.content };
+      });
+      assertCombinedSize(oldBytes, parsed.files);
+      return jsonResult({ headSha: head, files });
+    },
+  );
+
+  registerWriteTool(
+    "github_file_commit",
+    {
+      mutates: "github.file.commit",
+      // A commit moves a branch; the inverse needs the head and the old blob shas, captured first.
+      recoverable: false,
+      capturePreState: async (parsed) => {
+        const token = requireProcessEnv("GITHUB_PAT");
+        const head = await branchHead(token, parsed);
+        const { files: read } = await readGithubFilesAt(
+          token,
+          parsed.owner,
+          parsed.repo,
+          head,
+          parsed.files.map((f) => f.path),
+          { withContent: false, maxReadBytes: READ_LIMIT },
+        );
+        return {
+          branch: parsed.branch,
+          headSha: head,
+          files: read.map((f) => ({ path: f.path, oldSha: f.exists ? f.sha : null })),
+        };
+      },
+      scopeTargetOf: repoScope,
+    },
+    "Commit one or more whole text files to a branch as ONE commit, but only if the branch head is still expectedHeadSha (the head the owner approved); never forced. Existing files keep their mode, new files are 100644. No deletes, no mode changes.",
+    githubCommitInputSchema.extend({
+      message: z.string().min(1).max(5000),
+      expectedHeadSha: fullShaSchema,
+    }),
+    async (parsed) => {
+      assertCommitFiles(parsed.files);
+      const token = requireProcessEnv("GITHUB_PAT");
+      const expected = parsed.expectedHeadSha.toLowerCase();
+      // 1. The head AGAIN: the approval was for this commit, not for whatever the branch became.
+      const head = await branchHead(token, parsed);
+      if (head !== expected) {
+        throw new Error(`branch head is ${head}, not the approved ${expected}`);
+      }
+      // 2. Existing modes and sizes from the tree at that head; the blob is read too, only to refuse a
+      // binary file (its content is not otherwise needed).
+      const { treeSha: baseTree, files: existing } = await readGithubFilesAt(
+        token,
+        parsed.owner,
+        parsed.repo,
+        head,
+        parsed.files.map((f) => f.path),
+        { withContent: true, maxReadBytes: READ_LIMIT },
+      );
+      let oldBytes = 0;
+      const modes = new Map<string, string>();
+      for (const f of existing) {
+        if (!f.exists) continue;
+        if (f.kind !== "text") throw notOverwritable(f.path);
+        oldBytes += f.size;
+        modes.set(f.path, f.mode);
+      }
+      assertCombinedSize(oldBytes, parsed.files);
+      const base = ghRepoPath(parsed.owner, parsed.repo);
+      const post = async (path: string, body: unknown): Promise<Record<string, unknown>> => {
+        const res = await ghFetch(token, `${base}${path}`, jsonInit("POST", body));
+        const json = res.json as Record<string, unknown> | null;
+        if (!res.ok || json === null || typeof json["sha"] !== "string") {
+          throw new Error(`GitHub ${String(res.status)}: ${res.text.slice(0, 300)}`);
+        }
+        return json;
+      };
+      // 3. One blob per file, then one tree on top of the head's tree, then one commit.
+      const treeEntries: { path: string; mode: string; type: "blob"; sha: string }[] = [];
+      for (const f of parsed.files) {
+        const blob = await post("/git/blobs", { content: f.content, encoding: "utf-8" }); // NOSONAR S9382: sequential on purpose; a failed blob stops the commit before any tree exists.
+        treeEntries.push({
+          path: f.path,
+          mode: modes.get(f.path) ?? "100644",
+          type: "blob",
+          sha: String(blob["sha"]),
+        });
+      }
+      const tree = await post("/git/trees", { base_tree: baseTree, tree: treeEntries });
+      const commit = await post("/git/commits", {
+        message: parsed.message,
+        tree: String(tree["sha"]),
+        parents: [head],
+      });
+      // 4. Move the branch, fast-forward only. A moved head or a refusal is a 409 or a 422.
+      const refPath = parsed.branch.split("/").map(encodeURIComponent).join("/");
+      const moved = await ghFetch(
+        token,
+        `${base}/git/refs/heads/${refPath}`,
+        jsonInit("PATCH", { sha: String(commit["sha"]), force: false }),
+      );
+      if (!moved.ok) {
+        const why =
+          moved.status === 409 || moved.status === 422 ? "head moved or ref update refused: " : "";
+        throw new Error(`GitHub ${String(moved.status)}: ${why}${moved.text.slice(0, 300)}`);
+      }
+      return jsonResult({
+        ok: true,
+        commitSha: String(commit["sha"]),
+        branch: parsed.branch,
+        parent: head,
+      });
+    },
+  );
 }

package/connectors/gitlab/src/gitlab-files.ts

@@ -0,0 +1,213 @@
+/**
+ * gitlab-files: read files at a commit through the Repository Files API, for the batch read
+ * (`gitlab_files_get`), the prepare tool (`gitlab_commit_prepare`) and the commit
+ * (`gitlab_commit_create`), so what the owner was shown and what is committed come from one reader.
+ *
+ * Sources (https://docs.gitlab.com/api/{repository_files,branches,commits}/):
+ * - `GET /projects/:id/repository/files/:file_path?ref=` returns `content` (base64), `blob_id`,
+ *   `commit_id`, `last_commit_id`, `execute_filemode` and `size`; the file path is fully URL-encoded,
+ *   slashes as `%2F` and, in the page's examples, dots as `%2E` (`lib%2Fclass%2Erb`).
+ * - `GET /projects/:id/repository/branches/:branch` returns `commit.id`.
+ * - `GET /projects/:id/repository/commits/:sha` accepts a hash, a branch or a tag name; `id` is the
+ *   full hash.
+ */
+
+import { decodeBase64Text, notOverwritable } from "../../../shared/commit-files.ts";
+import type { RestFetchResult } from "../../../shared/rest-tool-kit.ts";
+
+/** A GET against the GitLab API: a path relative to the API base, already carrying the token. */
+export type GitlabGet = (path: string) => Promise<RestFetchResult>;
+
+const FULL_SHA = /^[0-9a-f]{40}$/i;
+
+export type GitlabFileRead =
+  | { readonly path: string; readonly exists: false }
+  | {
+      readonly path: string;
+      readonly exists: true;
+      readonly kind: "text";
+      readonly lastCommitId: string;
+      readonly executable: boolean;
+      readonly size: number;
+      readonly content: string;
+    }
+  | {
+      readonly path: string;
+      readonly exists: true;
+      readonly kind: "binary" | "too-large" | "budget";
+      readonly lastCommitId: string;
+      readonly executable: boolean;
+      readonly size: number;
+    };
+
+/** A file path as GitLab's API wants it: `encodeURIComponent`, plus every `.` as `%2E`. */
+export function encodeFilePath(path: string): string {
+  return encodeURIComponent(path).replaceAll(".", "%2E");
+}
+
+function fail(res: { status: number; text: string }): never {
+  throw new Error(`GitLab ${String(res.status)}: ${res.text.slice(0, 300)}`);
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** The commit a BRANCH points at now. */
+export async function branchHead(get: GitlabGet, project: string, branch: string): Promise<string> {
+  const res = await get(`/projects/${project}/repository/branches/${encodeURIComponent(branch)}`);
+  if (res.status === 404) throw new Error(`GitLab 404: branch "${branch}" not found`);
+  if (!res.ok) fail(res);
+  const commit = isRecord(res.json) && isRecord(res.json["commit"]) ? res.json["commit"] : {};
+  const id = commit["id"];
+  if (typeof id !== "string" || !FULL_SHA.test(id))
+    throw new Error("GitLab returned no branch head");
+  return id.toLowerCase();
+}
+
+/** The commit a branch, tag or sha names. */
+export async function refCommit(get: GitlabGet, project: string, ref: string): Promise<string> {
+  const res = await get(`/projects/${project}/repository/commits/${encodeURIComponent(ref)}`);
+  if (res.status === 404) throw new Error(`GitLab 404: ref "${ref}" not found`);
+  if (!res.ok) fail(res);
+  const id = isRecord(res.json) ? res.json["id"] : undefined;
+  if (typeof id !== "string" || !FULL_SHA.test(id)) throw new Error("GitLab returned no commit id");
+  return id.toLowerCase();
+}
+
+/** Entries per tree page (the API's own maximum is not stated on its page; 100 is what it is asked for). */
+const TREE_PAGE = 100;
+/** A directory of more than this many pages (5,000 entries) is refused rather than guessed about. */
+const TREE_MAX_PAGES = 50;
+
+type TreeEntry = { readonly path: string; readonly type: string; readonly mode: string };
+
+/**
+ * The entries of directory `dir` ("" for the root) at `sha`, paged until a short page.
+ * `GET /projects/:id/repository/tree?path=&ref=&per_page=&page=`; each entry has `id, name, path, mode,
+ * type` (https://docs.gitlab.com/api/repositories/). A 404 is a directory that does not exist.
+ */
+async function listTree(
+  get: GitlabGet,
+  project: string,
+  sha: string,
+  dir: string,
+): Promise<TreeEntry[]> {
+  const out: TreeEntry[] = [];
+  for (let page = 1; page <= TREE_MAX_PAGES; page++) {
+    const q = new URLSearchParams();
+    if (dir !== "") q.set("path", dir);
+    q.set("ref", sha);
+    q.set("per_page", String(TREE_PAGE));
+    q.set("page", String(page));
+    const res = await get(`/projects/${project}/repository/tree?${q.toString()}`); // NOSONAR S9382: pages are read in order until a short one.
+    if (res.status === 404) return out;
+    if (!res.ok) fail(res);
+    const entries = Array.isArray(res.json) ? res.json : [];
+    for (const e of entries) {
+      if (isRecord(e) && typeof e["path"] === "string" && typeof e["type"] === "string") {
+        out.push({
+          path: e["path"],
+          type: e["type"],
+          mode: typeof e["mode"] === "string" ? e["mode"] : "",
+        });
+      }
+    }
+    if (entries.length < TREE_PAGE) return out;
+  }
+  throw new Error(`GitLab directory "${dir}" has too many entries to check`);
+}
+
+/**
+ * Refuse a target the commit tools must not write over. The Repository Files API reports no mode, so
+ * a symlink reads as a text file holding its target; the tree listing does report one. For each
+ * distinct parent directory (sorted, one listing per directory, paged) every target path must be
+ * either absent or a plain `blob` whose mode is not 120000 (symlink) or 160000 (submodule); a
+ * directory or a submodule where a file is expected is refused too, and so is an existing file the
+ * listing does not show (it cannot be verified). Fail closed, before any write.
+ */
+export async function assertRegularTargets(
+  get: GitlabGet,
+  project: string,
+  sha: string,
+  files: readonly { readonly path: string; readonly exists: boolean }[],
+): Promise<void> {
+  const dirOf = (p: string): string => (p.includes("/") ? p.slice(0, p.lastIndexOf("/")) : "");
+  const dirs = [...new Set(files.map((f) => dirOf(f.path)))].sort((a, b) => a.localeCompare(b));
+  const byPath = new Map<string, TreeEntry>();
+  for (const dir of dirs) {
+    for (const entry of await listTree(get, project, sha, dir)) byPath.set(entry.path, entry); // NOSONAR S9382
+  }
+  for (const f of files) {
+    const entry = byPath.get(f.path);
+    if (entry === undefined) {
+      if (f.exists) throw notOverwritable(f.path);
+      continue;
+    }
+    if (entry.type !== "blob" || entry.mode === "120000" || entry.mode === "160000") {
+      throw notOverwritable(f.path);
+    }
+  }
+}
+
+/**
+ * Read `paths` at the commit `sha`; a 404 for a path is `exists: false`. With `totalBudget`, the
+ * content of all the files together is capped (the files API returns a file whole, so a withheld file
+ * has still been transferred; only its content is dropped from the result).
+ */
+export async function readGitlabFilesAt(
+  get: GitlabGet,
+  project: string,
+  sha: string,
+  paths: readonly string[],
+  maxReadBytes: number,
+  totalBudget?: number,
+): Promise<GitlabFileRead[]> {
+  const out: GitlabFileRead[] = [];
+  let used = 0;
+  let exhausted = false;
+  for (const path of paths) {
+    const query = new URLSearchParams({ ref: sha }).toString();
+    const res = await get(`/projects/${project}/repository/files/${encodeFilePath(path)}?${query}`); // NOSONAR S9382: sequential on purpose; paths are few and an error stops the read.
+    if (res.status === 404) {
+      out.push({ path, exists: false });
+      continue;
+    }
+    if (!res.ok) fail(res);
+    const f = isRecord(res.json) ? res.json : {};
+    const lastCommitId = f["last_commit_id"];
+    const content = f["content"];
+    if (typeof lastCommitId !== "string" || typeof content !== "string") {
+      throw new Error(`GitLab returned an unreadable file for ${path}`);
+    }
+    const size = typeof f["size"] === "number" ? f["size"] : 0;
+    const executable = f["execute_filemode"] === true;
+    if (size > maxReadBytes) {
+      out.push({ path, exists: true, kind: "too-large", lastCommitId, executable, size });
+      continue;
+    }
+    // The combined content of all the files is capped. The first file that does not fit, and every
+    // one after it, is reported `budget` with its metadata and no content.
+    if (totalBudget !== undefined && (exhausted || used + size > totalBudget)) {
+      exhausted = true;
+      out.push({ path, exists: true, kind: "budget", lastCommitId, executable, size });
+      continue;
+    }
+    used += size;
+    const decoded = decodeBase64Text(content);
+    out.push(
+      "binary" in decoded
+        ? { path, exists: true, kind: "binary", lastCommitId, executable, size }
+        : {
+            path,
+            exists: true,
+            kind: "text",
+            lastCommitId,
+            executable,
+            size,
+            content: decoded.text,
+          },
+    );
+  }
+  return out;
+}