@a2f0/agent-tool 0.1.1

package/src/pr/mergeChecks.ts

@@ -0,0 +1,90 @@
+import { run } from "../git/prContext";
+import { loadConfig, type AgentToolConfig } from "../config";
+
+type CheckPolicy = Pick<AgentToolConfig["merge"], "requireChecks" | "requiredChecks">;
+
+function field(value: unknown, key: string): unknown {
+  return typeof value === "object" && value !== null
+    ? Reflect.get(value, key)
+    : undefined;
+}
+
+export function assertMergeChecks(source: string, expectedHead: string, policy: CheckPolicy = loadConfig().merge): void {
+  const payload: unknown = JSON.parse(source);
+  if (field(payload, "headRefOid") !== expectedHead) {
+    throw new Error(
+      "PR head changed while checking CI; re-review before merging.",
+    );
+  }
+  const checks = field(payload, "checks");
+  if (!Array.isArray(checks)) throw new Error("Could not read CI checks; refusing to merge.");
+  if (checks.length === 0 && policy.requireChecks) {
+    throw new Error("PR has no CI checks; refusing to merge.");
+  }
+  for (const check of checks) {
+    const name = field(check, "name");
+    const success = field(check, "state") === "SUCCESS";
+    const skipped = field(check, "state") === "SKIPPED";
+    if (!success && !skipped) {
+      throw new Error(
+        `CI check '${String(name)}' has not passed; refusing to merge.`,
+      );
+    }
+  }
+  for (const required of policy.requiredChecks) {
+    if (!checks.some(check => field(check, "name") === required.name && field(check, "state") === "SUCCESS" && (required.workflow === undefined || field(check, "workflow") === required.workflow))) {
+      throw new Error(
+        `Required CI check '${required.name}' has not passed; refusing to merge.`,
+      );
+    }
+  }
+}
+
+export function requirePassingMergeChecks(
+  pr: { readonly prNumber: string; readonly repo: string },
+  expectedHead: string,
+  read: typeof run = run,
+  policy: CheckPolicy = loadConfig().merge,
+): void {
+  // gh pr checks paginates and selects the latest run per workflow/job/event.
+  // Raw statusCheckRollup can retain failures from superseded runs. JSON mode
+  // can exit zero for pending/failed checks: assertMergeChecks enforces states.
+  // API and other command failures also throw before any merge.
+  let checks: unknown;
+  try {
+    checks = JSON.parse(
+      read("gh", [
+        "pr",
+        "checks",
+        pr.prNumber,
+        "-R",
+        pr.repo,
+        "--json",
+        "name,state,workflow",
+      ]),
+    );
+  } catch (error) {
+    if (policy.requireChecks || policy.requiredChecks.length) throw error;
+    // gh pr checks exits nonzero when no checks exist. Independently confirm
+    // an empty rollup before honoring an explicit no-check project policy.
+    const rollup = field(JSON.parse(read("gh", ["pr", "view", pr.prNumber, "-R", pr.repo, "--json", "statusCheckRollup"])), "statusCheckRollup");
+    if (!Array.isArray(rollup) || rollup.length !== 0) throw error;
+    checks = [];
+  }
+  const head: unknown = JSON.parse(
+    read("gh", [
+      "pr",
+      "view",
+      pr.prNumber,
+      "-R",
+      pr.repo,
+      "--json",
+      "headRefOid",
+    ]),
+  );
+  assertMergeChecks(
+    JSON.stringify({ headRefOid: field(head, "headRefOid"), checks }),
+    expectedHead,
+    policy,
+  );
+}

package/src/pr/openPr.ts

@@ -0,0 +1,80 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import {
+  findOpenPrNumber,
+  remoteBranchHead,
+  resolveRepoContext,
+  resolveRepositoryGitUrl,
+  run,
+  spawnExitCode,
+} from "../git/prContext";
+import { assertBranchPushed } from "./assertBranchPushed";
+import { assertNoClaudeBranding } from "./assertNoClaudeBranding";
+import { singleLineSubject } from "./subjectLine";
+import { validateCommitSubject } from "./validateCommitSubject";
+import { loadConfig } from "../config";
+
+/** Read the PR body from stdin, or "" when stdin is a terminal/empty. */
+function readBody(): string {
+  // With no pipe/redirect, fd 0 is an open TTY and a blocking read would hang.
+  if (process.stdin.isTTY) {
+    return "";
+  }
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Open a pull request for the current branch with a policy-conforming
+ * title. The title defaults to the branch's latest commit subject, is validated
+ * against data-only project policy before the PR is created; the body is read from
+ * stdin. The base defaults to the repository's default branch. The branch must
+ * already be pushed at the local head; this never pushes.
+ */
+export function openPr(rootDir: string, titleArg: string | undefined): number {
+  const { branch, repo, defaultBranch } = resolveRepoContext();
+
+  const existing = findOpenPrNumber(branch, repo);
+  if (existing.length > 0) {
+    throw new Error(`An open PR already exists for '${branch}': #${existing}.`);
+  }
+
+  const tipSubject = run("git", ["log", "-1", "--format=%s"]);
+  const title = singleLineSubject(titleArg, tipSubject, "PR title");
+  validateCommitSubject(rootDir, title);
+
+  const body = readBody();
+  if (loadConfig(rootDir).pr.rejectClaudeBranding) assertNoClaudeBranding(body);
+
+  // Local validation first; the remote head is the last thing checked.
+  assertBranchPushed({
+    branch,
+    localHead: run("git", ["rev-parse", "HEAD"]),
+    remoteHead: remoteBranchHead(resolveRepositoryGitUrl(repo), branch),
+  });
+
+  // Pin the base to the repo default branch; without --base, gh honors a
+  // branch.<name>.gh-merge-base git config that could target another branch.
+  const baseArgs = defaultBranch.length > 0 ? ["--base", defaultBranch] : [];
+  const result = spawnSync(
+    "gh",
+    [
+      "pr",
+      "create",
+      "--title",
+      title,
+      "--body-file",
+      "-",
+      "--head",
+      branch,
+      ...baseArgs,
+      "-R",
+      repo,
+    ],
+    { input: body, stdio: ["pipe", "inherit", "inherit"] },
+  );
+  return spawnExitCode("gh pr create", result);
+}

package/src/pr/prNumberSuffix.ts

@@ -0,0 +1,43 @@
+// Matches a trailing GitHub reference like " (#1531)" at the very end of a
+// subject line. Anchored to the end so a mid-subject reference is left intact,
+// and un-globbed so only the final reference is removed per call.
+const PR_NUMBER_SUFFIX = /\s*\(#\d+\)$/;
+
+/** Strip the single trailing `(#<n>)` reference from a subject, if present. */
+export function stripPrNumberSuffix(subject: string): string {
+  return subject.replace(PR_NUMBER_SUFFIX, "");
+}
+
+/**
+ * Append ` (#<prNumber>)` to a subject that has already had its trailing
+ * reference removed (see `stripPrNumberSuffix`). Deliberately strip-free: the
+ * caller strips exactly once, so the validated base and the merged subject stay
+ * in sync and an earlier `(#<n>)` reference is never silently discarded. Throws
+ * when `prNumber` is not a positive integer.
+ */
+export function appendPrNumberSuffix(
+  baseSubject: string,
+  prNumber: string,
+): string {
+  if (!/^\d+$/.test(prNumber)) {
+    throw new Error(
+      `Invalid PR number '${prNumber}' for the squash subject suffix.`,
+    );
+  }
+  const result = `${baseSubject} (#${prNumber})`;
+  assertPrNumberSuffix(result, prNumber);
+  return result;
+}
+
+/**
+ * Assert a subject ends with the exact `(#<prNumber>)` reference — the invariant
+ * every squash subject must satisfy before the merge runs.
+ */
+export function assertPrNumberSuffix(subject: string, prNumber: string): void {
+  const suffix = ` (#${prNumber})`;
+  if (!subject.endsWith(suffix)) {
+    throw new Error(
+      `Squash subject must end with '${suffix}', got: '${subject}'.`,
+    );
+  }
+}

package/src/pr/squashMerge.ts

@@ -0,0 +1,229 @@
+import { spawnSync } from "node:child_process";
+
+import { loadConfig } from "../config";
+import { prState, resolvePr, run, spawnExitCode } from "../git/prContext";
+import { assertStrictBaseFreshness } from "./baseFreshness";
+import { requirePassingMergeChecks } from "./mergeChecks";
+import {
+  appendPrNumberSuffix,
+  assertPrNumberSuffix,
+  stripPrNumberSuffix,
+} from "./prNumberSuffix";
+import { singleLineSubject } from "./subjectLine";
+import { validateCommitSubject } from "./validateCommitSubject";
+
+/**
+ * Resolve the squash subject from the CLI argument, falling back to the PR
+ * title. Rejects an empty subject and any embedded line break so the squash
+ * commit stays a single subject line.
+ */
+export function resolveSubject(
+  subjectArg: string | undefined,
+  prTitle: string,
+): string {
+  return singleLineSubject(subjectArg, prTitle, "squash subject");
+}
+
+const PULL_REQUEST_MERGE_TARGET_QUERY = `
+  query($owner: String!, $name: String!, $number: Int!) {
+    repository(owner: $owner, name: $name) {
+      pullRequest(number: $number) {
+        autoMergeRequest { enabledAt }
+        baseRefName
+        headRefOid
+        id
+        isInMergeQueue
+        state
+      }
+    }
+  }
+`;
+
+const MERGE_PULL_REQUEST_MUTATION = `
+  mutation(
+    $pullRequestId: ID!
+    $commitHeadline: String!
+    $commitBody: String!
+    $expectedHeadOid: GitObjectID!
+    $mergeMethod: PullRequestMergeMethod!
+  ) {
+    mergePullRequest(input: {
+      pullRequestId: $pullRequestId
+      commitHeadline: $commitHeadline
+      commitBody: $commitBody
+      expectedHeadOid: $expectedHeadOid
+      mergeMethod: $mergeMethod
+    }) {
+      pullRequest { state }
+    }
+  }
+`;
+
+interface PullRequestMergeTarget {
+  readonly baseRefName: string;
+  readonly headOid: string;
+  readonly id: string;
+}
+
+function recordField(value: unknown, key: string): unknown {
+  return typeof value === "object" && value !== null
+    ? Reflect.get(value, key)
+    : undefined;
+}
+
+/** Parse the current target and reject unsafe asynchronous merge state. */
+export function parsePullRequestMergeTarget(
+  source: string,
+  expectedBaseRef?: string,
+): PullRequestMergeTarget {
+  const parsed: unknown = JSON.parse(source);
+  const data = recordField(parsed, "data");
+  const repository = recordField(data, "repository");
+  const pullRequest = recordField(repository, "pullRequest");
+  const baseRefName = recordField(pullRequest, "baseRefName");
+  const id = recordField(pullRequest, "id");
+  const headOid = recordField(pullRequest, "headRefOid");
+  const state = recordField(pullRequest, "state");
+  if (
+    state !== "OPEN" ||
+    typeof baseRefName !== "string" ||
+    typeof id !== "string" ||
+    typeof headOid !== "string"
+  ) {
+    throw new Error("Could not resolve an open pull request merge target.");
+  }
+  if (
+    recordField(pullRequest, "isInMergeQueue") === true ||
+    recordField(pullRequest, "autoMergeRequest") !== null
+  ) {
+    throw new Error(
+      "Pull request already has a queued or automatic merge; cancel it before running squashMerge.",
+    );
+  }
+  if (expectedBaseRef !== undefined && baseRefName !== expectedBaseRef) {
+    throw new Error(
+      `Pull request base changed from '${expectedBaseRef}' to '${baseRefName}'; revalidate and re-review before merging.`,
+    );
+  }
+  return { baseRefName, headOid, id };
+}
+
+function resolvePullRequestMergeTarget(
+  pr: {
+    prNumber: string;
+    repo: string;
+  },
+  expectedBaseRef?: string,
+): PullRequestMergeTarget {
+  const repoParts = pr.repo.split("/");
+  if (repoParts.length !== 2 || repoParts.some((part) => part.length === 0)) {
+    throw new Error(`Invalid repository slug '${pr.repo}'.`);
+  }
+  const [owner, name] = repoParts;
+  const source = run("gh", [
+    "api",
+    "graphql",
+    "-f",
+    `query=${PULL_REQUEST_MERGE_TARGET_QUERY}`,
+    "-f",
+    `owner=${owner}`,
+    "-f",
+    `name=${name}`,
+    "-F",
+    `number=${pr.prNumber}`,
+  ]);
+  return parsePullRequestMergeTarget(source, expectedBaseRef);
+}
+
+/**
+ * Build a direct GraphQL merge mutation for a subject-only squash. Unlike
+ * `gh pr merge`, this cannot silently enable auto-merge or enqueue the PR.
+ */
+export function buildSquashMergeArgs(
+  target: PullRequestMergeTarget,
+  finalSubject: string,
+  prNumber: string,
+  expectedHeadSha?: string,
+): string[] {
+  // Keep the final assertion at the mutation boundary so no caller can build a
+  // custom headline that accidentally suppresses GitHub's PR reference.
+  assertPrNumberSuffix(finalSubject, prNumber);
+  return [
+    "api",
+    "graphql",
+    "-f",
+    `query=${MERGE_PULL_REQUEST_MUTATION}`,
+    "-f",
+    `pullRequestId=${target.id}`,
+    "-f",
+    `commitHeadline=${finalSubject}`,
+    // Empty body keeps the squash commit to the subject line only.
+    "-f",
+    "commitBody=",
+    "-f",
+    `expectedHeadOid=${expectedHeadSha || target.headOid}`,
+    "-f",
+    "mergeMethod=SQUASH",
+  ];
+}
+
+/**
+ * Squash-merge the open PR for the current branch with a subject-only commit
+ * message — no auto-generated body or extended message. The subject defaults to
+ * the PR title when one is not supplied, and is validated against the repo's
+ * data-only subject policy before the merge runs. When `expectedHeadSha` is supplied the
+ * merge is bound to that commit through GraphQL's `expectedHeadOid` input. An
+ * expected base ref is checked immediately before the mutation, but GitHub has
+ * no corresponding atomic merge precondition for the target branch; policy can
+ * require a non-bypassable strict status rule that makes GitHub enforce it.
+ */
+export function squashMerge(
+  rootDir: string,
+  subjectArg: string | undefined,
+  expectedHeadSha?: string,
+  expectedBaseRef?: string,
+): number {
+  const pr = resolvePr();
+  const subject = resolveSubject(subjectArg, pr.title);
+
+  // Validate the human-authored subject without the PR-number suffix: GitHub's
+  // native squash appends `(#<n>)` server-side, past the commit-msg hook, so the
+  // repo's existing history carries suffixes over its configured header limit. Keep
+  // the suffix "free" here too by validating the base, then append it ourselves —
+  // a custom GraphQL commit headline otherwise drops GitHub's automatic reference.
+  const baseSubject = stripPrNumberSuffix(subject);
+  validateCommitSubject(rootDir, baseSubject);
+  const finalSubject = appendPrNumberSuffix(baseSubject, pr.prNumber);
+  const mergeTarget = resolvePullRequestMergeTarget(pr, expectedBaseRef);
+  if (loadConfig(rootDir).merge.requireStrictBaseFreshness) {
+    assertStrictBaseFreshness(pr.repo, mergeTarget.baseRefName);
+  }
+  requirePassingMergeChecks(pr, expectedHeadSha || mergeTarget.headOid);
+
+  const result = spawnSync(
+    "gh",
+    buildSquashMergeArgs(
+      mergeTarget,
+      finalSubject,
+      pr.prNumber,
+      expectedHeadSha,
+    ),
+    { stdio: "inherit" },
+  );
+  const exitCode = spawnExitCode("GitHub mergePullRequest mutation", result);
+  if (exitCode !== 0) {
+    return exitCode;
+  }
+
+  // Confirm that GitHub committed the direct mutation before cleanup can run.
+  const state = prState(pr.prNumber, pr.repo);
+  if (state !== "MERGED") {
+    process.stderr.write(
+      `PR #${pr.prNumber} is not merged (state: ${state || "unknown"}). ` +
+        "The synchronous subject-only squash did not land.\n",
+    );
+    return 1;
+  }
+
+  return 0;
+}

package/src/pr/subjectLine.ts

@@ -0,0 +1,21 @@
+/**
+ * Resolve a single-line commit-style subject: trim the supplied value, fall
+ * back to `fallback` when it is empty, and reject an empty result or any
+ * embedded line break so the value stays a single header line (commitlint would
+ * otherwise accept later lines as a body and let them through). `noun` labels
+ * the value in error messages.
+ */
+export function singleLineSubject(
+  value: string | undefined,
+  fallback: string,
+  noun: string,
+): string {
+  const subject = (value ?? "").trim() || fallback;
+  if (subject.length === 0) {
+    throw new Error(`No ${noun} provided and no fallback is available.`);
+  }
+  if (/[\r\n]/.test(subject)) {
+    throw new Error(`${noun} must be a single line (no line breaks).`);
+  }
+  return subject;
+}

package/src/pr/validateCommitSubject.ts

@@ -0,0 +1,12 @@
+import { loadConfig } from "../config";
+
+/** Validate a data-only header policy without running branch-controlled code. */
+export function validateCommitSubject(rootDir: string, subject: string): void {
+  const policy = loadConfig(rootDir).subject;
+  if (!subject.trim() || /[\r\n]/.test(subject)) throw new Error("Commit subject must be a nonempty single line.");
+  if ([...subject].length > policy.maxLength) throw new Error(`Commit subject exceeds ${policy.maxLength} characters.`);
+  if (policy.conventional) {
+    const match = /^([a-z]+)(?:\([^\r\n()]+\))?!?: \S.*$/.exec(subject);
+    if (!match || !policy.types.includes(match[1]!)) throw new Error(`Commit subject must use a conventional type: ${policy.types.join(", ")}.`);
+  }
+}

package/src/review/destinationPaths.ts

@@ -0,0 +1,154 @@
+import {
+  closeSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readdirSync,
+  rmSync,
+} from "node:fs";
+import path from "node:path";
+
+function portableCollisionKey(relativePath: string): string {
+  return relativePath.normalize("NFC").toLowerCase().normalize("NFC");
+}
+
+export function destinationFor(rootDir: string, relativePath: string): string {
+  const resolvedRoot = path.resolve(rootDir);
+  const destination = path.resolve(resolvedRoot, ...relativePath.split("/"));
+  const relativeDestination = path.relative(resolvedRoot, destination);
+  if (
+    relativeDestination === "" ||
+    relativeDestination === ".." ||
+    relativeDestination.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relativeDestination)
+  ) {
+    throw new Error(
+      `Unsafe destination in reviewed Git tree: ${JSON.stringify(relativePath)}`,
+    );
+  }
+  return destination;
+}
+
+function collision(prior: string, candidate: string): never {
+  throw new Error(
+    `Colliding paths in reviewed Git tree: ${JSON.stringify(prior)} and ${JSON.stringify(candidate)}`,
+  );
+}
+
+function nodeIdentity(destination: string): string {
+  const stats = lstatSync(destination);
+  return `${stats.dev}:${stats.ino}`;
+}
+
+function priorFilesystemAlias(
+  destination: string,
+  identities: ReadonlyMap<string, string>,
+): string | undefined {
+  try {
+    return identities.get(nodeIdentity(destination));
+  } catch {
+    return undefined;
+  }
+}
+
+function assertExactStoredName(
+  destination: string,
+  relativePath: string,
+): void {
+  const expectedName = Buffer.from(relativePath.split("/").at(-1) ?? "");
+  const exactNameExists = readdirSync(path.dirname(destination), {
+    encoding: "buffer",
+  }).some((name) => Buffer.compare(Buffer.from(name), expectedName) === 0);
+  if (!exactNameExists) {
+    throw new Error(
+      `Destination filesystem rewrote reviewed Git path: ${JSON.stringify(relativePath)}`,
+    );
+  }
+}
+
+function probeDestinationFilesystem(
+  rootDir: string,
+  relativePaths: string[],
+): void {
+  if (relativePaths.length === 0) {
+    return;
+  }
+  const directories = new Set<string>();
+  for (const relativePath of relativePaths) {
+    const segments = relativePath.split("/");
+    for (let end = 1; end < segments.length; end += 1) {
+      directories.add(segments.slice(0, end).join("/"));
+    }
+  }
+  const nodes = new Map<string, boolean>();
+  for (const directory of directories) {
+    nodes.set(directory, true);
+  }
+  for (const relativePath of relativePaths) {
+    if (nodes.has(relativePath)) {
+      collision(relativePath, relativePath);
+    }
+    nodes.set(relativePath, false);
+  }
+  const orderedNodes = [...nodes].sort(([left], [right]) => {
+    const depth = left.split("/").length - right.split("/").length;
+    return depth || Buffer.compare(Buffer.from(left), Buffer.from(right));
+  });
+  const probeRoot = mkdtempSync(
+    path.join(rootDir, ".agent-tool-destination-probe-"),
+  );
+  const identities = new Map<string, string>();
+  try {
+    for (const [relativePath, isDirectory] of orderedNodes) {
+      const destination = destinationFor(probeRoot, relativePath);
+      try {
+        if (isDirectory) {
+          mkdirSync(destination);
+        } else {
+          closeSync(openSync(destination, "wx"));
+        }
+      } catch (error) {
+        const prior = priorFilesystemAlias(destination, identities);
+        if (prior !== undefined) {
+          collision(prior, relativePath);
+        }
+        throw new Error(
+          `Destination filesystem rejected reviewed Git path: ${JSON.stringify(relativePath)}`,
+          { cause: error },
+        );
+      }
+      const identity = nodeIdentity(destination);
+      const prior = identities.get(identity);
+      if (prior !== undefined && prior !== relativePath) {
+        collision(prior, relativePath);
+      }
+      identities.set(identity, relativePath);
+      assertExactStoredName(destination, relativePath);
+    }
+  } finally {
+    rmSync(probeRoot, { recursive: true, force: true });
+  }
+}
+
+/** Reject paths that alias lexically or on the actual snapshot filesystem. */
+export function validateDestinationPaths(
+  rootDir: string,
+  relativePaths: string[],
+): void {
+  const seenPaths = new Map<string, string>();
+  for (const relativePath of relativePaths) {
+    const segments = relativePath.split("/");
+    for (let end = 1; end <= segments.length; end += 1) {
+      const candidate = segments.slice(0, end).join("/");
+      const key = portableCollisionKey(candidate);
+      const prior = seenPaths.get(key);
+      if (prior !== undefined && prior !== candidate) {
+        collision(prior, candidate);
+      }
+      seenPaths.set(key, candidate);
+    }
+    destinationFor(rootDir, relativePath);
+  }
+  probeDestinationFilesystem(rootDir, relativePaths);
+}

package/src/review/executable.ts

@@ -0,0 +1,34 @@
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import type { ReviewerEnv } from "./runReview";
+
+function within(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+/**
+ * Find a PATH executable whose entry and target both lie outside the
+ * repository. `candidate` keeps the PATH entry, which multi-call binaries such
+ * as `bunx` need; `resolved` is its real file.
+ */
+export function outsideExecutable(name: string, env: ReviewerEnv, repositoryRoot = process.cwd()): { candidate: string; resolved: string } | undefined {
+  const root = realpathSync(repositoryRoot);
+  for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+    if (!path.isAbsolute(directory)) continue;
+    const candidate = path.join(directory, name);
+    try {
+      accessSync(candidate, constants.X_OK);
+      const resolved = realpathSync(candidate);
+      if (!statSync(resolved).isFile() || within(root, candidate) || within(root, resolved)) continue;
+      return { candidate, resolved };
+    } catch { /* Continue searching outside the repository. */ }
+  }
+  // Never fall back to a predictable path or PATH resolution after rejection.
+  return undefined;
+}
+
+/** Never launch a reviewer binary supplied by the repository being reviewed. */
+export function reviewExecutable(name: string, env: ReviewerEnv, repositoryRoot = process.cwd()): string | undefined {
+  return outsideExecutable(name, env, repositoryRoot)?.resolved;
+}