From 5cca3a6d12cb6c2d1eba9ce43c6b3379051ee0f6 Mon Sep 17 00:00:00 2001 From: mikemolinet Date: Mon, 4 May 2026 09:39:34 -0700 Subject: [PATCH] chore: seed parity-manifest.json (Layer 2 of parity discipline) First-pass audit of cueapi-cli coverage against the hosted CueAPI API. Mirrors the schema landed in cueapi-python concurrently. CLI command coverage is more comprehensive than the SDK's (23 commands vs 14 SDK methods), but per-command flag drift is real: - ``cueapi create`` and ``cueapi update`` are missing 8 flags shipped in private over recent months: --require-payload-override, --required-keys, --transport, --delivery, --alerts, --catch-up, --verification, --on-success-fire. - ``cueapi executions get`` doesn't display the new ``payload`` field shipped in private PR #589. - ``cueapi executions list`` missing 4 filters: --outcome-state, --result-type, --has-evidence, --triggered-by. - 8 endpoints missing entirely: replay, verification helpers, worker registration, fleet visibility, webhook-secret retrieval, and the whole Phase 12.1.5 messaging primitive surface (agents, messages, inbox). Two PRs from 2026-05-03 (private repo #589 + #590) have explicit Backlog rows pending port to this CLI; both are priority=now once their source PRs merge. Co-Authored-By: Claude Opus 4.7 (1M context) --- parity-manifest.json | 105 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 parity-manifest.json diff --git a/parity-manifest.json b/parity-manifest.json new file mode 100644 index 0000000..c98be1a --- /dev/null +++ b/parity-manifest.json @@ -0,0 +1,105 @@ +{ + "manifest_version": 1, + "description": "Parity tracking for cueapi-cli against the hosted CueAPI API. Enumerates which API surfaces this CLI covers and which it doesn't, so drift becomes visible at audit time. Per the 3-layer parity discipline (PR template + this manifest + Backlog rows for each port).", + "private_source_repo": "https://github.com/cueapi/cueapi", + "private_source_paths": [ + "app/routers/", + "cli/cueapi/cli.py (private mirror)" + ], + "last_full_audit": "2026-05-04", + "cli_version_at_audit": "0.1.x", + "audit_methodology": "Walk every endpoint in private cueapi/app/routers/ and map to a CLI command in cueapi-cli/cueapi/cli.py. Per-command, walk the corresponding private schemas/*.py to verify field-level coverage in the command's --flag set. Drift goes in `endpoints_missing` or `command_drift` keyed by command.", + "audit_cadence": "Monthly full sweep. Per-PR diffs handled via the .github/pull_request_template.md `Parity Impact` section in the private repo.", + + "commands_covered": { + "cueapi login": "POST /v1/auth/device-code + /poll + /submit-email", + "cueapi whoami": "GET /v1/auth/me", + "cueapi logout": "local credentials only — no API call", + "cueapi quickstart": "wraps multiple endpoints for first-time setup", + "cueapi create": "POST /v1/cues", + "cueapi list": "GET /v1/cues", + "cueapi get ": "GET /v1/cues/{id}", + "cueapi pause ": "PATCH /v1/cues/{id} (status=paused)", + "cueapi resume ": "PATCH /v1/cues/{id} (status=active)", + "cueapi delete ": "DELETE /v1/cues/{id}", + "cueapi fire ": "POST /v1/cues/{id}/fire (with --payload-override + --merge-strategy)", + "cueapi update ": "PATCH /v1/cues/{id}", + "cueapi upgrade": "POST /v1/billing/checkout", + "cueapi manage": "POST /v1/billing/portal", + "cueapi usage": "GET /v1/usage", + "cueapi executions list": "GET /v1/executions", + "cueapi executions list-claimable": "GET /v1/executions/claimable", + "cueapi executions get ": "GET /v1/executions/{id}", + "cueapi executions claim ": "POST /v1/executions/{id}/claim", + "cueapi executions claim-next": "POST /v1/executions/claim", + "cueapi executions heartbeat ": "POST /v1/executions/{id}/heartbeat", + "cueapi executions report-outcome ": "POST /v1/executions/{id}/outcome", + "cueapi key regenerate": "POST /v1/auth/key/regenerate" + }, + + "endpoints_missing": { + "POST /v1/executions/{id}/replay": {"blocker": "Replay flow exists server-side; no CLI surface."}, + "POST /v1/executions/{id}/verification-pending": {"blocker": "Verification helper for handlers that produce evidence asynchronously."}, + "POST /v1/executions/{id}/verify": {"blocker": "Manual verification flow; no CLI surface."}, + "POST /v1/worker/heartbeat": {"blocker": "Worker registration; CLI users can register workers via cueapi-worker but not via this CLI directly."}, + "GET /v1/workers": {"blocker": "Fleet visibility — list workers + heartbeat status. Useful for ops."}, + "GET /v1/auth/webhook-secret": {"blocker": "Webhook-secret retrieval for users running their own webhook servers."}, + "POST /v1/auth/webhook-secret/regenerate": {"blocker": "Destructive — re-evaluate."}, + "Messaging primitive (all of /v1/agents, /v1/messages, /v1/agents/{id}/inbox)": { + "blocker": "Phase 12.1.5 messaging primitive on prod but no CLI surface. Would need new command group: `cueapi agents` + `cueapi messages`. Significant new surface." + } + }, + + "command_drift": { + "cueapi create": { + "covered_flags": [ + "--name", "--cron", "--at", "--url / --callback", "--method", + "--timezone", "--payload", "--description", "--worker", + "--on-failure" + ], + "missing_flags": [ + "--require-payload-override (PR #590, enforces payload_override on /fire)", + "--required-keys (PR #590, comma-separated list)", + "--transport (currently inferred from --worker; explicit flag would be cleaner)", + "--delivery (delivery config JSON)", + "--alerts (alert config JSON)", + "--catch-up (run_once_if_missed / skip_missed / replay_all)", + "--verification (verification config JSON)", + "--on-success-fire (cue ID for native chaining, Gap 1)" + ] + }, + "cueapi update": { + "covered_flags": [ + "--name", "--cron", "--at", "--url / --callback", "--method", + "--timezone", "--payload", "--description" + ], + "missing_flags": [ + "--require-payload-override / --no-require-payload-override", + "--required-keys", + "--on-failure", "--delivery", "--alerts", "--catch-up", + "--verification", "--on-success-fire / --clear-on-success-fire", + "--status (active / paused; alternative to pause/resume commands)" + ] + }, + "cueapi executions get": { + "current_display": "execution metadata + outcome + evidence fields", + "missing_display": "payload field (PR #589, just shipped) — should display the effective payload (payload_override OR cue.payload) so users can see what the handler actually saw" + }, + "cueapi executions list": { + "covered_flags": ["--cue-id", "--status", "--limit", "--offset"], + "missing_flags": [ + "--outcome-state (filter by reported_success / verified_success / verification_pending / etc.)", + "--result-type (filter by evidence result_type)", + "--has-evidence (filter to executions with evidence_external_id)", + "--triggered-by (filter manual_fire / scheduled / chain)" + ] + } + }, + + "ported_pr_history": [ + "PR #589 (expose payload on GET /v1/executions): NOT YET PORTED — Backlog row 'Parity port: PR #590 → cueapi-cli' priority=now (the row covers both #589 + #590 since they touch the same surface). CLI needs to display the new payload field on `executions get` output.", + "PR #590 (require_payload_override): NOT YET PORTED — Backlog row priority=now. Adds --require-payload-override + --required-keys to create + update." + ], + + "notes": "First seeded 2026-05-04 as Layer 2 of parity discipline (PR template in cueapi/cueapi#615 + this manifest + Backlog rows). Schema mirrors cueapi-python's manifest. The `endpoints_missing` and `command_drift` sections are deliberately verbose — they are the audit checklist for catching up the CLI to the hosted API." +}