feat: expose cueapi 0.2.0 fire + executions subgroup commands

[mikemolinet]

Mirrors the cueapi-cli 0.2.0 surface (just published 2026-05-03) in this Action. New command values: fire, executions-list, executions-list-claimable, executions-get, executions-claim, executions-claim-next, executions-heartbeat, executions-report-outcome. New inputs: payload-override, merge-strategy, execution-id, worker-id, task, agent, success, external-id, result-url, summary, offset — all optional, command-specific. Composite step's case block adds one branch per new command. Backwards-compatible: every existing command still works with its existing input shape. README updated with a separate worker-execution-lifecycle command table and the new inputs documented.

[mikemolinet]

@govindkavaturi-art friendly nudge — this PR mirrors the @cueapi/mcp v0.4.0 and cueapi-cli 0.2.0 surface 1:1 (both of which you merged earlier this week). It exposes the new fire + 7 worker-execution-lifecycle subcommands (executions-list, executions-list-claimable, executions-get, executions-claim, executions-claim-next, executions-heartbeat, executions-report-outcome) in action.yml so CueAPI-Desktop / CI users can use them from GitHub Actions without dropping to raw curl.

State: open + mergeable + clean (no conflicts, no failing checks). Just needs your review nod.

Context: this closes the third leg of the ecosystem-parity sprint — CLI and MCP are already shipped; Action was the last lagging surface. A user firing a cue from CI today still has to write raw curl because cueapi/cueapi-action@v1 doesn't know about fire yet.

Filed cueapi-core issue #30 for the GitHub-Action gap-detector that would catch this kind of lag automatically going forward — half-day lift if you want to take it after this PR ships.

[mikemolinet]

Cross-agent review (cueapi-secondary, cueapi engineering)

Looks good to me. Leaving formal approval to Govind/maintainer per the cross-agent self-approval pattern (validated by cue-mac-app on cueapi #592/#593 and by me on cueapi-python #23).

The CLI surface mapping is clean and the README updates are comprehensive. Detailed findings below — one of them is a security issue worth addressing here even though it's pre-existing in the action; this PR adds 16 new instances of the same pattern, which is the natural moment to fix it.

---

CI status

statusCheckRollup is empty on this PR — no CI configured for cueapi-action AFAICT. Worth confirming with Govind whether a smoke workflow is planned (e.g. exercise each command path against a test API key on PR). Not blocking; just noting.

---

Findings

1. Shell injection via ${{ inputs.* }} interpolation — HIGH (security; pre-existing pattern, but this PR adds 16 new instances)

The current action.yml interpolates inputs directly into the bash script:

[ -n "${{ inputs.payload-override }}" ]  && cmd+=(--payload-override "${{ inputs.payload-override }}")
[ -n "${{ inputs.cue-id }}" ]            && cmd+=("${{ inputs.cue-id }}")
[ -n "${{ inputs.summary }}" ]           && cmd+=(--summary "${{ inputs.summary }}")

GitHub Actions documents this as a classic injection vector. A workflow caller passing payload-override: '"; rm -rf /; #' (or any number of variations) will get arbitrary shell execution at the runner.

The pre-existing pattern (lines for name, cron, etc. before this PR) is already vulnerable. This PR adds 16 new instances on the same pattern, so the surface area roughly doubles.

Standard fix: pipe inputs through env vars and reference via $VAR_NAME (bash quotes the env-var expansion automatically):

env:
  PAYLOAD_OVERRIDE: ${{ inputs.payload-override }}
  CUE_ID: ${{ inputs.cue-id }}
  EXECUTION_ID: ${{ inputs.execution-id }}
  WORKER_ID: ${{ inputs.worker-id }}
  TASK: ${{ inputs.task }}
  AGENT: ${{ inputs.agent }}
  EXTERNAL_ID: ${{ inputs.external-id }}
  RESULT_URL: ${{ inputs.result-url }}
  SUMMARY: ${{ inputs.summary }}
  # ... etc for every input
run: |
  set -euo pipefail
  [ -n "$PAYLOAD_OVERRIDE" ] && cmd+=(--payload-override "$PAYLOAD_OVERRIDE")
  [ -n "$CUE_ID" ]           && cmd+=("$CUE_ID")
  # ...

This is the right time to fix the pattern — you're already touching every input. If the maintainer wants to keep this PR scope tight on the new commands, the env-var refactor is a sensible follow-up PR (and worth filing as a Backlog row for security parity).

2. success input requires exact string "true" / "false" — MEDIUM (UX)

if [ "${{ inputs.success }}" = "true" ]; then
  cmd+=(--success)
elif [ "${{ inputs.success }}" = "false" ]; then
  cmd+=(--failure)
fi

If a user passes "True" (Python-style), 1, yes, or accidentally leaves it unset, neither branch fires and the CLI runs without --success or --failure. The CLI then errors (since one is required), but the error message is "missing required option" rather than "invalid success input." Worth either:

• (a) Normalizing case: lower=$(echo "$SUCCESS" | tr A-Z a-z); if [ "$lower" = "true" ] ...
• (b) Failing fast with a clear ::error:: if success isn't "true"/"false" for executions-report-outcome

Lean (b) — explicit input validation is more aligned with the rest of the Action's case-statement style.

3. executions-report-outcome missing --metadata, --result-ref, --artifacts — MEDIUM (parity gap)

The CLI's cueapi executions report-outcome accepts more flags than this Action surfaces:

• --metadata (JSON blob)
• --result-ref (alternative to --result-url)
• --artifacts (JSON list)

Adding metadata, result-ref, artifacts inputs and wiring them in the case branch closes the parity gap. Otherwise CI users using the Action have to fall back to run: cueapi ... directly when they need any of those.

4. No output capture for new commands — LOW (DX)

Looking at the diff, ## Outputs section is untouched. New commands like executions-claim return useful data:

{"claimed": true, "execution_id": "exec_xxx", "lease_seconds": 900}

A workflow that does executions-claim typically wants to chain into subsequent steps using the claimed execution_id and the lease_seconds. Without output declarations like outputs.execution-id / outputs.lease-seconds, callers have to parse stdout themselves (or use tee /dev/stderr | jq shims).

Not blocking — output wiring can be a follow-up. But worth a tracking row in Backlog.

5. worker-id not validated for required commands — LOW (DX)

executions-claim, executions-claim-next, and executions-heartbeat all REQUIRE worker-id per the CLI contract. The Action accepts it as an optional input and only appends it to the command if it's non-empty. If the caller forgets to set worker-id, the CLI errors with "missing required option" — same pattern as the success issue above.

Could fail-fast with a clearer error in the case branch:

executions-claim)
  if [ -z "$WORKER_ID" ]; then
    echo "::error::worker-id is required for executions-claim"
    exit 1
  fi
  ...

Apply consistently to claim / claim-next / heartbeat.

---

What works well

• Help-text discoverability: the README split into "Cue management" and "Worker-execution lifecycle" tables is exactly the right shape — readers can grep for the lifecycle they care about and ignore the other.

• Per-command cmd=(cueapi ...) rewrite: the change from cmd=(cueapi "${{ inputs.command }}") (single setup line) to per-branch cmd=(...) initialization is good. Lets each branch invoke the right CLI subgroup (e.g. cmd=(cueapi executions list) for executions-list). Without this rewrite, the executions subcommands wouldn't work at all.

• Input-name to flag-name mapping is consistent: payload-override → --payload-override, external-id → --external-id, etc. No surprises for readers.

• Comments mark cueapi 0.2.0 boundaries in action.yml: helps future readers understand which inputs come from which CLI version.

• merge-strategy doc note: "merge (default, server-side)" correctly flags that the server has the default, not the CLI/Action. Same pin I shipped in cueapi-cli's tests last week — important for users calling fire --payload-override without --merge-strategy.

---

Summary

Solid mirror of cueapi 0.2.0. One real security finding (#1) that's worth addressing here since this PR's the natural fix point. The other 4 findings are non-blocking parity / DX gaps that can ship as follow-ups.

— cueapi-secondary (CueAPI engineering)

[govindkavaturi-art]

Documents the v0.2.0 fire + executions subgroup commands. README + action.yml only — surface matches cueapi-cli's published 0.2.0 surface. Approve.