@mnaimfaizy/agent-kit 0.0.0-stage → 1.0.0-alpha.12

package/src/doctor.mjs

@@ -0,0 +1,368 @@
+// `agent-kit doctor`: read-only checks of a Consumer repository against the
+// Agent-kit tag its Callers pin. Local mode (an admin `gh` login) runs every
+// check; CI mode runs only the file and pin checks and lists the rest as
+// skipped. A skipped check is never reported as passed.
+
+import { readWorkflows } from "./callers.mjs";
+import { checkClaudeApp } from "./checks/claude-app.mjs";
+import { checkKitOwnedTrees } from "./checks/kit-owned-trees.mjs";
+import { checkLabels } from "./checks/labels.mjs";
+import { checkPins } from "./checks/pins.mjs";
+import { result, sanitizeLine } from "./checks/result.mjs";
+import {
+  checkCreationRule,
+  checkPersonalTagPush,
+  checkTagRuleset,
+  checkUpdateRule,
+  loadRulesets,
+} from "./checks/rulesets.mjs";
+import {
+  checkSecrets,
+  checkVariables,
+  deriveRequirements,
+  deriveVariables,
+} from "./checks/secrets-and-variables.mjs";
+import { firstLine } from "./exec.mjs";
+import { createGitHub } from "./github.mjs";
+import { DEFAULT_SERVER, openKitTag, PreManifestTagError } from "./kit-tag.mjs";
+
+const SERVER = /^https:\/\/[A-Za-z0-9.-]+(?::\d+)?$/;
+
+/**
+ * The GitHub server the pins resolve on: the repository's host in a local
+ * run, GITHUB_SERVER_URL in GitHub Actions (set on GitHub Enterprise Server
+ * too), else github.com.
+ */
+function serverFor(info, env) {
+  if (info?.host) return `https://${info.host}`;
+  const fromEnv = String(env.GITHUB_SERVER_URL ?? "").replace(/\/$/, "");
+  return SERVER.test(fromEnv) ? fromEnv : DEFAULT_SERVER;
+}
+
+/** The checks that need a `gh` login with admin on the repository. */
+export const LOCAL_ONLY_CHECKS = [
+  ["secrets", "Secrets the Callers pass are set"],
+  ["variables", "Repository variables the Callers read are set"],
+  ["trigger-labels", "Trigger labels exist"],
+  ["claude-app", "Claude GitHub App installed"],
+  ["ruleset-update", "Default branch has an update rule"],
+  ["ruleset-creation", "Release branches have a creation rule"],
+  ["ruleset-tags", "Release tags have a v* tag ruleset"],
+  ["release-tag-push", "Release tags can be pushed under the tag ruleset"],
+];
+
+const skipAll = (ids, reason) => ids.map(([id, title]) => result(id, title, "skip", reason));
+
+/**
+ * @param {{
+ *   cwd: string,
+ *   runner: import("./exec.mjs").Runner,
+ *   ci?: boolean,
+ *   strict?: boolean,
+ *   repo?: string,
+ *   openTag?: typeof openKitTag,
+ *   env?: NodeJS.ProcessEnv,
+ * }} opts
+ * @returns {{ mode: "local" | "ci", modeReason: string | null, repo: string | null, tag: string | null, results: object[], refusal: string | null, exitCode: number }}
+ */
+export function runDoctor({
+  cwd,
+  runner,
+  ci = false,
+  strict = false,
+  repo: repoArg,
+  openTag = openKitTag,
+  env = process.env,
+}) {
+  const results = [];
+  let mode = ci ? "ci" : "local";
+  let modeReason = ci ? "--ci" : null;
+
+  // Which repository, and may this login read its settings?
+  let info = null;
+  if (!ci) {
+    const github = createGitHub(runner, { cwd });
+    try {
+      info = repoInfo(github, repoArg);
+      if (!info.admin) {
+        mode = "ci";
+        modeReason = `your gh login is not an admin on ${info.repo}`;
+      }
+    } catch (err) {
+      mode = "ci";
+      modeReason = `gh could not read the repository (${firstLine(err.message)})`;
+    }
+  }
+
+  let root = cwd;
+  const top = runner("git", ["-C", cwd, "rev-parse", "--show-toplevel"]);
+  if (top.status === 0) root = top.stdout.trim();
+  else {
+    results.push(result("pins", "uses: pins agree", "fail", `${cwd} is not a git repository.`));
+    return finish({
+      mode,
+      modeReason,
+      repo: info?.repo ?? null,
+      tag: null,
+      results,
+      refusal: null,
+      strict,
+    });
+  }
+
+  let workflows;
+  try {
+    workflows = readWorkflows(root);
+  } catch (err) {
+    // Nothing else can run without the Callers: report it, never crash.
+    results.push(result("pins", "uses: pins agree", "fail", firstLine(err?.message ?? err)));
+    return finish({
+      mode,
+      modeReason,
+      repo: info?.repo ?? null,
+      tag: null,
+      results,
+      refusal: null,
+      strict,
+    });
+  }
+  const { files, callers } = workflows;
+  const pins = checkPins(files);
+  results.push(pins.result);
+
+  let snapshot = null;
+  let refusal = null;
+  if (pins.tag) {
+    try {
+      // Read-only: accept any safe manifest path, so an older CLI can check a
+      // newer tag. Code that deletes paths keeps the strict shapes.
+      snapshot = openTag({
+        runner,
+        repo: pins.repo,
+        tag: pins.tag,
+        serverUrl: serverFor(info, env),
+        forDeletion: false,
+      });
+    } catch (err) {
+      if (err instanceof PreManifestTagError) refusal = err.message;
+      else
+        results.push(
+          result("kit-owned-trees", "Kit-owned paths match the pinned tag", "fail", err.message),
+        );
+    }
+  } else {
+    results.push(
+      result(
+        "kit-owned-trees",
+        "Kit-owned paths match the pinned tag",
+        "skip",
+        "No single pinned tag to compare against.",
+      ),
+    );
+  }
+  if (refusal) {
+    return finish({
+      mode,
+      modeReason,
+      repo: info?.repo ?? null,
+      tag: pins.tag,
+      results,
+      refusal,
+      strict,
+    });
+  }
+
+  try {
+    if (snapshot) {
+      try {
+        results.push(checkKitOwnedTrees({ runner, cwd: root, snapshot }));
+      } catch (err) {
+        results.push(
+          result("kit-owned-trees", "Kit-owned paths match the pinned tag", "fail", err.message),
+        );
+      }
+    }
+
+    if (mode === "ci") {
+      results.push(
+        ...skipAll(
+          LOCAL_ONLY_CHECKS,
+          `CI mode (${modeReason}): needs a local run with an admin gh login.`,
+        ),
+      );
+    } else {
+      results.push(...localChecks({ runner, cwd, info, files, callers, snapshot }));
+    }
+  } finally {
+    snapshot?.cleanup();
+  }
+  return finish({
+    mode,
+    modeReason,
+    repo: info?.repo ?? null,
+    tag: pins.tag,
+    results,
+    refusal: null,
+    strict,
+  });
+}
+
+function repoInfo(github, repoArg) {
+  return github.repoInfo(repoArg);
+}
+
+const TITLES = Object.fromEntries(LOCAL_ONLY_CHECKS);
+
+/** Run one check; an exception becomes a FAIL for that check, never a silent pass. */
+export function guarded(id, run) {
+  try {
+    return run();
+  } catch (err) {
+    return result(
+      id,
+      TITLES[id] ?? id,
+      "fail",
+      `Check crashed: ${firstLine(err?.message ?? err)}`,
+      {
+        details: ["This is a bug in doctor; the other checks still ran."],
+      },
+    );
+  }
+}
+
+function localChecks({ runner, cwd, info, files, callers, snapshot }) {
+  const github = createGitHub(runner, { cwd, hostname: info.host ?? null });
+  const { repo, owner, ownerType, defaultBranch } = info;
+  const raw = [];
+  const out = { push: (...items) => raw.push(...items) };
+
+  if (snapshot) {
+    let requirements = null;
+    out.push(
+      guarded("secrets", () => {
+        requirements = deriveRequirements(callers, (file) =>
+          snapshot.readFile(`.github/workflows/${file}`),
+        );
+        return checkSecrets({ github, repo, ownerType, requirements });
+      }),
+    );
+    out.push(
+      guarded("variables", () =>
+        checkVariables({
+          github,
+          repo,
+          ownerType,
+          requirements: requirements ?? { variables: deriveVariables(callers) },
+        }),
+      ),
+    );
+  } else {
+    out.push(
+      ...skipAll(
+        LOCAL_ONLY_CHECKS.slice(0, 1),
+        "Needs the pinned tag's reusable workflows; fix the pins first.",
+      ),
+    );
+    // Variables come from the Caller files alone.
+    out.push(
+      guarded("variables", () =>
+        checkVariables({
+          github,
+          repo,
+          ownerType,
+          requirements: { variables: deriveVariables(callers) },
+        }),
+      ),
+    );
+  }
+
+  const readReusable = snapshot ? (file) => snapshot.readFile(`.github/workflows/${file}`) : null;
+  if (callers.length) {
+    out.push(guarded("trigger-labels", () => checkLabels({ github, repo, callers, readReusable })));
+  } else
+    out.push(
+      result(
+        "trigger-labels",
+        "Trigger labels exist",
+        "skip",
+        "No Caller to read Trigger labels from.",
+      ),
+    );
+
+  out.push(guarded("claude-app", () => checkClaudeApp({ github, repo, owner, ownerType })));
+
+  let rulesets = null;
+  let rulesetError = null;
+  try {
+    rulesets = loadRulesets(github, repo);
+  } catch (err) {
+    rulesetError = `Could not read rulesets: ${err.message}`;
+  }
+  if (rulesets) {
+    out.push(guarded("ruleset-update", () => checkUpdateRule(rulesets, { defaultBranch })));
+    out.push(guarded("ruleset-creation", () => checkCreationRule(rulesets)));
+    out.push(guarded("ruleset-tags", () => checkTagRuleset(rulesets)));
+  } else {
+    out.push(...skipAll(LOCAL_ONLY_CHECKS.slice(4, 7), rulesetError));
+  }
+  out.push(guarded("release-tag-push", () => checkPersonalTagPush({ ownerType, files })));
+  return raw;
+}
+
+function finish({ mode, modeReason, repo, tag, results, refusal, strict }) {
+  const final = strict
+    ? results.map((r) => (r.status === "warn" ? { ...r, status: "fail", strict: true } : r))
+    : results;
+  const failed = refusal !== null || final.some((r) => r.status === "fail");
+  return { mode, modeReason, repo, tag, results: final, refusal, exitCode: failed ? 1 : 0 };
+}
+
+const LABEL = { pass: "PASS", warn: "WARN", fail: "FAIL", skip: "SKIP" };
+
+/** Plain-text report. Every line is sanitized for terminals and CI logs. */
+export function formatReport(report, opts = {}) {
+  return formatLines(report, opts).map(sanitizeLine).join("\n");
+}
+
+function formatLines(report, { version } = {}) {
+  const lines = [];
+  lines.push(`agent-kit doctor${version ? ` ${version}` : ""}`);
+  lines.push(`  repository: ${report.repo ?? "(unknown)"}`);
+  lines.push(`  pinned tag: ${report.tag ?? "(none)"}`);
+  lines.push(`  mode:       ${report.mode}${report.modeReason ? ` (${report.modeReason})` : ""}`);
+  lines.push("");
+  if (report.refusal) {
+    for (const r of report.results) lines.push(...formatResult(r));
+    lines.push(`REFUSED  ${report.refusal}`);
+    lines.push("");
+    lines.push("Result: refused (exit 1).");
+    return lines;
+  }
+  for (const r of report.results) lines.push(...formatResult(r));
+  const count = (s) => report.results.filter((r) => r.status === s).length;
+  const skipped = report.results.filter((r) => r.status === "skip");
+  lines.push("");
+  lines.push(
+    `Result: ${count("fail")} failed, ${count("warn")} warning(s), ${skipped.length} skipped, ${count("pass")} passed (exit ${report.exitCode}).`,
+  );
+  if (skipped.length) {
+    lines.push(
+      `Skipped checks did not run and are not passes: ${skipped.map((r) => r.id).join(", ")}.`,
+    );
+  }
+  if (report.results.some((r) => r.fix.length)) {
+    lines.push(
+      "Lines starting with $ are POSIX shell (bash, zsh) commands for you to run; doctor ran none of them.",
+    );
+  }
+  return lines;
+}
+
+function formatResult(r) {
+  const out = [
+    `${LABEL[r.status]}  ${r.title}: ${r.summary}${r.strict ? " (warning; failed by --strict)" : ""}`,
+  ];
+  for (const d of r.details) out.push(`      ${d}`);
+  for (const f of r.fix) out.push(`      $ ${f}`);
+  return out;
+}

package/src/exec.mjs

@@ -0,0 +1,51 @@
+// Runs `git` and `gh` as argument arrays, never through a shell, so no string
+// from a Consumer file or a GitHub response is ever parsed as shell syntax.
+// Every module takes a runner as a parameter; tests inject a fake one.
+
+import { spawnSync } from "node:child_process";
+
+const ALLOWED = new Set(["git", "gh"]);
+
+/**
+ * @typedef {{ status: number | null, stdout: string, stderr: string }} RunResult
+ * @typedef {(cmd: string, args: string[], opts?: { cwd?: string, env?: NodeJS.ProcessEnv }) => RunResult} Runner
+ */
+
+/** @type {Runner} */
+export function systemRunner(cmd, args, opts = {}) {
+  if (!ALLOWED.has(cmd)) throw new Error(`refusing to run ${cmd}: only git and gh are allowed`);
+  if (!Array.isArray(args) || args.some((a) => typeof a !== "string")) {
+    throw new TypeError("runner arguments must be an array of strings");
+  }
+  const result = spawnSync(cmd, args, {
+    cwd: opts.cwd,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GH_PROMPT_DISABLED: "1", ...opts.env },
+    encoding: "utf8",
+    shell: false,
+    windowsHide: true,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (result.error) {
+    return { status: null, stdout: "", stderr: `${cmd}: ${result.error.message}` };
+  }
+  return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+
+/**
+ * The line of a command's stderr that says what went wrong, for short
+ * messages: the first `fatal:` or `error:` line, else the first line that is
+ * not a `warning:` or `hint:` (git prints those before the real error, for
+ * example about line endings), else the first non-empty line.
+ */
+export function firstLine(text) {
+  const lines = String(text ?? "")
+    .split(/\r\n|\r|\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  return (
+    lines.find((l) => /^(fatal|error):/i.test(l)) ??
+    lines.find((l) => !/^(warning|hint):/i.test(l)) ??
+    lines[0] ??
+    ""
+  );
+}

package/src/github.mjs

@@ -0,0 +1,88 @@
+// Read-only GitHub API calls through the adopter's own `gh` login. The CLI
+// never changes GitHub settings: it only reads, and prints `gh` commands for
+// the adopter to run.
+
+import { REPO_PATTERN as REPO } from "./checks/result.mjs";
+import { firstLine } from "./exec.mjs";
+
+const HOST = /^[A-Za-z0-9.-]+(?::\d+)?$/;
+
+export class GhError extends Error {
+  constructor(message, { status } = {}) {
+    super(message);
+    this.httpStatus = status ?? null;
+  }
+}
+
+function fail(r, what) {
+  const text = `${r.stderr}\n${r.stdout}`;
+  const m = /HTTP (\d{3})/.exec(text);
+  return new GhError(`${what}: ${firstLine(r.stderr) || firstLine(r.stdout) || "gh failed"}`, {
+    status: m ? Number(m[1]) : null,
+  });
+}
+
+export function checkRepoName(repo) {
+  if (!REPO.test(repo)) throw new GhError(`not a GitHub repository name: ${JSON.stringify(repo)}`);
+  return repo;
+}
+
+/**
+ * @param {import("./exec.mjs").Runner} runner
+ * @param {{ cwd?: string, hostname?: string | null }} [opts] hostname: a GitHub
+ *   Enterprise Server host; gh api then targets it with --hostname.
+ */
+export function createGitHub(runner, { cwd, hostname = null } = {}) {
+  if (hostname !== null && !HOST.test(hostname)) {
+    throw new GhError(`not a host name: ${JSON.stringify(hostname)}`);
+  }
+  const gh = (args) => runner("gh", args, { cwd });
+  const host = hostname && hostname !== "github.com" ? ["--hostname", hostname] : [];
+
+  /** GET an endpoint and parse its JSON. */
+  function getJson(endpoint) {
+    const r = gh(["api", ...host, "--method", "GET", endpoint]);
+    if (r.status !== 0) throw fail(r, `gh api ${endpoint}`);
+    return JSON.parse(r.stdout);
+  }
+
+  /** GET every page of an endpoint and return one line per `jq` result. */
+  function getLines(endpoint, jq) {
+    const r = gh(["api", ...host, "--method", "GET", "--paginate", endpoint, "--jq", jq]);
+    if (r.status !== 0) throw fail(r, `gh api ${endpoint}`);
+    return r.stdout.split(/\r?\n/).filter(Boolean);
+  }
+
+  /** The repository doctor checks, and whether this login is an admin on it. */
+  function repoInfo(repo) {
+    const args = [
+      "repo",
+      "view",
+      "--json",
+      "nameWithOwner,isInOrganization,viewerPermission,defaultBranchRef,url",
+    ];
+    if (repo) args.splice(2, 0, checkRepoName(repo));
+    const r = gh(args);
+    if (r.status !== 0) throw fail(r, "gh repo view");
+    const data = JSON.parse(r.stdout);
+    // The host the repository lives on: github.com, or a GitHub Enterprise Server.
+    let hostName = "github.com";
+    try {
+      if (data.url) hostName = new URL(data.url).host.toLowerCase();
+    } catch {
+      hostName = "github.com";
+    }
+    if (!HOST.test(hostName))
+      throw new GhError(`unexpected repository URL ${JSON.stringify(data.url)}`);
+    return {
+      host: hostName,
+      repo: checkRepoName(data.nameWithOwner),
+      owner: data.nameWithOwner.split("/")[0],
+      ownerType: data.isInOrganization ? "Organization" : "User",
+      admin: data.viewerPermission === "ADMIN",
+      defaultBranch: data.defaultBranchRef?.name ?? "main",
+    };
+  }
+
+  return { getJson, getLines, repoInfo };
+}

package/src/kit-owned-paths.mjs

@@ -0,0 +1,48 @@
+// Parses kit-owned-paths.txt.
+//
+// Two levels of trust:
+// - forDeletion (the default): `upgrade` deletes every entry before copying
+//   it fresh, so only the permitted shapes pass, the same rule
+//   scripts/kit-owned-paths-contract.test.py enforces on the kit side. A tag
+//   that broke that rule must not delete Consumer files.
+// - read-only (`forDeletion: false`, used by doctor): any plain relative
+//   folder path is accepted, so an older CLI can still check a newer tag that
+//   adds a new kind of Kit-owned path. Nothing is deleted on this path.
+
+const ALLOWED_SHAPE =
+  /^(?:\.claude\/skills\/[A-Za-z0-9._-]+\/|\.github\/(?:agent-runtime|agent-pipeline|security-audit)\/)$/;
+const SAFE_PATH = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\/$/;
+
+export class ManifestError extends Error {}
+
+function safe(line) {
+  const parts = line.slice(0, -1).split("/");
+  return (
+    SAFE_PATH.test(line) &&
+    !parts.includes("..") &&
+    !parts.includes(".") &&
+    !parts.some((p) => p.toLowerCase() === ".git")
+  );
+}
+
+/**
+ * @param {string} text
+ * @param {{ forDeletion?: boolean }} [opts]
+ */
+export function parseKitOwnedPaths(text, { forDeletion = true } = {}) {
+  const entries = [];
+  for (const raw of String(text).split("\n")) {
+    const line = raw.replace(/\r$/, "");
+    if (!line || line.startsWith("#")) continue;
+    const ok = safe(line) && (!forDeletion || ALLOWED_SHAPE.test(line));
+    if (!ok) {
+      throw new ManifestError(
+        `kit-owned-paths.txt: ${JSON.stringify(line)} is not a permitted Kit-owned path`,
+      );
+    }
+    if (entries.includes(line)) throw new ManifestError(`kit-owned-paths.txt lists ${line} twice`);
+    entries.push(line);
+  }
+  if (entries.length === 0) throw new ManifestError("kit-owned-paths.txt lists no paths");
+  return entries;
+}

package/src/kit-tag.mjs

@@ -0,0 +1,119 @@
+// 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).
+
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+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 { 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+)?$/;
+
+export class KitTagError extends Error {}
+
+/** A tag with no kit-owned-paths.txt (up to v1.0.0-alpha.10): the CLI refuses it. */
+export class PreManifestTagError extends KitTagError {
+  constructor(repo, tag, serverUrl = DEFAULT_SERVER) {
+    super(
+      `${tag} has no kit-owned-paths.txt, so the CLI cannot handle it ` +
+        `(the manifest ships from ${FIRST_MANIFEST_TAG}). Adopt or upgrade ${tag} by hand ` +
+        `with that tag's ${serverUrl}/${repo}/blob/${tag}/docs/adopt.md, ` +
+        `or move your pins to ${FIRST_MANIFEST_TAG} or later.`,
+    );
+    this.repo = repo;
+    this.tag = tag;
+  }
+}
+
+function checkPath(path) {
+  if (!SAFE_PATH.test(path) || path.split("/").includes("..")) {
+    throw new KitTagError(`refusing to read ${JSON.stringify(path)} from the tag`);
+  }
+  return path.replace(/\/$/, "");
+}
+
+/**
+ * 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,
+}) {
+  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)}`);
+  }
+  const url = remoteUrl ?? `${serverUrl}/${repo}.git`;
+  const tmp = mkdtempSync(join(tmpdir(), "agent-kit-tag-"));
+  const dir = join(tmp, "repo.git");
+  const noHooks = join(tmp, "no-hooks");
+  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]);
+  try {
+    let r = runner("git", ["init", "--bare", "--quiet", "--template=", dir]);
+    if (r.status !== 0) throw new KitTagError(`git init failed: ${firstLine(r.stderr)}`);
+    r = git(
+      "fetch",
+      "--quiet",
+      "--depth=1",
+      "--no-tags",
+      "--",
+      url,
+      `+refs/tags/${tag}:refs/tags/${tag}`,
+    );
+    if (r.status !== 0) {
+      throw new KitTagError(
+        `could not fetch ${tag} from ${repo}: ${firstLine(r.stderr) || "git fetch failed"}`,
+      );
+    }
+    r = git("rev-parse", "--verify", "--quiet", `refs/tags/${tag}^{commit}`);
+    if (r.status !== 0) throw new KitTagError(`${tag} does not point at a commit`);
+    const commit = r.stdout.trim();
+
+    const readFile = (path) => {
+      const res = git("cat-file", "blob", `${commit}:${checkPath(path)}`);
+      return res.status === 0 ? res.stdout : null;
+    };
+    const treeHash = (path) => {
+      // `<rev>:<path>` takes the rest as a path, so `^{tree}` cannot follow it:
+      // resolve the object, then check its type.
+      const res = git("rev-parse", "--verify", "--quiet", `${commit}:${checkPath(path)}`);
+      if (res.status !== 0) return null;
+      const hash = res.stdout.trim();
+      const type = git("cat-file", "-t", hash);
+      return type.status === 0 && type.stdout.trim() === "tree" ? hash : null;
+    };
+
+    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 };
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
+}