Skip to content

feat(local-dev): add --json status output and a non-TTY build heartbeat#6027

Merged
Yicong-Huang merged 1 commit into
apache:mainfrom
Yicong-Huang:feat/local-dev-json
Jun 30, 2026
Merged

feat(local-dev): add --json status output and a non-TTY build heartbeat#6027
Yicong-Huang merged 1 commit into
apache:mainfrom
Yicong-Huang:feat/local-dev-json

Conversation

@Yicong-Huang

Copy link
Copy Markdown
Contributor

What changes were proposed in this PR?

Two small, agent/script-friendly additions to bin/local-dev.sh — no change to the human TTY experience.

1. --json machine-readable status. status --json prints one JSON object on stdout (no colours, no table) and exits 0 iff every service is running, else 1:

{"branch":"...","sha":"...","running":14,"total":14,"services":[
  {"service":"texera-web","port":8080,"type":"jvm","pid":25823,"state":"running"}, ...]}

up and down also accept --json: human progress is routed to stderr (unbuffered) and the final status JSON goes to stdout (via a saved fd), so a caller can up --json >state.json 2>progress.log and parse stdout directly.

2. Non-TTY build heartbeat. In non-TTY mode the spinner can't render in place, so a long silent step (sbt dist, output redirected to a log) used to print one line then go quiet for 25s+ — indistinguishable from "stuck" to a non-interactive caller. tui_spinner now emits … still running (Ns) every TUI_HEARTBEAT_SECS (default 15), polling at 1s so it still returns within ~1s of the job finishing (no trailing latency).

Any related issues, documentation, discussions?

Closes #6026. Usage banner (--help) updated to document --json on status/up/down.

How was this PR tested?

  • bash bin/local-dev/tests/test_local_dev_sh.sh19 passed, 0 failed (added 6: JSON shape/consistency, health-based exit code, unknown-flag negative case, --help coverage, heartbeat regression guard, up/down --json wiring).
  • python -m pytest bin/local-dev/tests/38 passed (no regression).
  • Dogfooded end to end: down --json → stdout pure JSON (running:0, 14 stopped), exit 0; up --json → single-line JSON running:14/14 on stdout, and stderr showed the new heartbeat across a ~60s build (… still running (15s/30s/45s/60s)), 14/14 healthy.
  • Verified stdout/stderr separation: up --json >state.json 2>progress.log yields parseable JSON in state.json.

Was this PR authored or co-authored using generative AI tooling?

Generated-by: Claude Code (Opus 4.8)

@github-actions

Copy link
Copy Markdown
Contributor

Automated Reviewer Suggestions

Based on the git blame history of the changed files, we recommend the following reviewers:

  • No candidates found from git blame history.

@Yicong-Huang Yicong-Huang added this pull request to the merge queue Jun 29, 2026
Merged via the queue into apache:main with commit 3f87773 Jun 30, 2026
20 checks passed
@Yicong-Huang Yicong-Huang deleted the feat/local-dev-json branch June 30, 2026 00:08
Mrudhulraj pushed a commit to Mrudhulraj/texera that referenced this pull request Jun 30, 2026
…at (apache#6027)

### What changes were proposed in this PR?

Two small, agent/script-friendly additions to `bin/local-dev.sh` — no
change to the human TTY experience.

**1. `--json` machine-readable status.** `status --json` prints one JSON
object on stdout (no colours, no table) and exits `0` iff every service
is running, else `1`:

```json
{"branch":"...","sha":"...","running":14,"total":14,"services":[
  {"service":"texera-web","port":8080,"type":"jvm","pid":25823,"state":"running"}, ...]}
```

`up` and `down` also accept `--json`: human progress is routed to
**stderr** (unbuffered) and the final status JSON goes to **stdout**
(via a saved fd), so a caller can `up --json >state.json 2>progress.log`
and parse stdout directly.

**2. Non-TTY build heartbeat.** In non-TTY mode the spinner can't render
in place, so a long silent step (`sbt dist`, output redirected to a log)
used to print one line then go quiet for 25s+ — indistinguishable from
"stuck" to a non-interactive caller. `tui_spinner` now emits `… still
running (Ns)` every `TUI_HEARTBEAT_SECS` (default 15), polling at 1s so
it still returns within ~1s of the job finishing (no trailing latency).

### Any related issues, documentation, discussions?

Closes apache#6026. Usage banner (`--help`) updated to document `--json` on
`status`/`up`/`down`.

### How was this PR tested?

- `bash bin/local-dev/tests/test_local_dev_sh.sh` → **19 passed, 0
failed** (added 6: JSON shape/consistency, health-based exit code,
unknown-flag negative case, `--help` coverage, heartbeat regression
guard, up/down `--json` wiring).
- `python -m pytest bin/local-dev/tests/` → **38 passed** (no
regression).
- Dogfooded end to end: `down --json` → stdout pure JSON (`running:0`,
14 `stopped`), exit 0; `up --json` → single-line JSON `running:14/14` on
stdout, and stderr showed the new heartbeat across a ~60s build (`…
still running (15s/30s/45s/60s)`), 14/14 healthy.
- Verified stdout/stderr separation: `up --json >state.json
2>progress.log` yields parseable JSON in `state.json`.

### Was this PR authored or co-authored using generative AI tooling?

Generated-by: Claude Code (Opus 4.8)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make bin/local-dev.sh agent-friendly: --json status and a non-TTY build heartbeat

2 participants