@mnaimfaizy/agent-kit 1.0.0-alpha.12 → 1.0.0-beta.1

package/src/kit-tag.mjs

@@ -1,6 +1,8 @@
-// Fetches one Agent-kit tag into a throwaway bare repository and reads files
-// and tree hashes from it. Nothing is bundled in the npm package: the git tag
-// Consumers pin in `uses:` is the only source of kit files (ADR 0001).
+// Fetches Agent-kit tags into a throwaway bare repository and reads files,
+// file lists and tree hashes from them. Nothing is bundled in the npm
+// package: the git tag Consumers pin in `uses:` is the only source of kit
+// files (ADR 0001). One repository can hold two tags, so `upgrade` can diff
+// them.
 
 import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -8,12 +10,28 @@ import { join } from "node:path";
 import { REPO_PATTERN } from "./checks/result.mjs";
 import { firstLine } from "./exec.mjs";
 import { parseKitOwnedPaths } from "./kit-owned-paths.mjs";
+import { caseCollisions, checkSafePath, fileDirConflicts } from "./safe-paths.mjs";
 import { FIRST_MANIFEST_TAG, isReleaseTag } from "./tags.mjs";
 
 const SAFE_PATH = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\/?$/;
 export const DEFAULT_SERVER = "https://github.com";
 const SERVER = /^https:\/\/[A-Za-z0-9.-]+(?::\d+)?$/;
 
+/** GITHUB_SERVER_URL when it is a valid server URL (set on GitHub Enterprise Server too), else github.com. */
+export function serverFromEnv(env) {
+  const fromEnv = String(env.GITHUB_SERVER_URL ?? "").replace(/\/$/, "");
+  return SERVER.test(fromEnv) ? fromEnv : DEFAULT_SERVER;
+}
+
+/** The git modes of an executable and of a regular file. */
+export const EXECUTABLE_MODE = "100755";
+export const REGULAR_MODE = "100644";
+
+/** File modes the CLI copies: a regular file, or an executable one. */
+const FILE_MODES = new Set([REGULAR_MODE, EXECUTABLE_MODE]);
+const MODE_NAMES = { 120000: "a symbolic link", 160000: "a submodule" };
+const OID = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+
 export class KitTagError extends Error {}
 
 /** A tag with no kit-owned-paths.txt (up to v1.0.0-alpha.10): the CLI refuses it. */
@@ -37,34 +55,28 @@ function checkPath(path) {
   return path.replace(/\/$/, "");
 }
 
+function checkArgs({ repo, serverUrl }) {
+  if (!REPO_PATTERN.test(repo)) {
+    throw new KitTagError(`not a GitHub repository name: ${JSON.stringify(repo)}`);
+  }
+  if (!SERVER.test(serverUrl)) {
+    throw new KitTagError(`not a GitHub server URL: ${JSON.stringify(serverUrl)}`);
+  }
+}
+
 /**
- * Fetch `tag` of `repo`. The tag must carry kit-owned-paths.txt, or this throws
- * PreManifestTagError. Call `cleanup()` when done.
+ * Open a throwaway bare repository for `repo`, to fetch one or more tags
+ * into. Call `cleanup()` when done.
  *
  * @param {{
  *   runner: import("./exec.mjs").Runner,
  *   repo: string,
- *   tag: string,
  *   serverUrl?: string,   // https://github.com, or a GitHub Enterprise Server host
  *   remoteUrl?: string,   // tests: fetch from here instead
- *   forDeletion?: boolean // strict manifest shapes, for code that deletes paths
  * }} opts
  */
-export function openKitTag({
-  runner,
-  repo,
-  tag,
-  serverUrl = DEFAULT_SERVER,
-  remoteUrl,
-  forDeletion = true,
-}) {
-  if (!REPO_PATTERN.test(repo)) {
-    throw new KitTagError(`not a GitHub repository name: ${JSON.stringify(repo)}`);
-  }
-  if (!isReleaseTag(tag)) throw new KitTagError(`not a Release-line tag: ${JSON.stringify(tag)}`);
-  if (!SERVER.test(serverUrl)) {
-    throw new KitTagError(`not a GitHub server URL: ${JSON.stringify(serverUrl)}`);
-  }
+export function openKitRepo({ runner, repo, serverUrl = DEFAULT_SERVER, remoteUrl }) {
+  checkArgs({ repo, serverUrl });
   const url = remoteUrl ?? `${serverUrl}/${repo}.git`;
   const tmp = mkdtempSync(join(tmpdir(), "agent-kit-tag-"));
   const dir = join(tmp, "repo.git");
@@ -72,11 +84,26 @@ export function openKitTag({
   mkdirSync(noHooks);
   const cleanup = () => rmSync(tmp, { recursive: true, force: true });
   // No hooks run, whatever the adopter's global git config says.
-  const git = (...args) => runner("git", ["-C", dir, "-c", `core.hooksPath=${noHooks}`, ...args]);
+  const base = ["-C", dir, "-c", `core.hooksPath=${noHooks}`];
+  const git = (...args) => runner("git", [...base, ...args]);
+  const gitBytes = (...args) => runner("git", [...base, ...args], { encoding: "buffer" });
   try {
-    let r = runner("git", ["init", "--bare", "--quiet", "--template=", dir]);
+    const r = runner("git", ["init", "--bare", "--quiet", "--template=", dir]);
     if (r.status !== 0) throw new KitTagError(`git init failed: ${firstLine(r.stderr)}`);
-    r = git(
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
+
+  /**
+   * Fetch `tag` into the repository. It must carry kit-owned-paths.txt, or
+   * this throws PreManifestTagError.
+   */
+  const fetchTag = (tag, { forDeletion = true } = {}) => {
+    if (!isReleaseTag(tag)) throw new KitTagError(`not a Release-line tag: ${JSON.stringify(tag)}`);
+    let r = git(
+      "-c",
+      "fetch.fsckObjects=true",
       "fetch",
       "--quiet",
       "--depth=1",
@@ -108,12 +135,123 @@ export function openKitTag({
       return type.status === 0 && type.stdout.trim() === "tree" ? hash : null;
     };
 
+    /**
+     * Every file under folder `path` at the tag, as `{ path, mode, oid }`.
+     * Throws KitTagError for anything that is not a regular or executable
+     * file (a symbolic link, a submodule), for a file path that is not safe
+     * to write on every platform, and for two paths that would be one file
+     * on a case-insensitive file system.
+     */
+    const listFiles = (path) => {
+      const folder = checkPath(path);
+      const res = git("ls-tree", "-r", "-z", "--full-tree", commit, "--", folder);
+      if (res.status !== 0) {
+        throw new KitTagError(`could not list ${folder}/ at ${tag}: ${firstLine(res.stderr)}`);
+      }
+      const files = [];
+      for (const entry of res.stdout.split("\0").filter(Boolean)) {
+        const m = /^(\d{6}) (\w+) ([0-9a-f]+)\t(.+)$/s.exec(entry);
+        if (!m) throw new KitTagError(`unexpected git ls-tree output at ${tag}`);
+        const [, mode, type, oid, file] = m;
+        if (!file.startsWith(`${folder}/`)) continue;
+        if (!FILE_MODES.has(mode) || type !== "blob" || !OID.test(oid)) {
+          const kind = MODE_NAMES[mode] ?? `mode ${mode}`;
+          throw new KitTagError(
+            `${tag} has ${JSON.stringify(file)} as ${kind}; the CLI copies only regular files`,
+          );
+        }
+        try {
+          checkSafePath(file, `${tag} file`);
+        } catch (err) {
+          throw new KitTagError(err.message);
+        }
+        files.push({ path: file, mode, oid });
+      }
+      const names = files.map((f) => f.path);
+      const collisions = caseCollisions(names);
+      if (collisions.length) {
+        throw new KitTagError(
+          `${tag} has files that differ only in case, which would overwrite each other on ` +
+            `Windows and macOS: ${collisions.map((g) => g.join(" and ")).join("; ")}`,
+        );
+      }
+      const conflicts = fileDirConflicts(names);
+      if (conflicts.length) {
+        throw new KitTagError(
+          `${tag} has ${conflicts[0][0]} as both a file and a folder (${conflicts[0][1]})`,
+        );
+      }
+      return files;
+    };
+
+    /** The exact bytes of a blob listed by listFiles, as a Buffer. */
+    const readBlob = (oid) => {
+      if (!OID.test(oid)) throw new KitTagError(`not a git object id: ${JSON.stringify(oid)}`);
+      const res = gitBytes("cat-file", "blob", oid);
+      if (res.status !== 0 || !Buffer.isBuffer(res.stdout)) {
+        throw new KitTagError(`could not read ${oid} at ${tag}: ${firstLine(res.stderr)}`);
+      }
+      return res.stdout;
+    };
+
     const manifest = readFile("kit-owned-paths.txt");
     if (manifest === null) throw new PreManifestTagError(repo, tag, serverUrl);
     const kitOwnedPaths = parseKitOwnedPaths(manifest, { forDeletion });
-    return { repo, tag, commit, serverUrl, kitOwnedPaths, readFile, treeHash, cleanup };
+    return { repo, tag, commit, serverUrl, kitOwnedPaths, readFile, treeHash, listFiles, readBlob };
+  };
+
+  /**
+   * `git diff` of folder `path` between two fetched tags, as text. No
+   * external diff tool or textconv filter from the adopter's git config runs.
+   */
+  const diff = (oldSnapshot, newSnapshot, path) => {
+    const folder = checkPath(path);
+    const res = git(
+      "diff",
+      "--no-ext-diff",
+      "--no-textconv",
+      "--no-color",
+      oldSnapshot.commit,
+      newSnapshot.commit,
+      "--",
+      `${folder}/`,
+    );
+    if (res.status !== 0) throw new KitTagError(`git diff failed: ${firstLine(res.stderr)}`);
+    return res.stdout;
+  };
+
+  return { repo, serverUrl, fetchTag, diff, cleanup };
+}
+
+/**
+ * Fetch `tag` of `repo`. The tag must carry kit-owned-paths.txt, or this throws
+ * PreManifestTagError. Call `cleanup()` when done.
+ *
+ * @param {{
+ *   runner: import("./exec.mjs").Runner,
+ *   repo: string,
+ *   tag: string,
+ *   serverUrl?: string,   // https://github.com, or a GitHub Enterprise Server host
+ *   remoteUrl?: string,   // tests: fetch from here instead
+ *   forDeletion?: boolean // strict manifest shapes, for code that deletes paths
+ * }} opts
+ */
+export function openKitTag({
+  runner,
+  repo,
+  tag,
+  serverUrl = DEFAULT_SERVER,
+  remoteUrl,
+  forDeletion = true,
+}) {
+  checkArgs({ repo, serverUrl });
+  // Checked before any git runs, so a bad tag never reaches the command line.
+  if (!isReleaseTag(tag)) throw new KitTagError(`not a Release-line tag: ${JSON.stringify(tag)}`);
+  const kit = openKitRepo({ runner, repo, serverUrl, remoteUrl });
+  try {
+    return { ...kit.fetchTag(tag, { forDeletion }), cleanup: kit.cleanup };
   } catch (err) {
-    cleanup();
+    kit.cleanup();
     throw err;
   }
 }

package/src/local-tree.mjs

@@ -17,6 +17,9 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:
 import { tmpdir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { firstLine } from "./exec.mjs";
+import { EXECUTABLE_MODE, REGULAR_MODE } from "./kit-tag.mjs";
+
+const MODES = new Set([EXECUTABLE_MODE, REGULAR_MODE]);
 
 const SAFE_PATH = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\/$/;
 
@@ -37,6 +40,42 @@ export function filterDrivers(configNames) {
   return [...drivers];
 }
 
+/**
+ * True when core.fileMode is off (the default on Windows): git then cannot
+ * see an executable bit on disk and takes a file's mode from the index.
+ */
+export function fileModeIsOff(runner, root) {
+  const r = runner("git", ["-C", root, "config", "--type=bool", "core.fileMode"]);
+  return r.status === 0 && r.stdout.trim() === "false";
+}
+
+/**
+ * `-c` options that keep git from running anything the checkout's or the
+ * adopter's git config names: no hooks (`noHooks` is an empty folder), no
+ * fsmonitor, no background maintenance, and no clean/process filter drivers.
+ */
+export function gitSafetyArgs({ runner, root, noHooks }) {
+  const safety = [
+    "-c",
+    `core.hooksPath=${noHooks}`,
+    "-c",
+    "core.fsmonitor=false",
+    "-c",
+    "gc.auto=0",
+    "-c",
+    "maintenance.auto=false",
+  ];
+  const listed = runner("git", ["-C", root, "config", "--name-only", "--get-regexp", "^filter\\."]);
+  for (const driver of filterDrivers(listed.status === 0 ? listed.stdout.split("\n") : [])) {
+    if (/[=\r\n]/.test(driver)) {
+      throw new LocalTreeError(`cannot turn off git filter driver ${JSON.stringify(driver)}`);
+    }
+    safety.push("-c", `filter.${driver}.clean=`, "-c", `filter.${driver}.process=`);
+    safety.push("-c", `filter.${driver}.required=false`);
+  }
+  return safety;
+}
+
 /**
  * @param {{ runner: import("./exec.mjs").Runner, cwd: string, paths: string[] }} opts
  * @returns {{ root: string, hashes: Map<string, string | null>, skipped: Map<string, string>, notes: Map<string, string> }}
@@ -75,29 +114,7 @@ export function localTreeHashes({ runner, cwd, paths }) {
     // splits on ':' on POSIX, so a path containing one would break it.
     writeFileSync(join(objects, "info", "alternates"), `${realObjects}\n`);
 
-    const safety = [
-      "-c",
-      `core.hooksPath=${noHooks}`,
-      "-c",
-      "core.fsmonitor=false",
-      "-c",
-      "gc.auto=0",
-    ];
-    const listed = runner("git", [
-      "-C",
-      root,
-      "config",
-      "--name-only",
-      "--get-regexp",
-      "^filter\\.",
-    ]);
-    for (const driver of filterDrivers(listed.status === 0 ? listed.stdout.split("\n") : [])) {
-      if (/[=\r\n]/.test(driver)) {
-        throw new LocalTreeError(`cannot turn off git filter driver ${JSON.stringify(driver)}`);
-      }
-      safety.push("-c", `filter.${driver}.clean=`, "-c", `filter.${driver}.process=`);
-      safety.push("-c", `filter.${driver}.required=false`);
-    }
+    const safety = gitSafetyArgs({ runner, root, noHooks });
     const base = ["-C", root, ...safety, "--literal-pathspecs"];
     const env = { GIT_INDEX_FILE: index, GIT_OBJECT_DIRECTORY: objects };
     const git = (...args) => runner("git", [...base, ...args], { env });
@@ -113,6 +130,10 @@ export function localTreeHashes({ runner, cwd, paths }) {
       }
     }
 
+    // Without core.fileMode (the default on Windows) git cannot see an
+    // executable bit on disk and takes the mode from the index: so does this.
+    const trustIndexModes = fileModeIsOff(runner, root);
+
     const hashes = new Map();
     const skipped = new Map();
     const notes = new Map();
@@ -160,6 +181,35 @@ export function localTreeHashes({ runner, cwd, paths }) {
           );
         }
       }
+      if (trustIndexModes) {
+        const modes = (res) =>
+          new Map(
+            (res.status === 0 ? res.stdout.split("\0") : [])
+              .filter(Boolean)
+              .map((e) => [e.slice(e.indexOf("\t") + 1), e.slice(0, 6)]),
+          );
+        const inReal = modes(real("ls-files", "-s", "-z", "--", path));
+        const inTemp = modes(git("ls-files", "-s", "-z", "--", path));
+        // Both directions: the real index may have gained or lost the bit.
+        for (const [want, flag] of [
+          [EXECUTABLE_MODE, "--chmod=+x"],
+          [REGULAR_MODE, "--chmod=-x"],
+        ]) {
+          const fix = [...inReal]
+            .filter(
+              ([f, mode]) => mode === want && MODES.has(inTemp.get(f)) && inTemp.get(f) !== want,
+            )
+            .map(([f]) => f);
+          for (let i = 0; i < fix.length; i += 200) {
+            const chmod = git("update-index", flag, "--", ...fix.slice(i, i + 200));
+            if (chmod.status !== 0) {
+              throw new LocalTreeError(
+                `git update-index ${flag} failed: ${firstLine(chmod.stderr)}`,
+              );
+            }
+          }
+        }
+      }
       const inIndex = git("ls-files", "-z", "--", path);
       const staged = inIndex.status === 0 ? inIndex.stdout.split("\0").filter(Boolean) : [];
       if (staged.length === 0) {

package/src/local-writes.mjs

@@ -0,0 +1,307 @@
+// What `init` and `upgrade` share for changing a Consumer's checkout: path
+// checks, the uncommitted-changes check, reading Kit-owned files from a tag,
+// and carrying out a plan. Both commands plan first and write second: every
+// refusal (a Refusal) is raised while planning, before anything is written.
+
+import {
+  chmodSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { firstLine } from "./exec.mjs";
+import { EXECUTABLE_MODE } from "./kit-tag.mjs";
+import { fileModeIsOff, gitSafetyArgs } from "./local-tree.mjs";
+import { checkSafePath } from "./safe-paths.mjs";
+
+/** A reason not to start. Nothing has been written when this is thrown. */
+export class Refusal extends Error {
+  constructor(message, details = []) {
+    super(message);
+    this.details = details;
+  }
+}
+
+/** The most items a plan or a refusal lists before "…". */
+export const MAX_LISTED = 20;
+
+/** `items`, cut to MAX_LISTED with a closing "…" when there are more. */
+export function listed(items) {
+  return items.length > MAX_LISTED ? [...items.slice(0, MAX_LISTED), "…"] : items;
+}
+
+/** Print a refusal and its details; the exit code is 1. */
+export function reportRefusal(out, err) {
+  out(`REFUSED  ${err.message}`);
+  for (const d of err.details ?? []) out(`      ${d}`);
+  out("Nothing was changed.");
+  return 1;
+}
+
+export function lstatOrNull(path) {
+  try {
+    return lstatSync(path);
+  } catch (err) {
+    if (err.code === "ENOENT" || err.code === "ENOTDIR") return null;
+    throw err;
+  }
+}
+
+/**
+ * Refuse unless `rel` (a repository-relative path, no trailing slash) can be
+ * deleted and written without leaving `root`: it must be a safe path (the
+ * strict rules for names that come from a tag), no part of it may be a
+ * symbolic link or junction, and every existing parent must be a folder.
+ */
+export function checkLocalPath(root, rel, { deleted = [] } = {}) {
+  try {
+    checkSafePath(rel);
+  } catch (err) {
+    throw new Refusal(err.message);
+  }
+  checkNoLinks(root, rel, { deleted });
+}
+
+/**
+ * Refuse unless no part of `rel` is a symbolic link or junction and every
+ * existing parent is a folder. For the Consumer's own files, rewritten in
+ * place, whose names need not follow the strict tag rules.
+ *
+ * `deleted` lists folders the plan deletes before it writes: what is on disk
+ * inside them now (a file the new tag turns into a folder, say) is gone by
+ * the time `rel` is written, so the walk stops there.
+ */
+export function checkNoLinks(root, rel, { deleted = [] } = {}) {
+  const parts = rel.split("/");
+  for (let i = 1; i <= parts.length; i++) {
+    const sub = parts.slice(0, i).join("/");
+    if (deleted.includes(sub)) return;
+    const st = lstatOrNull(join(root, sub));
+    if (!st) return;
+    if (st.isSymbolicLink()) {
+      throw new Refusal(
+        `${sub} is a symbolic link or junction; the CLI does not delete or write through links. ` +
+          `Replace it with a plain folder or file, then run the command again.`,
+      );
+    }
+    if (i < parts.length && !st.isDirectory()) {
+      throw new Refusal(`${sub} is a file, but ${rel} needs it to be a folder.`);
+    }
+  }
+}
+
+/** Links inside `rel`: never followed or guessed at. */
+function linksUnder(root, rel) {
+  const found = [];
+  const walk = (sub) => {
+    const st = lstatOrNull(join(root, sub));
+    if (!st) return;
+    if (st.isSymbolicLink()) found.push(sub);
+    else if (st.isDirectory()) {
+      for (const name of readdirSync(join(root, sub)).sort()) walk(`${sub}/${name}`);
+    }
+  };
+  walk(rel);
+  return found;
+}
+
+/** Refuse unless folder `rel` can be deleted whole: checkLocalPath, and no link inside it. */
+export function checkDeletable(root, rel) {
+  checkLocalPath(root, rel);
+  const links = linksUnder(root, rel);
+  if (links.length) {
+    throw new Refusal(
+      `${rel}/ holds a symbolic link or junction, which the kit never ships: ${links[0]}. ` +
+        `Remove it by hand, then run the command again.`,
+    );
+  }
+}
+
+/** A temporary empty hooks folder and the safe git options for `root`; call done(). */
+function safeGit(runner, root) {
+  const tmp = mkdtempSync(join(tmpdir(), "agent-kit-git-"));
+  const noHooks = join(tmp, "no-hooks");
+  mkdirSync(noHooks);
+  try {
+    return {
+      args: ["-C", root, ...gitSafetyArgs({ runner, root, noHooks }), "--literal-pathspecs"],
+      done: () => rmSync(tmp, { recursive: true, force: true }),
+    };
+  } catch (err) {
+    rmSync(tmp, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+/**
+ * Files under `paths` with uncommitted changes (modified, staged, deleted or
+ * untracked), as "XY path", and, apart, the ignored files and folders there
+ * (deleting the paths deletes those too). git runs no hooks, fsmonitor or
+ * filter drivers, and takes no optional locks.
+ *
+ * @returns {{ changed: string[], ignored: string[] }}
+ */
+export function uncommittedChanges({ runner, root, paths }) {
+  const git = safeGit(runner, root);
+  try {
+    const r = runner("git", [
+      ...git.args,
+      "--no-optional-locks",
+      "status",
+      "--porcelain=v1",
+      "-z",
+      "--untracked-files=all",
+      "--ignored=matching",
+      "--ignore-submodules=all",
+      "--no-renames",
+      "--",
+      ...paths,
+    ]);
+    if (r.status !== 0) throw new Refusal(`git status failed: ${firstLine(r.stderr)}`);
+    const entries = r.stdout.split("\0").filter(Boolean);
+    // git status cannot see local edits to files marked assume-unchanged
+    // (a lower-case tag) or skip-worktree (S): count those as changed.
+    const flagged = runner("git", [...git.args, "ls-files", "-v", "-z", "--", ...paths]);
+    if (flagged.status !== 0)
+      throw new Refusal(`git ls-files failed: ${firstLine(flagged.stderr)}`);
+    const hidden = flagged.stdout
+      .split("\0")
+      .filter((e) => /^(?:[a-z]|S) /.test(e))
+      .map(
+        (e) =>
+          `${e[0]} ${e.slice(2)} (marked ${e[0] === "S" ? "skip-worktree" : "assume-unchanged"})`,
+      );
+    return {
+      changed: [
+        ...entries
+          .filter((e) => !e.startsWith("!!"))
+          .map((e) => `${e.slice(0, 2).trim() || "?"} ${e.slice(3)}`),
+        ...hidden,
+      ],
+      ignored: entries.filter((e) => e.startsWith("!!")).map((e) => e.slice(3)),
+    };
+  } finally {
+    git.done();
+  }
+}
+
+/**
+ * Every file of every Kit-owned path at the tag, with its bytes, ready to
+ * write. Refuses a listed path with no files.
+ *
+ * @returns {{ path: string, mode: string, bytes: Buffer }[]}
+ */
+export function kitFileWrites(snap) {
+  const writes = [];
+  for (const path of snap.kitOwnedPaths) {
+    const listed = snap.listFiles(path);
+    if (listed.length === 0) {
+      throw new Refusal(
+        `${snap.tag}'s kit-owned-paths.txt lists ${path}, but the tag has no files there.`,
+      );
+    }
+    for (const f of listed) {
+      writes.push({ path: f.path, mode: f.mode, bytes: snap.readBlob(f.oid) });
+    }
+  }
+  return writes;
+}
+
+/**
+ * Carry out a plan: delete each folder in `deletes`, write each file in
+ * `writes` (paths from a tag), then each file in `rewrites` (the Consumer's
+ * own files, rewritten in place, whose names need not follow the tag rules).
+ * Only file-system errors can stop it part-way.
+ *
+ * @param {string} root
+ * @param {{ deletes?: string[], writes: { path: string, mode?: string, bytes: Buffer | string }[], rewrites?: { path: string, bytes: Buffer | string }[] }} plan
+ */
+export function applyPlan(root, { deletes = [], writes, rewrites = [] }) {
+  // Checked again here: time may have passed at the confirmation prompt.
+  for (const rel of deletes) checkDeletable(root, rel);
+  for (const w of writes) checkLocalPath(root, w.path, { deleted: deletes });
+  for (const w of rewrites) checkNoLinks(root, w.path);
+  for (const rel of deletes) rmSync(join(root, rel), { recursive: true, force: true });
+  for (const w of [...writes, ...rewrites]) {
+    const target = join(root, w.path);
+    mkdirSync(dirname(target), { recursive: true });
+    const executable = w.mode === EXECUTABLE_MODE;
+    writeFileSync(target, w.bytes, { mode: executable ? 0o755 : 0o644 });
+    if (executable) chmodSync(target, 0o755);
+  }
+}
+
+/**
+ * Without core.fileMode (the default on Windows) git cannot see an
+ * executable bit on disk, and `git add` keeps the mode the index already
+ * has (100644 for a new file). So stage the tag's mode: +x for each
+ * executable file written, and -x for each regular file the index still
+ * records as executable. Returns a line to print, or null when nothing was
+ * needed.
+ *
+ * @param {{ runner: import("./exec.mjs").Runner, root: string, writes: { path: string, mode?: string }[] }} opts
+ */
+export function stageFileModes({ runner, root, writes }) {
+  if (writes.length === 0 || !fileModeIsOff(runner, root)) return null;
+  const git = safeGit(runner, root);
+  try {
+    const failed = [];
+    const add = writes.filter((w) => w.mode === EXECUTABLE_MODE).map((w) => w.path);
+    const regular = writes.filter((w) => w.mode !== EXECUTABLE_MODE).map((w) => w.path);
+    const regularSet = new Set(regular);
+    const drop = [];
+    for (const batch of batches(regular)) {
+      const indexed = runner("git", [...git.args, "ls-files", "-s", "-z", "--", ...batch]);
+      if (indexed.status !== 0) {
+        failed.push(`--chmod=-x (git ls-files: ${firstLine(indexed.stderr)}): ${batch.join(", ")}`);
+        continue;
+      }
+      drop.push(
+        ...indexed.stdout
+          .split("\0")
+          .filter((e) => e.startsWith(`${EXECUTABLE_MODE} `))
+          .map((e) => e.slice(e.indexOf("\t") + 1))
+          .filter((f) => regularSet.has(f)),
+      );
+    }
+    for (const [flag, files] of [
+      ["--chmod=+x", add],
+      ["--chmod=-x", drop],
+    ]) {
+      for (const batch of batches(files)) {
+        // --sparse: a path outside a sparse-checkout cone is refused without
+        // it. git before 2.34 has no --sparse; it then gets a plain add.
+        let r = runner("git", [...git.args, "add", "--sparse", flag, "--", ...batch]);
+        if (r.status !== 0 && /unknown option|usage: git add/i.test(r.stderr)) {
+          r = runner("git", [...git.args, "add", flag, "--", ...batch]);
+        }
+        if (r.status !== 0) failed.push(`${flag} (${firstLine(r.stderr)}): ${batch.join(", ")}`);
+      }
+    }
+    if (failed.length) {
+      return (
+        "Could not stage the tag's file modes; after `git add`, run " +
+        `\`git update-index <flag> -- <file>\` for: ${failed.join("; ")}`
+      );
+    }
+    if (add.length + drop.length === 0) return null;
+    return (
+      `Staged the tag's file mode for ${add.length + drop.length} file(s) ` +
+      "(core.fileMode is off here, so git cannot see it on disk)."
+    );
+  } finally {
+    git.done();
+  }
+}
+
+/** Command-line-sized slices of a file list. */
+function batches(files, size = 200) {
+  const out = [];
+  for (let i = 0; i < files.length; i += size) out.push(files.slice(i, i + size));
+  return out;
+}