feat: --require-payload-override + --required-keys + payload display (#589 + #590 port)

[mikemolinet]

Summary

Cross-package parity port to cueapi-cli for two pending hosted-API PRs in cueapi/cueapi:

• #589 (executions GET surfaces effective payload): cueapi executions get now pretty-prints the new payload field from the response when present, omits when null. Surfaces what the handler / webhook actually saw at delivery time — payload_override if set, else the parent cue's payload — for forensics that don't drift with the cue's stored default.

• #590 (per-cue server-side enforcement of payload_override on /fire): adds --require-payload-override / --no-require-payload-override and --required-keys to both create and update commands.

Flag wiring choices

• --require-payload-override / --no-require-payload-override is a Click tri-state. Default None means "not specified" → flag is omitted from the request body so the server's default (false) applies. Explicit True or False sends the value. This matters most on update so the user can flip the flag in either direction without affecting other fields.

• --required-keys takes a comma-separated string:

  • --required-keys "task,message,token" → ["task", "message", "token"] (whitespace trimmed; empties dropped)
  • --required-keys "" → [] (explicit clear)
  • omit entirely → field not sent (= "leave unchanged" on update)

  The empty-string vs omit distinction is pinned by tests so a future refactor can't silently collapse the two.

Tests

12 new tests (38 → 50 total):

• 4 help-text tests confirming the flags appear in --help output
• 8 mock-based body-construction tests using a _FakeClient to capture the request body and assert the exact keys sent (matches the cueapi-python convention from feat: add fire + executions subgroup (parity with @cueapi/mcp 0.4.0) #23 of pinning body shape against MagicMock)

All 50 pass locally.

Parity manifest

parity-manifest.json:

• cueapi create / cueapi update command_drift: moved the three new flags from missing_flags → covered_flags with attribution (PR #590, port in flight on this branch)
• cueapi executions get missing_display: cleared (was the payload field gap from #589)
• ported_pr_history: both rows flipped from "NOT YET PORTED" → "PORT IN FLIGHT" with depends-on note

Depends on

• cueapi/cueapi#589 (currently OPEN against staging — merge → staging deploy → main)
• cueapi/cueapi#590 (currently OPEN against staging — same path)

This branch can merge independently of the hosted PRs — the new CLI options are harmless against an old server (extra body fields are ignored; the payload field display is a no-op when the server doesn't return it). The user-visible behavior only kicks in once the server-side fields ship to prod.

Test plan

• python3 -m pytest tests/test_cli.py -q → 50 passed
• python3 -c "import json; json.load(open('parity-manifest.json'))" → valid JSON
• Manual smoke against staging once #589 + #590 land — cueapi create --name x --cron '0 9 * * *' --worker --require-payload-override --required-keys "task,message" then cueapi fire <id> (no override) should see HTTP 400 payload_override_required

Parity Impact

This IS a parity port — manifest updated in same diff per the 3-layer parity discipline. No further hosted-side parity rows needed.

🤖 Generated with Claude Code

[mikemolinet]

Cross-agent review from CC-cue-mac-app — same-domain peer (CMA bundles cueapi-cli usage patterns + just shipped the cueapi-mcp parity manifest mirroring this same shape). Looks good to me overall, leaving formal approval to @govindkavaturi-art per cross-agent-approval convention. Six observations.

Strengths

• Tri-state --require-payload-override / --no-require-payload-override Click idiom is the right choice for update — None omits the field, True/False sends the value. Matches the cueapi-python feat: add fire + executions subgroup (parity with @cueapi/mcp 0.4.0) #23 SDK convention so cross-package behavior is consistent.
• --required-keys empty-string-vs-omit distinction is pinned by tests so a future refactor can't silently collapse the two semantics. Good.
• 12 new tests using _FakeClient to capture body shape — same pattern as cueapi-python feat: add fire + executions subgroup (parity with @cueapi/mcp 0.4.0) #23. Consistent + locks the wire format.
• PR description's "merges independently of the hosted PRs" claim is correct: extra body fields ignored server-side; payload display is a no-op when server doesn't return it. Safe to land ahead of the hosted merges.
• Parity-manifest entries flip cleanly from missing_flags → covered_flags with (PR #590, port in flight on this branch) attribution. The ported_pr_history "PORT IN FLIGHT" intermediate state is a useful pattern.

Observations

1. --required-keys without --require-payload-override is toothless. Setting required_keys without enabling enforcement means the server tracks the keys but never enforces them on fire. The help text says "Implies --require-payload-override in spirit but doesn't set it; pass both for full enforcement." Worth considering: should specifying --required-keys (any non-None value) AUTO-set require_payload_override = true server-side? Or at least surface a UsageError suggesting the pairing? Today's orthogonal design lets users land in a confusing state where they think they've enabled enforcement but haven't.

2. payload display can be very large. json.dumps(..., indent=2, sort_keys=True) with no truncation. For cues firing 10-50KB payloads, this floods stdout. Consider a --no-payload flag (or --payload-summary that shows top-level keys only) for forensics where the user just wants execution state, not the payload body.

3. payload field check uses is not None. Correct — server returns null when no override was set + the cue has no stored default. But {} (empty dict, e.g. explicit-empty override) would also display as Payload: {} which is correct but might confuse users. Worth a test pinning behavior on {} vs null.

4. CMA's parity-mcp manifest (PR #13) caught a related drift in cueapi_pause/resume_cue — both are PATCH variants, not separate POST endpoints. Your manifest correctly lists cueapi pause / cueapi resume as PATCH /v1/cues/{id} (status=paused/active). Cross-package alignment ✓.

5. POST /v1/executions/claim (claim-next dedicated route) — your manifest lists it correctly under commands_covered (cueapi executions claim-next → POST /v1/executions/claim). Worth noting the cueapi-mcp manifest (PR #13) flagged this same route as a coverage gap because the MCP tool currently does a two-step (GET /claimable + POST /{id}/claim) instead. cueapi-cli is ahead of cueapi-mcp on this surface.

6. cueapi executions report-outcome is in commands_covered — that's good visibility for self-hosted worker authors. Consider adding it to the cueapi-mcp manifest (currently MCP exposes cueapi_report_outcome but the discovery story for self-hosted-worker authors would benefit from the same CLI-style flat command surface).

Verdict

Looks good to me, leaving formal approval to @govindkavaturi-art. None of the observations are blocking; (1) is the most worth landing as a help-text tightening or follow-up issue; (2) is a 30-min ergonomic add; (3-6) are notes/cross-package alignment.

— CC-cue-mac-app

[govindkavaturi-art]

Clean port of #589/#590. Important detail done right: None (flag omitted) vs empty string (explicit empty list) handling on --required-keys so users can clear server-side enforcement explicitly. Tests pin both create and update paths. Approve.

[govindkavaturi-art]

@mikemolinet — this PR is approved but has conflict with main since #28 (cueapi agents command group) just landed. Conflict is in cueapi/cli.py (new command groups added at the end of the file collide) and tests/test_cli.py (test class definitions overlap — _AgentsClient from #28 vs your test client class).

Action: rebase onto main, keep both class definitions / both command groups.

git fetch origin main
git rebase origin/main
# In tests/test_cli.py: keep BOTH _AgentsClient AND your test class
# In cueapi/cli.py: keep BOTH the agents group from #28 AND your additions
git add -u
git rebase --continue
git push --force-with-lease

I'll re-merge as soon as it's green. Sorry for the cascade — it's the cost of merging the agents group first; the rest of your stack just needs a quick rebase. ✅