dsh-pstack 0.1.0 → 0.2.0-beta.3

package/dist/pstack/skills/poteto-mode/scripts/support.mjs

@@ -0,0 +1,93 @@
+import { expect } from "./expect.mjs";
+import { spawn as spawn$1, spawnSync as spawnSync$1 } from "node:child_process";
+// runtime/skills/poteto-mode/scripts/support.ts
+/**
+* The one support module the ported upstream tests import.
+*
+* The five upstream test files were written for `bun:test` and use exactly two
+* Bun facilities: its `expect`, and `Bun.spawnSync` / `Bun.spawn` for running git
+* and short-lived processes. Rather than rewrite every call site, this module
+* supplies those two shapes and the test patch only replaces the import line. The
+* bodies below stay byte-for-byte the upstream text, so a future upstream change
+* is still readable against this tree.
+*
+* `Bun.spawnSync` returns `{ exitCode, stdout, stderr, success }` with Buffer
+* output and never throws on a nonzero exit; `node:child_process.spawnSync`
+* returns `{ status, stdout, stderr }`. The adapter is the mapping between them,
+* not a second implementation.
+*
+* `Bun.spawn` returns `{ pid, exited: Promise<number> }`. The adapter runs the
+* child to completion and resolves `exited` with the exit status, which is what
+* the one call site awaits.
+*/
+/**
+* Run a command to completion, Bun-shaped.
+*
+* A signal-terminated child reports `exitCode: 1` rather than `null`, so a test
+* that formats the code never prints `undefined` for a killed process.
+*/
+function spawnSync(argv, options = {}) {
+	const [command, ...args] = argv;
+	if (command === void 0) throw new TypeError("spawnSync needs a command");
+	const result = spawnSync$1(command, args, {
+		cwd: options.cwd,
+		env: options.env,
+		stdio: [
+			options.stdin === "inherit" ? "inherit" : "pipe",
+			options.stdout === "inherit" ? "inherit" : "pipe",
+			options.stderr === "inherit" ? "inherit" : "pipe"
+		],
+		encoding: "buffer"
+	});
+	const exitCode = result.status ?? 1;
+	return {
+		exitCode,
+		stdout: Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.alloc(0),
+		stderr: Buffer.isBuffer(result.stderr) ? result.stderr : Buffer.alloc(0),
+		success: exitCode === 0
+	};
+}
+/**
+* A child that exits immediately, as a real process.
+*
+* The current interpreter running an empty program is a process like any other: its
+* `pid` is real and its exit status is 0.
+*/
+function immediateExit() {
+	return spawn$1(process.execPath, ["-e", ""], { stdio: "ignore" });
+}
+/** Whether `command` starts at all, checked without a shell. */
+function resolves(command) {
+	return spawnSync$1(command, ["--version"], { stdio: "ignore" }).error === void 0;
+}
+/**
+* Start a command and expose Bun's `{ pid, exited }` shape.
+*
+* The one upstream call is `spawn(["true"])`, used to obtain a pid that has already
+* exited so the test can plant a stale lock. It reads `pid` *before* awaiting
+* `exited`, so the pid must be real and already dead when this returns.
+*
+* That rules out "spawn it and fall back on failure": the failure is asynchronous, so
+* the caller would read `-1`. The probe is synchronous instead, which lets this
+* function choose the right child before returning. `true` is used when it exists and
+* the current interpreter otherwise — a `PATH` without the usual Unix utilities is
+* exactly the environment this release has to work in.
+*/
+function spawn(argv) {
+	const [command, ...args] = argv;
+	if (command === void 0) throw new TypeError("spawn needs a command");
+	const child = resolves(command) ? spawn$1(command, args, { stdio: "ignore" }) : immediateExit();
+	return {
+		pid: child.pid ?? -1,
+		exited: new Promise((resolve) => {
+			child.once("close", (code) => resolve(code ?? 1));
+			child.once("error", () => resolve(1));
+		})
+	};
+}
+/** The `Bun` global the upstream tests reference, limited to what they call. */
+const Bun = {
+	spawnSync,
+	spawn
+};
+export { Bun, expect, spawn, spawnSync };

package/dist/pstack/skills/poteto-mode/scripts/watch-pr/cli.mjs

@@ -0,0 +1,123 @@
+import { nonEmpty, parsePrNumber } from "./types.mjs";
+import { GhGitHubReader, WatcherQueryError, discoverStack, resolveContext } from "./github.mjs";
+import { runQueued, runSimple, statusQueryVerdict, verdictFactory } from "./policy.mjs";
+import { renderJson, renderPretty } from "./render.mjs";
+import { setTimeout } from "node:timers/promises";
+import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
+// runtime/skills/poteto-mode/scripts/watch-pr/cli.ts
+function positiveNumber(value) {
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed <= 0) throw new InvalidArgumentError("must be greater than zero");
+	return parsed;
+}
+function nonNegativeNumber(value) {
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed < 0) throw new InvalidArgumentError("must be zero or greater");
+	return parsed;
+}
+function positiveInteger(value) {
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new InvalidArgumentError("must be a positive integer");
+	return parsed;
+}
+function prNumber(value) {
+	try {
+		return parsePrNumber(Number(value.replace(/^#/, "")));
+	} catch {
+		throw new InvalidArgumentError("must be a positive integer");
+	}
+}
+function stackPrList(value) {
+	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;
+}
+function parseArgs(argv, io) {
+	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();
+	if (raw.stackPrs !== void 0 && !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
+		}
+	};
+}
+function realRuntime() {
+	return {
+		reader: new GhGitHubReader(),
+		clock: {
+			now: () => performance.now() / 1e3,
+			observedAt: () => (/* @__PURE__ */ new Date()).toISOString(),
+			sleep: async (seconds) => {
+				await setTimeout(seconds * 1e3);
+			}
+		},
+		stdout: (value) => process.stdout.write(value),
+		stderr: (value) => process.stderr.write(value)
+	};
+}
+async function main(argv, runtime = realRuntime()) {
+	let options;
+	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) => runtime.stdout(render(verdict));
+	let contexts;
+	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;
+}
+export { main, parseArgs };

package/dist/pstack/skills/poteto-mode/scripts/watch-pr/cli.test.mjs

@@ -0,0 +1,217 @@
+import { expect } from "../expect.mjs";
+import "../support.mjs";
+import { parsePrNumber } from "./types.mjs";
+import { renderJson, renderPretty } from "./render.mjs";
+import { main, parseArgs } from "./cli.mjs";
+import { fakeReader, passingCheck } from "./fakes.test-helper.mjs";
+import { describe, it } from "node:test";
+// runtime/skills/poteto-mode/scripts/watch-pr/cli.test.ts
+const silentIo = {
+	stdout: () => {},
+	stderr: () => {}
+};
+function testRuntime(reader) {
+	const stdout = [];
+	const stderr = [];
+	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 () => {
+		for (const argv of [
+			["--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"
+			]
+		]) {
+			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
+			}
+		}]
+	};
+	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) | — | — | ✅ 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 harness = testRuntime(fakeReader());
+		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 = 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 harness = testRuntime(fakeReader({
+			facts: { mergeStateStatus: "BLOCKED" },
+			fastPath: {
+				kind: "checks",
+				checks: [passingCheck()]
+			},
+			commitRollups: [{
+				oid: "head",
+				state: "FAILURE"
+			}]
+		}));
+		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([]);
+	});
+});
+export {};

package/dist/pstack/skills/poteto-mode/scripts/watch-pr/fakes.test-helper.mjs

@@ -0,0 +1,119 @@
+import { parsePrNumber } from "./types.mjs";
+// runtime/skills/poteto-mode/scripts/watch-pr/fakes.test-helper.ts
+function toRawThread(thread) {
+	return {
+		id: thread.id,
+		firstComment: thread.firstComment,
+		resolved: false
+	};
+}
+function passingCheck(name = "ci") {
+	return {
+		kind: "passed",
+		name,
+		reportedState: "SUCCESS",
+		description: "",
+		link: "",
+		workflow: ""
+	};
+}
+function pendingCheck(name = "ci") {
+	return {
+		kind: "pending",
+		name,
+		reportedState: "PENDING",
+		description: "",
+		link: "",
+		workflow: ""
+	};
+}
+function failedCheck(name = "ci") {
+	return {
+		kind: "failed",
+		name,
+		reportedState: "FAILURE",
+		description: "",
+		link: "",
+		workflow: ""
+	};
+}
+function fakeReader(options = {}) {
+	const calls = [];
+	const context = options.current ?? {
+		owner: "owner",
+		repo: "repo",
+		number: parsePrNumber(1)
+	};
+	const defaults = {
+		context,
+		mergeable: "MERGEABLE",
+		mergeStateStatus: "CLEAN",
+		reviewDecision: "APPROVED",
+		headRefOid: "head",
+		headRefName: "feature",
+		baseRefName: "main",
+		state: "OPEN",
+		mergedAt: null,
+		isDraft: false
+	};
+	let page = 0;
+	let threadPage = 0;
+	return {
+		calls,
+		async originRepo() {
+			calls.push("originRepo");
+			return options.origin === void 0 ? {
+				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 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"
+			}];
+		}
+	};
+}
+export { failedCheck, fakeReader, passingCheck, pendingCheck };