pstack-claude-mirror 0.0.0-stage → 0.9.133

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

@@ -0,0 +1,266 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { DeadlineExceeded, WatchDeadline } from "./deadline.ts";
+import {
+  Command,
+  CommanderError,
+  InvalidArgumentError,
+  Option,
+} from "commander";
+import {
+  GhGitHubReader,
+  WatcherQueryError,
+  discoverStack,
+  resolveContext,
+} from "./github.ts";
+import {
+  NO_CHECKS_CONFIRM_SECONDS,
+  runQueued,
+  deadlineVerdict,
+  runSimple,
+  statusQueryVerdict,
+  verdictFactory,
+  type WatchClock,
+} from "./policy.ts";
+import { renderJson, renderPretty } from "./render.ts";
+import type * as T from "./types.ts";
+import { nonEmpty, parsePrNumber } from "./types.ts";
+export interface CliOptions {
+  readonly owner: string | null;
+  readonly repo: string | null;
+  readonly pr: T.PrNumber | null;
+  readonly mode: T.WatchMode;
+  readonly stackPrs: readonly T.PrNumber[];
+  readonly statusOnly: boolean;
+  readonly pretty: boolean;
+  readonly polling: T.PollingOptions;
+}
+function positiveNumber(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0)
+    throw new InvalidArgumentError("must be greater than zero");
+  return parsed;
+}
+// A timer delay above 2^31 - 1 ms is replaced with 1 ms, so a longer sleep
+// would return at once and the loop would poll without pause.
+const MAX_SLEEP_SECONDS = (2 ** 31 - 1) / 1_000;
+function sleepSeconds(value: string): number {
+  const parsed = positiveNumber(value);
+  if (parsed > MAX_SLEEP_SECONDS)
+    throw new InvalidArgumentError(`must be at most ${MAX_SLEEP_SECONDS}`);
+  return parsed;
+}
+function nonNegativeNumber(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0)
+    throw new InvalidArgumentError("must be zero or greater");
+  return parsed;
+}
+function positiveInteger(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0)
+    throw new InvalidArgumentError("must be a positive integer");
+  return parsed;
+}
+function prNumber(value: string): T.PrNumber {
+  try {
+    return parsePrNumber(Number(value.replace(/^#/, "")));
+  } catch {
+    throw new InvalidArgumentError("must be a positive integer");
+  }
+}
+function stackPrList(value: string): T.NonEmpty<T.PrNumber> {
+  const numbers = value.split(",").map((part) => prNumber(part.trim()));
+  if (new Set(numbers).size !== numbers.length)
+    throw new InvalidArgumentError("contains a duplicate PR");
+  const parsed = nonEmpty(numbers);
+  if (parsed === null) throw new InvalidArgumentError("cannot be empty");
+  return parsed;
+}
+interface RawOptions {
+  readonly owner?: string;
+  readonly repo?: string;
+  readonly pr?: T.PrNumber;
+  readonly stack: boolean;
+  readonly queuedStack: boolean;
+  readonly stackPrs?: T.NonEmpty<T.PrNumber>;
+  readonly interval: number;
+  readonly sweepInterval: number;
+  readonly timeout: number;
+  readonly maxQueryErrors: number;
+  readonly statusOnly: boolean;
+  readonly allowDraft: boolean;
+  readonly pretty: boolean;
+}
+export function parseArgs(
+  argv: readonly string[],
+  io: Pick<CliRuntime, "stdout" | "stderr">
+): CliOptions {
+  const program = new Command("watch-pr")
+    .description(
+      "Watch one pull request, a connected stack, or an immutable queued stack.\nJSON (NDJSON while polling) is the default; --pretty renders human text."
+    )
+    .configureOutput({ writeOut: io.stdout, writeErr: io.stderr })
+    .exitOverride()
+    .option("--owner <owner>", "GitHub repository owner")
+    .option("--repo <repo>", "GitHub repository name")
+    .option("--pr <number>", "pull request number", prNumber)
+    .addOption(
+      new Option("--stack", "watch the connected open stack")
+        .default(false)
+        .conflicts("queuedStack")
+    )
+    .option(
+      "--queued-stack",
+      "watch the captured stack until all PRs merge",
+      false
+    )
+    .option(
+      "--stack-prs <n,...>",
+      "frozen bottom-to-top queue (queued mode only)",
+      stackPrList
+    )
+    .option(
+      "--interval <seconds>",
+      `poll interval; a PR with no checks takes ${NO_CHECKS_CONFIRM_SECONDS} seconds to confirm whatever this is`,
+      sleepSeconds,
+      60
+    )
+    .option(
+      "--sweep-interval <seconds>",
+      "whole-stack sweep interval",
+      positiveNumber,
+      300
+    )
+    .option(
+      "--timeout <seconds>",
+      "deadline; 0 disables it",
+      nonNegativeNumber,
+      0
+    )
+    .option(
+      "--max-query-errors <count>",
+      "consecutive query-error budget",
+      positiveInteger,
+      5
+    )
+    .option(
+      "--status-only",
+      "print one status table and exit; exit 0 means the table was read, not that the PR is ready",
+      false
+    )
+    .option("--allow-draft", "do not treat a draft as a merge gate", false)
+    .option("--pretty", "render human text instead of JSON", false);
+  program.parse(argv, { from: "user" });
+  const raw = program.opts<RawOptions>();
+  if (raw.stackPrs !== undefined && !raw.queuedStack)
+    program.error("error: --stack-prs requires --queued-stack");
+  return {
+    owner: raw.owner ?? null,
+    repo: raw.repo ?? null,
+    pr: raw.pr ?? null,
+    mode: raw.queuedStack ? "queued-stack" : raw.stack ? "stack" : "single",
+    stackPrs: raw.stackPrs ?? [],
+    statusOnly: raw.statusOnly,
+    pretty: raw.pretty,
+    polling: {
+      interval: raw.interval,
+      sweepInterval: raw.sweepInterval,
+      timeout: raw.timeout,
+      maxQueryErrors: raw.maxQueryErrors,
+      allowDraft: raw.allowDraft,
+    },
+  };
+}
+export interface CliRuntime {
+  readonly deadline: WatchDeadline;
+  readonly reader: T.GitHubReader;
+  readonly clock: WatchClock;
+  readonly stdout: (value: string) => void;
+  readonly stderr: (value: string) => void;
+}
+function realRuntime(timeout: number): CliRuntime {
+  const deadline = new WatchDeadline(timeout, () => performance.now() / 1_000);
+  return {
+    deadline,
+    reader: new GhGitHubReader(deadline),
+    clock: {
+      now: () => performance.now() / 1_000,
+      observedAt: () => new Date().toISOString(),
+      sleep: async (seconds) => {
+        await delay(seconds * 1_000);
+      },
+    },
+    stdout: (value) => process.stdout.write(value),
+    stderr: (value) => process.stderr.write(value),
+  };
+}
+export async function main(
+  argv: readonly string[],
+  supplied?: CliRuntime
+): Promise<number> {
+  let options: CliOptions;
+  try {
+    options = parseArgs(
+      argv,
+      supplied ?? {
+        stdout: (value) => process.stdout.write(value),
+        stderr: (value) => process.stderr.write(value),
+      }
+    );
+  } catch (error) {
+    if (!(error instanceof CommanderError)) throw error;
+    return error.exitCode === 0 ? 0 : 64;
+  }
+  const runtime = supplied ?? realRuntime(options.polling.timeout);
+  const render = options.pretty ? renderPretty : renderJson;
+  const emit = (verdict: T.ProgressVerdict): void =>
+    runtime.stdout(render(verdict));
+  let contexts: T.NonEmpty<T.PrContext>;
+  try {
+    const seed = await resolveContext({
+      reader: runtime.reader,
+      owner: options.owner,
+      repo: options.repo,
+      pr: options.pr ?? options.stackPrs[0] ?? null,
+    });
+    contexts =
+      nonEmpty(options.stackPrs.map((number) => ({ ...seed, number }))) ??
+      (options.mode === "single"
+        ? [seed]
+        : await discoverStack(runtime.reader, seed));
+  } catch (error) {
+    if (
+      !(error instanceof WatcherQueryError) &&
+      !(error instanceof DeadlineExceeded)
+    )
+      throw error;
+    const verdict =
+      error instanceof DeadlineExceeded
+        ? deadlineVerdict(verdictFactory(runtime.clock, options.mode))
+        : statusQueryVerdict(
+            verdictFactory(runtime.clock, options.mode),
+            1,
+            error.failure
+          );
+    runtime.stdout(render(verdict));
+    return verdict.exitCode;
+  }
+  const dependencies = {
+    reader: runtime.reader,
+    clock: runtime.clock,
+    emit,
+    deadline: runtime.deadline,
+  };
+  const verdict =
+    options.mode === "queued-stack" && !options.statusOnly
+      ? await runQueued({ dependencies, contexts, options: options.polling })
+      : await runSimple({
+          dependencies,
+          contexts,
+          mode: options.mode,
+          statusOnly: options.statusOnly,
+          options: options.polling,
+        });
+  runtime.stdout(render(verdict));
+  return verdict.exitCode;
+}

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

@@ -0,0 +1,20 @@
+export class DeadlineExceeded extends Error {
+  constructor() {
+    super("watch deadline reached");
+    this.name = "DeadlineExceeded";
+  }
+}
+
+/** One monotonic budget shared by discovery, commands, polling and retries. */
+export class WatchDeadline {
+  private readonly expiresAt: number;
+  constructor(
+    timeout: number,
+    private readonly now: () => number
+  ) {
+    this.expiresAt = timeout > 0 ? now() + timeout : Infinity;
+  }
+  remaining(): number {
+    return Math.max(0, this.expiresAt - this.now());
+  }
+}

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

@@ -0,0 +1,157 @@
+import type {
+  Check,
+  ChecksFastPath,
+  CommitRollup,
+  GitHubReader,
+  OpenPullRequest,
+  PrContext,
+  PullRequestFacts,
+  Repository,
+  RawReviewThread,
+  ReviewThread,
+  ReviewThreadPage,
+  RollupPage,
+} from "./types.ts";
+import { parsePullRequest } from "./github.ts";
+import { parsePrNumber } from "./types.ts";
+
+export interface FakeReaderOptions {
+  readonly facts?: Partial<Omit<PullRequestFacts, "context">>;
+  readonly factsOnReread?: Partial<Omit<PullRequestFacts, "context">>;
+  readonly fastPath?: ChecksFastPath;
+  readonly rollupPages?: readonly RollupPage[];
+  readonly threads?: readonly ReviewThread[];
+  readonly threadPages?: readonly ReviewThreadPage[];
+  readonly commitRollups?: readonly CommitRollup[];
+  readonly openPullRequests?: readonly OpenPullRequest[];
+  readonly defaultBranch?: string;
+  readonly origin?: Repository | null;
+  readonly current?: PrContext;
+}
+
+function toRawThread(thread: ReviewThread): RawReviewThread {
+  return { id: thread.id, firstComment: thread.firstComment, resolved: false };
+}
+
+export function passingCheck(name = "ci"): Check {
+  return {
+    kind: "passed",
+    name,
+    reportedState: "SUCCESS",
+    description: "",
+    link: "",
+    workflow: "",
+  };
+}
+
+export function pendingCheck(name = "ci"): Check {
+  return {
+    kind: "pending",
+    name,
+    reportedState: "PENDING",
+    description: "",
+    link: "",
+    workflow: "",
+  };
+}
+
+export function failedCheck(name = "ci"): Check {
+  return {
+    kind: "failed",
+    name,
+    reportedState: "FAILURE",
+    description: "",
+    link: "",
+    workflow: "",
+  };
+}
+
+export function fakeReader(
+  options: FakeReaderOptions = {}
+): GitHubReader & { readonly calls: readonly string[] } {
+  const calls: string[] = [];
+  const context = options.current ?? {
+    owner: "owner",
+    repo: "repo",
+    number: parsePrNumber(1),
+  };
+  const defaults: PullRequestFacts = {
+    context,
+    mergeable: "MERGEABLE",
+    mergeStateStatus: "CLEAN",
+    reviewDecision: "APPROVED",
+    headRefOid: "head",
+    baseRefOid: "base",
+    headRefName: "feature",
+    baseRefName: "main",
+    state: "OPEN",
+    mergedAt: null,
+    isDraft: false,
+  };
+  let page = 0;
+  let reads = 0;
+  let threadPage = 0;
+  return {
+    calls,
+    async originRepo() {
+      calls.push("originRepo");
+      return options.origin === undefined
+        ? { owner: "owner", repo: "repo" }
+        : options.origin;
+    },
+    async currentPr(pr) {
+      calls.push("currentPr");
+      return { ...context, number: pr ?? context.number };
+    },
+    async pullRequest(requested) {
+      calls.push("pullRequest");
+      reads += 1;
+      const facts = {
+        ...defaults,
+        ...options.facts,
+        ...(reads > 1 ? options.factsOnReread : {}),
+      };
+      return parsePullRequest(
+        {
+          ...facts,
+          baseRef: { target: { oid: facts.baseRefOid } },
+        },
+        requested
+      );
+    },
+    async openPullRequests() {
+      calls.push("openPullRequests");
+      return options.openPullRequests ?? [];
+    },
+    async defaultBranch() {
+      calls.push("defaultBranch");
+      return options.defaultBranch ?? "main";
+    },
+    async checksFastPath() {
+      calls.push("checksFastPath");
+      return options.fastPath ?? { kind: "checks", checks: [passingCheck()] };
+    },
+    async checkRollupPage(_requested, after) {
+      calls.push(`checkRollupPage:${after ?? "null"}`);
+      const pages = options.rollupPages ?? [];
+      return (
+        pages[Math.min(page++, pages.length - 1)] ?? {
+          kind: "contexts",
+          checks: [],
+          endCursor: null,
+        }
+      );
+    },
+    async reviewThreadPage(_requested, after) {
+      calls.push(`reviewThreadPage:${after ?? "null"}`);
+      return options.threadPages?.[threadPage++] ?? {
+        threads: (options.threads ?? []).map(toRawThread),
+        endCursor: null,
+      };
+    },
+    async commitRollups() {
+      calls.push("commitRollups");
+      return options.commitRollups ?? [{ oid: "head", state: "SUCCESS" }];
+    },
+  };
+}

package/plugins/pstack/skills/poteto-mode/scripts/watch-pr/fresh-install.test.ts

@@ -0,0 +1,35 @@
+import { expect, it } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { cpSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+
+// A plugin update ships the scripts without node_modules, so the first run of
+// each entry point installs commander. --no-install turns off Bun's
+// auto-install, which otherwise fetches commander from the registry and hides
+// a process that cannot see the node_modules it just installed.
+const scriptsDirectory = join(import.meta.dir, "..");
+
+for (const [name, entry] of [
+  ["watch-pr", "watch-pr/watch-pr"],
+  ["ship-pr", "watch-pr/ship-pr"],
+]) {
+  it(`${name} --help runs on the first run after an install`, () => {
+    const copy = mkdtempSync(join(tmpdir(), "poteto-mode-scripts-"));
+    try {
+      cpSync(scriptsDirectory, copy, {
+        recursive: true,
+        filter: (source) => basename(source) !== "node_modules",
+      });
+      const result = spawnSync(
+        process.execPath,
+        ["--no-install", join(copy, entry), "--help"],
+        { cwd: tmpdir(), encoding: "utf8", timeout: 60_000 }
+      );
+      expect(result.status, result.stderr).toBe(0);
+      expect(result.stdout).toContain(`Usage: ${name}`);
+    } finally {
+      rmSync(copy, { recursive: true, force: true });
+    }
+  }, 90_000);
+}