Skip to content

michael-denyer/pstack-claude / plugins/pstack/skills/poteto-mode

poteto-mode

Verified

poteto's agent style for concise, detailed responses, deliberate subagents, unslopped prose, simple code, and verified work. Use for poteto, /poteto-mode, or requests to work in this style.

FileKindSize
SKILL.mdskill md18.1 KB
playbooks/authoring-a-skill.mdmarkdown852 B
playbooks/autonomous-run.mdmarkdown1.9 KB
playbooks/autopilot-full.mdmarkdown8.3 KB
playbooks/autopilot-stack.mdmarkdown1.3 KB
playbooks/babysit.mdmarkdown2.3 KB
playbooks/bug-fix.mdmarkdown4.8 KB
playbooks/eval.mdmarkdown2.8 KB
playbooks/feature.mdmarkdown3.4 KB
playbooks/hillclimb.mdmarkdown4.4 KB
playbooks/investigation.mdmarkdown920 B
playbooks/multi-phase-plan.mdmarkdown1.6 KB
playbooks/opening-a-pr.mdmarkdown1.0 KB
playbooks/pause-safely.mdmarkdown1.9 KB
playbooks/perf-issue.mdmarkdown1.5 KB
playbooks/prototype.mdmarkdown2.1 KB
playbooks/refactoring.mdmarkdown3.3 KB
playbooks/runtime-forensics.mdmarkdown1.3 KB
playbooks/session-pickup.mdmarkdown2.7 KB
playbooks/shipping.mdmarkdown7.2 KB
playbooks/trace-forensics.mdmarkdown1.8 KB
playbooks/visual-parity.mdmarkdown1.2 KB
playbooks/worktree-cleanup.mdmarkdown4.5 KB
references/agents/comment-sicko.mdmarkdown2.9 KB
references/agy-tools.mdmarkdown10.3 KB
references/bugbot-triage.mdmarkdown9.4 KB
references/codex-tools.mdmarkdown13.6 KB
references/copilot-tools.mdmarkdown20.6 KB
references/grok.mdmarkdown3.9 KB
references/kimi-tools.mdmarkdown4.6 KB
references/licenses/LICENSEother1.1 KB
references/licenses/LICENSE-cursor-team-kitother1.0 KB
references/licenses/LICENSE-thermosother1.0 KB
references/licenses/NOTICE.mdmarkdown1.9 KB
references/merge-safety.mdmarkdown5.2 KB
references/minimax-tools.mdmarkdown10.2 KB
references/muse-tools.mdmarkdown12.5 KB
references/omp-tools.mdmarkdown5.7 KB
references/opencode-tools.mdmarkdown3.3 KB
references/pi-tools.mdmarkdown23.5 KB
references/resume-storage.mdmarkdown3.6 KB
scripts/.prettierignoreother652 B
scripts/.prettierrc.jsonconfig29 B
scripts/bootstrap.tsscript2.0 KB
scripts/bun.lockother6.5 KB
scripts/check-playbooks.mjsscript6.5 KB
scripts/codex-session-effort.mjsscript3.9 KB
scripts/package.jsonmanifest320 B
scripts/resume.mjsscript7.2 KB
scripts/tsconfig.jsonconfig304 B
scripts/watch-pr/cli.test.tsscript11.2 KB
scripts/watch-pr/cli.tsscript8.1 KB
scripts/watch-pr/deadline.tsscript522 B
scripts/watch-pr/fakes.test-helper.tsscript4.2 KB
scripts/watch-pr/fresh-install.test.tsscript1.3 KB
scripts/watch-pr/github.port.test.tsscript17.1 KB
scripts/watch-pr/github.test.tsscript16.6 KB
scripts/watch-pr/github.tsscript34.6 KB
scripts/watch-pr/integrity.test.tsscript24.3 KB
scripts/watch-pr/landing.tsscript3.0 KB
scripts/watch-pr/live-merge-safety.mjsscript7.4 KB
scripts/watch-pr/policy.port.test.tsscript24.5 KB
scripts/watch-pr/policy.test.tsscript14.8 KB
scripts/watch-pr/policy.tsscript30.0 KB
scripts/watch-pr/render.tsscript8.9 KB
scripts/watch-pr/ship-prexecutablescript220 B
scripts/watch-pr/shipping-cli.test.tsscript5.3 KB
scripts/watch-pr/shipping-cli.tsscript2.3 KB
scripts/watch-pr/shipping.test-helper.tsscript2.1 KB
scripts/watch-pr/shipping.test.tsscript11.0 KB
scripts/watch-pr/shipping.tsscript6.7 KB
scripts/watch-pr/transport.test.tsscript12.6 KB
scripts/watch-pr/tsconfig.jsonconfig270 B
scripts/watch-pr/types.compile.tsscript2.6 KB
scripts/watch-pr/types.tsscript14.2 KB
scripts/watch-pr/watch-prexecutablescript211 B
scripts/watch-pr/wrapper.test.tsscript587 B
scripts/worktree-audit.mjsexecutablescript22.4 KB
worker.mdmarkdown1.3 KB

scripts/watch-pr/github.ts

View on GitHub
import { baseRefTargetOid, text } from "./landing.ts";
import { spawn } from "node:child_process";
import { DeadlineExceeded, type WatchDeadline } from "./deadline.ts";
import type * as T from "./types.ts";
import { nonEmpty, parsePrNumber } from "./types.ts";
export const REVIEW_THREADS_QUERY =
  "\nquery ReviewThreads($owner: String!, $repo: String!, $pr: Int!, $after: String) {\n  repository(owner: $owner, name: $repo) {\n    pullRequest(number: $pr) {\n      reviewThreads(first: 100, after: $after) {\n        pageInfo {\n          hasNextPage\n          endCursor\n        }\n        nodes {\n          id\n          isResolved\n          comments(first: 10) {\n            nodes {\n              body\n              createdAt\n              path\n              line\n              author { login }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n";
export const PR_COMMIT_STATUS_QUERY =
  "\nquery PrCommitStatuses($owner: String!, $repo: String!, $pr: Int!) {\n  repository(owner: $owner, name: $repo) {\n    pullRequest(number: $pr) {\n      commits(last: 50) {\n        nodes {\n          commit {\n            oid\n            statusCheckRollup {\n              state\n            }\n          }\n        }\n      }\n    }\n  }\n}\n";
export const PR_FACTS_QUERY = `query PullRequestFacts($owner: String!, $repo: String!, $pr: Int!) {
  repository(owner: $owner, name: $repo) {
    pullRequest(number: $pr) {
      mergeable
      mergeStateStatus
      reviewDecision
      headRefOid
      headRefName
      baseRefName
      baseRef { target { oid } }
      state
      mergedAt
      isDraft
    }
  }
}`;
export const PR_CHECK_ROLLUP_QUERY =
  "\nquery PrCheckRollup($owner: String!, $repo: String!, $pr: Int!, $after: String) {\n  repository(owner: $owner, name: $repo) {\n    pullRequest(number: $pr) {\n      commits(last: 1) {\n        nodes {\n          commit {\n            statusCheckRollup {\n              contexts(first: 100, after: $after) {\n                pageInfo {\n                  hasNextPage\n                  endCursor\n                }\n                nodes {\n                  __typename\n                  ... on CheckRun {\n                    name\n                    status\n                    conclusion\n                    detailsUrl\n                  }\n                  ... on StatusContext {\n                    context\n                    state\n                    targetUrl\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n";

interface CommandResult {
  readonly code: number;
  readonly stdout: string;
  readonly stderr: string;
}
export class WatcherQueryError extends Error {
  readonly failure: T.QueryFailure;
  constructor(failure: T.QueryFailure) {
    super(failure.detail);
    this.name = "WatcherQueryError";
    this.failure = failure;
  }
}
export class ChecksUnavailable extends WatcherQueryError {
  constructor(detail: string) {
    super({ kind: "checks-unavailable", retryable: true, detail });
    this.name = "ChecksUnavailable";
  }
}
const firstLine = (value: string): string =>
  value.trim().split(/\r?\n/, 1)[0]?.slice(0, 240) ?? "";
function run(
  argv: readonly [string, ...string[]],
  deadline: WatchDeadline
): Promise<CommandResult> {
  if (deadline.remaining() === 0) return Promise.reject(new DeadlineExceeded());
  return new Promise((resolve, reject) => {
    const child = spawn(argv[0], argv.slice(1), {
      stdio: ["ignore", "pipe", "pipe"],
    });
    let stdout = "";
    let stderr = "";
    let expired = false;
    let timer: ReturnType<typeof setTimeout> | undefined;
    const scheduleDeadline = (): void => {
      const seconds = deadline.remaining();
      if (!Number.isFinite(seconds)) return;
      if (seconds === 0) {
        expired = true;
        child.kill("SIGKILL");
      } else {
        timer = setTimeout(
          scheduleDeadline,
          Math.min(seconds * 1_000, 2_147_483_647)
        );
      }
    };
    scheduleDeadline();
    child.stdout.setEncoding("utf8");
    child.stderr.setEncoding("utf8");
    child.stdout.on("data", (chunk: string) => {
      stdout += chunk;
    });
    child.stderr.on("data", (chunk: string) => {
      stderr += chunk;
    });
    child.on("error", (error) => {
      clearTimeout(timer);
      reject(
        new WatcherQueryError({
          kind: "spawn-failed",
          retryable: false,
          detail: `could not run ${argv[0]}: ${error.message}`,
        })
      );
    });
    child.on("close", (code) => {
      clearTimeout(timer);
      if (expired) reject(new DeadlineExceeded());
      else resolve({ code: code ?? -1, stdout, stderr });
    });
  });
}
function parseJson(text: string, label: string): unknown {
  try {
    return JSON.parse(text);
  } catch (error) {
    throw new WatcherQueryError({
      kind: "json-parse",
      retryable: true,
      detail: `${label}: ${error instanceof Error ? error.message : String(error)}`,
    });
  }
}
export async function runJson(
  argv: readonly [string, ...string[]],
  deadline: WatchDeadline
): Promise<unknown> {
  const result = await run(argv, deadline);
  if (result.code !== 0)
    throw new WatcherQueryError({
      kind: "command-exit",
      retryable: true,
      code: result.code,
      detail:
        firstLine(result.stderr) || `${argv.join(" ")} exited ${result.code}`,
    });
  return parseJson(result.stdout, argv.join(" "));
}
function raw(value: unknown): string {
  try {
    return JSON.stringify(value);
  } catch {
    return String(value);
  }
}
function missing(path: string, value?: unknown): never {
  throw new WatcherQueryError({
    kind: "missing-field",
    retryable: true,
    detail:
      value === undefined
        ? `missing ${path}`
        : `invalid ${path}: ${raw(value)}`,
    ...(value === undefined ? {} : { rawValue: raw(value) }),
  });
}
function advanceCursor(cursors: Set<string>, after: string, label: string) {
  if (cursors.has(after))
    missing(`${label}.pageInfo.endCursor must advance`, after);
  cursors.add(after);
}
function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}
function record(value: unknown, path: string): Record<string, unknown> {
  if (!isRecord(value)) missing(path, value);
  return value;
}
function list(value: unknown, path: string): readonly unknown[] {
  if (!Array.isArray(value)) missing(path, value);
  return value;
}
function at(value: unknown, path: readonly string[]): unknown {
  let current = value;
  for (const key of path) {
    const object = record(current, path.join("."));
    if (!(key in object)) missing(path.join("."));
    current = object[key];
  }
  return current;
}
function string(value: unknown, path: string): string {
  if (typeof value !== "string") missing(path, value);
  return value;
}
const optionalString = (value: unknown, path: string): string | null =>
  value === null ? null : string(value, path);
function enumValue<const V extends readonly string[]>(
  value: unknown,
  values: V,
  path: string
): V[number] {
  if (typeof value === "string")
    for (const candidate of values) if (candidate === value) return candidate;
  return missing(path, value);
}
const nullableEnum = <const V extends readonly string[]>(
  value: unknown,
  values: V,
  path: string
): V[number] | null => (value === null ? null : enumValue(value, values, path));
const MERGE_STATES = [
  "BEHIND",
  "BLOCKED",
  "CLEAN",
  "CONFLICTING",
  "DIRTY",
  "DRAFT",
  "HAS_HOOKS",
  "UNKNOWN",
  "UNSTABLE",
] as const satisfies readonly T.MergeStateStatus[];
const ROLLUP_STATES = [
  "ERROR",
  "EXPECTED",
  "FAILURE",
  "PENDING",
  "SUCCESS",
] as const;
const OPEN_PR_LIMIT = 300;
const REVIEW_DECISIONS = [
  "APPROVED",
  "CHANGES_REQUESTED",
  "REVIEW_REQUIRED",
] as const;
const reviewDecision = (value: unknown): T.ReviewDecision =>
  nullableEnum(value, REVIEW_DECISIONS, "pull request.reviewDecision");
function parseRemote(value: string): T.Repository | null {
  let normalized = value.trim();
  if (normalized.startsWith("git@github.com:"))
    normalized = `https://github.com/${normalized.slice(15)}`;
  if (normalized.startsWith("ssh://git@github.com/"))
    normalized = `https://github.com/${normalized.slice(21)}`;
  try {
    const url = new URL(normalized);
    const parts = url.pathname
      .replace(/\.git$/, "")
      .split("/")
      .filter(Boolean);
    if (
      url.protocol !== "https:" ||
      url.hostname !== "github.com" ||
      url.port ||
      url.username ||
      url.password ||
      url.search ||
      url.hash ||
      parts.length !== 2
    )
      return null;
    return { owner: parts[0], repo: parts[1] };
  } catch {
    return null;
  }
}
function parsePrUrl(value: string): T.PrContext {
  try {
    const url = new URL(value);
    const parts = url.pathname.split("/").filter(Boolean);
    if (
      url.protocol !== "https:" ||
      url.hostname !== "github.com" ||
      url.port ||
      url.username ||
      url.password ||
      url.search ||
      url.hash ||
      parts.length !== 4 ||
      parts[2] !== "pull"
    )
      throw new Error("not a canonical GitHub pull URL");
    return {
      owner: parts[0],
      repo: parts[1],
      number: parsePrNumber(Number(parts[3])),
    };
  } catch (error) {
    throw new WatcherQueryError({
      kind: "invalid-context-url",
      retryable: false,
      rawValue: value,
      detail: `could not infer owner/repo from PR URL: ${value} (${error instanceof Error ? error.message : String(error)})`,
    });
  }
}
function checkDetails(value: Record<string, unknown>, nameKey: string) {
  return {
    name: string(value[nameKey], nameKey),
    description: typeof value.description === "string" ? value.description : "",
    link:
      typeof value.link === "string"
        ? value.link
        : typeof value.detailsUrl === "string"
          ? value.detailsUrl
          : "",
    workflow: typeof value.workflow === "string" ? value.workflow : "",
  };
}
// gh buckets every state it does not name as pending, including completed
// conclusions like STALE and STARTUP_FAILURE. Only these are in flight, the
// same states mapRollupNode treats as pending.
const IN_FLIGHT_STATES = new Set([
  "EXPECTED",
  "REQUESTED",
  "WAITING",
  "QUEUED",
  "PENDING",
  "IN_PROGRESS",
]);
export function parseFastCheck(value: unknown): T.Check {
  const object = record(value, "check");
  const details = checkDetails(object, "name");
  const state = string(object.state, "check.state").toUpperCase();
  const bucket = string(object.bucket, "check.bucket");
  if (state === "ACTION_REQUIRED") return gateOr("failed", details, state);
  if (bucket === "fail" || ["FAILURE", "ERROR"].includes(state))
    return { ...details, kind: "failed", reportedState: state };
  if (bucket === "pending" && IN_FLIGHT_STATES.has(state))
    return gateOr("pending", details, state);
  if (bucket === "pass")
    return { ...details, kind: "passed", reportedState: state };
  if (bucket === "skipping")
    return { ...details, kind: "skipped", reportedState: state };
  return { ...details, kind: "failed", reportedState: state };
}
// Every read path classifies the owner-approval gate here, so the rule has one
// home. A gate that is pending or waits on an owner approval must not count as
// pending or failed, or the watcher waits on a human.
function gateOr(
  kind: "pending" | "failed",
  details: {
    readonly name: string;
    readonly description: string;
    readonly link: string;
    readonly workflow: string;
  },
  reportedState: string
): T.Check {
  return details.name === "Code Review Gate"
    ? {
        ...details,
        kind: "code-review-gate",
        name: "Code Review Gate",
        reportedState,
      }
    : { ...details, kind, reportedState };
}
export function mapRollupNode(value: unknown): T.Check | null {
  const object = record(value, "rollup node");
  const typename = object.__typename;
  if (typename !== "CheckRun" && typename !== "StatusContext") return null;
  const details = checkDetails(
    object,
    typename === "CheckRun" ? "name" : "context"
  );
  const link =
    typeof object.targetUrl === "string" ? object.targetUrl : details.link;
  if (typename === "CheckRun") {
    const status =
      typeof object.status === "string" ? object.status.toUpperCase() : "";
    const conclusion =
      typeof object.conclusion === "string"
        ? object.conclusion.toUpperCase()
        : "";
    if (status !== "COMPLETED")
      return gateOr("pending", { ...details, link }, "PENDING");
    if (conclusion === "SUCCESS")
      return { ...details, link, kind: "passed", reportedState: "SUCCESS" };
    if (conclusion === "NEUTRAL" || conclusion === "SKIPPED")
      return { ...details, link, kind: "skipped", reportedState: conclusion };
    if (conclusion === "ACTION_REQUIRED")
      return gateOr("failed", { ...details, link }, conclusion);
    return { ...details, link, kind: "failed", reportedState: "FAILURE" };
  }
  const state =
    typeof object.state === "string" ? object.state.toUpperCase() : "";
  if (state === "PENDING" || state === "EXPECTED")
    return gateOr("pending", { ...details, link }, "PENDING");
  return state === "SUCCESS"
    ? { ...details, link, kind: "passed", reportedState: state }
    : { ...details, link, kind: "failed", reportedState: state || "FAILURE" };
}
function parseComment(value: unknown): T.ReviewComment {
  const object = record(value, "review comment");
  const author =
    object.author === null
      ? null
      : record(object.author, "review comment.author");
  return {
    authorLogin:
      author === null
        ? null
        : optionalString(author.login, "review comment.author.login"),
    body: string(object.body, "review comment.body"),
    path: optionalString(object.path, "review comment.path"),
    line:
      object.line === null
        ? null
        : Number.isInteger(object.line)
          ? Number(object.line)
          : missing("review comment.line", object.line),
    createdAt: string(object.createdAt, "review comment.createdAt"),
  };
}
function isBugbot(comment: T.ReviewComment | null): boolean {
  if (comment === null) return false;
  const author = (comment.authorLogin ?? "").toLowerCase();
  const body = comment.body.toLowerCase();
  return (
    author.includes("bugbot") ||
    (author === "cursor" &&
      [
        "bugbot",
        "cursor_automation_id",
        "agentic security review",
        "description start",
        "severity",
      ].some((token) => body.includes(token)))
  );
}
function passKey(comment: T.ReviewComment | null): string | null {
  if (comment === null) return null;
  for (const pattern of [
    /RUN_ID:\s*([a-zA-Z0-9_.:-]+)/,
    /CURSOR_AUTOMATION_ID:\s*([a-zA-Z0-9_.:-]+)/,
  ]) {
    const match = pattern.exec(comment.body);
    if (match?.[1]) return match[1];
  }
  return null;
}
export function parseReviewThreadPage(value: unknown): T.ReviewThreadPage {
  const reviewThreads = record(
    at(value, ["data", "repository", "pullRequest", "reviewThreads"]),
    "reviewThreads"
  );
  const nodes = list(reviewThreads.nodes, "reviewThreads.nodes");
  const threads: T.RawReviewThread[] = [];
  for (const node of nodes) {
    const thread = record(node, "review thread");
    if (typeof thread.isResolved !== "boolean")
      missing("review thread.isResolved", thread.isResolved);
    const comments = list(
      at(thread, ["comments", "nodes"]),
      "review thread.comments.nodes"
    );
    threads.push({
      id: string(thread.id, "review thread.id"),
      firstComment: comments.length === 0 ? null : parseComment(comments[0]),
      resolved: thread.isResolved,
    });
  }
  const page = record(reviewThreads.pageInfo, "reviewThreads.pageInfo");
  if (typeof page.hasNextPage !== "boolean")
    missing("reviewThreads.pageInfo.hasNextPage", page.hasNextPage);
  const cursor = optionalString(
    page.endCursor,
    "reviewThreads.pageInfo.endCursor"
  );
  if (page.hasNextPage && !cursor)
    missing("reviewThreads.pageInfo.endCursor", cursor);
  return { threads, endCursor: page.hasNextPage && cursor ? cursor : null };
}
export function buildReviewThreads(
  threads: readonly T.RawReviewThread[]
): readonly T.ReviewThread[] {
  const keys = new Set<string>();
  let keyless = false;
  for (const thread of threads) {
    if (!isBugbot(thread.firstComment)) continue;
    const key = passKey(thread.firstComment);
    if (key === null) keyless = true;
    else keys.add(key);
  }
  const passes = keys.size > 0 ? keys.size : keyless ? 1 : 0;
  return threads
    .filter((thread) => !thread.resolved)
    .map(({ id, firstComment }) => ({
      id,
      firstComment,
      isBugbot: isBugbot(firstComment),
      bugbotReviewPasses: passes,
    }));
}
export function parsePullRequest(
  value: unknown,
  context: T.PrContext
): T.PullRequestFacts {
  const object = record(value, "pull request");
  if (typeof object.isDraft !== "boolean")
    missing("pull request.isDraft", object.isDraft);
  const facts = {
    context,
    mergeable: enumValue(
      object.mergeable,
      ["MERGEABLE", "CONFLICTING", "UNKNOWN"] as const,
      "pull request.mergeable"
    ),
    mergeStateStatus: enumValue(
      object.mergeStateStatus,
      MERGE_STATES,
      "pull request.mergeStateStatus"
    ),
    reviewDecision: reviewDecision(object.reviewDecision),
    headRefOid: optionalString(object.headRefOid, "pull request.headRefOid"),
    baseRefOid: baseRefTargetOid(object.baseRef),
    headRefName: string(object.headRefName, "pull request.headRefName"),
    baseRefName: string(object.baseRefName, "pull request.baseRefName"),
    state: enumValue(
      object.state,
      ["OPEN", "CLOSED", "MERGED"] as const,
      "pull request.state"
    ),
    mergedAt: optionalString(object.mergedAt, "pull request.mergedAt"),
    isDraft: object.isDraft,
  };
  return facts.state === "OPEN"
    ? {
        ...facts,
        state: facts.state,
        headRefOid: text(facts.headRefOid, "headRefOid"),
        baseRefName: text(facts.baseRefName, "baseRefName"),
        baseRefOid: text(facts.baseRefOid, "baseRefOid"),
      }
    : { ...facts, state: facts.state };
}
function graphqlArgs(
  query: string,
  context: T.PrContext
): [string, ...string[]] {
  return [
    "gh",
    "api",
    "graphql",
    "-f",
    `query=${query}`,
    "-f",
    `owner=${context.owner}`,
    "-f",
    `repo=${context.repo}`,
    "-F",
    `pr=${context.number}`,
  ];
}

export class GhGitHubReader implements T.GitHubReader {
  constructor(private readonly deadline: WatchDeadline) {}
  private run(argv: readonly [string, ...string[]]): Promise<CommandResult> {
    return run(argv, this.deadline);
  }
  private runJson(argv: readonly [string, ...string[]]): Promise<unknown> {
    return runJson(argv, this.deadline);
  }
  async originRepo(): Promise<T.Repository | null> {
    const result = await this.run(["git", "remote", "get-url", "origin"]);
    return result.code === 0 ? parseRemote(result.stdout) : null;
  }
  async currentPr(pr: T.PrNumber | null): Promise<T.PrContext> {
    const argv: [string, ...string[]] = ["gh", "pr", "view"];
    if (pr !== null) argv.push(String(pr));
    argv.push("--json", "number,url");
    const object = record(await this.runJson(argv), "current PR");
    const parsed = parsePrUrl(string(object.url, "current PR.url"));
    return {
      ...parsed,
      number: pr ?? parsePrNumber(object.number, "current PR.number"),
    };
  }
  private async graphql(
    query: string,
    context: T.PrContext,
    after: string | null = null
  ): Promise<Record<string, unknown>> {
    const argv = graphqlArgs(query, context);
    if (after !== null) argv.push("-f", `after=${after}`);
    const response = record(await this.runJson(argv), "GraphQL response");
    if (response.errors !== undefined)
      missing("GraphQL errors", response.errors);
    return record(
      at(response, ["data", "repository", "pullRequest"]),
      "data.repository.pullRequest"
    );
  }
  async pullRequest(context: T.PrContext): Promise<T.PullRequestFacts> {
    return parsePullRequest(
      await this.graphql(PR_FACTS_QUERY, context),
      context
    );
  }
  async openPullRequests(
    repository: T.Repository
  ): Promise<readonly T.OpenPullRequest[]> {
    const value = await this.runJson([
      "gh",
      "pr",
      "list",
      "--repo",
      `${repository.owner}/${repository.repo}`,
      "--state",
      "open",
      "--limit",
      String(OPEN_PR_LIMIT),
      "--json",
      "number,headRefName,baseRefName,headRepository,headRepositoryOwner",
    ]);
    return list(value, "open PRs").map((item, index) => {
      const object = record(item, `open PRs[${index}]`);
      const headRepository =
        object.headRepository === null
          ? null
          : record(object.headRepository, "headRepository");
      const headOwner =
        object.headRepositoryOwner === null
          ? null
          : record(object.headRepositoryOwner, "headRepositoryOwner");
      return {
        number: parsePrNumber(object.number, `open PRs[${index}].number`),
        headRepository:
          headRepository === null || headOwner === null
            ? null
            : {
                owner: string(headOwner.login, "headRepositoryOwner.login"),
                repo: string(headRepository.name, "headRepository.name"),
              },
        headRefName: string(
          object.headRefName,
          `open PRs[${index}].headRefName`
        ),
        baseRefName: string(
          object.baseRefName,
          `open PRs[${index}].baseRefName`
        ),
      };
    });
  }
  async defaultBranch(repository: T.Repository): Promise<string> {
    const value = await this.runJson([
      "gh",
      "repo",
      "view",
      `${repository.owner}/${repository.repo}`,
      "--json",
      "defaultBranchRef",
    ]);
    return string(
      at(value, ["defaultBranchRef", "name"]),
      "defaultBranchRef.name"
    );
  }
  async checksFastPath(context: T.PrContext): Promise<T.ChecksFastPath> {
    const result = await this.run([
      "gh",
      "pr",
      "checks",
      String(context.number),
      "--repo",
      `${context.owner}/${context.repo}`,
      "--json",
      "name,state,description,link,workflow,bucket",
    ]);
    if ([0, 1, 8].includes(result.code) && result.stdout.trim()) {
      try {
        const value = parseJson(result.stdout, "gh pr checks");
        if (Array.isArray(value))
          return { kind: "checks", checks: value.map(parseFastCheck) };
      } catch (error) {
        if (!(error instanceof WatcherQueryError)) throw error;
      }
    }
    // Only this stderr line means gh read the head commit and found no checks.
    // Any other exit 1 is a failed query.
    if (
      result.code === 1 &&
      firstLine(result.stderr).startsWith("no checks reported on the ")
    )
      return { kind: "none-reported" };
    return { kind: "unusable", exitCode: result.code, stderr: result.stderr };
  }
  async checkRollupPage(
    context: T.PrContext,
    after: string | null
  ): Promise<T.RollupPage> {
    const pullRequest = await this.graphql(
      PR_CHECK_ROLLUP_QUERY,
      context,
      after
    );
    const commits = list(
      at(pullRequest, ["commits", "nodes"]),
      "commits.nodes"
    );
    if (commits.length === 0)
      return { kind: "contexts", checks: [], endCursor: null };
    const commit = record(
      at(commits[commits.length - 1], ["commit"]),
      "commit"
    );
    if (commit.statusCheckRollup === null) return { kind: "no-rollup" };
    const contexts = record(
      at(commit, ["statusCheckRollup", "contexts"]),
      "contexts"
    );
    const checks = list(contexts.nodes, "contexts.nodes")
      .map(mapRollupNode)
      .filter((check): check is T.Check => check !== null);
    const page = record(contexts.pageInfo, "contexts.pageInfo");
    if (typeof page.hasNextPage !== "boolean")
      missing("contexts.pageInfo.hasNextPage", page.hasNextPage);
    const cursor = optionalString(
      page.endCursor,
      "contexts.pageInfo.endCursor"
    );
    return {
      kind: "contexts",
      checks,
      endCursor: page.hasNextPage && cursor ? cursor : null,
    };
  }
  async reviewThreadPage(
    context: T.PrContext,
    after: string | null
  ): Promise<T.ReviewThreadPage> {
    const argv = graphqlArgs(REVIEW_THREADS_QUERY, context);
    if (after !== null) argv.push("-f", `after=${after}`);
    return parseReviewThreadPage(await this.runJson(argv));
  }
  async commitRollups(
    context: T.PrContext
  ): Promise<readonly T.CommitRollup[]> {
    const pullRequest = await this.graphql(PR_COMMIT_STATUS_QUERY, context);
    const commits = list(
      at(pullRequest, ["commits", "nodes"]),
      "commits.nodes"
    );
    return commits.map((item, index) => {
      const commit = record(at(item, ["commit"]), `commits[${index}].commit`);
      const rollup = commit.statusCheckRollup;
      return {
        oid: string(commit.oid, `commits[${index}].oid`),
        state:
          rollup === null
            ? null
            : nullableEnum(
                at(rollup, ["state"]),
                ROLLUP_STATES,
                `commits[${index}].statusCheckRollup.state`
              ),
      };
    });
  }
  async unsettledSuites(
    context: T.PrContext,
    head: string,
    checksRead: T.CheckRead["kind"]
  ): Promise<readonly T.Check[]> {
    return unsettledSuiteChecks(
      await this.runJson([
        "gh",
        "api",
        "--paginate",
        "--slurp",
        `repos/${context.owner}/${context.repo}/commits/${head}/check-suites?per_page=100`,
      ]),
      head,
      checksRead
    );
  }
}

// A fork workflow awaiting approval has a check suite but no check runs, so no
// check read shows it. An app other than Actions, such as Claude, queues a suite
// on every push and may never run it. Beside reported checks, the check read
// shows each suite's runs and hides a run that a later run replaced, so only a
// suite with no runs that waits for approval or for Actions to start counts.
export function unsettledSuiteChecks(
  pages: unknown,
  head: string,
  checksRead: T.CheckRead["kind"]
): T.Check[] {
  const checks: T.Check[] = [];
  const slurped = list(pages, "check suite pages");
  if (slurped.length === 0) missing("check suite pages", slurped);
  for (const page of slurped) {
    for (const value of list(at(page, ["check_suites"]), "check_suites")) {
      const suite = record(value, "check suite");
      if (string(suite.head_sha, "check suite.head_sha") !== head)
        missing(
          "check suite.head_sha must match the queried head",
          suite.head_sha
        );
      const status = string(suite.status, "check suite.status");
      const conclusion = optionalString(
        suite.conclusion,
        "check suite.conclusion"
      );
      if (
        status === "completed" &&
        ["success", "neutral", "skipped"].includes(conclusion ?? "")
      )
        continue;
      const app = isRecord(suite.app) ? suite.app : {};
      const idleApp =
        status === "queued" &&
        suite.latest_check_runs_count === 0 &&
        typeof app.slug === "string" &&
        app.slug !== "github-actions";
      if (idleApp) continue;
      const unseen =
        suite.latest_check_runs_count === 0 &&
        (conclusion === "action_required" ||
          (status !== "completed" && app.slug === "github-actions"));
      if (checksRead === "reported" && !unseen) continue;
      const details = {
        name: `${typeof app.name === "string" ? app.name : "Unknown app"} check suite`,
        link: "",
        workflow: "",
      };
      if (status !== "completed") {
        checks.push({
          ...details,
          kind: "pending",
          reportedState: status.toUpperCase(),
          description: "has not finished",
        });
        continue;
      }
      if (conclusion === null)
        missing("check suite.conclusion of a completed suite", conclusion);
      checks.push({
        ...details,
        kind: "failed",
        reportedState: conclusion.toUpperCase(),
        description:
          conclusion === "action_required"
            ? "waits for maintainer approval to run; approve the workflows on the pull request"
            : `concluded ${conclusion}`,
      });
    }
  }
  return checks;
}
export async function resolveChecks(
  reader: T.GitHubReader,
  context: T.PrContext
): Promise<T.CheckRead> {
  const fast = await reader.checksFastPath(context);
  const direct = fast.kind === "checks" ? nonEmpty(fast.checks) : null;
  if (direct !== null)
    return { kind: "reported", source: "gh-pr-checks", checks: direct };
  const checks: T.Check[] = [];
  const cursors = new Set<string>();
  let after: string | null = null;
  let headHasRollup = true;
  do {
    const page = await reader.checkRollupPage(context, after);
    if (page.kind === "no-rollup") {
      headHasRollup = false;
      break;
    }
    checks.push(...page.checks);
    after = page.endCursor;
    if (after !== null) advanceCursor(cursors, after, "contexts");
  } while (after !== null);
  const fallback = nonEmpty(checks);
  if (fallback !== null)
    return { kind: "reported", source: "graphql-rollup", checks: fallback };
  // Both reads have to say it. A null rollup beside a failed fast path can be a
  // credential that cannot see checks, and a rollup that exists but maps to no
  // check can hold a context type this reader does not know.
  if (fast.kind === "none-reported" && !headHasRollup)
    return { kind: "no-checks", checks: [] };
  const suffix =
    fast.kind === "unusable"
      ? `fast path exit=${fast.exitCode}; GraphQL rollup was empty${firstLine(fast.stderr) ? `; ${firstLine(fast.stderr)}` : ""}`
      : fast.kind === "none-reported"
        ? "fast path reported no checks; GraphQL rollup exists but listed no readable check"
        : "fast path and GraphQL rollup were empty";
  throw new ChecksUnavailable(`could not read PR checks: ${suffix}`);
}
export async function resolveReviewThreads(
  reader: T.GitHubReader,
  context: T.PrContext
): Promise<readonly T.ReviewThread[]> {
  const threads: T.RawReviewThread[] = [];
  const cursors = new Set<string>();
  let after: string | null = null;
  do {
    const page = await reader.reviewThreadPage(context, after);
    threads.push(...page.threads);
    after = page.endCursor;
    if (after !== null) advanceCursor(cursors, after, "reviewThreads");
  } while (after !== null);
  return buildReviewThreads(threads);
}
export async function resolveContext(args: {
  readonly reader: T.GitHubReader;
  readonly owner: string | null;
  readonly repo: string | null;
  readonly pr: T.PrNumber | null;
}): Promise<T.PrContext> {
  if (args.pr !== null && args.owner !== null && args.repo !== null)
    return { owner: args.owner, repo: args.repo, number: args.pr };
  if (args.pr !== null) {
    const origin = await args.reader.originRepo();
    if (origin !== null)
      return {
        owner: args.owner ?? origin.owner,
        repo: args.repo ?? origin.repo,
        number: args.pr,
      };
  }
  const inferred = await args.reader.currentPr(args.pr);
  if (args.pr === null) {
    // The checkout's PR number means nothing in another repository.
    const found = `${inferred.owner}/${inferred.repo}`;
    const requested = `${args.owner ?? inferred.owner}/${args.repo ?? inferred.repo}`;
    if (requested.toLowerCase() !== found.toLowerCase()) {
      const url = `https://github.com/${found}/pull/${inferred.number}`;
      throw new WatcherQueryError({
        kind: "invalid-context-url",
        retryable: false,
        rawValue: url,
        detail: `the current branch's PR ${url} is not in ${requested}; pass --pr`,
      });
    }
  }
  return {
    owner: args.owner ?? inferred.owner,
    repo: args.repo ?? inferred.repo,
    number: args.pr ?? inferred.number,
  };
}
export function orderStack(
  context: T.PrContext,
  trunk: string,
  everyOpen: readonly T.OpenPullRequest[]
): T.NonEmpty<T.PrContext> {
  const localHead = (pr: T.OpenPullRequest): boolean =>
    pr.headRepository !== null &&
    pr.headRepository.owner.toLowerCase() === context.owner.toLowerCase() &&
    pr.headRepository.repo.toLowerCase() === context.repo.toLowerCase();
  const open = everyOpen.filter(
    (pr) => !(localHead(pr) && pr.headRefName === trunk)
  );
  const byNumber = new Map(open.map((pr) => [pr.number, pr]));
  const byHead = new Map<string, T.OpenPullRequest[]>();
  const invalid = (detail: string): never => {
    throw new WatcherQueryError({
      kind: "invalid-stack",
      retryable: true,
      detail,
    });
  };
  for (const pr of open.filter(localHead)) {
    byHead.set(pr.headRefName, [...(byHead.get(pr.headRefName) ?? []), pr]);
  }
  const parentFor = (branch: string): T.OpenPullRequest | undefined => {
    const candidates = byHead.get(branch) ?? [];
    if (candidates.length > 1)
      invalid(`multiple PRs have the same repository branch: ${branch}`);
    return candidates[0];
  };
  const children = new Map<string, T.OpenPullRequest[]>();
  for (const pr of open)
    children.set(pr.baseRefName, [...(children.get(pr.baseRefName) ?? []), pr]);
  for (const values of children.values())
    values.sort((a, b) => a.number - b.number);
  const start = byNumber.get(context.number);
  if (start === undefined) return [context];
  const down: T.OpenPullRequest[] = [];
  const ancestors = new Set<T.PrNumber>([start.number]);
  let current = start;
  while (byHead.has(current.baseRefName)) {
    const parent = parentFor(current.baseRefName);
    if (parent === undefined) break;
    if (ancestors.has(parent.number))
      invalid(`cycle in PR stack at #${parent.number}`);
    ancestors.add(parent.number);
    down.push(parent);
    current = parent;
  }
  const seen = new Set<T.PrNumber>([
    ...down.map((pr) => pr.number),
    start.number,
  ]);
  const up: T.OpenPullRequest[] = [];
  const visit = (parent: T.OpenPullRequest): void => {
    if (!localHead(parent)) return;
    const descendants = children.get(parent.headRefName) ?? [];
    if (descendants.length > 0) parentFor(parent.headRefName);
    for (const child of descendants) {
      if (seen.has(child.number)) continue;
      seen.add(child.number);
      up.push(child);
      visit(child);
    }
  };
  visit(start);
  return (
    nonEmpty(
      [...down.reverse(), start, ...up].map((pr) => ({
        ...context,
        number: pr.number,
      }))
    ) ?? [context]
  );
}
export async function discoverStack(
  reader: T.GitHubReader,
  context: T.PrContext
): Promise<T.NonEmpty<T.PrContext>> {
  const open = await reader.openPullRequests(context);
  // gh returns the newest PRs with no truncation signal, so a full page may
  // have dropped an older PR from the bottom of the stack.
  if (open.length >= OPEN_PR_LIMIT)
    throw new WatcherQueryError({
      kind: "invalid-stack",
      retryable: true,
      detail: `open PR list reached the ${OPEN_PR_LIMIT}-PR limit, so the stack may be incomplete`,
    });
  return orderStack(context, await reader.defaultBranch(context), open);
}
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall