dsh-pstack 0.1.0 → 0.2.0-beta.3

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

@@ -0,0 +1,523 @@
+import { expect } from "../expect.mjs";
+import "../support.mjs";
+import { parsePrNumber } from "./types.mjs";
+import { WatcherQueryError } from "./github.mjs";
+import { applyQueueSnapshot, assessGitHubMerge, classifyPr, createQueueState, evaluateQueue, planQueue, queryBackoffSeconds, readSnapshot, runQueued, runSimple, selectTierMajorStackDecision } from "./policy.mjs";
+import { failedCheck, fakeReader, passingCheck, pendingCheck } from "./fakes.test-helper.mjs";
+import { describe, it } from "node:test";
+// runtime/skills/poteto-mode/scripts/watch-pr/policy.test.ts
+const context = (number) => ({
+	owner: "owner",
+	repo: "repo",
+	number: parsePrNumber(number)
+});
+const options = {
+	interval: 10,
+	sweepInterval: 300,
+	timeout: 0,
+	maxQueryErrors: 5,
+	allowDraft: false
+};
+describe("readiness truth table", () => {
+	it("covers every specified row and every UNKNOWN rollup value", () => {
+		for (const [mergeStateStatus, headRollupState, expected] of [
+			[
+				"BLOCKED",
+				"FAILURE",
+				"refused"
+			],
+			[
+				"BLOCKED",
+				"ERROR",
+				"refused"
+			],
+			[
+				"BLOCKED",
+				"PENDING",
+				"allowed"
+			],
+			[
+				"UNSTABLE",
+				"FAILURE",
+				"allowed"
+			],
+			[
+				"UNKNOWN",
+				"ERROR",
+				"allowed"
+			],
+			[
+				"UNKNOWN",
+				"EXPECTED",
+				"allowed"
+			],
+			[
+				"UNKNOWN",
+				"FAILURE",
+				"allowed"
+			],
+			[
+				"UNKNOWN",
+				"PENDING",
+				"allowed"
+			],
+			[
+				"UNKNOWN",
+				"SUCCESS",
+				"allowed"
+			],
+			[
+				"UNKNOWN",
+				null,
+				"allowed"
+			],
+			[
+				"CLEAN",
+				"SUCCESS",
+				"allowed"
+			]
+		]) expect(assessGitHubMerge({
+			mergeStateStatus,
+			headRollupState
+		}).kind).toBe(expected);
+	});
+	it("turns a clean visible list plus GitHub refusal into an explicit CI blocker", async () => {
+		const reader = fakeReader({
+			facts: { mergeStateStatus: "BLOCKED" },
+			fastPath: {
+				kind: "checks",
+				checks: [passingCheck()]
+			},
+			commitRollups: [{
+				oid: "head",
+				state: "FAILURE"
+			}]
+		});
+		const snapshot = await readSnapshot({
+			reader,
+			context: context(1),
+			pendingHistory: "include",
+			allowDraft: false
+		});
+		expect(snapshot.kind).toBe("open");
+		if (snapshot.kind !== "open") throw new Error("expected open snapshot");
+		expect(snapshot.ci.kind).toBe("ci-github-rejected");
+		expect(classifyPr(snapshot)).toMatchObject({
+			kind: "blocker",
+			blocker: { kind: "failing-checks" }
+		});
+	});
+});
+describe("snapshot query planning", () => {
+	it("does not query commit rollups while queued checks are pending", async () => {
+		const reader = fakeReader({ fastPath: {
+			kind: "checks",
+			checks: [pendingCheck()]
+		} });
+		const snapshot = await readSnapshot({
+			reader,
+			context: context(2),
+			pendingHistory: "omit",
+			allowDraft: false
+		});
+		expect(snapshot.kind).toBe("open");
+		if (snapshot.kind !== "open") throw new Error("expected open snapshot");
+		expect(snapshot.ci.kind).toBe("ci-pending");
+		expect(reader.calls).toEqual([
+			"pullRequest",
+			"reviewThreadPage:null",
+			"checksFastPath"
+		]);
+	});
+	it("queries rollups for settled and failed lists", async () => {
+		const settled = fakeReader();
+		await readSnapshot({
+			reader: settled,
+			context: context(3),
+			pendingHistory: "omit",
+			allowDraft: false
+		});
+		expect(settled.calls).toContain("commitRollups");
+		const failed = fakeReader({ fastPath: {
+			kind: "checks",
+			checks: [failedCheck()]
+		} });
+		await readSnapshot({
+			reader: failed,
+			context: context(4),
+			pendingHistory: "omit",
+			allowDraft: false
+		});
+		expect(failed.calls).toContain("commitRollups");
+	});
+	it("short-circuits merged rows before threads and checks", async () => {
+		const reader = fakeReader({ facts: {
+			state: "MERGED",
+			mergedAt: "2026-07-26T00:00:00Z"
+		} });
+		expect((await readSnapshot({
+			reader,
+			context: context(5),
+			pendingHistory: "include",
+			allowDraft: false
+		})).kind).toBe("merged");
+		expect(reader.calls).toEqual(["pullRequest"]);
+	});
+});
+it("scans stacks tier-major so an upstack conflict outranks frontier CI", async () => {
+	const frontier = await readSnapshot({
+		reader: fakeReader({
+			fastPath: {
+				kind: "checks",
+				checks: [failedCheck()]
+			},
+			commitRollups: [{
+				oid: "head",
+				state: "FAILURE"
+			}]
+		}),
+		context: context(10),
+		pendingHistory: "omit",
+		allowDraft: false
+	});
+	const upstack = await readSnapshot({
+		reader: fakeReader({ facts: { mergeable: "CONFLICTING" } }),
+		context: context(11),
+		pendingHistory: "omit",
+		allowDraft: false
+	});
+	const decision = selectTierMajorStackDecision([frontier, upstack]);
+	expect(decision).toMatchObject({
+		kind: "blocker",
+		blocker: {
+			kind: "merge-conflicts",
+			pr: { number: 11 }
+		}
+	});
+});
+it("attributes a stack wait to the PR whose checks are pending, not the bottom", async () => {
+	const readyBottom = await readSnapshot({
+		reader: fakeReader(),
+		context: context(20),
+		pendingHistory: "omit",
+		allowDraft: false
+	});
+	const pendingUpstack = await readSnapshot({
+		reader: fakeReader({ fastPath: {
+			kind: "checks",
+			checks: [pendingCheck("upstack-build")]
+		} }),
+		context: context(21),
+		pendingHistory: "omit",
+		allowDraft: false
+	});
+	const decision = selectTierMajorStackDecision([readyBottom, pendingUpstack]);
+	expect(decision).toMatchObject({
+		kind: "waiting",
+		frontier: { number: 21 },
+		pending: [{ name: "upstack-build" }]
+	});
+});
+it("waits on a draft while checks are pending, then reports the draft gate", async () => {
+	const pending = await readSnapshot({
+		reader: fakeReader({
+			facts: { isDraft: true },
+			fastPath: {
+				kind: "checks",
+				checks: [pendingCheck()]
+			}
+		}),
+		context: context(12),
+		pendingHistory: "omit",
+		allowDraft: false
+	});
+	expect(classifyPr(pending).kind).toBe("waiting");
+	const settled = await readSnapshot({
+		reader: fakeReader({ facts: { isDraft: true } }),
+		context: context(12),
+		pendingHistory: "omit",
+		allowDraft: false
+	});
+	expect(classifyPr(settled)).toMatchObject({
+		kind: "blocker",
+		blocker: {
+			kind: "merge-gate",
+			reason: "draft-pr"
+		}
+	});
+});
+describe("queued-stack cadence", () => {
+	async function openSnapshot(pr) {
+		return readSnapshot({
+			reader: fakeReader(),
+			context: pr,
+			pendingHistory: "omit",
+			allowDraft: false
+		});
+	}
+	it("drops a sweep head only after its snapshot succeeds", async () => {
+		const queue = [
+			context(20),
+			context(21),
+			context(22)
+		];
+		let state = createQueueState(queue, 0);
+		const first = await openSnapshot(queue[0]);
+		state = applyQueueSnapshot(state, first, 0, options).state;
+		expect(state.work).toMatchObject({
+			kind: "whole-stack-sweep",
+			remaining: [{ number: 21 }, { number: 22 }]
+		});
+		const second = await openSnapshot(queue[1]);
+		state = applyQueueSnapshot(state, second, 60, options).state;
+		expect(state.work).toMatchObject({
+			kind: "whole-stack-sweep",
+			remaining: [{ number: 22 }]
+		});
+	});
+	it("resumes the sweep at the PR whose read failed", async () => {
+		const middle = context(21);
+		const base = fakeReader();
+		let failNext = true;
+		const timeline = [];
+		const reader = {
+			...base,
+			async pullRequest(pr) {
+				if (pr.number === middle.number && failNext) {
+					failNext = false;
+					timeline.push(`fail:${pr.number}`);
+					throw new WatcherQueryError({
+						kind: "command-exit",
+						retryable: true,
+						detail: "rate limited",
+						code: 1
+					});
+				}
+				timeline.push(`read:${pr.number}`);
+				return base.pullRequest(pr);
+			}
+		};
+		let now = 0;
+		let sleeps = 0;
+		const running = runQueued({
+			dependencies: {
+				reader,
+				clock: {
+					now: () => now,
+					observedAt: () => "2026-07-26T00:00:00.000Z",
+					async sleep(seconds) {
+						timeline.push("sleep");
+						now += seconds;
+						sleeps += 1;
+						if (sleeps === 2) throw new Error("stop after resume proof");
+					}
+				},
+				emit(verdict) {
+					timeline.push(`emit:${verdict.kind}`);
+				}
+			},
+			contexts: [
+				context(20),
+				middle,
+				context(22)
+			],
+			options
+		});
+		await expect(running).rejects.toThrow("stop after resume proof");
+		expect(timeline).toEqual([
+			"emit:QUEUE",
+			"read:20",
+			"fail:21",
+			"emit:RETRY",
+			"sleep",
+			"read:21",
+			"read:22",
+			"emit:STATUS",
+			"emit:WAITING",
+			"sleep"
+		]);
+	});
+	it("emits a completed sweep only after its final successful snapshot", async () => {
+		const queue = [context(30), context(31)];
+		let state = createQueueState(queue, 0);
+		const first = applyQueueSnapshot(state, await openSnapshot(queue[0]), 0, options);
+		expect(first.completedSweepRows).toBeNull();
+		state = first.state;
+		const second = applyQueueSnapshot(state, await openSnapshot(queue[1]), 5, options);
+		expect(second.completedSweepRows?.map((row) => Number(row.context.number))).toEqual([30, 31]);
+		expect(second.state.nextSweepAt).toBe(305);
+	});
+	it("ADVANCE continues directly to the new frontier without sleeping", async () => {
+		const one = context(40);
+		const two = context(41);
+		const base = fakeReader();
+		const reads = /* @__PURE__ */ new Map();
+		const timeline = [];
+		const reader = {
+			...base,
+			async pullRequest(pr) {
+				timeline.push(`read:${pr.number}`);
+				const facts = await base.pullRequest(pr);
+				const count = (reads.get(pr.number) ?? 0) + 1;
+				reads.set(pr.number, count);
+				return pr.number === one.number && count > 1 ? {
+					...facts,
+					state: "MERGED",
+					mergedAt: "2026-07-26T00:00:00Z"
+				} : facts;
+			}
+		};
+		let now = 0;
+		let sleeps = 0;
+		const emitted = [];
+		const running = runQueued({
+			dependencies: {
+				reader,
+				clock: {
+					now: () => now,
+					observedAt: () => "2026-07-26T00:00:00.000Z",
+					async sleep(seconds) {
+						timeline.push("sleep");
+						now += seconds;
+						sleeps += 1;
+						if (sleeps === 2) throw new Error("stop after advance proof");
+					}
+				},
+				emit(verdict) {
+					emitted.push(verdict);
+					timeline.push(`emit:${verdict.kind}`);
+				}
+			},
+			contexts: [one, two],
+			options
+		});
+		await expect(running).rejects.toThrow("stop after advance proof");
+		expect(emitted.some((event) => event.kind === "ADVANCE")).toBe(true);
+		const firstSleep = timeline.indexOf("sleep");
+		expect(timeline.slice(firstSleep, firstSleep + 5)).toEqual([
+			"sleep",
+			"read:40",
+			"emit:ADVANCE",
+			"read:41",
+			"emit:WAITING"
+		]);
+	});
+	it("deduplicates identical waits and schedules the next due sweep", async () => {
+		const queue = [context(50)];
+		let state = createQueueState(queue, 0);
+		state = applyQueueSnapshot(state, await openSnapshot(queue[0]), 0, options).state;
+		const first = evaluateQueue(state, 0, options);
+		expect(first.kind).toBe("waiting");
+		if (first.kind !== "waiting") throw new Error("expected waiting");
+		expect(first.emit).toBe(true);
+		const second = evaluateQueue(first.state, 10, options);
+		expect(second.kind).toBe("waiting");
+		if (second.kind !== "waiting") throw new Error("expected waiting");
+		expect(second.emit).toBe(false);
+		expect(planQueue(second.state, 300).work?.kind).toBe("whole-stack-sweep");
+	});
+});
+it("uses the specified retry floor and cap", () => {
+	expect(queryBackoffSeconds(1, 1)).toBe(60);
+	expect(queryBackoffSeconds(1, 2)).toBe(120);
+	expect(queryBackoffSeconds(60, 4)).toBe(300);
+});
+describe("polling deadline sleeps", () => {
+	for (const mode of [
+		"single",
+		"queued-stack",
+		"query-retry"
+	]) it(`caps ${mode} sleeps at the configured deadline`, async () => {
+		let now = 0;
+		const sleeps = [];
+		const pending = fakeReader({ fastPath: {
+			kind: "checks",
+			checks: [pendingCheck()]
+		} });
+		const dependencies = {
+			reader: mode === "query-retry" ? {
+				...pending,
+				async pullRequest() {
+					throw new WatcherQueryError({
+						kind: "command-exit",
+						retryable: true,
+						code: 1,
+						detail: "temporary failure"
+					});
+				}
+			} : pending,
+			clock: {
+				now: () => now,
+				observedAt: () => "2026-07-26T00:00:00.000Z",
+				async sleep(seconds) {
+					sleeps.push(seconds);
+					now += seconds;
+				}
+			},
+			emit() {}
+		};
+		const polling = {
+			...options,
+			interval: 60,
+			timeout: 5
+		};
+		const result = mode === "queued-stack" ? await runQueued({
+			dependencies,
+			contexts: [context(1)],
+			options: polling
+		}) : await runSimple({
+			dependencies,
+			contexts: [context(1)],
+			mode: "single",
+			statusOnly: false,
+			options: polling
+		});
+		expect(result.kind).toBe("TIMEOUT");
+		expect(sleeps).toEqual([5]);
+		expect(now).toBe(5);
+	});
+	it("preserves the polling interval when the deadline is disabled", async () => {
+		let now = 0;
+		let reads = 0;
+		const sleeps = [];
+		const pending = fakeReader({ fastPath: {
+			kind: "checks",
+			checks: [pendingCheck()]
+		} });
+		const passed = fakeReader({ fastPath: {
+			kind: "checks",
+			checks: [passingCheck()]
+		} });
+		const result = await runSimple({
+			dependencies: {
+				reader: {
+					...pending,
+					async checksFastPath(pr) {
+						reads += 1;
+						return reads === 1 ? pending.checksFastPath(pr) : passed.checksFastPath(pr);
+					}
+				},
+				clock: {
+					now: () => now,
+					observedAt: () => "2026-07-26T00:00:00.000Z",
+					async sleep(seconds) {
+						sleeps.push(seconds);
+						now += seconds;
+					}
+				},
+				emit() {}
+			},
+			contexts: [context(1)],
+			mode: "single",
+			statusOnly: false,
+			options: {
+				...options,
+				interval: 60,
+				timeout: 0
+			}
+		});
+		expect(result.kind).toBe("READY");
+		expect(sleeps).toEqual([60]);
+	});
+});
+export {};

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

@@ -0,0 +1,106 @@
+// runtime/skills/poteto-mode/scripts/watch-pr/render.ts
+const renderJson = (verdict) => `${JSON.stringify(verdict)}\n`;
+function ciCell(row) {
+	if (row.kind !== "open") return "—";
+	const was = row.ci.hadPreviousPassingCi ? ", was ✅" : "";
+	switch (row.ci.kind) {
+		case "ci-clean": return "✅";
+		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: return row.ci;
+	}
+}
+function reviewCell(row) {
+	if (row.kind !== "open") return "—";
+	const open = row.threads.length;
+	return row.reviewAutomationRunning ? open ? `🤖 running, ${open} open` : "🤖 running" : open ? `📝 ${open} open` : "✅";
+}
+function mergeCell(row) {
+	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" : "✅";
+}
+function renderStatusTable(rows) {
+	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) {
+	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(" ");
+}
+function renderBlocker(blocker) {
+	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" : "resolve the changes-requested review before waiting for the merge queue";
+			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}`,
+			"action=verify current PR context, GitHub authentication, and API availability, then rearm"
+		].join("\n");
+		default: return blocker;
+	}
+}
+function renderPretty(verdict) {
+	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": 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: GitHub status query failed; retrying in ${verdict.retryInSeconds}s\ndetail=${verdict.failure.detail}\n`;
+		case "BLOCKER": return `${renderBlocker(verdict.blocker)}\n`;
+		case "READY": return `READY: no merge conflicts, no unresolved review threads, no failing or pending checks${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 — do not mark ready" : ""}` : ""}\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 === "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: return verdict;
+	}
+}
+export { renderJson, renderPretty, renderStatusTable };

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

@@ -0,0 +1,9 @@
+// runtime/skills/poteto-mode/scripts/watch-pr/types.ts
+function nonEmpty(items) {
+	return items.length === 0 ? null : [items[0], ...items.slice(1)];
+}
+function parsePrNumber(value, label = "PR number") {
+	if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) throw new Error(`${label} must be a positive integer`);
+	return value;
+}
+export { nonEmpty, parsePrNumber };

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

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// runtime/skills/poteto-mode/scripts/watch-pr/watch-pr
+const { main } = await import("./cli.mjs");
+process.exitCode = await main(process.argv.slice(2));
+export {};