casey / casey/just

Feature request: `--events-fd <FD>` — machine-readable NDJSON recipe-execution events

Open
#3,370 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
35.8k
Forks
846
Avg merge
27m
Merged PRs (30d)
3

Description

Programs that supervise `just` runs — agent harnesses, TUIs, CI annotators — can't reliably recover which recipe is running, which command produced which bytes, or how each recipe ended from the human-oriented terminal output.

**Proposal:** `just --events-fd ` writes newline-delimited JSON to a caller-supplied file descriptor: a leading `plan` record, then `recipe_start` / `recipe_command` / `output` / `recipe_complete` records carrying dependency structure (`depth`/`parent`), evaluated command text with 1-indexed source lines, captured child output, and per-recipe exit status and duration. Without the flag, behavior is byte-identical to today.

```
$ just --events-fd 3 hello 3>events.ndjson
{"type":"plan","version":1,"recipe_count":2}
{"type":"recipe_start","tp":1,"name":"hello","namepath":"hello","depth":0,"parent":null,"doc":null,"quiet":false}
{"type":"recipe_start","tp":2,"name":"dep","namepath":"dep","depth":1,"parent":1,"doc":null,"quiet":false}
{"type":"recipe_command","tp":2,"command":"echo dep-output","line":5}
{"type":"output","tp":2,"stream":"stdout","format":"utf8","data":"dep-output\n"}
{"type":"recipe_complete","tp":2,"exit_code":0,"signal":null,"duration_ms":1}
...
```

We've implemented this in a fork we maintain, [amarbel-llc/just-us](https://github.com/amarbel-llc/just-us), with:

- a normative wire-format spec: [RFC 0002](https://github.com/amarbel-llc/just-us/blob/master/docs/rfcs/0002-just-events-fd-stream.md)
- a design record with known limitations (buffered output, no PTY, unix-only): [FDR 0001](https://github.com/amarbel-llc/just-us/blob/master/docs/features/0001-events-fd.md)
- a bats conformance suite (`zz-tests_bats/events_fd.bats`)

We know pull requests are disabled (#3227), and this isn't an ask to merge anything — we're happy maintaining the fork. This issue just puts the use case and a worked design on record. The fork is CC0 like upstream, so if you ever want the feature, take or reimplement whatever is useful, in whatever shape you'd actually want it.

In the spirit of #3227's reasoning, full transparency: the implementation and this issue were largely written by a coding agent, supervised by @friedenberg.

---
:clown: Filed by [Clown](https://github.com/amarbel-llc/clown) `0.4.0+cd38c2d` ([build commit](https://github.com/amarbel-llc/clown/commit/cd38c2d6298ea4b271bfa70c6476212c2d35e29e)) on behalf of @friedenberg.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.