[parity-automation] GitHub Action: detect new router endpoints lacking wrapper coverage

[mikemolinet]

Motivation

The CueAPI ecosystem has 4 wrapper repos that all expose the same surface as app/routers/:

• cueapi-cli — Python CLI
• cueapi-python — SDK
• cueapi-mcp — MCP server (@cueapi/mcp)
• cueapi-action — GitHub Action

When a new endpoint lands in cueapi-core/app/routers/*, none of those wrappers expose it until somebody manually opens 4 PRs (one per repo). Recent example: fire_cue + the worker-execution-lifecycle endpoints (/v1/executions/claimable, /claim, /claim-next, /heartbeat, /outcome) shipped in cueapi-core ~2 weeks before any wrapper exposed them. The gap surfaced when a Desktop user couldn't fire a cue from CI without dropping to raw curl.

This issue proposes an automated detector so the gap is visible at PR-review time, not 2 weeks later.

Proposal — GitHub Action: parity-check

Lives in cueapi-core/.github/workflows/parity-check.yml. Runs on every PR touching app/routers/**. Posts a single sticky comment listing wrapper coverage status for any newly-added or modified endpoint.

Detection logic

1. Compute the diff between PR head and base for app/routers/*.py.

2. For each modified file, parse with ast and extract every @router.{get,post,put,delete,patch}(\"<path>\") decorator (path string + HTTP method).

3. Diff the set against the file at base — surface NEW (path, method) pairs.

4. For each NEW pair, look up wrapper coverage:

   • cueapi-cli: grep for the path in cueapi/cli.py (or wherever click commands are defined).
   • cueapi-python: grep for the path in cueapi/client.py SDK methods.
   • cueapi-mcp: grep for the path in src/tools/*.ts MCP tool definitions.
   • cueapi-action: grep for the path in action.yml command enum + per-command case blocks.

5. Render a Markdown table:

   Endpoint	CLI	Python	MCP	Action
   POST /v1/executions/{id}/heartbeat	❌	❌	❌	❌
   GET /v1/agents/{id}/inbox	❌	❌	❌	❌

6. Post (or update — sticky-comment via comment marker) on the PR with the table + a short "file follow-up issues in each wrapper repo" prompt.

Behavior on no new endpoints

If the diff has zero new (path, method) pairs (e.g. PR is a refactor or doc-only change to a router file), action exits 0 silently — no comment.

Behavior on first endpoint added with full coverage

If a new endpoint already has coverage in all 4 wrappers (rare, but possible if wrapper PRs landed first), surface the table with all-✅ + a one-line "already covered — no follow-up needed."

Scope notes

• In scope: detection + comment.
• Out of scope (v1): auto-opening PRs in wrapper repos. That's option (B) in the original PRD; (A) is the right starting point because it surfaces the gap without committing to wrapper-side conventions.
• Out of scope: parity for non-router contracts (response schemas, error codes). v1 only checks endpoint existence by path + method. Schema parity is a separate (harder) check.

Estimated lift

• ~4 hr to write the action + sticky-comment logic.
• ~2 hr to wire it into .github/workflows/ + test on a draft PR.
• ~2 hr to author the README section explaining the table + follow-up convention.
• Total: ~half-day per the original PRD estimate.

Acceptance criteria

• Action runs on every PR touching app/routers/**.
• Action exits 0 + posts no comment when no new endpoints land.
• Action posts a sticky comment listing wrapper coverage for each new (path, method) pair.
• Comment updates in place on subsequent pushes (does not stack new comments).
• False positives < 5% on a manual sample of 10 historical PRs (test via act or via opening the workflow on a draft PR).
• README documents the convention for follow-up issues in wrapper repos.

References

• PRD context: this issue corresponds to option (A) from Mike's ecosystem-parity PRD.
• Related immediate stopgap: option (C), docs-first reminder in cueapi-core CONTRIBUTING.md noting the 4 wrapper repos that need updating when a router changes — could land as a one-line PR before this action ships.