@nimbus-dev/connectors 0.7.0 → 0.8.0

package/connectors/gitlab/src/tools.ts

@@ -1,6 +1,17 @@
 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";
@@ -21,6 +32,14 @@ import {
   type RestFetchResult,
   toRestFetchResult,
 } from "../../../shared/rest-tool-kit.ts";
+import {
+  assertRegularTargets,
+  branchHead,
+  type GitlabFileRead,
+  type GitlabGet,
+  readGitlabFilesAt,
+  refCommit,
+} from "./gitlab-files.ts";
 
 /**
  * A project reference that reaches a URL path: a numeric id, or `/`-separated segments of
@@ -163,6 +182,9 @@ export const GITLAB_TOOL_NAMES = [
   "gitlab_job_log_tail",
   "gitlab_pipeline_retry",
   "gitlab_pipeline_cancel",
+  "gitlab_files_get",
+  "gitlab_commit_prepare",
+  "gitlab_commit_create",
 ] as const;
 
 export function registerGitlabTools(
@@ -182,6 +204,16 @@ export function registerGitlabTools(
     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: "gitlab",
+    scopeEnv: "NIMBUS_MCP_GITLAB_WRITE_SCOPE",
+    scopeKinds: ["repo"],
+  });
+
   /**
    * Standard GitLab tool, read or write: `token → glFetch(buildUrl[, buildInit]) →
    * mcpJsonResultIfOk("GitLab", res)`. `buildUrl` returns the relative path (or absolute URL) and
@@ -707,4 +739,198 @@ export function registerGitlabTools(
     "Cancel a pipeline.",
     "cancel",
   );
+
+  // -------------------------------------------------------------------------------------------
+  // Multi-file commit: gitlab_files_get (read), gitlab_commit_prepare (prepare), gitlab_commit_create
+  // -------------------------------------------------------------------------------------------
+
+  /** Bound GETs: the token is read at call time, before the first request. */
+  const gitlabGet = (): GitlabGet => {
+    const token = requireProcessEnv("GITLAB_PAT");
+    return (path) => glFetch(token, path);
+  };
+
+  const READ_LIMIT = COMMIT_MAX_COMBINED_BYTES;
+
+  /** What a read tool reports for one file; `content` only for text. */
+  function fileView(f: GitlabFileRead): Record<string, unknown> {
+    if (!f.exists) return { path: f.path, exists: false };
+    const base = {
+      path: f.path,
+      exists: true,
+      lastCommitId: f.lastCommitId,
+      executable: f.executable,
+      size: f.size,
+    };
+    return f.kind === "text" ? { ...base, content: f.content } : { ...base, withheld: f.kind };
+  }
+
+  reg(
+    "gitlab_files_get",
+    'Read up to 50 files at a branch, tag or commit: {ref, headSha, files:[{path, exists, lastCommitId, executable, size, content}]}. A binary or over-192-KiB file is reported with `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.',
+    projectPathArg.extend({
+      ref: gitlabRefSchema,
+      paths: z.array(commitFilePathSchema).min(1).max(50),
+    }),
+    async (parsed) => {
+      const get = gitlabGet();
+      const project = encodeURIComponent(parsed.projectPath);
+      const sha = await refCommit(get, project, parsed.ref);
+      const files = await readGitlabFilesAt(
+        get,
+        project,
+        sha,
+        parsed.paths,
+        READ_LIMIT,
+        READ_LIMIT,
+      );
+      return jsonResult({ ref: parsed.ref, headSha: sha, files: files.map(fileView) });
+    },
+  );
+
+  const gitlabCommitInputSchema = projectPathArg.extend({
+    branch: gitlabRefSchema,
+    files: commitFilesSchema,
+  });
+
+  const repoScopeOf = (p: { projectPath: string }): { kind: string; value: string } => ({
+    kind: "repo",
+    value: p.projectPath,
+  });
+
+  registerPrepareTool(
+    "gitlab_commit_prepare",
+    { scopeTargetOf: repoScopeOf },
+    `Read the state a gitlab_commit_create is bound to: the branch head and, for each file, whether it exists, its last_commit_id, whether it is executable and its 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 projectPath, branch and files.`,
+    gitlabCommitInputSchema,
+    async (parsed) => {
+      assertCommitFiles(parsed.files);
+      const get = gitlabGet();
+      const project = encodeURIComponent(parsed.projectPath);
+      const head = await branchHead(get, project, parsed.branch);
+      const read = await readGitlabFilesAt(
+        get,
+        project,
+        head,
+        parsed.files.map((f) => f.path),
+        READ_LIMIT,
+      );
+      // The files API reports no mode, so a symlink looks like a text file: read the tree entries and
+      // refuse a symlink, a submodule or a directory before anything is written.
+      await assertRegularTargets(get, project, head, read);
+      let oldBytes = 0;
+      const files = read.map((f) => {
+        if (!f.exists) return { path: f.path, exists: false };
+        if (f.kind !== "text") throw notOverwritable(f.path);
+        oldBytes += f.size;
+        return {
+          path: f.path,
+          exists: true,
+          lastCommitId: f.lastCommitId,
+          executable: f.executable,
+          oldContent: f.content,
+        };
+      });
+      assertCombinedSize(oldBytes, parsed.files);
+      return jsonResult({ headSha: head, files });
+    },
+  );
+
+  registerWriteTool(
+    "gitlab_commit_create",
+    {
+      mutates: "gitlab.commit.create",
+      // A commit moves a branch; the inverse needs the head and each file's last commit, captured first.
+      recoverable: false,
+      capturePreState: async (parsed) => {
+        const get = gitlabGet();
+        const project = encodeURIComponent(parsed.projectPath);
+        const head = await branchHead(get, project, parsed.branch);
+        const read = await readGitlabFilesAt(
+          get,
+          project,
+          head,
+          parsed.files.map((f) => f.path),
+          READ_LIMIT,
+        );
+        return {
+          branch: parsed.branch,
+          headSha: head,
+          files: read.map((f) => ({
+            path: f.path,
+            lastCommitId: f.exists ? f.lastCommitId : null,
+          })),
+        };
+      },
+      scopeTargetOf: repoScopeOf,
+    },
+    "Commit one or more whole text files to a branch as ONE commit. The branch head is checked against expectedHeadSha (the head the owner approved) before the write, but GitLab has no head-conditional commit, so that check is NOT atomic with the write. What protects the files is last_commit_id: each update carries the file's last_commit_id read at the approved head, and GitLab refuses it if that file changed since. A commit to OTHER files that lands between the check and the write is not detected before the write; movedHead: true in the result reports it afterwards (the new commit's parent is not the approved head). Never forced.",
+    gitlabCommitInputSchema.extend({
+      message: z.string().min(1).max(5000),
+      expectedHeadSha: fullShaSchema,
+    }),
+    async (parsed) => {
+      assertCommitFiles(parsed.files);
+      const get = gitlabGet();
+      const token = requireProcessEnv("GITLAB_PAT");
+      const project = encodeURIComponent(parsed.projectPath);
+      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(get, project, parsed.branch);
+      if (head !== expected) {
+        throw new Error(`branch head is ${head}, not the approved ${expected}`);
+      }
+      // 2. Each existing file AT that head: its last_commit_id goes on the update action.
+      const read = await readGitlabFilesAt(
+        get,
+        project,
+        head,
+        parsed.files.map((f) => f.path),
+        READ_LIMIT,
+      );
+      // The files API reports no mode, so a symlink looks like a text file: read the tree entries and
+      // refuse a symlink, a submodule or a directory before anything is written.
+      await assertRegularTargets(get, project, head, read);
+      let oldBytes = 0;
+      const actions = parsed.files.map((f, i) => {
+        const existing = read[i];
+        if (existing === undefined || !existing.exists) {
+          return { action: "create", file_path: f.path, content: f.content, encoding: "text" };
+        }
+        if (existing.kind !== "text") throw notOverwritable(f.path);
+        oldBytes += existing.size;
+        return {
+          action: "update",
+          file_path: f.path,
+          content: f.content,
+          encoding: "text",
+          last_commit_id: existing.lastCommitId,
+        };
+      });
+      assertCombinedSize(oldBytes, parsed.files);
+      // 3. One commit, no force, no start_branch.
+      const res = await glFetch(
+        token,
+        `/projects/${project}/repository/commits`,
+        jsonBody("POST", { branch: parsed.branch, commit_message: parsed.message, actions }),
+      );
+      if (!res.ok) {
+        throw new Error(`GitLab ${String(res.status)}: ${res.text.slice(0, 300)}`);
+      }
+      const made = (res.json ?? {}) as { id?: unknown; parent_ids?: unknown; web_url?: unknown };
+      // The head can move between step 1 and this POST (the API has no head-conditional commit):
+      // say so when the new commit's parent is not the head that was approved.
+      const movedHead = !(
+        Array.isArray(made.parent_ids) && made.parent_ids.map(String).includes(expected)
+      );
+      return jsonResult({
+        ok: true,
+        commitId: made.id,
+        branch: parsed.branch,
+        parent: expected,
+        webUrl: made.web_url,
+        movedHead,
+      });
+    },
+  );
 }

package/connectors/kubernetes/src/tools.ts

@@ -2,21 +2,15 @@ import { z } from "zod";
 import { cliArg } from "../../../shared/cli-json-kit.ts";
 import type { ConsentServer } from "../../../shared/consent-kit.ts";
 import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { isKubectlNotFound, projectDeployment } from "../../../shared/k8s-deployment-view.ts";
 import {
   createRegisterSimpleTool,
   createZodToolRegistrar,
   mcpJsonResult as jsonResult,
 } from "../../../shared/mcp-tool-kit.ts";
+import { withPrivateKubeconfig } from "../../../shared/private-kubeconfig.ts";
 import { runCliJsonThrowing, runCliOkThrowing } from "../../../shared/run-cli-json.ts";
 
-function requireKubeconfigPath(): string {
-  const p = process.env["KUBECONFIG"]?.trim();
-  if (p === undefined || p === "") {
-    throw new Error("KUBECONFIG env must be set to a kubeconfig file path");
-  }
-  return p;
-}
-
 function kubectlBase(): string[] {
   const args = ["kubectl"];
   const ctx = process.env["KUBE_CONTEXT"]?.trim();
@@ -26,13 +20,17 @@ function kubectlBase(): string[] {
   return args;
 }
 
-function kubeEnv(): Record<string, string | undefined> {
-  return { KUBECONFIG: requireKubeconfigPath() };
+/**
+ * Run `body` against a private copy of the kubeconfig `KUBECONFIG` names (shared/private-kubeconfig.ts):
+ * one tool call, one copy, so a call can neither change the owner's file nor race another call.
+ */
+function withKube<T>(body: (env: { readonly KUBECONFIG: string }) => Promise<T>): Promise<T> {
+  return withPrivateKubeconfig({ source: process.env["KUBECONFIG"] ?? "" }, body);
 }
 
-async function kubectlJson(rest: string[]): Promise<unknown> {
+function kubectlJson(rest: string[]): Promise<unknown> {
   const cmd = [...kubectlBase(), ...rest, "-o", "json"];
-  return runCliJsonThrowing(cmd, kubeEnv());
+  return withKube((env) => runCliJsonThrowing(cmd, env));
 }
 
 const optionalNamespaceSchema = z.object({ namespace: cliArg.optional() });
@@ -46,6 +44,7 @@ async function k8sListNamespacedResource(p: { namespace?: string | undefined },
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const KUBERNETES_TOOL_NAMES = [
   "k8s_pod_list",
+  "k8s_deployment_get",
   "k8s_deployment_list",
   "k8s_event_list",
   "k8s_rollout_restart",
@@ -76,6 +75,27 @@ export function registerKubernetesTools(
     (p) => k8sListNamespacedResource(p, "pods"),
   );
 
+  reg(
+    "k8s_deployment_get",
+    "Get one deployment's state: {name, namespace, replicas, readyReplicas, generation, observedGeneration, restartedAt, images}. The before-state of a restart or a scale.",
+    z.object({ namespace: cliArg.optional(), name: cliArg }),
+    async (p) => {
+      let data: unknown;
+      try {
+        // kubectlJson builds on kubectlBase(), so the configured KUBE_CONTEXT applies as it does
+        // to every other call here.
+        data = await kubectlJson(["get", "deployment", p.name, "-n", p.namespace ?? "default"]);
+      } catch (e) {
+        // Exit code of a missing object is not documented, so NotFound is read from the message.
+        if (e instanceof Error && isKubectlNotFound(e.message)) {
+          throw new Error("deployment not found", { cause: e });
+        }
+        throw e;
+      }
+      return jsonResult(projectDeployment(data));
+    },
+  );
+
   reg("k8s_deployment_list", "List deployments in a namespace.", optionalNamespaceSchema, (p) =>
     k8sListNamespacedResource(p, "deployments"),
   );
@@ -100,7 +120,7 @@ export function registerKubernetesTools(
     async (p) => {
       const ns = p.namespace ?? "default";
       const cmd = [...kubectlBase(), "rollout", "restart", p.resourceType, p.name, "-n", ns];
-      await runCliOkThrowing(cmd, kubeEnv());
+      await withKube((env) => runCliOkThrowing(cmd, env));
       return jsonResult({ ok: true });
     },
   );
@@ -124,7 +144,7 @@ export function registerKubernetesTools(
     async (p) => {
       const ns = p.namespace ?? "default";
       const cmd = [...kubectlBase(), "delete", "pod", p.podName, "-n", ns];
-      await runCliOkThrowing(cmd, kubeEnv());
+      await withKube((env) => runCliOkThrowing(cmd, env));
       return jsonResult({ ok: true });
     },
   );
@@ -153,7 +173,7 @@ export function registerKubernetesTools(
         ns,
         `--replicas=${String(p.replicas)}`,
       ];
-      await runCliOkThrowing(cmd, kubeEnv());
+      await withKube((env) => runCliOkThrowing(cmd, env));
       return jsonResult({ ok: true });
     },
   );

package/connectors/snowflake/src/server.ts

@@ -2,8 +2,9 @@ import { z } from "zod";
 import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
 import { cursorListInputSchema } from "../../../shared/cursor-list-tool.ts";
 import { requiredEnv } from "../../../shared/env-json-api.ts";
+import { guardedFetch } from "../../../shared/guarded-fetch.ts";
 import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
-import { fetchWithTimeout, mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
 import {
   runReadOnlyMcpConnector,
   type ZodToolRegistrar,
@@ -26,7 +27,9 @@ function authHeader(): Record<string, string> {
  */
 async function executeStatement(statement: string): Promise<unknown> {
   const url = `https://${requiredEnv("SNOWFLAKE_ACCOUNT")}.snowflakecomputing.com/api/v2/statements`;
-  const res = await fetchWithTimeout(url, {
+  // guardedFetch: the Bearer token must never follow a redirect to another origin, and a redirect
+  // on this POST (which may be a write) is refused rather than replayed.
+  const res = await guardedFetch("Snowflake", url, {
     method: "POST",
     headers: authHeader(),
     body: JSON.stringify({ statement, timeout: 60 }),
@@ -55,6 +58,23 @@ function sfLiteral(v: string): string {
   return `'${v.replaceAll("'", "''")}'`;
 }
 
+/** The parts of `db.schema.name`, each already vetted by {@link assertSfIdentifier}. */
+function splitObjectName(object: string): { db: string; schema: string; name: string } {
+  // The name is placed in string literals, where Snowflake reads a backslash as an escape.
+  if (object.includes("\\")) throw new Error("object must not contain a backslash");
+  const parts = assertSfIdentifier(object, "object").split(".");
+  const [db, schema, name] = parts;
+  if (parts.length !== 3 || db === undefined || schema === undefined || name === undefined) {
+    throw new Error("object must be a fully qualified name: database.schema.name");
+  }
+  return { db, schema, name };
+}
+
+/** An identifier part's name as Snowflake stores it: a quoted part verbatim, else upper-cased. */
+function storedName(part: string): string {
+  return part.startsWith('"') ? part.slice(1, -1) : part.toUpperCase();
+}
+
 const TABLES_SQL =
   "SELECT table_catalog AS database_name, table_schema AS schema_name, table_name, " +
   "row_count, last_altered FROM information_schema.tables WHERE table_schema <> 'INFORMATION_SCHEMA'";
@@ -108,6 +128,43 @@ function tableKey(row: Record<string, unknown>): string {
   return `${db}.${schema}.${table}`;
 }
 
+/**
+ * The metadata a comment or tag change is previewed against: the object's COMMENT and its tags,
+ * direct and inherited. Two statements, both live (never ACCOUNT_USAGE, whose TAG_REFERENCES lags
+ * up to 120 minutes):
+ * - `SHOW TABLES|VIEWS LIKE '<name>' IN SCHEMA db.schema` for the `comment` column. The LIKE pattern
+ *   supports the wildcards % and _ and the page documents no escape for them
+ *   (https://docs.snowflake.com/en/sql-reference/sql/show-tables), so none is relied on: the pattern
+ *   only NARROWS the rows, and the object is picked by exact name in code.
+ * - `INFORMATION_SCHEMA.TAG_REFERENCES('db.schema.name', 'TABLE')`; the domain TABLE covers views
+ *   (https://docs.snowflake.com/en/sql-reference/functions/tag_references).
+ * Metadata only: no row data is ever selected.
+ */
+async function objectMetadata(
+  objectType: "table" | "view",
+  object: string,
+): Promise<Record<string, unknown>> {
+  const { db, schema, name } = splitObjectName(object);
+  const verb = objectType === "view" ? "VIEWS" : "TABLES";
+  const shown = rowsFromStatementsResponse(
+    await executeStatement(
+      `SHOW ${verb} LIKE ${sfLiteral(name.startsWith('"') ? name.slice(1, -1) : name)} IN SCHEMA ${db}.${schema}`,
+    ),
+  );
+  const wanted = storedName(name);
+  const row = shown.find((r) => r["name"] === wanted);
+  if (row === undefined) throw new Error(`Snowflake ${objectType} not found: ${object}`);
+  const tagRows = rowsFromStatementsResponse(
+    await executeStatement(
+      `SELECT tag_name, tag_value FROM TABLE(${db}.INFORMATION_SCHEMA.TAG_REFERENCES(${sfLiteral(object)}, 'TABLE'))`,
+    ),
+  );
+  const tags = tagRows
+    .map((t) => ({ name: String(t["tag_name"] ?? ""), value: t["tag_value"] ?? null }))
+    .sort((a, b) => a.name.localeCompare(b.name) || String(a.value).localeCompare(String(b.value)));
+  return { object, objectType, comment: row["comment"] ?? "", tags };
+}
+
 /**
  * Register the three read-only Snowflake tools on `reg`. Exported (rather than inlined into the
  * `runReadOnlyMcpConnector` call) so the tool handlers can be exercised in unit tests without
@@ -166,6 +223,16 @@ export function registerSnowflakeTools(reg: ZodToolRegistrar, server: unknown):
     },
   );
 
+  reg(
+    "snowflake_object_metadata_get",
+    "Get a table's or view's COMMENT and tags (direct and inherited) by fully qualified name: {object, objectType, comment, tags:[{name, value}]}. The before-state of snowflake_comment_set and snowflake_tag_set; objectType defaults to table. Metadata only, never row data.",
+    z.object({
+      objectType: z.enum(["table", "view"]).optional(),
+      object: z.string().min(1),
+    }),
+    async (p) => jsonResult(await objectMetadata(p.objectType ?? "table", p.object)),
+  );
+
   registerWriteTool(
     "snowflake_tag_set",
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-dev/connectors",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public"
   },

package/shared/audit-chain.ts

@@ -23,7 +23,9 @@ import { setTimeout as sleep } from "node:timers/promises";
  * `out of scope` and `budget exhausted` are decided before any prompt. `budget exhausted after
  * approval` follows an `accepted` entry: writes in flight together spent the last of the budget
  * while this one's prompt was open, so a human approved a write that then did not run. A client
- * that cannot prompt is never offered a write tool at all, so it leaves no entry.
+ * that cannot prompt is never offered a write tool at all, so it leaves no entry. `prepared` is a
+ * prepare-class tool (consent-kit.ts) that ran in scope: it changes nothing and spends no budget,
+ * but the operator can see what was read on a write's behalf.
  */
 export type AuditOutcome =
   | "requested"
@@ -31,7 +33,8 @@ export type AuditOutcome =
   | "declined"
   | "refused"
   | "executed"
-  | "failed";
+  | "failed"
+  | "prepared";
 
 export type AuditEntry = {
   readonly ts: string;

package/shared/commit-files.ts

@@ -0,0 +1,138 @@
+/**
+ * commit-files: what the multi-file commit tools (`github_file_commit`, `gitlab_commit_create`) and
+ * their prepare tools (`github_commit_prepare`, `gitlab_commit_prepare`) agree on, so the preview the
+ * owner approves and the commit that runs are bounded by the same rules.
+ *
+ * - Text files only, written whole: no deletes, no mode changes, no symlinks, no submodules.
+ * - At most {@link COMMIT_MAX_FILES} files, and the combined size of the old content that is shown and
+ *   the new content that is sent at most {@link COMMIT_MAX_COMBINED_BYTES}. The prepare tool REFUSES a
+ *   bigger commit rather than truncating: the preview never shows less than is sent, and its reply
+ *   stays under the gateway's 256 KiB cap.
+ */
+
+import { z } from "zod";
+
+export const COMMIT_MAX_FILES = 20;
+export const COMMIT_MAX_COMBINED_BYTES = 192 * 1024;
+
+const FULL_SHA = /^[0-9a-f]{40}$/i;
+
+/** A full 40-hex commit sha, any case. */
+export const fullShaSchema = z.string().regex(FULL_SHA, "a full 40-hex commit sha");
+
+/**
+ * A character the approval preview cannot be trusted to show as it is: any Unicode control (Cc, which
+ * includes DEL and the C1 range U+0080..U+009F), format character (Cf: bidi overrides, zero-width
+ * spaces, the byte-order mark), line or paragraph separator (Zl, Zp), or lone surrogate (Cs).
+ */
+const UNSHOWABLE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cs}]/u;
+
+/**
+ * Whether a path segment spells `.git` on a filesystem that folds it: NTFS and HFS+ ignore trailing
+ * dots and spaces and compare case-insensitively, and NTFS also knows the short name `GIT~1`. A
+ * segment that is nothing but dots and spaces is refused too, since it folds to the empty name.
+ */
+function isGitSpelling(segment: string): boolean {
+  const folded = segment.replace(/[. ]+$/u, "").toLowerCase();
+  return folded === "" || folded === ".git" || folded === "git~1";
+}
+
+/**
+ * Whether `path` is a repository-relative file path the commit tools accept: 1..1024 characters, no
+ * leading or trailing `/`, no `//`, no backslash, no unshowable character (see {@link UNSHOWABLE}),
+ * and no `.` or `..` segment or spelling of `.git` (see {@link isGitSpelling}). The path reaches a
+ * URL path or a JSON body, never a shell.
+ */
+export function isSafeCommitPath(path: string): boolean {
+  if (path.length < 1 || path.length > 1024) return false;
+  if (path.startsWith("/") || path.endsWith("/") || path.includes("//") || path.includes("\\")) {
+    return false;
+  }
+  if (UNSHOWABLE.test(path)) return false;
+  return path.split("/").every((seg) => seg !== "." && seg !== ".." && !isGitSpelling(seg));
+}
+
+export const commitFilePathSchema = z
+  .string()
+  .refine(isSafeCommitPath, "not a safe repository file path");
+
+/** One file of a commit: its path and its whole new text. */
+export const commitFileSchema = z.object({
+  path: commitFilePathSchema,
+  content: z.string(),
+});
+
+export type CommitFile = z.infer<typeof commitFileSchema>;
+
+/** The `files` field: 1..{@link COMMIT_MAX_FILES} entries. Uniqueness is checked by {@link assertCommitFiles}. */
+export const commitFilesSchema = z.array(commitFileSchema).min(1).max(COMMIT_MAX_FILES);
+
+/** UTF-8 byte length of `text`. */
+export function utf8Length(text: string): number {
+  return new TextEncoder().encode(text).length;
+}
+
+/**
+ * The checks a schema cannot make (a schema holding them would have to be `.refine()`d, which loses
+ * `.shape`): paths unique, and the NEW content alone within the combined cap. Throws a fixed message.
+ */
+export function assertCommitFiles(files: readonly CommitFile[]): void {
+  if (files.length > COMMIT_MAX_FILES) {
+    throw new Error(`a commit may touch at most ${String(COMMIT_MAX_FILES)} files`);
+  }
+  const seen = new Set<string>();
+  for (const f of files) {
+    if (seen.has(f.path)) throw new Error(`duplicate file path in commit: ${f.path}`);
+    seen.add(f.path);
+  }
+  // A path and one beneath it (`a` and `a/b`) cannot both be files of one tree.
+  for (const path of seen) {
+    const segments = path.split("/");
+    for (let i = 1; i < segments.length; i++) {
+      const parent = segments.slice(0, i).join("/");
+      if (seen.has(parent)) {
+        throw new Error(
+          `path collision in commit: ${parent} is a file and also a directory of ${path}`,
+        );
+      }
+    }
+  }
+  const bytes = files.reduce((n, f) => n + utf8Length(f.content), 0);
+  if (bytes > COMMIT_MAX_COMBINED_BYTES) {
+    throw new Error(commitTooLarge());
+  }
+}
+
+/** The one refusal for a commit over the combined cap. */
+export function commitTooLarge(): string {
+  return `commit too large: the old and new content together exceed ${String(COMMIT_MAX_COMBINED_BYTES / 1024)} KiB`;
+}
+
+/** Throws when `oldBytes + newBytes` is over the combined cap. */
+export function assertCombinedSize(oldBytes: number, files: readonly CommitFile[]): void {
+  const newBytes = files.reduce((n, f) => n + utf8Length(f.content), 0);
+  if (oldBytes + newBytes > COMMIT_MAX_COMBINED_BYTES) throw new Error(commitTooLarge());
+}
+
+export type DecodedText = { readonly text: string } | { readonly binary: true };
+
+/**
+ * Decode base64 file bytes as UTF-8. Bytes that are not valid UTF-8, or that hold a NUL, are
+ * `binary`: their content is withheld and the commit tools refuse to overwrite them.
+ */
+export function decodeBase64Text(base64: string): DecodedText {
+  const bytes = Buffer.from(base64.replaceAll(/\s/g, ""), "base64");
+  if (bytes.includes(0)) return { binary: true };
+  try {
+    return { text: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
+  } catch {
+    return { binary: true };
+  }
+}
+
+/** The error a commit tool throws for an existing file it will not overwrite. */
+export function notOverwritable(path: string): Error {
+  return new Error(
+    `${path} is not a text file the commit tools can overwrite (binary, symlink, submodule, a directory in the way, or too large)`,
+  );
+}