diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 84cd09f..39170e8 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -118,7 +118,7 @@ { "name": "wait-for-action", "source": "./", - "description": "Wait for CI, PR checks, a review, or a workflow run in one blocking call. Use before a merge (\"is it ready to merge\", wait for the PR to be green, CI, then the CodeRabbit or PR-Agent review), after a push, merge or workflow dispatch, or when a run failed and you need its log. Replaces any hand-written `gh run watch`, `gh pr checks --watch` or sleep loop.", + "description": "Discover and wait for observable PR activity in one read-only blocking call, including CI and bot reviewers outside Actions. Use after a push or to check what is still running. Reports unknown reviewer activity without requiring or triggering reviews. Also supports targeted checks, reviews, and workflow waits.", "strict": false, "skills": [ "./skills/wait-for-action" diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index ae78c58..d1fb6f5 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -83,7 +83,7 @@ { "name": "wait-for-action", "source": "./skills/wait-for-action", - "description": "Wait for CI, PR checks, a review, or a workflow run in one blocking call. Use before a merge (\"is it ready to merge\", wait for the PR to be green, CI, then the CodeRabbit or PR-Agent review), after a push, merge or workflow dispatch, or when a run failed and you need its log. Replaces any hand-written `gh run watch`, `gh pr checks --watch` or sleep loop.", + "description": "Discover and wait for observable PR activity in one read-only blocking call, including CI and bot reviewers outside Actions. Use after a push or to check what is still running. Reports unknown reviewer activity without requiring or triggering reviews. Also supports targeted checks, reviews, and workflow waits.", "category": "workflow", "homepage": "https://github.com/killallgit/killall-skills", "version": "5.5.0" diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 1753f2b..1ec30e9 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -119,7 +119,7 @@ { "name": "wait-for-action", "source": "./", - "description": "Wait for CI, PR checks, a review, or a workflow run in one blocking call. Use before a merge (\"is it ready to merge\", wait for the PR to be green, CI, then the CodeRabbit or PR-Agent review), after a push, merge or workflow dispatch, or when a run failed and you need its log. Replaces any hand-written `gh run watch`, `gh pr checks --watch` or sleep loop.", + "description": "Discover and wait for observable PR activity in one read-only blocking call, including CI and bot reviewers outside Actions. Use after a push or to check what is still running. Reports unknown reviewer activity without requiring or triggering reviews. Also supports targeted checks, reviews, and workflow waits.", "strict": false, "skills": [ "./skills/wait-for-action" diff --git a/README.md b/README.md index 972e63d..f0be5ed 100644 --- a/README.md +++ b/README.md @@ -119,6 +119,21 @@ explicitly waives review. Self-review and passing tests are not substitutes; a waiver is reported as **WAIVED**, not reviewed. Other skills, such as `ship` and `lets-finish`, run it too. +## Wait for action + +`skills/wait-for-action/scripts/wait-for-action.sh [--pr N]` now defaults to +read-only PR activity discovery: checks, statuses, Actions runs, and bot-review +signals. It never triggers or requires reviews. Exit 0 means no observable work +is pending, not merge approval or a completed independent review. Exit 5 means +no current-head execution/review was observed; newly pushed work may not have +registered yet, even after other fast checks have completed. + +This changes the old bare invocation, which watched one workflow on `HEAD`. +Without a PR, or for post-merge workflows and failure logs, pass `--run-id ID` +(or `--sha COMMIT` for the newest workflow on that commit). Default discovery +requires `gh` 2.48+ and Python 3 or `uv`. Explicit legacy reviewer modes may still +trigger reviews unless `--no-trigger` is supplied. + ## Lets finish `/lets-finish` (or "let's finish", "wrap up", "ship it") lands work that is ready. It runs on a small model, so fixes go to the `builder` agent. Words after the command skip or stop steps: `/lets-finish don't review`, `/lets-finish stop after CI`. `/lets-finish and release` also runs the project's release after the merge: its `release` or `deploy` skill, or the process its docs describe. It never releases unless you say so. A branch with no PR gets one, diff --git a/drafts/prime/SKILL.md b/drafts/prime/SKILL.md new file mode 100644 index 0000000..e69de29 diff --git a/skill-fields.md b/skill-fields.md new file mode 100644 index 0000000..daa7ebf --- /dev/null +++ b/skill-fields.md @@ -0,0 +1,189 @@ +# SKILL.md fields by harness + +YAML frontmatter at the top of `SKILL.md`. The portable set is the [Agent Skills spec](https://agentskills.io/specification). Each harness below either requires a field, accepts it, or leaves it undocumented. + +| Mark | Meaning | +| --- | --- | +| req | Required | +| yes | Accepted and used | +| pass | Accepted; the harness does not act on the value | +| — | Not part of that harness's documented set | + +| Field | Spec | Claude Code | Cursor | Codex | Copilot CLI | +| --- | --- | --- | --- | --- | --- | +| `name` | req | yes | req | req | req | +| `description` | req | yes | req | req | req | +| `license` | yes | pass | — | pass | yes | +| `compatibility` | yes | pass | — | — | — | +| `metadata` | yes | pass | yes | yes | — | +| `allowed-tools` | yes | yes | — | pass | yes | +| `when_to_use` | — | yes | — | — | — | +| `argument-hint` | — | yes | — | — | yes | +| `arguments` | — | yes | — | — | — | +| `disable-model-invocation` | — | yes | yes | — | yes | +| `user-invocable` | — | yes | — | — | yes | +| `disallowed-tools` | — | yes | — | — | — | +| `model` | — | yes | — | — | — | +| `effort` | — | yes | — | — | — | +| `context` | — | yes | — | — | — | +| `agent` | — | yes | — | — | — | +| `background` | — | yes | — | — | — | +| `hooks` | — | yes | — | — | — | +| `paths` | — | yes | yes | — | — | +| `globs` | — | — | yes | — | — | +| `shell` | — | yes | — | — | — | +| `icon` | — | — | yes | — | — | +| `color` | — | — | yes | — | — | + +Codex does not take invocation policy from `SKILL.md`. That lives in `agents/openai.yaml`: + +| Field | Required | Purpose | +| --- | --- | --- | +| `interface.display_name` | no | Name shown in the UI | +| `interface.short_description` | no | Short UI description | +| `interface.default_prompt` | no | Suggested prompt inserted when the skill is invoked | +| `policy.allow_implicit_invocation` | no | `false` keeps the skill from running unless the user invokes it | + +The interface metadata is optional at runtime; a policy-only file is valid. +Plugin-submission checks may impose additional requirements and should be checked +separately from runtime parsing. + +`metadata.short-description` in `SKILL.md` is the one metadata key the Codex parser reads. `allow_implicit_invocation: false` is the Codex counterpart of `disable-model-invocation: true`. + +## Field notes + +**`name`.** Spec: 1–64 characters, lowercase letters, digits, and hyphens, no leading, trailing, or doubled hyphen, and it must match the parent directory. Claude Code treats it as optional and defaults to the directory name. Cursor requires it and expects the same directory match. Codex caps it at 64 characters and requires it to be non-empty; the bundled validator also enforces hyphen-case. Copilot requires it, caps it at 64 characters, and allows letters, numbers, hyphens, underscores, dots, colons, and spaces, as long as it starts with a letter or number. + +**`description`.** Spec: 1–1024 characters, what the skill does and when to use it. Claude Code recommends it and, if it is missing, uses the first non-empty body line. `description` plus `when_to_use` is truncated at 1,536 characters in Claude's skill listing. Codex requires a non-empty description and does not cap its length. + +**`metadata`.** Spec: a map of string keys to string values. Claude Code stores the map and does not act on it. Cursor documents it as an arbitrary key-value map. Codex reads `short-description` from it. + +**`allowed-tools`.** Spec marks this experimental: a space-separated list of tools the skill may use without a prompt. Claude Code also accepts a comma-separated string or a YAML list, and the grant lasts for the turn that invoked the skill. Copilot accepts a comma-separated string or a YAML array of its tool names, or `"*"` for every tool. Pre-approving `shell` or `bash` skips confirmation for terminal commands. The names each harness actually ships are in [Built-in tools](#built-in-tools). + +**`paths`.** Globs that limit automatic activation. Claude Code and Cursor both accept a comma-separated string or a YAML list. Cursor's older name for the same field is `globs`. + +**`disable-model-invocation`.** `true` loads the skill only when the user types `/name`. Default is automatic invocation. Cursor and Copilot use the same field. Codex uses `policy.allow_implicit_invocation` instead. + +**`user-invocable` and `argument-hint`.** Claude Code and Copilot both accept these. `user-invocable: false` hides the skill from the `/` menu (default `true`). `argument-hint` is the autocomplete hint, such as `[issue-number]`. + +**Claude-only behavior fields.** `context: fork` runs the skill in a subagent; `agent` picks the subagent type and `background: false` waits for that subagent in the same turn. `model` and `effort` (`low`, `medium`, `high`, `xhigh`, `max`) apply for the rest of the turn, or to the forked subagent. `disallowed-tools` removes tools while the skill is active. `hooks` registers session hooks when the skill is invoked. `shell` is `bash` or `powershell` for `` !`command` `` injection. `arguments` names positional arguments for `$name` substitution. `when_to_use` is extra discovery text appended to `description`. + +**Cursor presentation.** `icon` and `color` style the badge when the skill is used as a Custom Mode. Colors are `default`, `green`, `cyan`, `blue`, `purple`, `magenta`, `orange`, `yellow`, `red`, and `brand`. + +## What the checkers reject + +The spec defines six fields: + +`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`. + +When Codex's bundled `quick_validate.py` must also pass, use the five-field +intersection: omit `compatibility`. The six-field set does not pass every checker. + +These checkers fail the file when any other key is present: + +- `skills-ref validate` +- claude.ai skill uploads, the Skills API, and `package_skill.py` +- Codex `quick_validate.py`, which allows `name`, `description`, `license`, `allowed-tools`, and `metadata` (it does not list `compatibility`) + +Claude Code ignores a key it does not recognize. The Codex runtime parser reads `name`, `description`, and `metadata.short-description`, and tolerates other keys. Cursor documents the fields in the table above. + +In this repo, `scripts/generate_manifests.py` reads `name` and `description` when it builds the marketplace catalogs. Other frontmatter stays in `SKILL.md` for the host that understands it. + +## Built-in tools + +Tool names belong to one harness. Claude's `Bash` is Cursor's `Shell`, Codex's `exec_command`, and Copilot's `bash`. `allowed-tools` has to use the names from the harness that will run the skill. + +| Job | Claude Code | Cursor | Codex | Copilot CLI | +| --- | --- | --- | --- | --- | +| Read a file | `Read` | `Read` | shell, or `view_image` for images | `view` | +| Find files | `Glob` | `Glob` | shell | `glob` | +| Search contents | `Grep`, `LSP` | `Grep` | shell | `grep` | +| Edit files | `Edit`, `Write`, `NotebookEdit` | `Write` | `apply_patch` | `edit`, `create`, `apply_patch` | +| Run a command | `Bash`, `PowerShell` | `Shell` | `exec_command`, `write_stdin` | `bash`, `powershell` | +| Fetch or search the web | `WebFetch`, `WebSearch` | `WebFetch`, `WebSearch` | `web_search` | `web_fetch` | +| Ask the user | `AskUserQuestion` | documented, no tool id | `request_user_input` | `ask_user` | +| Run a subagent | `Agent` | `Task` | `spawn_agent` | `task` | +| Invoke a skill | `Skill` | — | — | `skill` | + +Cursor's agent overview describes search, web, rules, read, edit, shell, browser, image generation, and questions. The identifiers above are the ones Cursor publishes for hooks and the Agent SDK. The SDK spells them in lowercase (`read`, `grep`, `shell`) and also exposes `edit`, `delete`, `ls`, and `mcp`. Its hook layer maps Claude's `Edit` onto `Write`, and it does not map Claude's `Glob`. + +### Claude Code + +From the [tools reference](https://code.claude.com/docs/en/tools). Permission rules can narrow a tool, as in `Bash(git status *)`, `Read(~/secrets/**)`, or `Skill(deploy *)`. + +| Group | Tools | +| --- | --- | +| Files | `Read`, `Edit`, `Write`, `NotebookEdit`, `Glob`, `Grep`, `LSP` | +| Shell | `Bash`, `PowerShell`, `Monitor` | +| Web | `WebFetch`, `WebSearch` | +| User | `AskUserQuestion`, `PushNotification`, `SendUserFile`, `EndConversation` | +| Plan and tasks | `EnterPlanMode`, `ExitPlanMode`, `TodoWrite`, `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`, `TaskOutput`, `TaskStop` | +| Agents | `Agent`, `SendMessage`, `Workflow`, `CronCreate`, `CronDelete`, `CronList`, `ScheduleWakeup` | +| Worktrees | `EnterWorktree`, `ExitWorktree` | +| Skills | `Skill`, `ToolSearch`, `ReportFindings` | +| MCP | `ListMcpResourcesTool`, `ReadMcpResourceTool`, `WaitForMcpServers` | +| Account | `Artifact`, `RemoteTrigger`, `ShareOnboardingGuide` | + +Prompting depends on permission modes and configured rules, not only the tool. +`Read`, `Grep`, and `Glob` normally do not prompt inside the working directory. +Other tools may require approval, but some read-only `Bash` commands and +preapproved `WebFetch` domains can run without a prompt. Do not rely on a +confirmation always appearing for shell, editing, or web tools. + +### Cursor + +| Where the name is published | Tools | +| --- | --- | +| Hook tool names | `Shell`, `Read`, `Write`, `Grep`, `Task`, `WebFetch`, `WebSearch` | +| Agent SDK allowlist | `shell`, `read`, `edit`, `delete`, `grep`, `glob`, `ls`, `task`, `mcp` | +| SDK opt-in reminders | `reminders_create`, `reminders_list`, `reminders_cancel` | + +The changelog also treats `Glob` as an agent tool. Browser control, image generation, fetching rules, and asking questions are documented as agent abilities, without a tool identifier on the agent overview page. + +### Codex + +`codex-rs/core/src/tools/spec_plan.rs` registers a session's tools. A normal local session gets the core set. The others appear only when their feature flag is on. + +| Group | Tools | +| --- | --- | +| Core | `exec_command`, `write_stdin`, `apply_patch`, `update_plan`, `view_image` | +| MCP | `list_mcp_resources`, `list_mcp_resource_templates`, `read_mcp_resource` | +| User and permissions | `request_user_input`, `request_user_input_async`, `send_message_to_user_async`, `request_permissions` | +| Context | `get_context_remaining`, `new_context`, `wait_for_environment` | +| Agents | `spawn_agent`, `send_message`, `list_agents`, `followup_task`, `interrupt_agent`, `wait_agent` | +| Other, when enabled | `exec`, `wait`, `tool_search`, `web_search`, `create_goal`, `get_goal`, `update_goal`, `list_available_plugins_to_install`, `request_plugin_install`, `multi_env_copy_file` | + +Codex has no dedicated read or grep tool. Text search and file reads go through `exec_command`. `write_stdin` exists when unified exec is on, so a command can stay open and take more input. + +### Copilot CLI + +From the [CLI command reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference). These are the values for `--available-tools` and for a skill's `allowed-tools`. + +| Group | Tools | +| --- | --- | +| Shell | `bash`, `powershell`, `list_bash`, `list_powershell`, `read_bash`, `read_powershell`, `stop_bash`, `stop_powershell`, `write_bash`, `write_powershell` | +| Files | `view`, `create`, `edit`, `apply_patch` | +| Search | `glob`, `grep` | +| Agents | `task`, `list_agents`, `read_agent`, `write_agent` | +| Other | `ask_user`, `skill`, `web_fetch` | + +`grep` also answers to `rg`. Some models use `apply_patch` in place of `edit` and `create`. + +Permission rules use a different vocabulary from those tool names. `--allow-tool` and `--deny-tool` take `kind` or `kind(argument)`: + +| Kind | Matches | +| --- | --- | +| `read` | File or directory reads | +| `write` | Creating or modifying files | +| `shell` | Command execution. `shell(git:*)` matches `git push` and does not match `gitea` | +| `url` | `web_fetch` or shell access to a URL | +| `memory` | Storing facts in Copilot memory | +| `SERVER-NAME` | One MCP server, or `SERVER-NAME(tool)` for one of its tools | + +## Sources + +- [Agent Skills specification](https://agentskills.io/specification) +- [Claude Code skills](https://code.claude.com/docs/en/skills) and [built-in tools](https://code.claude.com/docs/en/tools) +- [Cursor agent skills](https://cursor.com/docs/skills), [agent tools](https://cursor.com/docs/agent/overview), [hook tool names](https://cursor.com/docs/reference/third-party-hooks), and [Agent SDK tools](https://cursor.com/docs/agent-sdk/reference/agent-config) +- [Codex skill parser](https://github.com/openai/codex/blob/main/codex-rs/skills/src/parser.rs), the bundled `skill-creator` validator, and [tool registration](https://github.com/openai/codex/blob/main/codex-rs/core/src/tools/spec_plan.rs) +- [GitHub Copilot CLI: add skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills) and the [command reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference) diff --git a/skills/independent-review/SKILL.md b/skills/independent-review/SKILL.md index da19b5c..7c1972c 100644 --- a/skills/independent-review/SKILL.md +++ b/skills/independent-review/SKILL.md @@ -104,8 +104,18 @@ in a reply. Stop after three rounds and report what is still open. Dispatch one reviewer that starts with **fresh context**: a new subagent, never a fork, and never this session. Where the host has no subagents, a headless -`claude -p` or `codex exec` process serves. Pick the best fit installed: a -`reviewer` agent, else a general-purpose subagent. +`claude -p` or `codex exec` process serves. + +Use the user's previously stated reviewer choice for this project when it is +available; check project instructions and relevant saved project preferences. +Otherwise, pick an available agent explicitly defined for code review. If no +such agent is available and no available project choice exists (including when +a previously stated choice is unavailable), ask the user which agent or process +to use and wait for their answer before dispatching. Do not +silently default to a general-purpose subagent or headless process. If no user +can answer (for example, in a noninteractive workflow), mark independent review +**BLOCKED** and stop the calling workflow. A previous choice applies only to +its stated project and scope, not every project. The brief names the base branch, tells the reviewer to diff `base...HEAD`, and asks for a review only: no edits, no commits, no PR comments. Leave out the PR @@ -122,9 +132,12 @@ responses without either verdict): an independent route that is actually available. A different skill using the same failing provider is not a fallback; do not repeat an unchanged auth or quota failure. -2. Attempt another available route with fresh context and the same neutral - brief. Continue through viable alternatives until one returns a review or - none remain. Never change credentials or install tooling without authority. +2. Apply the reviewer-selection rule above to each fallback: use an available + previously stated project choice or an explicitly defined review agent; + otherwise ask which agent or process to use and wait. Attempt the selected + route with fresh context and the same neutral brief. Continue through viable + alternatives until one returns a review or none remain. Never change + credentials or install tooling without authority. 3. If none works, mark independent review **BLOCKED**, list the failed routes and concrete errors, and stop the calling workflow before merge, release or deployment. Ask the user to restore a review route or explicitly waive diff --git a/skills/wait-for-action/.cursor-plugin/plugin.json b/skills/wait-for-action/.cursor-plugin/plugin.json index d75137f..59fceca 100644 --- a/skills/wait-for-action/.cursor-plugin/plugin.json +++ b/skills/wait-for-action/.cursor-plugin/plugin.json @@ -1,4 +1,4 @@ { "name": "wait-for-action", - "description": "Wait for CI, PR checks, a review, or a workflow run in one blocking call. Use before a merge (\"is it ready to merge\", wait for the PR to be green, CI, then the CodeRabbit or PR-Agent review), after a push, merge or workflow dispatch, or when a run failed and you need its log. Replaces any hand-written `gh run watch`, `gh pr checks --watch` or sleep loop." + "description": "Discover and wait for observable PR activity in one read-only blocking call, including CI and bot reviewers outside Actions. Use after a push or to check what is still running. Reports unknown reviewer activity without requiring or triggering reviews. Also supports targeted checks, reviews, and workflow waits." } diff --git a/skills/wait-for-action/SKILL.md b/skills/wait-for-action/SKILL.md index 6672f19..9570d16 100644 --- a/skills/wait-for-action/SKILL.md +++ b/skills/wait-for-action/SKILL.md @@ -1,19 +1,69 @@ --- name: wait-for-action -description: Wait for CI, PR checks, a review, or a workflow run in one blocking call. Use before a merge ("is it ready to merge", wait for the PR to be green, CI, then the CodeRabbit or PR-Agent review), after a push, merge or workflow dispatch, or when a run failed and you need its log. Replaces any hand-written `gh run watch`, `gh pr checks --watch` or sleep loop. +description: Discover and wait for observable PR activity in one read-only blocking call, including CI and bot reviewers outside Actions. Use after a push or to check what is still running. Reports unknown reviewer activity without requiring or triggering reviews. Also supports targeted checks, reviews, and workflow waits. --- # wait-for-action -One blocking Bash call that polls until a workflow run, every check on a pull -request, or the CodeRabbit or PR-Agent review reaches a terminal state. Costs no -conversation tokens while the wait is in flight, and pulls logs to disk instead -of into context. +Default: one read-only blocking call discovers observable PR activity across +GitHub checks, commit statuses, Actions workflows, submitted bot reviews, review +requests, and bot comments. It never posts comments, requests reviews, or infers +that an installed reviewer is required. Costs no conversation tokens while the +wait is in flight. + +## Default: discover PR activity + +```bash +./scripts/wait-for-action.sh [--pr N] [--repo OWNER/REPO] [--ttl 15m] +``` + +With no explicit wait mode, resolve the current branch's PR (or `--pr`) and: + +- Wait for queued/running checks, commit statuses, and workflows on the PR head. +- Discover external Apps through check runs, not just Actions. Track updates to + existing check IDs as well as new ones; use the newest run/status per source. +- Report current-head bot reviews separately from older-head reviews. A submitted + review is activity evidence, not proof that its findings have been resolved. +- Report bot review requests without acknowledgement as **start unconfirmed**. + Comments, including rate-limit/skip notices, are informational: without a + commit association they cannot prove a current-head review or running work. +- Report skipped/rate-limited CodeRabbit checks without triggering or waiting + for a review that has not started. Observable running work still gets waited on. +- Rediscover if the PR head changes. Require a 10-second stable activity snapshot + before returning. Unknown/unacknowledged reviewers do not extend the wait. + +Exit 0 means **no observable work pending**, NOT merge approval, required-check +satisfaction, or a completed independent review. Exit 5 (`NONE`) means no +current-head execution or submitted bot review was observed after settling; +review requests/comments alone do not prove either. This is not a missing-review +failure. Immediately after a push, work may not have registered yet, even if +other fast checks have already finished. A 10-second quiet period is not a +registration guarantee; enforce required checks/reviews separately. + +Exit 1 means observed CI/check failure; 2 means TTL expired; 3 means persistent +discovery/API failure. Missing API access is never silently treated as success. +Calls are noninteractive and bounded by the remaining TTL. + +Artifacts: `activity.json`, `summary.json`, and `poll.log` under +a unique `/tmp/actions/activity--/` (or `--log-dir`), +printed as `ARTIFACTS` at startup. Failure logs can be +fetched separately with the explicit workflow mode below. Project instructions +and the calling workflow, not discovery, decide which reviews are required. + +**Compatibility change:** bare invocation now requires a resolvable PR instead +of watching the newest workflow on local `HEAD`. For branches without a PR and +post-merge runs, use `--run-id ID` or `--sha COMMIT`. Default discovery does not +fetch job logs; `--tail` only affects explicit checks/workflow modes. + +The following explicit modes retain their specialized behavior for compatibility. +In particular, legacy `--ready`, `--coderabbit`, and `--pr-agent` may trigger +reviews unless `--no-trigger` is supplied. **Do not use those to implement the +default read-only discovery workflow.** ## When to use -- A pull request has to be ready to merge: CI green and, where the repo runs - one, the review done. That wait is `--ready` +- Discover what is running on a PR: no mode flag. Before merging, separately + enforce the project's required checks/reviews; discovery is not that policy - CI on a pull request has to finish before the next step. That wait is `--checks`, which covers every check on the head - Only the CodeRabbit or PR-Agent review matters: `--coderabbit` or `--pr-agent` @@ -28,16 +78,17 @@ the wait to the script. ## How ```bash -./scripts/wait-for-action.sh --ready [--pr N] [--repo OWNER/REPO] [--ttl 15m] +./scripts/wait-for-action.sh [--pr N] [--repo OWNER/REPO] [--ttl 15m] +./scripts/wait-for-action.sh --ready [--pr N] [--repo OWNER/REPO] [--ttl 15m] [--no-trigger] ./scripts/wait-for-action.sh --checks [--pr N] [--repo OWNER/REPO] [--ttl 15m] ./scripts/wait-for-action.sh --run-id [--repo OWNER/REPO] [--ttl 15m] ``` `--ready` waits for CI, then the review. `--checks` waits for the whole PR -rollup. With no `--run-id`, `--checks` or `--ready`, the script resolves the -newest Actions run for the current `HEAD` commit. That is one workflow, right -after a push, and wrong after any later commit — pass the id when you have it. -Confirming CI uses `--checks`; confirming a merge is safe uses `--ready`. +rollup. With no explicit mode (including no `--sha`), the script discovers PR +activity as described above. `--sha COMMIT` alone retains the historical lookup +of the newest Actions run for that commit; use `--run-id` for a specific run. +Neither discovery nor the legacy `--ready` wait replaces merge/review policy. | Flag | Default | Notes | |---|---|---| @@ -45,7 +96,7 @@ Confirming CI uses `--checks`; confirming a merge is safe uses `--ready`. | `--checks` | off | every check on the PR head; see below | | `--pr N` | open PR for the current branch | with `--checks`, `--ready`, `--coderabbit`, `--pr-agent`; the review waits read the PR's head commit from it | | `--sha COMMIT` | `git rev-parse HEAD` | the commit for `--coderabbit`, `--pr-agent`, `--ready` and the no-flag run lookup; see below | -| `--run-id ID` | newest run for `HEAD` | | +| `--run-id ID` | off | explicit single-workflow wait | | `--repo OWNER/REPO` | repo in cwd | with `--run-id`, `--checks` or `--ready` | | `--ttl DURATION` | `15m` | `45s`, `15m`, `1h`; raise it for known-slow pipelines | | `--tail N` | `40` | log lines echoed on failure | @@ -54,7 +105,7 @@ Confirming CI uses `--checks`; confirming a merge is safe uses `--ready`. | `--quiet` | off | only the terminal line and any failure log | | `--coderabbit` | off | wait for the CodeRabbit review of `HEAD` instead; see below | | `--pr-agent` | off | wait for the PR-Agent review of `HEAD` instead; see below | -| `--no-trigger` | off | with `--coderabbit`, `--pr-agent` or `--ready`: report instead of commenting | +| `--no-trigger` | off | legacy `--coderabbit`, `--pr-agent` or `--ready`: report instead of commenting; default discovery never triggers | Getting a run id: `gh run list --limit 5 --json databaseId,workflowName,status`, or `--json databaseId --jq '.[0].databaseId'` right after triggering. @@ -303,7 +354,7 @@ Monitor pattern: ^\[t=\d+s\] (DONE|FAILED|TIMEOUT|ERROR|NOT_REVIEWED|NONE) ## Notes -- Requires `gh` (authenticated) and `jq`. `--ready`, `--coderabbit` and `--pr-agent` also need `uv` or `python3`. +- Default discovery requires authenticated `gh` **2.48+** (`gh api --slurp`) and `python3` or `uv`. Legacy checks/workflow waits also require `jq`. - A run created seconds ago can 404 until GitHub catches up; the script retries through that for the first minute before giving up with exit 3. - Each poll is one API call, plus one per job at the moment it completes. diff --git a/skills/wait-for-action/scripts/pr_activity.py b/skills/wait-for-action/scripts/pr_activity.py new file mode 100644 index 0000000..9f9d434 --- /dev/null +++ b/skills/wait-for-action/scripts/pr_activity.py @@ -0,0 +1,256 @@ +#!/usr/bin/env python3 +"""Read-only discovery of observable PR activity. Never requests a review.""" +from __future__ import annotations + +import argparse +import json +import os +import subprocess +import tempfile +import time +from pathlib import Path + +from coderabbit import GhError, classify, interval_for + +GOOD = {"success", "neutral", "skipped"} + + +def identity(login): + return (login or "").lower().removesuffix("[bot]") + + +def bot(login): + """Known bot identities plus GitHub's general bot suffix.""" + login = login or "" + return login.endswith("[bot]") or login.lower() in {"coderabbitai", "copilot", "copilot-pull-request-reviewer", "github-copilot"} + + +class Client: + def __init__(self, repo=None): + self.repo = repo + self.deadline = 0 + + def gh(self, *args): + remaining = self.deadline - time.monotonic() + if remaining <= 0: + raise TimeoutError + env = dict(os.environ, GH_PROMPT_DISABLED="1") + if self.repo: + env["GH_REPO"] = self.repo + try: + result = subprocess.run(["gh", *args], capture_output=True, text=True, + timeout=min(30, remaining), env=env) + except subprocess.TimeoutExpired as err: + if time.monotonic() >= self.deadline: + raise TimeoutError from err + raise GhError("GitHub request timed out") from err + if result.returncode: + raise GhError(result.stderr.strip() or "GitHub request failed") + return json.loads(result.stdout) + + def pages(self, endpoint): + # gh pagination handles check/status/comment collections beyond page one. + return self.gh("api", "--paginate", "--slurp", endpoint) + + def snapshot(self, pr): + head = self.gh("pr", "view", *([str(pr)] if pr else []), "--json", + "number,url,headRefOid,reviewRequests") + sha, number = head["headRefOid"], head["number"] + root = "repos/{owner}/{repo}" + checks = [c for page in self.pages(f"{root}/commits/{sha}/check-runs?per_page=100") for c in page["check_runs"]] + statuses = [s for page in self.pages(f"{root}/commits/{sha}/statuses?per_page=100") for s in page] + workflows = [r for page in self.pages(f"{root}/actions/runs?head_sha={sha}&per_page=100") for r in page["workflow_runs"]] + reviews = [r for page in self.pages(f"{root}/pulls/{number}/reviews?per_page=100") for r in page] + comments = [c for page in self.pages(f"{root}/issues/{number}/comments?per_page=100") for c in page] + # Re-read to reject snapshots straddling a push. + latest = self.gh("pr", "view", str(number), "--json", "headRefOid") + if latest["headRefOid"] != sha: + return None + return dict(head=head, checks=checks, statuses=statuses, workflows=workflows, + reviews=reviews, comments=comments) + + +def latest_by(rows, key): + result = {} + for row in rows: + k = key(row) + if k not in result or row.get("id", 0) > result[k].get("id", 0): + result[k] = row + return list(result.values()) + + +def summarize(snapshot): + head = snapshot["head"] + pending, failed, observations = [], [], [] + workflows = snapshot["workflows"] + workflow_key = lambda r: (r.get("workflow_id"), r.get("event")) + newest_workflows = {workflow_key(r): r for r in latest_by(workflows, workflow_key)} + # A completed old run's checks must not fail a replacement run before its + # own checks register. Suppress only when suite metadata proves the link. + superseded_suites = { + r["check_suite_id"] for r in workflows + if r["status"] == "completed" and r.get("check_suite_id") is not None + and r["id"] != newest_workflows[workflow_key(r)]["id"] + } + # Job names are not unique across workflows/apps. Only supersede checks + # within one suite; missing suite metadata must not hide a distinct check. + checks = latest_by(snapshot["checks"], lambda c: ( + (c.get("app") or {}).get("id"), + (c.get("check_suite") or {}).get("id", ("check", c["id"])), c["name"])) + for c in checks: + if c["status"] == "completed" and (c.get("check_suite") or {}).get("id") in superseded_suites: + continue + name = c["name"] + if name == "CodeRabbit": + verdict = classify(c, None) + if verdict.kind in {"SKIPPED", "RATE_LIMITED"}: + observations.append(f"CodeRabbit: {verdict.kind.lower()} ({verdict.detail})") + continue + if c["status"] != "completed": + pending.append(f"{name}: {c['status']}") + elif c.get("conclusion") not in GOOD: + failed.append(f"{name}: {c.get('conclusion') or 'unknown conclusion'}") + else: + observations.append(f"{name}: {c['conclusion']}") + for s in latest_by(snapshot["statuses"], lambda s: s["context"]): + if s["context"] == "CodeRabbit": + verdict = classify(None, s) + if verdict.kind in {"SKIPPED", "RATE_LIMITED"}: + observations.append(f"CodeRabbit: {verdict.kind.lower()} ({verdict.detail})") + continue + if s["state"] == "pending": + pending.append(f"{s['context']}: pending") + elif s["state"] != "success": + failed.append(f"{s['context']}: {s['state']}") + else: + observations.append(f"{s['context']}: success") + # Workflows may be queued before their first job/check exists. Retain every + # incomplete run, even when a newer run has finished. Only completed results + # can be superseded by a newer run of the same workflow/event. + for r in workflows: + if r["status"] == "completed" and r["id"] != newest_workflows[workflow_key(r)]["id"]: + continue + if r["status"] != "completed": + pending.append(f"workflow {r['name']}: {r['status']}") + elif r.get("conclusion") not in GOOD: + failed.append(f"workflow {r['name']}: {r.get('conclusion') or 'unknown conclusion'}") + else: + observations.append(f"workflow {r['name']}: {r['conclusion']}") + reviews = [r for r in snapshot["reviews"] if bot((r.get("user") or {}).get("login"))] + current = {r["user"]["login"] for r in reviews if r.get("commit_id") == head["headRefOid"] and r.get("submitted_at")} + current_identities = {identity(login) for login in current} + for login in sorted(current): + observations.append(f"{login}: review submitted for current head (not a findings verdict)") + for login in sorted({r["user"]["login"] for r in reviews if identity(r["user"]["login"]) not in current_identities}): + observations.append(f"{login}: older-head review only; current activity unknown") + for request in head.get("reviewRequests", []): + login = request.get("login", "") + if bot(login) and identity(login) not in current_identities: + observations.append(f"{login}: requested, start unconfirmed") + # A comment alone cannot establish which commit was reviewed, nor prove a + # reviewer is still running. Keep only each bot's latest informational signal. + for c in latest_by(snapshot["comments"], lambda c: (c.get("user") or {}).get("login")): + login = (c.get("user") or {}).get("login") + if not bot(login) or identity(login) in current_identities: + continue + body = c.get("body", "").lower() + if "rate limit" in body: + state = "rate-limit notice" + elif "skip" in body or "paused" in body: + state = "skip/pause notice" + else: + state = "comment observed" + observations.append(f"{login}: {state}; current-head activity unconfirmed") + return dict(head=head["headRefOid"], url=head["url"], pending=sorted(set(pending)), + observed=bool(checks or snapshot["statuses"] or snapshot["workflows"] or current), + failed=sorted(set(failed)), observations=sorted(set(observations))) + + +def watch(client, pr, ttl, log_dir, quiet=False, fail_fast=True, clock=time, settle=10, interval=None): + start = clock.monotonic() + client.deadline = start + ttl + log_dir = Path(log_dir) + log_dir.mkdir(parents=True, exist_ok=True) + (log_dir / "poll.log").write_text("") + last = None + stable_at = start + errors = 0 + report = None + + def emit(kind, text): + line = f"[t={int(clock.monotonic() - start)}s] {kind} {text}" + with (log_dir / "poll.log").open("a") as f: + f.write(line + "\n") + if not quiet or kind != "PENDING": + print(line, flush=True) + + emit("ARTIFACTS", str(log_dir)) + while clock.monotonic() < client.deadline: + try: + snapshot = client.snapshot(pr) + if snapshot is None: + last = None + stable_at = clock.monotonic() + emit("PENDING", "PR head changed; rediscovering") + else: + report = summarize(snapshot) + (log_dir / "activity.json").write_text(json.dumps(snapshot, indent=2) + "\n") + (log_dir / "summary.json").write_text(json.dumps(report, indent=2) + "\n") + errors = 0 + key = json.dumps(report, sort_keys=True) + if key != last: + last, stable_at = key, clock.monotonic() + emit("PENDING", "; ".join(report["pending"] + report["failed"] + report["observations"]) or "no observable activity") + if report["failed"] and (fail_fast or not report["pending"]): + emit("FAILED", "; ".join(report["failed"])) + return 1 + if not report["pending"] and clock.monotonic() - stable_at >= settle: + # Unknown/unacknowledged reviewers are reported, never promoted + # to running work or to a successful independent review. + for observation in report["observations"]: + emit("OBSERVED", observation) + if not report["observed"]: + emit("NONE", f"no current-head execution or submitted bot review observed; work may not have registered yet {report['url']}") + return 5 + emit("NOTE", "Late-registering work may still appear; enforce required checks/reviews separately") + emit("DONE", f"no observable work pending; not a merge/review approval {report['url']}") + return 0 + except TimeoutError: + break + except (GhError, ValueError, KeyError, TypeError, OSError) as err: + errors += 1 + last = None + stable_at = clock.monotonic() + emit("PENDING", f"discovery error: {err}") + if errors >= 3: + emit("ERROR", f"discovery failed: {err}") + return 3 + remaining = client.deadline - clock.monotonic() + if remaining > 0: + nap = interval if interval is not None else ( + interval_for(int(clock.monotonic() - start)) if report and report["pending"] else 5) + clock.sleep(min(nap, remaining)) + emit("TIMEOUT", f"activity not settled within {ttl}s; see {log_dir}") + return 2 + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--pr") + parser.add_argument("--repo") + parser.add_argument("--ttl", type=int, default=900) + parser.add_argument("--log-dir") + parser.add_argument("--quiet", action="store_true") + parser.add_argument("--no-fail-fast", action="store_true") + args = parser.parse_args() + if args.ttl <= 0: + parser.error("--ttl must be positive") + log_dir = args.log_dir + if not log_dir: + Path("/tmp/actions").mkdir(parents=True, exist_ok=True) + log_dir = tempfile.mkdtemp(prefix=f"activity-{args.pr or 'current'}-", dir="/tmp/actions") + return watch(Client(args.repo), args.pr, args.ttl, log_dir, args.quiet, not args.no_fail_fast) + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/skills/wait-for-action/scripts/wait-for-action.sh b/skills/wait-for-action/scripts/wait-for-action.sh index 7c9efaf..dde6b7a 100755 --- a/skills/wait-for-action/scripts/wait-for-action.sh +++ b/skills/wait-for-action/scripts/wait-for-action.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Block until a GitHub Actions run reaches a terminal state, then report. +# Discover PR activity read-only by default; explicit modes target individual waits. # # One blocking call. While the run is healthy this prints a line per state # change and nothing else; logs never reach the caller unless the run fails. @@ -10,7 +10,8 @@ # wait-for-action.sh --checks [--pr N] # every check on the PR, any source # wait-for-action.sh --ready [--pr N] # --checks, then the review the repo runs # wait-for-action.sh --run-id [options] -# wait-for-action.sh # newest run for the current HEAD +# wait-for-action.sh [--pr N] [--repo O/R] # read-only PR activity discovery +# wait-for-action.sh --sha COMMIT # newest Actions run for that commit # wait-for-action.sh --coderabbit # CodeRabbit review of HEAD instead # wait-for-action.sh --pr-agent # PR-Agent review of HEAD instead # @@ -18,16 +19,16 @@ # --checks wait until every check on the PR head has finished. # That is Actions runs, other check runs, and commit # statuses — anything `gh pr checks` reports. Use this -# to confirm CI. With no flags the script still watches -# only the newest Actions run for HEAD. +# to confirm CI. With no mode flags, discover PR activity +# including bot reviews; never trigger or require a review. # --ready ready to merge: --checks, then, when a "CodeRabbit" check # or a pr-agent check exists, that review of the PR head. # One terminal line and one exit code for both, one --ttl # for both. CodeRabbit wins when both run. Without a # reviewer it is --checks. Review files land in # /review -# --pr N pull request number for --checks, --ready, --coderabbit -# and --pr-agent (default with --checks and --ready: the +# --pr N pull request number for discovery, --checks, --ready, +# --coderabbit and --pr-agent (default: the # open PR for the current branch). The review waits read # the PR's head commit from it # --sha COMMIT commit to watch, for a checkout where `git rev-parse @@ -62,7 +63,8 @@ # 3.5m-5.5m every 60s # 5.5m+ every 3m # -# Exit: 0 success 1 failed 2 ttl expired 3 usage or API error +# Exit: 0 settled (NOT merge/review approval) 1 failed 2 ttl expired +# 3 usage or API error # 4 CodeRabbit did not review (--coderabbit and --ready) # 5 no check ever appeared (--checks and --ready) # (--pr-agent uses 0, 2 and 3 only) @@ -146,10 +148,11 @@ done (( CHECKS == 0 || PR_AGENT == 0 && CODERABBIT == 0 )) || die "--checks does not combine with --coderabbit or --pr-agent" (( READY == 0 || CHECKS == 0 && PR_AGENT == 0 && CODERABBIT == 0 )) || die "--ready already covers --checks, --coderabbit and --pr-agent; use it alone" [[ -z "$RUN_ID" || "$CHECKS" -eq 0 && "$READY" -eq 0 ]] || die "--checks and --ready do not combine with --run-id" -(( CHECKS || READY || CODERABBIT || PR_AGENT )) || [[ -z "$PR" ]] || die "--pr only applies to --checks, --ready, --coderabbit or --pr-agent" +[[ -z "$PR" || -z "$RUN_ID" ]] || die "--pr does not combine with --run-id" [[ -z "$SHA" || "$CHECKS" -eq 0 ]] || die "--sha does not apply to --checks: the PR rollup already follows the PR head" +(( CHECKS || READY || CODERABBIT || PR_AGENT )) || [[ -z "$PR" || -z "$SHA" ]] \ + || die "--pr does not combine with the legacy --sha workflow lookup" command -v gh >/dev/null || die "gh CLI not found" -command -v jq >/dev/null || die "jq not found" REPO_ARG=() [[ -n "$REPO" ]] && REPO_ARG=(--repo "$REPO") @@ -207,6 +210,25 @@ if (( CODERABBIT || PR_AGENT )); then run_review "$script" "$TTL" "$LOG_DIR" fi +# With no explicit wait mode, discover PR activity without triggering anything. +# --sha retains the historical single-workflow lookup for compatibility. +if (( ! CHECKS && ! READY )) && [[ -z "$RUN_ID$SHA" ]]; then + here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd) + args=(--ttl "$TTL") + [[ -n "$PR" ]] && args+=(--pr "$PR") + [[ -n "$REPO" ]] && args+=(--repo "$REPO") + [[ -n "$LOG_DIR" ]] && args+=(--log-dir "$LOG_DIR") + (( QUIET )) && args+=(--quiet) + (( FAIL_FAST )) || args+=(--no-fail-fast) + if command -v uv >/dev/null; then + exec uv run --no-project "$here/pr_activity.py" "${args[@]}" + fi + command -v python3 >/dev/null || die "PR discovery requires python3 or uv" + exec python3 "$here/pr_activity.py" "${args[@]}" +fi + +command -v jq >/dev/null || die "jq not found" + if (( ! CHECKS && ! READY )); then if [[ -z "$RUN_ID" ]]; then [[ -n "$REPO" ]] && die "--repo requires --run-id" diff --git a/tests/test_pr_activity.py b/tests/test_pr_activity.py new file mode 100644 index 0000000..e15f9a3 --- /dev/null +++ b/tests/test_pr_activity.py @@ -0,0 +1,318 @@ +"""Read-only PR discovery; no real GitHub calls or sleeping.""" +import json +import os +from pathlib import Path +import subprocess +from types import SimpleNamespace + +import pytest + +import pr_activity as activity +from test_coderabbit import check + + +class Clock: + def __init__(self): + self.t = 0 + + def monotonic(self): + return self.t + + def sleep(self, seconds): + self.t += seconds + + +def snapshot(checks=(), statuses=(), workflows=(), reviews=(), comments=(), requests=(), head="abc"): + return dict(head=dict(number=7, headRefOid=head, url="https://example.test/pull/7", reviewRequests=list(requests)), + checks=list(checks), statuses=list(statuses), workflows=list(workflows), + reviews=list(reviews), comments=list(comments)) + + +class Client: + def __init__(self, *snapshots): + self.snapshots = snapshots + self.calls = 0 + + def snapshot(self, pr): + value = self.snapshots[min(self.calls, len(self.snapshots) - 1)] + self.calls += 1 + if isinstance(value, Exception): + raise value + return value + + +def run(tmp_path, *snapshots, ttl=40, **kwargs): + clock = Clock() + client = Client(*snapshots) + code = activity.watch(client, 7, ttl, tmp_path, clock=clock, settle=10, interval=5, **kwargs) + return code, clock, (tmp_path / "poll.log").read_text() + + +def test_no_activity_settles_without_inventing_a_requirement(tmp_path): + code, clock, log = run(tmp_path, snapshot()) + assert code == 5 + assert clock.t == 10 + assert "work may not have registered yet" in log + + +def test_queued_workflow_without_checks_is_running(tmp_path): + workflow = dict(id=1, workflow_id=2, name="CI", event="push", status="queued", conclusion=None) + code, _, log = run(tmp_path, snapshot(workflows=[workflow]), ttl=20) + assert code == 2 + assert "workflow CI: queued" in log + + +def test_waits_for_current_check_to_finish(tmp_path): + pending = snapshot(checks=[check(status="in_progress", conclusion=None)]) + code, _, log = run(tmp_path, pending, snapshot(checks=[check()])) + assert code == 0 + assert "CodeRabbit: success" in log + + +def test_updated_same_check_id_is_not_discarded(tmp_path): + skipped = snapshot(checks=[check(conclusion="neutral", title="Review skipped")]) + code, _, log = run(tmp_path, skipped, snapshot(checks=[check()])) + assert code == 0 + assert "CodeRabbit: success" in log + assert "TRIGGERED" not in log + + +@pytest.mark.parametrize("title", ["Review skipped", "Review rate limited", "Review paused"]) +def test_non_running_coderabbit_does_not_burn_ttl(tmp_path, title): + code, clock, log = run(tmp_path, snapshot(checks=[check(conclusion="neutral", title=title)])) + assert code == 0 + assert clock.t == 10 + assert title.lower().split()[-1] in log.lower() + + +def test_copilot_request_without_acknowledgement_is_unconfirmed(tmp_path): + code, clock, log = run(tmp_path, snapshot(requests=[dict(login="copilot-pull-request-reviewer[bot]")])) + assert code == 5 + assert clock.t == 10 + assert "requested, start unconfirmed" in log + + +def test_current_and_old_reviews_are_distinguished(): + reviews = [dict(user=dict(login="coderabbitai[bot]"), commit_id="old", submitted_at="yesterday"), + dict(user=dict(login="copilot-pull-request-reviewer[bot]"), commit_id="abc", submitted_at="today")] + observations = activity.summarize(snapshot(reviews=reviews))["observations"] + assert any("older-head review only" in o for o in observations) + assert any("review submitted for current head" in o for o in observations) + + +def test_review_request_and_submitted_review_normalize_bot_suffix(): + report = activity.summarize(snapshot( + requests=[dict(login="coderabbitai")], + reviews=[dict(user=dict(login="coderabbitai[bot]"), commit_id="abc", submitted_at="today")], + )) + assert not any("start unconfirmed" in o for o in report["observations"]) + assert report["observed"] is True + + +def test_comment_is_not_proof_of_current_head_or_running_activity(tmp_path): + comment = dict(id=1, user=dict(login="coderabbitai[bot]"), body="Review in progress") + code, clock, log = run(tmp_path, snapshot(comments=[comment])) + assert code == 5 + assert clock.t == 10 + assert "current-head activity unconfirmed" in log + + +def test_failure_is_not_hidden_by_pending_work(tmp_path): + code, clock, _ = run(tmp_path, snapshot(checks=[check(conclusion="failure"), check(id=2, name="CI", status="queued")])) + assert code == 1 + assert clock.t == 0 + + +def test_no_fail_fast_waits_for_pending_work(tmp_path): + failed = check(conclusion="failure") + code, clock, _ = run(tmp_path, snapshot(checks=[failed, check(id=2, name="CI", status="queued")]), + snapshot(checks=[failed]), fail_fast=False) + assert code == 1 + assert clock.t == 5 + + +def test_newest_workflow_and_status_supersede_old_failures(): + workflows = [dict(id=1, workflow_id=2, event="push", name="CI", status="completed", conclusion="failure"), + dict(id=2, workflow_id=2, event="push", name="CI", status="completed", conclusion="success")] + statuses = [dict(id=1, context="legacy", state="failure"), dict(id=2, context="legacy", state="success")] + assert activity.summarize(snapshot(workflows=workflows, statuses=statuses))["failed"] == [] + + +def test_completed_old_checks_cannot_fail_a_queued_replacement(tmp_path): + workflows = [ + dict(id=1, workflow_id=2, event="push", name="CI", check_suite_id=10, status="completed", conclusion="failure"), + dict(id=2, workflow_id=2, event="push", name="CI", check_suite_id=20, status="queued", conclusion=None), + ] + old_check = dict(check(conclusion="failure"), check_suite=dict(id=10)) + report = activity.summarize(snapshot(checks=[old_check], workflows=workflows)) + assert report["failed"] == [] + assert report["pending"] == ["workflow CI: queued"] + code, _, _ = run(tmp_path, snapshot(checks=[old_check], workflows=workflows), ttl=20) + assert code == 2 + + +def test_unlinked_check_failure_is_not_assumed_superseded(): + workflows = [dict(id=2, workflow_id=2, event="push", name="CI", status="queued", conclusion=None)] + report = activity.summarize(snapshot(checks=[check(conclusion="failure")], workflows=workflows)) + assert report["failed"] == ["CodeRabbit: failure"] + + +def test_older_incomplete_workflows_remain_observable(tmp_path): + workflows = [ + dict(id=1, workflow_id=2, event="push", name="CI", status="queued", conclusion=None), + dict(id=2, workflow_id=2, event="push", name="CI", status="completed", conclusion="success"), + ] + report = activity.summarize(snapshot(workflows=workflows)) + assert report["pending"] == ["workflow CI: queued"] + code, _, _ = run(tmp_path, snapshot(workflows=workflows), ttl=20) + assert code == 2 + + +def test_changed_head_restarts_settle(tmp_path): + code, clock, log = run(tmp_path, snapshot(), None, snapshot(head="new")) + assert code == 5 + assert clock.t == 20 + assert "PR head changed" in log + assert json.loads((tmp_path / "summary.json").read_text())["head"] == "new" + + +def test_api_errors_are_bounded_and_never_a_pass(tmp_path): + code, clock, log = run(tmp_path, activity.GhError("offline")) + assert code == 3 + assert clock.t == 10 + assert "ERROR discovery failed" in log + + +def test_a_discovery_error_breaks_the_stability_window(tmp_path): + code, clock, _ = run(tmp_path, snapshot(), activity.GhError("offline"), snapshot()) + assert code == 5 + assert clock.t == 20 + + +def test_short_ttl_is_respected(tmp_path): + code, clock, _ = run(tmp_path, snapshot(), ttl=3) + assert code == 2 + assert clock.t == 3 + + +def test_gh_is_read_only_noninteractive_and_deadline_bounded(monkeypatch): + calls = [] + def fake_run(args, **kwargs): + calls.append((args, kwargs)) + return SimpleNamespace(returncode=0, stdout="[]") + monkeypatch.setattr(subprocess, "run", fake_run) + client = activity.Client("owner/repo") + client.deadline = activity.time.monotonic() + 5 + assert client.gh("api", "repos/{owner}/{repo}/statuses") == [] + args, kwargs = calls[0] + assert "POST" not in args + assert kwargs["env"]["GH_REPO"] == "owner/repo" + assert kwargs["env"]["GH_PROMPT_DISABLED"] == "1" + assert 0 < kwargs["timeout"] <= 5 + + +def test_snapshot_fetches_paginated_sources_and_rechecks_head(): + class Fake(activity.Client): + def __init__(self): + self.paths = [] + self.reads = 0 + def gh(self, *args): + self.reads += 1 + return dict(number=7, headRefOid="abc", url="url", reviewRequests=[]) + def pages(self, path): + self.paths.append(path) + if "check-runs" in path: + return [dict(check_runs=[check()]), dict(check_runs=[check(id=2, name="CI")])] + if "actions/runs" in path: + return [dict(workflow_runs=[])] + return [[]] + client = Fake() + result = client.snapshot(7) + assert len(result["checks"]) == 2 + assert client.reads == 2 + assert len(client.paths) == 5 + assert all("per_page=100" in p for p in client.paths) + + +@pytest.mark.parametrize("options", [[], ["--pr", "7", "--repo", "owner/repo"]]) +def test_default_shell_routes_to_read_only_discovery(tmp_path, options): + gh = tmp_path / "gh" + gh.write_text('''#!/usr/bin/env python3 +import json, os, sys +from pathlib import Path +args = sys.argv[1:] +with Path(os.environ["CALLS"]).open("a") as f: + f.write(json.dumps(args) + "\\n") +if args[:2] == ["pr", "view"]: + print(json.dumps(dict(number=7, url="https://example.test/pull/7", headRefOid="abc", reviewRequests=[]))) +elif "check-runs" in args[-1]: + print(json.dumps([dict(check_runs=[dict(id=1, name="CI", status="completed", conclusion="failure")])] )) +elif "actions/runs" in args[-1]: + print(json.dumps([dict(workflow_runs=[])])) +elif args[0] == "api": + print("[[]]") +else: + sys.exit(9) +''') + gh.chmod(0o755) + calls = tmp_path / "calls.jsonl" + script = Path(__file__).resolve().parents[1] / "skills/wait-for-action/scripts/wait-for-action.sh" + result = subprocess.run(["bash", str(script), *options, "--ttl", "10s", "--log-dir", str(tmp_path / "logs")], + env=dict(os.environ, PATH=f"{tmp_path}:{os.environ['PATH']}", CALLS=str(calls)), + capture_output=True, text=True, timeout=15) + assert result.returncode == 1, result.stdout + result.stderr + assert "FAILED CI: failure" in result.stdout + commands = [json.loads(line) for line in calls.read_text().splitlines()] + assert len(commands) == 7 + assert all("POST" not in command and "-X" not in command for command in commands) + assert (tmp_path / "logs/summary.json").exists() + + +@pytest.mark.parametrize("payload", [ + snapshot(checks=[dict(check(), app=None)]), + snapshot(reviews=[dict(user=None, commit_id="abc", submitted_at="today")]), + snapshot(comments=[dict(id=1, user=None, body="old comment")]), +]) +def test_nullable_github_actors_and_apps_do_not_break_discovery(tmp_path, payload): + code, _, log = run(tmp_path, payload) + assert code == (0 if payload["checks"] else 5) + assert "discovery error" not in log + + +def test_same_named_checks_from_different_suites_cannot_hide_failure(): + checks = [dict(check(id=1, name="lint", conclusion="failure"), app=dict(id=10), check_suite=dict(id=20)), + dict(check(id=2, name="lint"), app=dict(id=10), check_suite=dict(id=30))] + assert activity.summarize(snapshot(checks=checks))["failed"] == ["lint: failure"] + + +def test_check_rerun_in_same_suite_supersedes_prior_failure(): + checks = [dict(check(id=1, conclusion="failure"), app=dict(id=10), check_suite=dict(id=20)), + dict(check(id=2), app=dict(id=10), check_suite=dict(id=20))] + assert activity.summarize(snapshot(checks=checks))["failed"] == [] + + +def test_missing_suite_metadata_does_not_hide_distinct_checks(): + checks = [check(id=1, name="lint", conclusion="failure"), check(id=2, name="lint")] + assert activity.summarize(snapshot(checks=checks))["failed"] == ["lint: failure"] + + +def test_completion_warns_about_late_registration(tmp_path): + code, _, log = run(tmp_path, snapshot(checks=[check()])) + assert code == 0 + assert "Late-registering work may still appear" in log + assert "not a merge/review approval" in log + + +def test_legacy_sha_lookup_cannot_silently_ignore_pr(): + script = Path(__file__).resolve().parents[1] / "skills/wait-for-action/scripts/wait-for-action.sh" + result = subprocess.run(["bash", str(script), "--pr", "7", "--sha", "abc"], + capture_output=True, text=True, timeout=10) + assert result.returncode == 3 + assert "--pr does not combine" in result.stderr + + +def test_transport_timeout_at_deadline_is_ttl_not_success(monkeypatch): + client = activity.Client() + client.deadline = activity.time.monotonic() - 1 + with pytest.raises(TimeoutError): + client.gh("api", "unused")