feat(cli): add --output json flag to run command

[Jdubin1417]

Summary

Adds a --output json / -o json flag to the jamjet run CLI command, enabling machine-readable output for scripting and CI pipelines.

Fixes #7

Changes

• Added --output option accepting text (default) or json
• JSON output includes: execution_id, final_state, steps_executed, total_duration_us, events
• Suppresses Rich console formatting when --output json for clean stdout
• Always follows execution to completion in JSON mode (ignores --no-follow)
• Validates input — rejects invalid values with clear error message

Example

# Human-readable (default)
jamjet run workflow.yaml

# Machine-readable JSON
jamjet run --output json workflow.yaml | jq '.final_state.status'

Output Schema

{
  "execution_id": "exec_abc123",
  "final_state": { ... },
  "steps_executed": 5,
  "total_duration_us": 1234567,
  "events": [ ... ]
}

Testing

• CLI flag appears in --help
• Invalid --output values rejected with clear error
• Syntax validation passed
• Code follows existing patterns (Typer, async)

---

Disclosure: This contribution was developed with AI assistance (Claude via OpenClaw).

Summary by CodeRabbit

• New Features
  • Added --output (or -o) CLI option to select output format: text for human-readable (default) or json for machine-readable results
  • JSON output includes execution ID, final state, executed steps count, total duration, and event details

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9a8c9c38-b664-4a57-9caa-9184df2eccef

📥 Commits

Reviewing files that changed from the base of the PR and between fa88c51 and 7a3b691.

📒 Files selected for processing (1)

• sdk/python/jamjet/cli/main.py

---

📝 Walkthrough

Walkthrough

Added --output/-o CLI option to the run() command supporting text (default) or json formats. JSON mode suppresses human-readable output, enforces completion wait, measures wall-clock duration, counts executed steps from events, and outputs a structured JSON object with execution metadata and event logs.

Changes

Cohort / File(s)	Summary
CLI JSON Output Feature sdk/python/jamjet/cli/main.py	Added --output parameter to run() function with text/json validation. Implemented conditional JSON output path that disables rich output and streaming, waits for completion, measures duration via time.monotonic_ns(), counts steps from node_started events via get_events(), and prints formatted JSON containing execution_id, final_state, steps_executed, total_duration_us, and event list.

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as CLI Handler
    participant Executor as Execution Engine
    participant EventAPI as Events API
    participant Output as JSON Output

    User->>CLI: jamjet run --output json
    CLI->>CLI: Validate output format
    CLI->>Executor: Start execution
    Executor->>Executor: Run workflow steps
    Note over Executor: Track wall-clock time
    Executor-->>CLI: Execution completes
    CLI->>EventAPI: get_events(exec_id)
    EventAPI-->>CLI: Return event list
    CLI->>CLI: Count node_started events
    CLI->>CLI: Calculate total_duration_us
    CLI->>Output: Format JSON object
    Output->>User: Print structured JSON

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A flag to speak in JSON's tongue,
No more the chatter, no more the song!
Structured steps and timings true,
Machine-readable paths for me and you.
The CLI hops with logic fine,
JSON output—chef's kiss—divine! 🎩✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat(cli): add --output json flag to run command' clearly and concisely describes the main change: adding a JSON output flag to the CLI run command.
Linked Issues check	✅ Passed	The implementation fully addresses issue #7 requirements: adds --output json flag to run command that outputs JSON with execution_id, final_state, steps_executed, total_duration_us, and events.
Out of Scope Changes check	✅ Passed	All changes in main.py are directly related to implementing the --output json flag for the run command as specified in issue #7; no unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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