pstack-claude-mirror 0.0.0-stage → 0.9.133

package/plugins/pstack/skills/poteto-mode/scripts/resume.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { parseArgs } from 'node:util';
+
+function git(project, ...args) {
+  return execFileSync('git', ['-C', project, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+function identity(project) {
+  return {
+    worktree: realpathSync(git(project, 'rev-parse', '--show-toplevel')),
+    gitDir: realpathSync(git(project, 'rev-parse', '--path-format=absolute', '--git-common-dir')),
+  };
+}
+function inside(root, file) {
+  const path = relative(root, file);
+  return path === '' || (!isAbsolute(path) && path !== '..' && !path.startsWith(`..${sep}`));
+}
+function string(value, name) {
+  if (typeof value !== 'string' || !value) throw new Error(`missing ${name}`);
+  return value;
+}
+function object(value, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`invalid ${name}`);
+  return value;
+}
+function fileInfo(path, roots) {
+  const canonical = realpathSync(path);
+  if (!roots.some(root => inside(root, canonical)) || !statSync(canonical).isFile())
+    throw new Error(`checkpoint file must belong to this project: ${path}`);
+  return { path: canonical, sha256: createHash('sha256').update(readFileSync(canonical)).digest('hex') };
+}
+function verifyFile(value, roots) {
+  const record = object(value, 'file record');
+  const file = fileInfo(string(record.path, 'file path'), roots);
+  if (file.sha256 !== string(record.sha256, 'file digest')) throw new Error(`checkpoint file changed: ${file.path}`);
+  return file;
+}
+const linkRule = 'Link each local file with an inline Markdown link whose destination is the path, written bare or as `<path>`, with no square brackets in the link text and no title after the path. Reference-style links are not read. The path is relative to the note or absolute, and it is percent-decoded, so write a literal `%` as `%25`. Wrap a path that contains spaces or parentheses in angle brackets, or percent-encode it. Links inside code spans and fenced code blocks are ignored.';
+function resolveLink(note, link, target) {
+  let decoded;
+  try { decoded = decodeURIComponent(target.split('#')[0]); }
+  catch { throw new Error(`link ${link} has malformed percent-encoding. ${linkRule}`); }
+  try { return realpathSync(resolve(dirname(note.path), decoded)); }
+  catch (error) { throw new Error(`link ${link} does not resolve (${error.code}). ${linkRule}`); }
+}
+function verifyLinks(note, artifacts) {
+  const prose = readFileSync(note.path, 'utf8')
+    .replace(/^\uFEFF/, '')
+    .replaceAll('\r\n', '\n')
+    .replace(/^ {0,3}((`|~)\2{2,}).*\n[\s\S]*?(?:^ {0,3}\1\2*[ \t]*$|(?![\s\S]))/gm, ' ')
+    .replace(/(?<!`)(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/g, ' ');
+  const links = [...prose.matchAll(/\[[^\]]*\]\((?:<([^<>]+)>|([^)]+))\)/g)]
+    .filter(([, angled, bare]) => !/^(?:[a-z]{2,}:|#)/i.test(angled ?? bare))
+    .map(([link, angled, bare]) => ({ link, path: resolveLink(note, link, angled ?? bare) }));
+  for (const artifact of artifacts)
+    if (!links.some(({ path }) => path === artifact.path))
+      throw new Error(`note must link requested artifact: ${artifact.path}. ${linkRule}`);
+  for (const { link, path } of links)
+    if (path !== note.path && !artifacts.some(artifact => artifact.path === path))
+      throw new Error(`register every local note link with --artifact: ${link} resolves to ${path}. ${linkRule}`);
+}
+function load(store, project) {
+  const pointer = join(store, 'latest.json');
+  fileInfo(pointer, [store]);
+  const record = object(JSON.parse(readFileSync(pointer, 'utf8')), 'checkpoint');
+  if (record.schemaVersion !== 1 || record.gitDir !== project.gitDir) throw new Error('checkpoint project mismatch');
+  const worktree = string(record.worktree, 'worktree');
+  const roots = [store, project.worktree];
+  if (worktree !== project.worktree) {
+    try {
+      if (identity(worktree).gitDir === project.gitDir) roots.push(realpathSync(worktree));
+    } catch { /* Removed worktrees cannot supply artifacts; store files remain readable. */ }
+  }
+  const note = verifyFile(record.note, [store]);
+  if (!Array.isArray(record.artifacts)) throw new Error('invalid artifact list');
+  const artifacts = record.artifacts.map(value => verifyFile(value, roots));
+  const branch = record.branch === null ? null : string(record.branch, 'branch');
+  const createdAt = string(record.createdAt, 'timestamp');
+  if (!Number.isFinite(Date.parse(createdAt))) throw new Error('invalid checkpoint timestamp');
+  verifyLinks(note, artifacts);
+  return { schemaVersion: 1, gitDir: project.gitDir, worktree, branch, createdAt, note, artifacts };
+}
+
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      project: { type: 'string', default: '.' },
+      note: { type: 'string' },
+      artifact: { type: 'string', multiple: true, default: [] },
+    },
+  });
+  const [operation] = positionals;
+  if (positionals.length !== 1 || !['begin', 'publish', 'read'].includes(operation))
+    throw new Error('usage: resume.mjs begin|publish|read --project <directory> [--note <file> --artifact <file> ...]');
+  if (operation !== 'publish' && (values.note || values.artifact.length)) throw new Error('only publish accepts files');
+  const project = identity(values.project);
+  const store = join(project.gitDir, 'pstack', 'resume');
+  if (operation === 'read') {
+    try {
+      lstatSync(join(store, 'latest.json'));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      console.log(JSON.stringify({ kind: 'missing' }));
+      process.exit(2);
+    }
+    console.log(JSON.stringify({ kind: 'checkpoint', checkpoint: load(store, project) }));
+  } else {
+    mkdirSync(store, { recursive: true, mode: 0o700 });
+    if (!inside(project.gitDir, realpathSync(store))) throw new Error('resume store escapes the Git directory');
+    if (operation === 'begin') {
+      const directory = join(store, randomUUID());
+      mkdirSync(directory, { mode: 0o700 });
+      console.log(JSON.stringify({ kind: 'directory', directory }));
+    } else {
+      const note = fileInfo(string(values.note, '--note'), [store]);
+      const artifacts = values.artifact.map(path => fileInfo(path, [store, project.worktree]));
+      if (new Set(artifacts.map(file => file.path)).size !== artifacts.length) throw new Error('duplicate artifact');
+      verifyLinks(note, artifacts);
+      const checkpoint = {
+        schemaVersion: 1, ...project,
+        branch: git(project.worktree, 'branch', '--show-current') || null,
+        createdAt: new Date().toISOString(), note, artifacts,
+      };
+      const temporary = join(store, `.latest-${randomUUID()}.json`);
+      try {
+        writeFileSync(temporary, JSON.stringify(checkpoint) + '\n', { flag: 'wx', mode: 0o600 });
+        renameSync(temporary, join(store, 'latest.json'));
+      } finally { rmSync(temporary, { force: true }); }
+      console.log(JSON.stringify({ kind: 'checkpoint', checkpoint: load(store, project) }));
+    }
+  }
+} catch (error) {
+  console.log(JSON.stringify({ kind: 'unavailable', detail: error.message }));
+  process.exitCode = 1;
+}

package/plugins/pstack/skills/poteto-mode/scripts/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "esnext",
+    "types": ["bun-types"]
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules"]
+}

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

@@ -0,0 +1,383 @@
+import { describe, expect, it } from "bun:test";
+import { type CliRuntime, main, parseArgs } from "./cli.ts";
+import { WatchDeadline } from "./deadline.ts";
+import { fakeReader, passingCheck } from "./fakes.test-helper.ts";
+import { renderJson, renderPretty } from "./render.ts";
+import type { GitHubReader, QueryFailure, 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,
+      deadline: new WatchDeadline(0, () => 0),
+      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",
+          baseRefOid: "base",
+          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 |"
+    );
+  });
+
+  const envelope = {
+    schemaVersion: 1,
+    sequence: 1,
+    observedAt: "2026-07-26T00:00:00.000Z",
+    mode: "single",
+  } as const;
+
+  it("does not call a PR that changed mid-read a failed query", () => {
+    const retry = (failure: QueryFailure) =>
+      renderPretty({
+        ...envelope,
+        kind: "RETRY",
+        terminal: false,
+        failure,
+        consecutiveFailures: 1,
+        retryInSeconds: 60,
+      });
+    expect(
+      retry({ kind: "snapshot-changed", retryable: true, detail: "moved" })
+    ).toBe(
+      "RETRY: the PR changed while its status was being read; retrying in 60s\ndetail=moved\n"
+    );
+    expect(
+      retry({ kind: "command-exit", retryable: true, detail: "502", code: 1 })
+    ).toBe("RETRY: GitHub status query failed; retrying in 60s\ndetail=502\n");
+  });
+
+  it("tells a caller whose command could not run to install it, not to check authentication", () => {
+    const action = (failure: QueryFailure) =>
+      renderPretty({
+        ...envelope,
+        kind: "BLOCKER",
+        terminal: true,
+        exitCode: 7,
+        blocker: { kind: "status-query", failures: 1, failure },
+      })
+        .trimEnd()
+        .split("\n")
+        .at(-1);
+    expect(
+      action({ kind: "spawn-failed", retryable: false, detail: "no gh" })
+    ).toBe(
+      "action=install the command that could not run, or put it on PATH, then rearm"
+    );
+    expect(
+      action({ kind: "command-exit", retryable: true, detail: "401", code: 1 })
+    ).toBe(
+      "action=verify current PR context, GitHub authentication, and API availability, then rearm"
+    );
+  });
+});
+
+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("rejects an interval longer than one timer can sleep, and accepts the longest one", async () => {
+    const harness = testRuntime(fakeReader());
+    expect(await main(["--interval", "2147484"], harness.runtime)).toBe(64);
+    expect(harness.stdout).toEqual([]);
+    expect(harness.stderr.join("")).toContain(
+      "option '--interval <seconds>' argument '2147484' is invalid. must be at most 2147483.647"
+    );
+    expect(
+      parseArgs(["--interval", "2147483.647"], silentIo).polling.interval
+    ).toBe(2147483.647);
+  });
+
+  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("names the absence of checks in the status table and the READY verdict", async () => {
+    const argv = [
+      "--owner",
+      "owner",
+      "--repo",
+      "repo",
+      "--pr",
+      "1",
+      "--pretty",
+    ];
+    const noChecks = () =>
+      testRuntime(
+        fakeReader({
+          facts: { reviewDecision: null },
+          fastPath: { kind: "none-reported" },
+          rollupPages: [{ kind: "no-rollup" }],
+          commitRollups: [{ oid: "head", state: null }],
+        })
+      );
+    const status = noChecks();
+    expect(await main([...argv, "--status-only"], status.runtime)).toBe(0);
+    expect(status.stdout.join("")).toContain(
+      "| [#1](https://github.com/owner/repo/pull/1) | ⏳ no checks reported yet | ✅ | ✅ |"
+    );
+    const ready = noChecks();
+    let now = 0;
+    const runtime = {
+      ...ready.runtime,
+      clock: {
+        ...ready.runtime.clock,
+        now: () => now,
+        async sleep(seconds: number) {
+          now += seconds;
+          if (now > 3600) throw new Error("no verdict within an hour");
+        },
+      },
+    };
+    expect(await main(argv, runtime)).toBe(0);
+    expect(ready.stdout).toEqual([
+      "WAITING: frontier=#1; no checks have reported on the head commit yet\n",
+      "READY: no merge conflicts, no unresolved review threads, no failing or pending checks\nmergeStateStatus=CLEAN\nreviewDecision=null\nisDraft=false\nchecks=none reported on the head commit\n",
+    ]);
+  });
+
+  it("says that mergeability is unknown in the status table, the WAITING line, and the TIMEOUT line", async () => {
+    const argv = [
+      "--owner",
+      "owner",
+      "--repo",
+      "repo",
+      "--pr",
+      "1",
+      "--pretty",
+    ];
+    const unknown = () =>
+      testRuntime(
+        fakeReader({
+          facts: { mergeable: "UNKNOWN", mergeStateStatus: "UNKNOWN" },
+        })
+      );
+    const status = unknown();
+    expect(await main([...argv, "--status-only"], status.runtime)).toBe(0);
+    expect(status.stdout.join("")).toContain(
+      "| [#1](https://github.com/owner/repo/pull/1) | ✅ | ✅ | ⏳ mergeability unknown |"
+    );
+    const waiting = unknown();
+    let now = 0;
+    const runtime = {
+      ...waiting.runtime,
+      deadline: new WatchDeadline(90, () => now),
+      clock: {
+        ...waiting.runtime.clock,
+        now: () => now,
+        async sleep(seconds: number) {
+          now += seconds;
+        },
+      },
+    };
+    expect(await main(argv, runtime)).toBe(5);
+    expect(waiting.stdout).toEqual([
+      "WAITING: frontier=#1; GitHub has not computed mergeability yet\n",
+      "WAITING: frontier=#1; GitHub has not computed mergeability yet\n",
+      "TIMEOUT: GitHub has not computed mergeability yet\n",
+    ]);
+  });
+
+  it("shows help without touching the reader", async () => {
+    const reader = fakeReader();
+    const harness = testRuntime(reader);
+    expect(await main(["--help"], harness.runtime)).toBe(0);
+    const help = harness.stdout.join("").replace(/\s+/g, " ");
+    expect(help).toContain("JSON (NDJSON while polling)");
+    expect(help).toContain(
+      "print one status table and exit; exit 0 means the table was read, not that the PR is ready"
+    );
+    expect(help).toContain(
+      "poll interval; a PR with no checks takes 60 seconds to confirm whatever this is"
+    );
+    expect(reader.calls).toEqual([]);
+  });
+});