pstack-claude-mirror 0.0.0-stage → 0.9.133

package/plugins/pstack/skills/poteto-mode/scripts/watch-pr/render.ts

@@ -0,0 +1,200 @@
+import type * as T from "./types.ts";
+export const renderJson = (verdict: T.WatcherVerdict): string =>
+  `${JSON.stringify(verdict)}\n`;
+function ciCell(row: T.PrSnapshot): string {
+  if (row.kind !== "open") return "\u2014";
+  const was = row.ci.hadPreviousPassingCi ? ", was ✅" : "";
+  switch (row.ci.kind) {
+    case "ci-clean":
+      return "✅";
+    case "ci-none":
+      return "➖ no checks";
+    case "ci-unreported":
+      return "⏳ no checks reported yet";
+    case "ci-pending":
+      return `⏳ ${row.ci.pending.length} pending${was}`;
+    case "ci-failing":
+      return `❌ ${row.ci.failed.length} failed${row.ci.pending.length ? `, ${row.ci.pending.length} pending` : ""}${was}`;
+    case "ci-github-rejected":
+      return `❌ GitHub reports failing checks${was}`;
+    default: {
+      const exhaustive: never = row.ci;
+      return exhaustive;
+    }
+  }
+}
+function reviewCell(row: T.PrSnapshot): string {
+  if (row.kind !== "open") return "\u2014";
+  const open = row.threads.length;
+  return row.reviewAutomationRunning
+    ? open
+      ? `🤖 running, ${open} open`
+      : "🤖 running"
+    : open
+      ? `📝 ${open} open`
+      : row.facts.reviewDecision === "REVIEW_REQUIRED"
+        ? "👀 review required"
+        : "✅";
+}
+function mergeCell(row: T.PrSnapshot): string {
+  if (row.kind === "merged") return "✅ merged";
+  if (row.kind === "closed") return "❌ closed";
+  if (row.facts.isDraft) return "⏸ draft";
+  if (row.facts.reviewDecision === "CHANGES_REQUESTED")
+    return "⚠️ changes requested";
+  return row.facts.mergeable === "CONFLICTING" ||
+    row.facts.mergeStateStatus === "DIRTY" ||
+    row.facts.mergeStateStatus === "CONFLICTING"
+    ? "⚠️ conflict"
+    : row.facts.mergeable === "UNKNOWN" ||
+        row.facts.mergeStateStatus === "UNKNOWN"
+      ? "⏳ mergeability unknown"
+      : row.facts.mergeStateStatus === "BLOCKED"
+        ? "⛔ blocked"
+        : row.facts.mergeStateStatus === "BEHIND"
+          ? "⚠️ behind base"
+          : "✅";
+}
+export function renderStatusTable(rows: T.NonEmpty<T.PrSnapshot>): string {
+  const lines = ["| PR | CI | Review | Merge |", "| --- | --- | --- | --- |"];
+  for (const row of rows) {
+    const url = `https://github.com/${row.context.owner}/${row.context.repo}/pull/${row.context.number}`;
+    lines.push(
+      `| [#${row.context.number}](${url}) | ${ciCell(row)} | ${reviewCell(row)} | ${mergeCell(row)} |`
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+function threadLine(thread: T.ReviewThread): string {
+  const comment = thread.firstComment;
+  return [
+    thread.id,
+    comment?.path ?? "None",
+    comment?.line ?? "None",
+    comment?.authorLogin ?? "None",
+    `isBugBot=${thread.isBugbot}`,
+    `bugbotReviewPasses=${thread.bugbotReviewPasses}`,
+    (comment?.body ?? "").split(/\r?\n/, 1)[0]?.slice(0, 180) ?? "",
+  ].join(" ");
+}
+type StatusQueryBlocker = {
+  readonly kind: "status-query";
+  readonly failures: number;
+  readonly failure: Pick<T.QueryFailure, "kind" | "detail">;
+};
+function renderBlocker(blocker: T.MergeBlocker | StatusQueryBlocker): string {
+  switch (blocker.kind) {
+    case "merge-conflicts":
+      return [
+        "BLOCKER: merge-conflicts",
+        `pr=${blocker.pr.number}`,
+        `mergeable=${blocker.facts.mergeable}`,
+        `mergeStateStatus=${blocker.facts.mergeStateStatus}`,
+        "action=resolve merge conflicts before waiting for CI",
+      ].join("\n");
+    case "review-threads":
+      return [
+        "BLOCKER: review-threads",
+        `pr=${blocker.pr.number}`,
+        `unresolved=${blocker.threads.length}`,
+        ...blocker.threads.map(threadLine),
+      ].join("\n");
+    case "failing-checks": {
+      const failed = blocker.ci.kind === "ci-failing" ? blocker.ci.failed : [];
+      const details = failed.map(
+        (check) =>
+          `${check.name} ${check.reportedState} ${check.description} ${check.link}`
+      );
+      if (blocker.ci.kind === "ci-github-rejected")
+        details.push(
+          `mergeStateStatus=${blocker.ci.github.mergeStateStatus}`,
+          `headRollupState=${blocker.ci.github.headRollupState}`
+        );
+      return [
+        "BLOCKER: failing-checks",
+        `pr=${blocker.pr.number}`,
+        `failed=${failed.length}`,
+        ...details,
+      ].join("\n");
+    }
+    case "merge-gate": {
+      const action =
+        blocker.reason === "closed-without-merge"
+          ? "restore or remove the closed PR from the queued stack"
+          : blocker.reason === "draft-pr"
+            ? "mark the PR ready for review before waiting for the merge queue"
+            : blocker.reason === "review-required"
+              ? "get the required approving review"
+              : blocker.reason === "merge-blocked"
+                ? "find the branch protection rule holding the merge (mergeStateStatus=BLOCKED with clean CI)"
+                : blocker.reason === "changes-requested"
+                  ? "resolve the changes-requested review before waiting for the merge queue"
+                  : blocker.reason === "behind-base"
+                    ? "update the branch with its base before waiting for the merge queue (mergeStateStatus=BEHIND)"
+                    : (blocker.reason satisfies never);
+      return [
+        `BLOCKER: ${blocker.reason}`,
+        `pr=${blocker.pr.number}`,
+        `action=${action}`,
+      ].join("\n");
+    }
+    case "status-query":
+      return [
+        "BLOCKER: status-query",
+        `failures=${blocker.failures}`,
+        `detail=${blocker.failure.detail}`,
+        blocker.failure.kind === "spawn-failed"
+          ? "action=install the command that could not run, or put it on PATH, then rearm"
+          : "action=verify current PR context, GitHub authentication, and API availability, then rearm",
+      ].join("\n");
+    default: {
+      const exhaustive: never = blocker;
+      return exhaustive;
+    }
+  }
+}
+export function renderPretty(verdict: T.WatcherVerdict): string {
+  switch (verdict.kind) {
+    case "QUEUE":
+      return `QUEUE: captured ${verdict.queue.length} PR${verdict.queue.length === 1 ? "" : "s"} bottom-to-top: ${verdict.queue.map((pr) => `#${pr.number}`).join(",")}\n`;
+    case "STATUS":
+      return renderStatusTable(verdict.rows);
+    case "WAITING":
+      if (verdict.reason.kind === "checks-unreported")
+        return `WAITING: frontier=#${verdict.frontier.number}; no checks have reported on the head commit yet\n`;
+      if (verdict.reason.kind === "mergeability-unknown")
+        return `WAITING: frontier=#${verdict.frontier.number}; GitHub has not computed mergeability yet\n`;
+      return verdict.reason.kind === "pending-checks"
+        ? `WAITING: frontier=#${verdict.frontier.number}; ${verdict.reason.pending.length} check${verdict.reason.pending.length === 1 ? "" : "s"} pending\n`
+        : `WAITING: frontier=#${verdict.frontier.number} is blocker-free; waiting for merge queue (${verdict.reason.unmergedCount} PR${verdict.reason.unmergedCount === 1 ? "" : "s"} unmerged)\n`;
+    case "ADVANCE":
+      return `ADVANCE: merged #${verdict.merged.number}; next=#${verdict.frontier.number}; remaining=${verdict.remaining}\n`;
+    case "RETRY":
+      return `RETRY: ${verdict.failure.kind === "snapshot-changed" ? "the PR changed while its status was being read" : "GitHub status query failed"}; retrying in ${verdict.retryInSeconds}s\ndetail=${verdict.failure.detail}\n`;
+    case "BLOCKER":
+      return `${renderBlocker(verdict.blocker)}\n`;
+    case "READY": {
+      const detail =
+        verdict.scope.kind === "single" && verdict.scope.pr.kind === "ready-pr"
+          ? `\nmergeStateStatus=${verdict.scope.pr.proof.ci.github.mergeStateStatus}\nreviewDecision=${verdict.scope.pr.proof.gate.reviewDecision}\nisDraft=${verdict.scope.pr.proof.gate.draft === "draft-allowed"}${verdict.scope.pr.proof.gate.draft === "draft-allowed" ? "\nnote=draft allowed (--allow-draft); leave draft \u2014 do not mark ready" : ""}${verdict.scope.pr.proof.ci.kind === "ci-none" ? "\nchecks=none reported on the head commit" : ""}`
+          : "";
+      return `READY: no merge conflicts, no unresolved review threads, no failing or pending checks${detail}\n`;
+    }
+    case "COMPLETE":
+      return `COMPLETE: queued stack merged (${verdict.queue.length} PR${verdict.queue.length === 1 ? "" : "s"})\n`;
+    case "TIMEOUT":
+      if (verdict.reason.kind === "pending-checks")
+        return "TIMEOUT: checks still pending\n";
+      if (verdict.reason.kind === "checks-unreported")
+        return "TIMEOUT: no checks reported on the head commit yet\n";
+      if (verdict.reason.kind === "mergeability-unknown")
+        return "TIMEOUT: GitHub has not computed mergeability yet\n";
+      if (verdict.reason.kind === "status-unavailable")
+        return "TIMEOUT: GitHub status remained unavailable\n";
+      return `TIMEOUT: queued stack still has ${verdict.reason.unmergedCount} PR${verdict.reason.unmergedCount === 1 ? "" : "s"} unmerged; frontier=#${verdict.reason.frontier.number}\n`;
+    default: {
+      const exhaustive: never = verdict;
+      return exhaustive;
+    }
+  }
+}

package/plugins/pstack/skills/poteto-mode/scripts/watch-pr/ship-pr

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { ensureDependenciesInstalled } from "../bootstrap.ts";
+
+ensureDependenciesInstalled();
+const { main } = await import("./shipping-cli.ts");
+process.exitCode = await main(process.argv.slice(2));

package/plugins/pstack/skills/poteto-mode/scripts/watch-pr/shipping-cli.test.ts

@@ -0,0 +1,159 @@
+import { expect, it } from "bun:test";
+import { spawnSync } from "node:child_process";
+import {
+  chmodSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { object } from "./landing.ts";
+
+function fixture(
+  body: (
+    run: (...args: string[]) => {
+      status: number | null;
+      output: Record<string, unknown>;
+    },
+    file: string,
+    dir: string
+  ) => void
+) {
+  const dir = mkdtempSync(join(tmpdir(), "shipping-cli-"));
+  const file = join(dir, "state.json");
+  writeFileSync(
+    file,
+    JSON.stringify({
+      id: "pr-id",
+      state: "OPEN",
+      headRefOid: "head",
+      baseRefName: "main",
+      baseRefOid: "stored-base",
+      baseRef: { target: { oid: "base" } },
+      autoMergeRequest: { enabledAt: "now" },
+      mergeQueueEntry: { id: "queue" },
+      mergeCommit: null,
+    })
+  );
+  const gh = join(dir, "gh");
+  writeFileSync(
+    gh,
+    `#!${process.execPath}
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fakeGitHub } from ${JSON.stringify(join(import.meta.dir, "shipping.test-helper.ts"))};
+const state = JSON.parse(readFileSync(process.env.SHIPPING_STATE, 'utf8'));
+const response = fakeGitHub(state, process.argv.slice(2));
+writeFileSync(process.env.SHIPPING_STATE, JSON.stringify(state));
+console.log(JSON.stringify(response));
+`
+  );
+  chmodSync(gh, 0o755);
+  const entry = join(dir, "entry.ts");
+  writeFileSync(
+    entry,
+    `import { main } from ${JSON.stringify(join(import.meta.dir, "shipping-cli.ts"))}; process.exitCode = await main(process.argv.slice(2));`
+  );
+  const run = (...args: string[]) => {
+    const result = spawnSync(process.execPath, [entry, ...args], {
+      encoding: "utf8",
+      timeout: 3000,
+      env: {
+        PATH: `${dir}:${process.env.PATH}`,
+        SHIPPING_STATE: file,
+      },
+    });
+    return {
+      status: result.status,
+      output: object(JSON.parse(result.stdout), "CLI result"),
+    };
+  };
+  try {
+    body(run, file, dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+it("the CLI inspects, saves, cancels both mechanisms, and reads back in fresh processes", () =>
+  fixture((run, file, dir) => {
+    const inspected = run("inspect", "--repo", "owner/repo", "--pr", "1");
+    expect(inspected.status).toBe(0);
+    expect(object(inspected.output.record, "record").revision).toEqual({
+      context: { owner: "owner", repo: "repo", number: 1 },
+      headRefOid: "head",
+      baseRefName: "main",
+      baseRefOid: "base",
+    });
+    const saved = join(dir, "record.json");
+    writeFileSync(saved, JSON.stringify(inspected.output));
+    const cancelled = run("cancel-pending", "--record", saved);
+    expect(cancelled.status).toBe(0);
+    expect(cancelled.output).toMatchObject({
+      kind: "cancelled",
+      record: { pending: { autoMerge: false, queueEntryId: null } },
+    });
+    expect(JSON.parse(readFileSync(file, "utf8"))).toMatchObject({
+      autoMergeRequest: null,
+      mergeQueueEntry: null,
+    });
+  }));
+
+it("the CLI refuses a changed base without cancelling anything", () =>
+  fixture((run, file, dir) => {
+    const inspected = run("inspect", "--repo", "owner/repo", "--pr", "1");
+    const saved = join(dir, "record.json");
+    writeFileSync(saved, JSON.stringify(inspected.output));
+    const changed = {
+      ...JSON.parse(readFileSync(file, "utf8")),
+      baseRef: { target: { oid: "advanced" } },
+    };
+    writeFileSync(file, JSON.stringify(changed));
+    const result = run("cancel-pending", "--record", saved);
+    expect(result.status).toBe(1);
+    expect(result.output.kind).toBe("changed");
+    expect(JSON.parse(readFileSync(file, "utf8"))).toEqual(changed);
+  }));
+
+it("the CLI treats a missing queue field as unavailable", () =>
+  fixture((run, file) => {
+    const raw = JSON.parse(readFileSync(file, "utf8"));
+    delete raw.mergeQueueEntry;
+    writeFileSync(file, JSON.stringify(raw));
+    const result = run("inspect", "--repo", "owner/repo", "--pr", "1");
+    expect(result.status).toBe(1);
+    expect(result.output.kind).toBe("unavailable");
+  }));
+
+for (const state of ["CLOSED", "MERGED"]) {
+  it(`the CLI inspects a ${state} PR with a deleted base and refuses cancellation`, () =>
+    fixture((run, file, dir) => {
+      const inspected = run("inspect", "--repo", "owner/repo", "--pr", "1");
+      expect(inspected.status).toBe(0);
+      const saved = join(dir, "record.json");
+      writeFileSync(saved, JSON.stringify(inspected.output));
+      const terminal = {
+        ...JSON.parse(readFileSync(file, "utf8")),
+        state,
+        baseRef: null,
+        autoMergeRequest: null,
+        mergeQueueEntry: null,
+        mergeCommit: state === "MERGED" ? { oid: "merged" } : null,
+      };
+      writeFileSync(file, JSON.stringify(terminal));
+      const record = {
+        state,
+        revision: { baseRefOid: "stored-base" },
+        mergeCommitOid: state === "MERGED" ? "merged" : null,
+      };
+
+      const observed = run("inspect", "--repo", "owner/repo", "--pr", "1");
+      expect(observed.status).toBe(0);
+      expect(observed.output).toMatchObject({ kind: "inspected", record });
+      const cancelled = run("cancel-pending", "--record", saved);
+      expect(cancelled.status).toBe(1);
+      expect(cancelled.output).toMatchObject({ kind: "not-open", record });
+      expect(JSON.parse(readFileSync(file, "utf8"))).toEqual(terminal);
+    }));
+}

package/plugins/pstack/skills/poteto-mode/scripts/watch-pr/shipping-cli.ts

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import { Command, CommanderError } from "commander";
+import { WatchDeadline } from "./deadline.ts";
+import { runJson } from "./github.ts";
+import { object, parseContext } from "./landing.ts";
+import {
+  GhShippingService,
+  cancelPending,
+  inspectLanding,
+  parseLandingRecord,
+  type ShippingResult,
+} from "./shipping.ts";
+
+export async function main(argv: readonly string[]): Promise<number> {
+  let result: ShippingResult | undefined;
+  const deadline = new WatchDeadline(60, () => performance.now() / 1000);
+  const service = new GhShippingService((args) => runJson(args, deadline));
+  const cli = new Command("ship-pr").exitOverride();
+  cli.description(
+    "Inspect a landing record or cancel its pending merge mechanisms. Never merges or rewrites branches."
+  );
+  cli
+    .command("inspect")
+    .requiredOption("--repo <owner/repo>")
+    .requiredOption("--pr <number>")
+    .action(async (options: { repo: string; pr: string }) => {
+      const parts = options.repo.split("/");
+      if (parts.length !== 2) throw new Error("--repo must be owner/repo");
+      const context = parseContext({
+        owner: parts[0],
+        repo: parts[1],
+        number: Number(options.pr),
+      });
+      result = await inspectLanding(service, context);
+    });
+  cli
+    .command("cancel-pending")
+    .requiredOption(
+      "--record <file>",
+      "JSON output from inspect or a successful cancellation"
+    )
+    .action(async (options: { record: string }) => {
+      const input = object(
+        JSON.parse(await readFile(options.record, "utf8")),
+        "saved inspection"
+      );
+      if (input.kind !== "inspected" && input.kind !== "cancelled")
+        throw new Error(
+          "record must contain a successful inspection or cancellation"
+        );
+      result = await cancelPending(service, parseLandingRecord(input.record));
+    });
+  try {
+    await cli.parseAsync(argv, { from: "user" });
+    if (!result) return 64;
+  } catch (error) {
+    if (error instanceof CommanderError) return error.exitCode === 0 ? 0 : 64;
+    result = {
+      kind: "unavailable",
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  return result.kind === "inspected" || result.kind === "cancelled" ? 0 : 1;
+}

package/plugins/pstack/skills/poteto-mode/scripts/watch-pr/shipping.test-helper.ts

@@ -0,0 +1,48 @@
+// The slice of GitHub's GraphQL schema the shipping service depends on: the
+// one required input field of each mutation, and the pull request field the
+// mutation clears. Regenerate the input names with
+//   gh api graphql -f query='{ __type(name:"DequeuePullRequestInput") { inputFields { name } } }'
+const MUTATIONS: Record<string, { input: string; clears: string }> = {
+  disablePullRequestAutoMerge: {
+    input: "pullRequestId",
+    clears: "autoMergeRequest",
+  },
+  dequeuePullRequest: { input: "id", clears: "mergeQueueEntry" },
+};
+
+const MUTATION =
+  /mutation\s*\w*\s*\(\s*\$id\s*:\s*ID!\s*\)\s*\{\s*(\w+)\(\s*input\s*:\s*\{\s*(\w+)\s*:\s*\$id\s*\}\s*\)/;
+
+/**
+ * Answer one `gh api graphql` call the way GitHub would.
+ *
+ * A query returns only the pull request fields it selects. A mutation is
+ * refused unless it declares `$id` as `ID!`, names a known mutation and its
+ * required input field, and carries this pull request's node id.
+ */
+export function fakeGitHub(
+  pullRequest: Record<string, unknown>,
+  argv: readonly string[]
+): { data: Record<string, unknown> } {
+  const query = argv.find((arg) => arg.startsWith("query=")) ?? "";
+  if (!query.includes("mutation")) {
+    // Drop nested selections, so `mergeQueueEntry { id }` does not count as
+    // selecting the pull request's own `id`.
+    const selection = query.replace(/\{[^{}]*\}/g, "");
+    const selected = Object.entries(pullRequest).filter(([field]) =>
+      new RegExp(`\\b${field}\\b`).test(selection)
+    );
+    return {
+      data: { repository: { pullRequest: Object.fromEntries(selected) } },
+    };
+  }
+  const [, name = "", input = ""] = MUTATION.exec(query) ?? [];
+  const contract = MUTATIONS[name];
+  if (!contract) throw new Error(`not a mutation GitHub accepts: ${query}`);
+  if (input !== contract.input)
+    throw new Error(`${name} input requires ${contract.input}, got ${input}`);
+  if (!argv.includes(`id=${pullRequest.id}`))
+    throw new Error("Could not resolve to a node with the given id");
+  pullRequest[contract.clears] = null;
+  return { data: { [name]: { clientMutationId: null } } };
+}