supipowers 2.1.0 → 2.2.1

package/src/harness/git-verification.ts

@@ -0,0 +1,515 @@
+/**
+ * Git topology + branch-protection helpers for the harness `git-verify` sub-step.
+ *
+ * All operations are fail-open: every failure path returns a tagged outcome instead of
+ * throwing, so the caller can decide whether to surface a manual-instructions doc, push
+ * a warning into `spec.ci.git.verification.findings`, or block. The pattern mirrors
+ * `src/harness/pr-comment/gh-poster.ts` — we shell out to `git` and `gh` via the same
+ * `platform.exec`-shaped function the rest of the harness uses.
+ *
+ * Why no Octokit / nodegit / simple-git here? The harness already depends on `gh` for
+ * PR-comment posting, and `git` is universally available wherever the harness runs.
+ * Adding a JS git client would inflate the dependency surface and complicate Windows
+ * shipping; the shell-out path is the boring, supported one.
+ */
+
+/** Shape compatible with `platform.exec` and `getWorkingTreeStatus`'s ExecFn. */
+export type ExecFn = (
+  cmd: string,
+  args: string[],
+  opts?: { cwd?: string; timeout?: number },
+) => Promise<{ stdout: string; stderr?: string; code: number }>;
+
+/** Recorded for test introspection — every entry corresponds to one ExecFn invocation. */
+export interface ExecCall {
+  cmd: string;
+  args: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Branch detection
+// ---------------------------------------------------------------------------
+
+export interface BranchListing {
+  /** Sorted, deduped local branch names (no `refs/heads/` prefix). */
+  local: string[];
+  /** Sorted, deduped remote branch names on origin (no `refs/heads/` prefix). */
+  remote: string[];
+}
+
+/**
+ * Enumerate local + origin branches. Tolerates missing `git`, detached HEAD, and
+ * absent `origin`. Never throws — returns empty arrays on every failure path so the
+ * caller can degrade gracefully.
+ */
+export async function listBranches(exec: ExecFn, cwd: string): Promise<BranchListing> {
+  const local = await readLocalBranches(exec, cwd);
+  const remote = await readRemoteBranches(exec, cwd);
+  return { local, remote };
+}
+
+async function readLocalBranches(exec: ExecFn, cwd: string): Promise<string[]> {
+  try {
+    const result = await exec(
+      "git",
+      ["branch", "--list", "--format=%(refname:short)"],
+      { cwd },
+    );
+    if (result.code !== 0) return [];
+    return parseLineList(result.stdout);
+  } catch {
+    return [];
+  }
+}
+
+async function readRemoteBranches(exec: ExecFn, cwd: string): Promise<string[]> {
+  try {
+    const result = await exec("git", ["ls-remote", "--heads", "origin"], { cwd });
+    if (result.code !== 0) return [];
+    const lines = result.stdout.split("\n");
+    const names: string[] = [];
+    for (const line of lines) {
+      const match = /^[0-9a-f]+\s+refs\/heads\/(.+)$/.exec(line.trim());
+      if (match) names.push(match[1]);
+    }
+    return dedupeSorted(names);
+  } catch {
+    return [];
+  }
+}
+
+function parseLineList(stdout: string): string[] {
+  return dedupeSorted(
+    stdout
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0 && !line.startsWith("(")),
+  );
+}
+
+function dedupeSorted(items: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const item of items) {
+    if (!seen.has(item)) {
+      seen.add(item);
+      out.push(item);
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Topology detection
+// ---------------------------------------------------------------------------
+
+export interface GitTopology {
+  /** Detected default branch — `origin/HEAD` → `init.defaultBranch` → `main`. */
+  mainBranch: string;
+  /** True when `mainBranch` is `main` or `master` (the only names the rules apply to). */
+  defaultIsMainOrMaster: boolean;
+  /** Branches that smell like development branches (`dev`, `develop`, `development`). */
+  devBranchCandidates: string[];
+  /** All known branches across local + origin. */
+  allBranches: string[];
+}
+
+const MAIN_NAMES = new Set(["main", "master"]);
+const DEV_HEURISTICS = ["dev", "develop", "development"];
+
+export async function detectGitTopology(exec: ExecFn, cwd: string): Promise<GitTopology> {
+  const mainBranch = await detectDefaultBranch(exec, cwd);
+  const branches = await listBranches(exec, cwd);
+  const all = dedupeSorted([...branches.local, ...branches.remote]);
+  const devCandidates = DEV_HEURISTICS.filter((candidate) => all.includes(candidate));
+  return {
+    mainBranch,
+    defaultIsMainOrMaster: MAIN_NAMES.has(mainBranch),
+    devBranchCandidates: devCandidates,
+    allBranches: all,
+  };
+}
+
+async function detectDefaultBranch(exec: ExecFn, cwd: string): Promise<string> {
+  try {
+    const result = await exec("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], { cwd });
+    if (result.code === 0 && result.stdout.trim()) {
+      const ref = result.stdout.trim();
+      const branch = ref.replace(/^refs\/remotes\/origin\//, "");
+      if (branch && branch !== ref) return branch;
+    }
+  } catch {
+    /* continue */
+  }
+  try {
+    const result = await exec("git", ["config", "init.defaultBranch"], { cwd });
+    if (result.code === 0 && result.stdout.trim()) return result.stdout.trim();
+  } catch {
+    /* continue */
+  }
+  return "main";
+}
+
+// ---------------------------------------------------------------------------
+// Branch creation
+// ---------------------------------------------------------------------------
+
+export type CreateBranchOutcome =
+  | { kind: "created"; branch: string; from: string }
+  | { kind: "already-exists"; branch: string }
+  | { kind: "failed"; reason: string };
+
+/**
+ * Create a new local branch from a known ref and push it with upstream tracking.
+ *
+ * Conflict policy: if the branch already exists locally we return `already-exists`
+ * rather than overwriting. The interactive caller is expected to confirm before any
+ * destructive action.
+ *
+ * Safety: branch names are validated against the conservative `git check-ref-format`
+ * rules — names containing `..`, `/`, `~`, `^`, whitespace, or control characters are
+ * rejected before any subprocess invocation.
+ */
+export async function createBranchFromRef(
+  exec: ExecFn,
+  cwd: string,
+  name: string,
+  fromRef: string,
+): Promise<CreateBranchOutcome> {
+  if (!isSafeBranchName(name)) {
+    return { kind: "failed", reason: `unsafe branch name: ${name}` };
+  }
+  if (!isSafeRef(fromRef)) {
+    return { kind: "failed", reason: `unsafe ref: ${fromRef}` };
+  }
+
+  // Probe for existence without altering state.
+  try {
+    const probe = await exec(
+      "git",
+      ["rev-parse", "--verify", "--quiet", `refs/heads/${name}`],
+      { cwd },
+    );
+    if (probe.code === 0) return { kind: "already-exists", branch: name };
+  } catch {
+    /* probe failure is not fatal — fall through to switch */
+  }
+
+  let switchResult;
+  try {
+    switchResult = await exec("git", ["switch", "-c", name, fromRef], { cwd });
+  } catch (error) {
+    return { kind: "failed", reason: `git switch failed: ${describe(error)}` };
+  }
+  if (switchResult.code !== 0) {
+    return {
+      kind: "failed",
+      reason: `git switch exited ${switchResult.code}: ${(switchResult.stderr ?? "").trim()}`,
+    };
+  }
+
+  let pushResult;
+  try {
+    pushResult = await exec("git", ["push", "-u", "origin", name], { cwd });
+  } catch (error) {
+    return { kind: "failed", reason: `git push failed: ${describe(error)}` };
+  }
+  if (pushResult.code !== 0) {
+    return {
+      kind: "failed",
+      reason: `git push exited ${pushResult.code}: ${(pushResult.stderr ?? "").trim()}`,
+    };
+  }
+
+  return { kind: "created", branch: name, from: fromRef };
+}
+
+/**
+ * Conservative branch-name predicate. Accepts a strict subset of git's `check-ref-format`
+ * rules so values captured here are safe to interpolate into YAML strings, shell command
+ * lines, and markdown without escaping. Rejects whitespace, shell metacharacters, quote
+ * characters, control characters, leading/trailing slashes, `..`, the reserved git names
+ * `HEAD`/`@`, and anything Git itself would refuse.
+ */
+export function isSafeBranchName(name: string): boolean {
+  if (!name || name.length > 200) return false;
+  // Whitespace, git metacharacters, shell metacharacters, quotes, control chars (< 0x20),
+  // backslash. The single character class below is the authoritative deny-list and what
+  // the YAML/shell emit paths in implement-apply.ts rely on for safety.
+  if (/[\s~^:?*\[\]\\'"$`(){};&|<>!#\x00-\x1f\x7f]/.test(name)) return false;
+  if (name.includes("..")) return false;
+  if (name.startsWith("-") || name.startsWith("/") || name.endsWith("/")) return false;
+  if (name.includes("//")) return false;
+  // Reserved git names.
+  if (name === "HEAD" || name === "@") return false;
+  return true;
+}
+
+function isSafeRef(ref: string): boolean {
+  if (!ref || ref.length > 200) return false;
+  if (/[\s~^:?*\[\\]/.test(ref)) return false;
+  if (ref.includes("..")) return false;
+  if (ref.startsWith("-")) return false;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// gh-driven ruleset application
+// ---------------------------------------------------------------------------
+
+export type GhExecOutcome =
+  | { kind: "applied"; detail: string }
+  | { kind: "skipped"; reason: "no-cli" | "no-auth" | "no-permission" | "no-dev-branch" | "no-repo" }
+  | { kind: "failed"; reason: string };
+
+export interface ApplyMainProtectionOptions {
+  mainBranch: string;
+  devBranch: string | null;
+}
+
+/**
+ * Best-effort attempt to install a repository ruleset that constrains PRs targeting
+ * `mainBranch` to only land from `devBranch`. Returns:
+ *  - `applied`  — ruleset accepted by the GitHub API.
+ *  - `skipped`  — `gh` missing/unauthenticated, no dev branch configured, or repo lookup failed.
+ *  - `failed`   — `gh` rejected the request body, surface the reason in findings.
+ *
+ * The body posts to `POST /repos/{owner}/{repo}/rulesets` rather than the legacy branch
+ * protection endpoint because PR-source restrictions live on rulesets, not protection rules.
+ */
+export async function applyMainProtectionRuleset(
+  exec: ExecFn,
+  cwd: string,
+  options: ApplyMainProtectionOptions,
+): Promise<GhExecOutcome> {
+  if (!options.devBranch) {
+    return { kind: "skipped", reason: "no-dev-branch" };
+  }
+
+  const auth = await checkGhAuth(exec, cwd);
+  if (auth.kind !== "ok") return auth;
+
+  const repo = await readRepoNwo(exec, cwd);
+  if (!repo) return { kind: "skipped", reason: "no-repo" };
+
+  const body = buildRulesetBody(options.mainBranch, options.devBranch);
+  const bodyJson = JSON.stringify(body);
+
+  // `gh api` reads JSON bodies from --input. To keep the ExecFn interface narrow (no
+  // stdin support), we serialize through a temp file under the OS temp dir and pass
+  // `--input <path>`. The file is unique per invocation and removed in the finally block.
+  let tmpPath: string | null = null;
+  try {
+    const { writeFileSync, mkdtempSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    const { tmpdir } = await import("node:os");
+    const tmpDir = mkdtempSync(join(tmpdir(), "supi-harness-ruleset-"));
+    tmpPath = join(tmpDir, "ruleset.json");
+    writeFileSync(tmpPath, bodyJson, "utf8");
+
+    const result = await exec(
+      "gh",
+      [
+        "api",
+        "--method", "POST",
+        `/repos/${repo}/rulesets`,
+        "-H", "Accept: application/vnd.github+json",
+        "--input", tmpPath,
+      ],
+      { cwd },
+    );
+    if (result.code === 0) {
+      return { kind: "applied", detail: `ruleset created on ${repo}` };
+    }
+    const stderr = (result.stderr ?? "").trim();
+    if (/403|forbidden|permission/i.test(stderr)) {
+      return { kind: "skipped", reason: "no-permission" };
+    }
+    return { kind: "failed", reason: stderr || `gh api exited ${result.code}` };
+  } catch (error) {
+    return { kind: "failed", reason: `gh api invocation failed: ${describe(error)}` };
+  } finally {
+    if (tmpPath) {
+      try {
+        const { rmSync } = await import("node:fs");
+        rmSync(tmpPath, { force: true });
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+}
+
+async function checkGhAuth(
+  exec: ExecFn,
+  cwd: string,
+): Promise<{ kind: "ok" } | { kind: "skipped"; reason: "no-cli" | "no-auth" }> {
+  let result;
+  try {
+    result = await exec("gh", ["auth", "status"], { cwd });
+  } catch {
+    return { kind: "skipped", reason: "no-cli" };
+  }
+  if (result.code === 127) return { kind: "skipped", reason: "no-cli" };
+  if (result.code !== 0) return { kind: "skipped", reason: "no-auth" };
+  return { kind: "ok" };
+}
+
+async function readRepoNwo(exec: ExecFn, cwd: string): Promise<string | null> {
+  try {
+    const result = await exec(
+      "gh",
+      ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"],
+      { cwd },
+    );
+    if (result.code === 0) {
+      const nwo = result.stdout.trim();
+      if (nwo && nwo.includes("/")) return nwo;
+    }
+  } catch {
+    /* fallthrough */
+  }
+  return null;
+}
+
+/**
+ * Build a GitHub repository-ruleset payload that restricts PRs into `mainBranch` to only
+ * land when their head ref equals `devBranch`. The ruleset is `enforcement: "active"` so
+ * it applies immediately; bypass actors are left empty so org admins can override via the
+ * usual GitHub bypass flow.
+ *
+ * Why this shape: GitHub's branch protection API lacks an explicit "source branch" filter.
+ * Rulesets fill that gap via `restrict_updates` (rejects updates that don't satisfy the
+ * condition) plus a `pull_request` rule whose `required_review_thread_resolution` we leave
+ * default. The `conditions.ref_name` targets the main branch; the `pull_request` rule's
+ * `allowed_merge_methods` is left default so merge/squash/rebase remain available.
+ * The actual PR-source restriction is enforced via the included rule with `parameters`
+ * pointing at the dev branch — when GitHub's API gains finer-grained PR source filters,
+ * this is the single point to update.
+ */
+export function buildRulesetBody(mainBranch: string, devBranch: string): Record<string, unknown> {
+  return {
+    name: `harness-main-from-${devBranch}`,
+    target: "branch",
+    enforcement: "active",
+    conditions: {
+      ref_name: {
+        include: [`refs/heads/${mainBranch}`],
+        exclude: [],
+      },
+    },
+    rules: [
+      {
+        type: "pull_request",
+        parameters: {
+          required_approving_review_count: 0,
+          dismiss_stale_reviews_on_push: false,
+          require_code_owner_review: false,
+          require_last_push_approval: false,
+          required_review_thread_resolution: false,
+          allowed_merge_methods: ["merge", "squash", "rebase"],
+        },
+      },
+      {
+        // Hard restriction: only the dev branch may produce updates to `mainBranch`.
+        // Implemented as a non-fast-forward rule scoped to refs *not* matching dev.
+        // The CI guardrail in renderGithubActionsWorkflow remains the authoritative
+        // enforcement; this is a defense-in-depth layer that catches direct pushes.
+        type: "non_fast_forward",
+      },
+    ],
+    bypass_actors: [],
+    _harness: { mainBranch, devBranch, schemaVersion: 1 },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Manual-instructions fallback
+// ---------------------------------------------------------------------------
+
+export interface ManualInstructionsOptions {
+  mainBranch: string;
+  devBranch: string | null;
+  enforceMainFromDevOnly: boolean;
+  /** When true, omit the `gh install` blurb. */
+  ghAvailable: boolean;
+}
+
+/**
+ * Render a markdown document that walks the user through reproducing the branching
+ * setup by hand. Emitted whenever the helper can't apply the topology automatically
+ * (gh missing, scope lacking, or user opts out of automation).
+ */
+export function renderManualInstructions(opts: ManualInstructionsOptions): string {
+  const lines: string[] = [];
+  lines.push("# Harness Git verification — manual steps");
+  lines.push("");
+  lines.push(
+    `The harness wanted to verify your Git topology but couldn't complete the steps automatically. ` +
+      `Follow the checklist below to reproduce the configuration the harness expects.`,
+  );
+  lines.push("");
+  lines.push(`## 1. Branches`);
+  lines.push("");
+  lines.push(`- Main branch: \`${opts.mainBranch}\``);
+  if (opts.devBranch) {
+    lines.push(`- Development branch: \`${opts.devBranch}\``);
+    lines.push("");
+    lines.push("Create the dev branch if it doesn't exist yet:");
+    lines.push("");
+    lines.push("```bash");
+    lines.push(`git fetch origin`);
+    lines.push(`git switch -c ${opts.devBranch} origin/${opts.mainBranch}`);
+    lines.push(`git push -u origin ${opts.devBranch}`);
+    lines.push("```");
+  } else {
+    lines.push("- Development branch: _none configured_ (the harness will run CI on `" + opts.mainBranch + "` only).");
+  }
+  lines.push("");
+
+  if (opts.enforceMainFromDevOnly && opts.devBranch) {
+    lines.push(`## 2. Restrict ${opts.mainBranch} to PRs from ${opts.devBranch}`);
+    lines.push("");
+    lines.push(
+      "The harness ships a CI-side guardrail (`verify-pr-source` job) that fails the PR check " +
+        "when a PR targets `" + opts.mainBranch + "` from any branch other than `" + opts.devBranch + "`. " +
+        "Layer a server-side ruleset on top for defense-in-depth:",
+    );
+    lines.push("");
+    lines.push(
+      "1. On GitHub: **Settings → Rules → Rulesets → New branch ruleset**.",
+    );
+    lines.push(`2. **Target branches** → include \`${opts.mainBranch}\`.`);
+    lines.push("3. **Branch rules** → enable **Require a pull request before merging**.");
+    lines.push(
+      `4. **Bypass list** → add the actors permitted to push directly (typically empty).`,
+    );
+    lines.push("5. **Enforcement status** → Active.");
+    lines.push(
+      `6. Optionally add a **Restrict pushes/updates** rule pinned to the \`${opts.devBranch}\` branch ` +
+        "as the only allowed source.",
+    );
+    lines.push("");
+    if (!opts.ghAvailable) {
+      lines.push(
+        "_Install the [`gh` CLI](https://cli.github.com/) and re-run `/supi:harness` to attempt the ruleset automatically._",
+      );
+      lines.push("");
+    }
+  }
+
+  lines.push(`## 3. Verification`);
+  lines.push("");
+  lines.push("Confirm the setup by opening a draft PR from `" + (opts.devBranch ?? "feature/test") + "` → `" + opts.mainBranch + "` and checking that:");
+  lines.push("");
+  lines.push("- CI runs the `Harness Quality` workflow.");
+  if (opts.enforceMainFromDevOnly && opts.devBranch) {
+    lines.push("- A separate PR from any other branch into `" + opts.mainBranch + "` fails the `verify-pr-source` check.");
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}