@zenspc/pi-pstack 0.1.0

package/skills/poteto-mode/scripts/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@zenspc/pi-pstack-tools",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "bun test orch watch-pr",
+    "typecheck": "tsc --project watch-pr/tsconfig.json --noEmit --strict"
+  },
+  "dependencies": {
+    "commander": "14.0.0"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "latest"
+  }
+}

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

@@ -0,0 +1,224 @@
+import { describe, expect, it } from "bun:test";
+import { type CliRuntime, main, parseArgs } from "./cli.ts";
+import { fakeReader, passingCheck } from "./fakes.test-helper.ts";
+import { renderJson, renderPretty } from "./render.ts";
+import type { GitHubReader, WatcherVerdict } from "./types.ts";
+import { parsePrNumber } from "./types.ts";
+
+const silentIo = { stdout: () => {}, stderr: () => {} };
+
+function testRuntime(reader: GitHubReader): {
+  readonly runtime: CliRuntime;
+  readonly stdout: string[];
+  readonly stderr: string[];
+} {
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  return {
+    stdout,
+    stderr,
+    runtime: {
+      reader,
+      clock: {
+        now: () => 0,
+        observedAt: () => "2026-07-26T00:00:00.000Z",
+        async sleep() {
+          throw new Error("test unexpectedly slept");
+        },
+      },
+      stdout: (value) => stdout.push(value),
+      stderr: (value) => stderr.push(value),
+    },
+  };
+}
+
+describe("parseArgs", () => {
+  it("uses the specified defaults", () => {
+    expect(parseArgs([], silentIo)).toMatchObject({
+      owner: null,
+      repo: null,
+      pr: null,
+      mode: "single",
+      stackPrs: [],
+      statusOnly: false,
+      pretty: false,
+      polling: {
+        interval: 60,
+        sweepInterval: 300,
+        timeout: 0,
+        maxQueryErrors: 5,
+        allowDraft: false,
+      },
+    });
+  });
+
+  it("parses a frozen queued stack bottom-to-top", () => {
+    const parsed = parseArgs(
+      [
+        "--queued-stack",
+        "--stack-prs",
+        "#10, 11,#12",
+        "--interval",
+        "2.5",
+        "--sweep-interval",
+        "30",
+        "--timeout",
+        "0",
+        "--max-query-errors",
+        "3",
+        "--allow-draft",
+        "--pretty",
+      ],
+      silentIo
+    );
+    expect(parsed.mode).toBe("queued-stack");
+    expect(parsed.stackPrs.map(Number)).toEqual([10, 11, 12]);
+    expect(parsed.polling).toEqual({
+      interval: 2.5,
+      sweepInterval: 30,
+      timeout: 0,
+      maxQueryErrors: 3,
+      allowDraft: true,
+    });
+    expect(parsed.pretty).toBe(true);
+  });
+
+  it("rejects every invalid mode and numeric shape as usage", async () => {
+    const invalid = [
+      ["--unknown"],
+      ["--interval", "0"],
+      ["--sweep-interval", "-1"],
+      ["--timeout", "-1"],
+      ["--max-query-errors", "1.5"],
+      ["--stack", "--queued-stack"],
+      ["--stack-prs", "1,2"],
+      ["--queued-stack", "--stack-prs", "1,1"],
+    ];
+    for (const argv of invalid) {
+      const harness = testRuntime(fakeReader());
+      expect(await main(argv, harness.runtime)).toBe(64);
+      expect(harness.stdout).toEqual([]);
+      expect(harness.stderr.join("")).toContain("error:");
+    }
+  });
+});
+
+describe("rendering", () => {
+  const context = {
+    owner: "owner",
+    repo: "repo",
+    number: parsePrNumber(1),
+  };
+  const status = {
+    schemaVersion: 1,
+    sequence: 1,
+    observedAt: "2026-07-26T00:00:00.000Z",
+    mode: "single",
+    kind: "STATUS",
+    terminal: true,
+    exitCode: 0,
+    reason: "status-only",
+    rows: [
+      {
+        kind: "merged",
+        context,
+        facts: {
+          context,
+          mergeable: "MERGEABLE",
+          mergeStateStatus: "CLEAN",
+          reviewDecision: "APPROVED",
+          headRefOid: "head",
+          headRefName: "feature",
+          baseRefName: "main",
+          state: "MERGED",
+          mergedAt: "now",
+          isDraft: false,
+        },
+      },
+    ],
+  } satisfies WatcherVerdict;
+
+  it("emits compact valid JSON by default", () => {
+    const rendered = renderJson(status);
+    expect(rendered.endsWith("\n")).toBe(true);
+    expect(JSON.parse(rendered)).toEqual(status);
+  });
+
+  it("renders the Markdown table from the same verdict only", () => {
+    const rendered = renderPretty(status);
+    expect(rendered).toContain("| PR | CI | Review | Merge |");
+    expect(rendered).toContain(
+      "| [#1](https://github.com/owner/repo/pull/1) | \u2014 | \u2014 | ✅ merged |"
+    );
+  });
+});
+
+describe("main", () => {
+  it("returns EX_USAGE 64 and writes usage errors only to stderr", async () => {
+    const harness = testRuntime(fakeReader());
+    expect(await main(["--interval", "0"], harness.runtime)).toBe(64);
+    expect(harness.stdout).toEqual([]);
+    expect(harness.stderr.join("")).toContain(
+      "option '--interval <seconds>' argument '0' is invalid"
+    );
+  });
+
+  it("bypasses the queue machine for queued-stack status-only", async () => {
+    const reader = fakeReader();
+    const harness = testRuntime(reader);
+    const code = await main(
+      [
+        "--owner",
+        "owner",
+        "--repo",
+        "repo",
+        "--queued-stack",
+        "--stack-prs",
+        "1",
+        "--status-only",
+      ],
+      harness.runtime
+    );
+    expect(code).toBe(0);
+    expect(harness.stdout).toHaveLength(1);
+    const verdict: unknown = JSON.parse(harness.stdout[0]);
+    expect(verdict).toMatchObject({
+      kind: "STATUS",
+      terminal: true,
+      exitCode: 0,
+      mode: "queued-stack",
+    });
+    expect(harness.stdout[0]).not.toContain('"kind":"QUEUE"');
+  });
+
+  it("returns exit 4 for a hidden GitHub-side CI refusal", async () => {
+    const reader = fakeReader({
+      facts: { mergeStateStatus: "BLOCKED" },
+      fastPath: { kind: "checks", checks: [passingCheck()] },
+      commitRollups: [{ oid: "head", state: "FAILURE" }],
+    });
+    const harness = testRuntime(reader);
+    const code = await main(
+      ["--owner", "owner", "--repo", "repo", "--pr", "1"],
+      harness.runtime
+    );
+    expect(code).toBe(4);
+    expect(harness.stdout).toHaveLength(1);
+    expect(JSON.parse(harness.stdout[0])).toMatchObject({
+      kind: "BLOCKER",
+      exitCode: 4,
+      blocker: {
+        kind: "failing-checks",
+        ci: { kind: "ci-github-rejected" },
+      },
+    });
+  });
+
+  it("shows help without touching the reader", async () => {
+    const reader = fakeReader();
+    const harness = testRuntime(reader);
+    expect(await main(["--help"], harness.runtime)).toBe(0);
+    expect(harness.stdout.join("")).toContain("JSON (NDJSON while polling)");
+    expect(reader.calls).toEqual([]);
+  });
+});

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

@@ -0,0 +1,223 @@
+import { setTimeout as delay } from "node:timers/promises";
+import {
+  Command,
+  CommanderError,
+  InvalidArgumentError,
+  Option,
+} from "commander";
+import {
+  GhGitHubReader,
+  WatcherQueryError,
+  discoverStack,
+  resolveContext,
+} from "./github.ts";
+import {
+  runQueued,
+  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;
+}
+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", positiveNumber, 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 0", 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 reader: T.GitHubReader;
+  readonly clock: WatchClock;
+  readonly stdout: (value: string) => void;
+  readonly stderr: (value: string) => void;
+}
+function realRuntime(): CliRuntime {
+  return {
+    reader: new GhGitHubReader(),
+    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[],
+  runtime: CliRuntime = realRuntime()
+): Promise<number> {
+  let options: CliOptions;
+  try {
+    options = parseArgs(argv, runtime);
+  } catch (error) {
+    if (!(error instanceof CommanderError)) throw error;
+    return error.exitCode === 0 ? 0 : 64;
+  }
+  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)) throw error;
+    const verdict = 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 };
+  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/skills/poteto-mode/scripts/watch-pr/fakes.test-helper.ts

@@ -0,0 +1,118 @@
+import type {
+  Check,
+  ChecksFastPath,
+  CommitRollup,
+  GitHubReader,
+  OpenPullRequest,
+  PrContext,
+  PullRequestFacts,
+  Repository,
+  ReviewThread,
+  RollupPage,
+} from "./types.ts";
+import { parsePrNumber } from "./types.ts";
+
+export interface FakeReaderOptions {
+  readonly facts?: Partial<Omit<PullRequestFacts, "context">>;
+  readonly fastPath?: ChecksFastPath;
+  readonly rollupPages?: readonly RollupPage[];
+  readonly threads?: readonly ReviewThread[];
+  readonly commitRollups?: readonly CommitRollup[];
+  readonly openPullRequests?: readonly OpenPullRequest[];
+  readonly origin?: Repository | null;
+  readonly current?: PrContext;
+}
+
+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",
+    headRefName: "feature",
+    baseRefName: "main",
+    state: "OPEN",
+    mergedAt: null,
+    isDraft: false,
+  };
+  let page = 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");
+      return { ...defaults, ...options.facts, context: requested };
+    },
+    async openPullRequests() {
+      calls.push("openPullRequests");
+      return options.openPullRequests ?? [];
+    },
+    async checksFastPath() {
+      calls.push("checksFastPath");
+      return options.fastPath ?? { kind: "checks", checks: [passingCheck()] };
+    },
+    async checkRollupPage(_requested, after) {
+      calls.push(`checkRollupPage:${after ?? "null"}`);
+      return options.rollupPages?.[page++] ?? { checks: [], endCursor: null };
+    },
+    async reviewThreads() {
+      calls.push("reviewThreads");
+      return options.threads ?? [];
+    },
+    async commitRollups() {
+      calls.push("commitRollups");
+      return options.commitRollups ?? [{ oid: "head", state: "SUCCESS" }];
+    },
+  };
+}