feat: comfy run-template — fetch, fill params, spend-gate, run to completion (BE-4131)

[mattmillerai]

ELI-5

comfy templates could only browse the gallery — you could list templates and fetch their JSON, but actually running one meant a manual fetch → edit → comfy run chain. This PR adds comfy run-template <name>: one command that fetches a gallery template, fills in any inputs you pass with --param KEY=VALUE, and runs it to completion on your local ComfyUI. If the template uses paid partner-API nodes (Flux Pro, Kling, Gemini, …), the command stops and asks for consent first — --allow-spend (or an interactive yes) is required before anything that burns Comfy credits is submitted.

What

• New top-level verb comfy run-template <name> (comfy_cli/command/templates.py, registered in cmdline.py):
  • Resolves <name> against the gallery index (same close-matches affordance as templates fetch), pulls templates/<name>.json.
  • --param KEY=VALUE (repeatable) fills parameterized inputs via the existing CQL slot engine (get_template_schema / apply_slots). KEY is a slot address (6.text, 62/34.text) or a unique slot name (prompt); VALUE is JSON-parsed with string fallback — identical semantics to comfy workflow set-slot. Unknown/ambiguous keys error with the candidate list so agents can self-correct.
  • Spend gate: before anything is submitted, the workflow's node types (including nodes inside UUID subgraph definitions) are checked against object_info (api_node: true / partner/ category — same signals as comfy run's partner detection), belt-and-suspendered with the gallery index's own paid markers (API tag, provider logos). Paid template + no --allow-spend → interactive confirm on a tty, hard error spend_consent_required (new registered error code) otherwise. Nothing is submitted, no credits spent.
  • Hands off to the existing run path (command.run.execute): UI→API conversion, partner-credential injection, preflight validation, execution, jobs state — nothing re-implemented. Runs to completion by default (wait=True); --async submits and returns. --host/--port/--timeout/--verbose/--api-key/--json/--gallery/--refresh mirror the surrounding commands.
• 14 new offline tests (tests/comfy_cli/command/test_run_template.py): resolution failures, param syntax/unknown-key/API-format rejection, the gate in all four postures (gallery-signal block, partner-node block without gallery signals, --allow-spend unblock, interactive decline), OSS pass-through, param filling by address and by name, wait/async handoff, temp-file cleanup.

Judgment calls

• BE-4103's shared spend-gate does not exist yet (no branch, PR, or commit in this repo references it), so there was nothing to "route through." I implemented the gate inline in run-template with a registered error code and the --allow-spend consent flag — the same consent-before-credit contract the BE-4103 ticket describes for comfy generate. When BE-4103 lands a shared helper, this call site is a one-line adoption.
• Gallery-signal calibration was checked against the live index (528 templates): 0 of 224 OSS templates carry provider logos, so the provider signal cannot over-gate OSS runs; openSource: false alone is deliberately NOT a signal (60 local-model workflows like sdxl_simple_example carry it). Exactly one OSS template (utility-gan_upscaler) carries the API tag and would be conservatively gated — cost is one flag, spends nothing.
• Missing-model behavior is deferred to the existing run path: local model gaps surface through comfy run's preflight//prompt validation errors, which the local MCP already maps (local-mcp-nomodel-001); the per-template runnable/missing verdict is feat: comfy templates check — per-template runnable/missing/api-required verdict #557's scope (comfy templates check, in review). The command help points OSS users at comfy model download.
• The completion envelope comes from the run path and is labeled command: "run" — kept as-is rather than threading a label parameter through execute()'s stable contract.
• Residual under-gate window: an API-format paid template + unreachable object_info would skip node detection — but every current gallery template is frontend-format (verified), frontend conversion hard-fails without object_info, and credential injection would also be absent, so no spend can occur silently.

Testing

• pytest tests/comfy_cli — 2550 passed; the only 2 failures (test_validate_command.py::test_api_format_unchanged / test_empty_dict_payload_unchanged) are pre-existing on main (fix is in-flight in test: fix repo-wide pytest failure — reconcile validate-command fixtures with the no-outputs check (BE-4097) #576).
• ruff check + ruff format --check clean on all touched files.
• comfy --json discover verified to surface the new command + error code.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 34 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a987f984-6436-48af-9e47-5b4194c2688d

📥 Commits

Reviewing files that changed from the base of the PR and between 18314a2 and 290c2fa.

📒 Files selected for processing (4)

• comfy_cli/cmdline.py
• comfy_cli/command/templates.py
• comfy_cli/error_codes.py
• tests/comfy_cli/command/test_run_template.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch matt/be-4131-run-template

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch matt/be-4131-run-template

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔍 Cursor Review — Consolidated panel

Triggered by @mattmillerai.

⚠️ Review failed

Judge call failed (status=parse_error): Could not parse JSON findings from output. First 500 chars:
I've verified the key claims against the actual code. Critical findings from my investigation:

- The top-rated panel finding (`providers` vs `logos` mismatch, rated high/critical by Gemini) is a **false positive**: `_flatten_templates` (outside the diff, line 106) remaps `logos[].provider` → a flat `providers` list on every row before it reaches `_gallery_paid_signals`. The reviewers relied on the raw fixture shape without tracing the transform. Dropped.
- The integer-slot-address findings are 

Re-trigger by removing and re-adding the cursor-review label.

[github-actions]

🔍 Cursor Review — Consolidated panel

Triggered by @mattmillerai.

⚠️ Review failed

Judge call failed (status=parse_error): Could not parse JSON findings from output. First 500 chars:
I've verified the findings against the actual code. Key results from my investigation:

- **Confirmed real:** The host parsing (`host.split(":")` + `int(s[1])`) reimplements the shared `comfy_cli/host_port.py` parser, whose docstring explicitly says "callers should not re-implement it." It crashes on bad ports, mangles IPv6, and skips the `frozenset("/@​?#")` validation that `execute` applies — but only *after* the pre-execution probe/object_info fetch. This unifies the host-crash, IPv6, and SSRF

Re-trigger by removing and re-adding the cursor-review label.