dsh-pstack 0.3.0-beta.1 → 0.3.1

package/dist/pstack/skills/poteto-mode/scripts/{check-plan.test.mjs → check-plan.test.ts}

@@ -1,13 +1,13 @@
-import { expect } from "./expect.mjs";
-import "./support.mjs";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
-import { test } from "node:test";
-// runtime/skills/poteto-mode/scripts/check-plan.test.ts
-const checker = join(import.meta.dirname, "check-plan.mjs");
-const rule = "Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked.";
+import { expect, test } from "bun:test";
+
+const checker = join(import.meta.dir, "check-plan.mjs");
+const rule =
+	"Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked.";
+
 const validPlan = `# Demo
 
 ## How to read this
@@ -20,7 +20,7 @@ ${rule}
 ### PR mechanics
 ### Verdict and merge
 ### Boot recipe
-\`git show origin/main:\` \`create_goal\` \`schedule_create\` status message
+\`git show origin/main:\` /loop 1h status message
 
 ## PR 1
 **Depends on.** None.
@@ -49,7 +49,8 @@ Close.
 ## Appendix Prototype evidence
 Recorded.
 `;
-const runPlan = (example, expectedExit) => {
+
+const runPlan = (example: string, expectedExit: number) => {
 	const directory = mkdtempSync(join(tmpdir(), "check-plan-test-"));
 	const file = join(directory, "plan.md");
 	writeFileSync(file, validPlan + example);
@@ -58,71 +59,52 @@ const runPlan = (example, expectedExit) => {
 		expect(result.status).toBe(expectedExit);
 		return result;
 	} finally {
-		rmSync(directory, {
-			recursive: true,
-			force: true
-		});
+		rmSync(directory, { recursive: true, force: true });
 	}
 };
+
 test("accepts ordinary, indented, and longer closing fences", () => {
-	for (const indent of [
-		"",
-		" ",
-		"  ",
-		"   "
-	]) runPlan(`${indent}\`\`\`markdown\n## Example only\n${indent}\`\`\`\n`, 0);
+	for (const indent of ["", " ", "  ", "   "])
+		runPlan(`${indent}\`\`\`markdown\n## Example only\n${indent}\`\`\`\n`, 0);
 	runPlan("```markdown\n## Example only\n````\n", 0);
 });
+
 test("accepts nested backticks and tilde info strings", () => {
 	runPlan("````markdown\n```markdown\n## Example only\n```\n````\n", 0);
 	runPlan("~~~markdown `info`\n## Example only\n ~~~\n", 0);
 });
+
 test("keeps mismatched, shorter, and suffixed closers inside the fence", () => {
 	runPlan("````markdown\n~~~\n## Example only\n````\n", 0);
 	runPlan("````markdown\n```\n## Example only\n````\n", 0);
 	runPlan("````markdown\n``` info\n## Example only\n````\n", 0);
 });
+
 test("rejects headings and prose outside a proper close", () => {
-	for (const suffix of ["  ", "	"]) {
+	for (const suffix of ["  ", "\t"]) {
 		const heading = runPlan(`\`\`\`markdown\n## Example only\n\`\`\`${suffix}\n## Example only\n`, 1);
-		expect(heading.stderr).toContain("\"## Example only\" after Close the program is not an appendix");
+		expect(heading.stderr).toContain('"## Example only" after Close the program is not an appendix');
 	}
+
 	const prose = runPlan("```markdown\nThis prose has a mid-sentence colon: inside code\n```\nThis prose has a mid-sentence colon: bad.\n", 1);
 	expect(prose.stderr).toContain("mid-sentence colon");
 });
+
 test("rejects backtick info strings containing a backtick", () => {
 	const result = runPlan("```markdown `invalid`\n## Example only\n```\n", 1);
-	expect(result.stderr).toContain("\"## Example only\" after Close the program is not an appendix");
+	expect(result.stderr).toContain('"## Example only" after Close the program is not an appendix');
 });
+
 test("ignores prose punctuation inside matching multi-backtick code spans", () => {
-	for (const count of [
-		2,
-		3,
-		4
-	]) {
+	for (const count of [2, 3, 4]) {
 		const delimiter = "`".repeat(count);
 		runPlan(`Use ${delimiter}echo \`x\`: “quoted” — example${delimiter}.\n`, 0);
 	}
 });
+
 test("checks prose following a multi-backtick span and unmatched delimiters", () => {
 	const outside = runPlan("Use ``echo `x`: y``. Bad: prose.\n", 1);
 	expect(outside.stderr).toContain("mid-sentence colon");
 	const unmatched = runPlan("Use ``unclosed: bad` here.\n", 1);
 	expect(unmatched.stderr).toContain("mid-sentence colon");
 });
-test("accepts the upstream /loop tick or the DSH goal plus schedule tick", () => {
-	const upstream = validPlan.replace("`git show origin/main:` `create_goal` `schedule_create` status message", "`git show origin/main:` /loop 1h status message");
-	const directory = mkdtempSync(join(tmpdir(), "check-plan-test-"));
-	const file = join(directory, "plan.md");
-	writeFileSync(file, upstream);
-	try {
-		const result = spawnSync("node", [checker, file], { encoding: "utf8" });
-		expect(result.status).toBe(0);
-	} finally {
-		rmSync(directory, {
-			recursive: true,
-			force: true
-		});
-	}
-});
-export {};

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

@@ -0,0 +1,16 @@
+{
+  "name": "@cursor-skill/poteto-mode-tools",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "bun test watch-pr check-plan.test.ts",
+    "typecheck": "tsc --project watch-pr/tsconfig.json --noEmit --strict"
+  },
+  "dependencies": {
+    "commander": "14.0.0"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "latest"
+  }
+}

package/dist/pstack/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/dist/pstack/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;
+}