Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,21 @@ with a custom scheme:
- **`build.sh` rejects an unknown command**
The `case` matched `help|*` before the `*` branch, so a mistyped command (`./build.sh relase`) printed the help and exited 0 — a CI step with a typo would pass without building anything — and the `Unknown command` branch could never run. An unknown command now prints `Unknown command: <name>` and the help to stderr and exits 1; `help` and no arguments still print the help and exit 0.

- **`--json` leaves exactly one JSON document on stdout, on every path (closes #16)**
`--json` promised a single parseable document but broke in four places. `confirm()` (`src/utils/fs.rs`) wrote its prompt to stdout, so `baller --json eject` on a terminal printed `Are you sure…? [y/N]` into the stream; `help`, `help <command>` and `version` ignored `--json` and printed text; clap answered `-h`/`--help`/`-V`/`--version` itself in text before baller's flags were read; and every error went to stderr as `[Error]: …`, leaving a consumer an empty stdout. Prompts now go to stderr, and under `--json` `confirm()` asks nothing: it returns the new `BallError::ConfirmationRequired` (carrying the question), so `eject`, `sweep`, `substitute` and `inject` need `--yes` under `--json` and change nothing without it. `execute_command_help` and `execute_command_version` (`src/cli/`) take `GlobalFlags` and print JSON documents: the overview lists `commands`, `injected` and `global_options`, a built-in's detail splits its help lines into `arguments`/`subcommands` rows of `name`/`description` plus `notes` paragraphs, and an injected command's detail carries every `.ball` field. Text help is byte-for-byte unchanged. `BallerCommand::parse_command` now takes the argument list; when clap reports a display request and `--json` is on the command line, the request is re-parsed as `help [<command>]` or `version`, keeping `--config` so injected commands still load. `main` reports a failure under `--json` as `{"command", "error", "code"}` on stdout (`utils::output::error_json`; `code` is the new `BallError::code()`, the variant name), with `command` read off the raw arguments by `cli::parse::scan_args` when clap fails before naming a subcommand (`null` if none). The exception is `referee audit`/`check`/`scan --fail-on`, which print their report and then fail: `print_json` and `referee`'s `deliver` record that a document went out, and `main` then sends the error to stderr as text, so stdout still holds one document. Under `--json` colour is off, so no escape codes reach JSON strings. Smaller fixes on the same paths: `inject --json` now reports `{"command": "inject", "name", "binary"}` instead of text, and `substitute`'s rollback warning moved from a stdout `println!` to `tracing::warn!`. Behaviour changes: prompts are on stderr in text mode too; `baller --json sweep` without `--yes` now fails with `ConfirmationRequired` instead of prompting, and its unreachable `"status": "aborted"` document is gone. New `tests/json_output.rs` drives the real binary and parses stdout as a single document for help, version, display flags, CLI and command errors, every confirmation, the read-only commands, and `--fail-on` against a mock OSV server. Documented in `docs/commands.md` (including a new `version` section), `docs/error-handling.md`, `docs/architecture.md` and `docs/inject.md`.

- **`roster <name> --json` prints only the search document, and hooks and package managers stay off `--json` stdout (closes #40)**
When the name was not on the roster, `execute_roster` (`src/commands/roster.rs`) printed `Searching '<name>' not found locally, searching registries...` with `println!` before `search_remote` printed its JSON, so `baller --json roster <name>` was text followed by a document and failed `jq`. The notice is progress, so it now goes through `tracing::info!`: on stderr, and hidden by `-q` and `--json`. In text mode it moves from stdout to stderr, which only shows when stdout is piped. The same match fell back to a registry search on *any* `get_package` error, so a roster that could not be read was reported as "not installed" and searched for; only `PackageNotFound` falls back now (`local_lookup`), and any other error is returned — the pattern #78 fixed for `is_frozen`. A full audit of baller's own stdout writes found no other print ahead of a `--json` document, but child processes inherit stdout too: a hook script that printed, `sudo apt-get/dnf/pacman install` for a system package, or `cargo install`, wrote into the stream ahead of the JSON. Under `--json` their stdout now goes to stderr through `utils::output::child_stdout()` (`src/core/hooks.rs`, `src/http/system.rs`, `src/http/cargo.rs`); `main` sets the mode once with `set_json_mode`, so `run_hook`'s 23 callers are untouched. Text mode is unchanged: a hook still prints to stdout. Injected commands still pass their output straight through, by design. New tests in `tests/json_output.rs` pin the search document, the notice on stderr and its absence under `-q`, and a hook's output on stderr under `--json` and on stdout without it; each fails when its fix is reverted. Documented in `docs/commands.md`, `docs/hooks.md` and `docs/architecture.md`.

- **`version` under `--quiet` keeps printing, by design (closes #41)**
#41 asked for `baller --json version` to print JSON — done in the `--json` fix above — and for `baller --quiet version` to print nothing. The second half is not adopted: `--quiet` suppresses progress output, and every command still prints its result under it (`-q roster` still prints the table), so a silent `-q version` would be the one command whose result disappears, and would do nothing at all. The `--quiet` row in `docs/commands.md` and the `version` section now say so, and `tests/json_output.rs` pins `-q version` printing `Baller <version>`.

- **`draft` no longer prints a stray `quiet=false` while installing a system package**
Installing a system package printed `System installing via apt... quiet=false` on stderr. Before the tracing migration (#32, `d5bf020`) progress went through a helper, `output::info(quiet, msg)`, that skipped the line when quiet; the migration turned its calls into `tracing::info!(…)`, but one call in `src/commands/draft.rs` kept the `quiet` argument, which tracing reads as a field to print. The argument is gone: the tracer already drops `info` lines under `-q` and `--json`, so the line is still hidden there. The leftover `test_info_is_quiet_safe` in `src/utils/output.rs`, which still exercised `tracing::info!(bool, …)`, is removed with it.

- **Referee's mock OSV server no longer drops a request that arrives late on Windows**
`test_a_cached_verdict_does_not_cover_another_version` and `test_refresh_re_queries_a_cached_identity` failed intermittently on the Windows CI runner with one request counted instead of two. The `MockServer` in `src/security/integration.rs` polls a non-blocking listener, and on Windows an accepted socket inherits that non-blocking mode, which voids `read_request`'s 5-second read timeout: a request still in flight when the connection was accepted read as `WouldBlock` and was dropped unrecorded, so the client saw a closed connection and Referee reported `unverified`. Linux sockets do not inherit the mode, so the bug never showed there. `read_request` now puts the stream back in blocking mode first. The new `test_the_mock_server_waits_for_a_request_that_arrives_late` sends its request 200 ms after connecting; built without the fix it failed 3 of 3 runs on a Windows 11 VM and under Wine, and with it it passed 3 of 3.

---

## [0.2.0] - 2026-10-01
Expand Down
27 changes: 23 additions & 4 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -311,10 +311,29 @@ packages installed as dependencies are marked `user_installed = false`, while
packages explicitly installed via `draft` are marked `user_installed = true`.

### Confirmation Prompts
Destructive commands (`eject`, `sweep`, `substitute`) prompt for confirmation
unless the global `--yes` / `-y` flag is passed. `--yes` is one of the global
flags declared on `BallerCommand` and carried to commands via
`AppContext::flags` (`src/context.rs`).
Destructive commands (`eject`, `sweep`, `substitute`, `inject`) prompt for
confirmation unless the global `--yes` / `-y` flag is passed. `--yes` is one of
the global flags declared on `BallerCommand` and carried to commands via
`AppContext::flags` (`src/context.rs`). `utils::fs::confirm` takes the `--json`
flag too: prompts go to stderr, and under `--json` it returns
`ConfirmationRequired` instead of prompting.

### JSON Output
Under `--json` every run leaves exactly one JSON document on stdout. Commands
print theirs through `utils::output::print_json`, which also records that a
document went out. `main` reports a failure as `utils::output::error_json`
(`command`, `error`, `code`) on stdout, unless a document was already printed
(`referee --fail-on`), in which case the error goes to stderr as text. Errors
raised before clap returns a parsed command still know `--json` and the
subcommand from `cli::parse::scan_args`, which reads the raw arguments; the
same scan rewrites `--json` with `-h`/`--help`/`-V`/`--version`, which clap
would otherwise answer itself in text, into the JSON-aware `help [<command>]`
and `version` subcommands.
Child processes inherit baller's stdout, so hooks (`core::hooks`) and the
package-manager installs (`http::system`, `http::cargo`) take theirs from
`utils::output::child_stdout()`: stderr under `--json`, inherited otherwise.
`main` sets the mode once with `set_json_mode`, the way it sets `colored`'s
override, so the flag is not threaded through every `run_hook` caller.

### Version Comparison
The `update` command uses `parse_version_flexible()` for version comparison,
Expand Down
85 changes: 80 additions & 5 deletions docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ These work on every subcommand and may appear before or after it —

| Flag | Description |
|------|-------------|
| `--yes`, `-y` | Skip confirmation prompts (`eject`, `sweep`, `substitute`) |
| `--quiet`, `-q` | Suppress progress bars and step-by-step output |
| `--yes`, `-y` | Skip confirmation prompts (`eject`, `sweep`, `substitute`, `inject`); required for them under `--json` |
| `--quiet`, `-q` | Suppress progress bars and step-by-step output; a command's result (a table, a report, `version`) is still printed |
| `--verbose`, `-v` | Increase output detail: resolved URLs, source chains and cache paths on stderr. `roster` prints full detail blocks |
| `--json` | Emit machine-readable JSON instead of formatted text; implies quiet |
| `--no-hooks` | Skip every pre/post install, eject and update hook |
Expand All @@ -28,7 +28,21 @@ These work on every subcommand and may appear before or after it —
| `--no-referee` | Skip the Referee security checks (both phases) for this run — see [referee.md](referee.md) |

`--json` prints a single JSON document on stdout and suppresses every other
print, so command output stays parseable.
print, so command output stays parseable. That holds for every path:

- `help`, `help <command>`, `version`, and `-h`/`--help`/`-V`/`--version`
combined with `--json`, print JSON documents (see [help](#help--list-commands-or-describe-one)
and [version](#version--print-the-version)).
- A failure prints `{"command": …, "error": …, "code": …}` on stdout instead of
`[Error]: …` on stderr, and still exits 1 — see
[error-handling.md](error-handling.md#overview).
- Confirmation prompts are never shown: a command that would prompt fails with
a `ConfirmationRequired` error instead, so pass `--yes` to run `eject`,
`sweep`, `substitute` or `inject` under `--json`.
- Programs baller runs on the way — hook scripts, `apt-get`/`dnf`/`pacman`
for system packages, `cargo install` — still run, but their output goes to
stderr instead of stdout. (An injected command's output is its own, and
passes straight through.)

Progress lines and verbose detail are written to **stderr**; stdout carries
only the data a command produces. `-v` raises the detail level, `-q` and
Expand Down Expand Up @@ -235,7 +249,11 @@ Active Roster (2 players):

**With a package name:** Shows detailed info for a locally installed package,
or falls back to searching remote registries. Remote search results include
descriptions when available.
descriptions when available. The `'<name>' not found locally, searching
registries...` notice is progress output: it goes to stderr and is hidden by
`-q` and `--json`, so `--json` prints only the search document. Only a package
that is absent from the roster falls back to the search; if the roster itself
cannot be read, that error is reported instead.

```
$ baller roster ripgrep
Expand Down Expand Up @@ -609,6 +627,9 @@ Done Injected 'my-tool' -> /usr/local/bin/my-tool
Run it with: baller my-tool
```

Under `--json`, `inject` needs `--yes` (its prompts are never shown) and
reports `{"command": "inject", "name": …, "binary": …}` on success.

---

## referee — Audit the Roster for Vulnerabilities
Expand Down Expand Up @@ -696,7 +717,35 @@ error. For an injected command the detail view shows its version, author,
flags, dependencies, root requirement, and the binary it points at.

`baller --help` and `-h` still print clap's own summary (stdout, exit 0) and
point at `baller help` for the injected list.
point at `baller help` for the injected list. Combined with `--json` they are
answered by `help` instead: `baller --json --help` is `baller --json help`, and
`baller --json eject -h` is `baller --json help eject` (a `referee` subcommand's
`-h` describes `referee`).

With `--json` the overview lists `commands` (`name`, `summary`, `usage`),
`injected` (`name`, `description`, `version`) and `global_options` (`name`,
`description`). A built-in's detail carries `topic`, `kind: "builtin"`,
`summary`, `usage`, `arguments` and `subcommands` (each `name`/`description`)
and `notes`; an injected command's carries `kind: "injected"` and every field
of its `.ball` manifest. An unknown name is a JSON error.

```
$ baller --json help eject
{
"command": "help",
"topic": "eject",
"kind": "builtin",
"summary": "Ejects (Uninstalls) a player from your team",
"usage": "baller eject <PACKAGE_NAME>",
"arguments": [
{ "name": "<PACKAGE_NAME>", "description": "Package to uninstall" },
{ "name": "-f, --force", "description": "Eject even when the package is frozen" },
…
],
"subcommands": [],
"notes": ["Frozen packages must be unfrozen before they can be ejected."]
}
```

```
$ baller help roster
Expand All @@ -709,6 +758,19 @@ Usage: baller roster [PACKAGE_NAME]

---

## version — Print the Version

```
baller version
```

Prints `Baller <version>`. `baller -V`/`--version` is clap's own form of the
same request (`baller <version>`). With `--json`, all three print
`{"command": "version", "version": "<version>"}`. `--quiet` does not hide it:
like every command's result, the version is data, not progress.

---

## Confirmation Prompts

Destructive commands (`eject`, `sweep`, `substitute`) prompt for confirmation
Expand All @@ -722,3 +784,16 @@ Ejected myapp
$ baller eject --yes myapp
Ejected myapp
```

The prompt is written to stderr, so it never mixes into output piped from
stdout. Under `--json` nothing is prompted: the command fails with a
`ConfirmationRequired` JSON error and changes nothing, and `--yes` is required.

```
$ baller --json eject myapp
{
"command": "eject",
"error": "confirmation required: Are you sure you want to eject myapp? — pass --yes/-y to proceed under --json",
"code": "ConfirmationRequired"
}
```
29 changes: 29 additions & 0 deletions docs/error-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,25 @@ BALLER uses the `BallError` enum for all error types. Commands propagate errors
via the `?` operator. User-facing errors are printed with `[Error]:` prefix and
the process exits with a non-zero status code.

Under the global `--json` flag the error is instead the run's JSON document, on
stdout, and stderr stays empty:

```json
{
"command": "build",
"error": "manifest not found: /x/baller.toml",
"code": "InvalidConfig"
}
```

`command` is the subcommand that failed — `null` when the command line could
not be parsed far enough to name one — `error` is the same message the text
form prints, and `code` is the `BallError` variant name below, stable for
scripts to branch on. The exit code is still 1. The one exception is a command
that has already printed its document: `baller --json referee … --fail-on`
prints its report and then fails, so the `RefereeAuditFailed` message goes to
stderr as text and stdout keeps the report as its only document.

## Error Types

| Variant | Meaning |
Expand All @@ -28,6 +47,9 @@ the process exits with a non-zero status code.
| `RefereeBlocked` | Referee's advisory gate refused the plan. Carries every package over the block threshold with its advisories and the reason. Raised before the install loop, so nothing was downloaded, linked or recorded |
| `RefereeScanBlocked` | Referee's artifact scan refused a downloaded package. Carries the package, version and every finding. Raised after extraction and before linking; the extract directory and cached archive are both purged (`discarded = false` on `build`'s cargo path, where the user's own compiled binary is deliberately left in place) |
| `RefereeUnavailable` | The advisory service could not be reached. Fatal only under `fail_policy = fail-closed`; the default fail-open path reports the packages as `unverified` and continues |
| `ConfirmationAborted` | The user answered no to a confirmation prompt |
| `ConfirmationRequired` | A destructive command needed confirmation under `--json`, where nothing is ever prompted. Carries the question; pass `--yes` to proceed |
| `PipeRedirected` | A confirmation prompt could not be asked because stdin is not a terminal; pass `--yes` |
| `RefereeAuditFailed` | `baller referee audit`/`check`/`scan --fail-on block\|warn` found an advisory or re-scan finding at or above that level; each package is named with the phase that tripped it. Raised after the report is printed, only to make the exit code non-zero for CI; nothing was changed |

## Database Startup Errors
Expand Down Expand Up @@ -281,6 +303,13 @@ Destructive operations require user confirmation unless `--yes` / `-y` is provid
- **`eject`** — removes a package and its orphaned dependencies
- **`sweep`** — clears cached archives (and, with `--all`, extracted packages)
- **`substitute`** — installs the replacement and removes the old package
- **`inject`** — adds a command that runs an arbitrary binary (three prompts)

The prompt is written to stderr, so stdout only ever carries command output.
With stdin redirected the prompt cannot be answered and the command fails with
`PipeRedirected`; under `--json` nothing is prompted at all and the command
fails with `ConfirmationRequired`, reported as a JSON error. Either way nothing
has been changed, and `--yes` is the way through.

## Orphan Dependency Cleanup

Expand Down
7 changes: 7 additions & 0 deletions docs/hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,13 @@ echo "Installing ripgrep $(echo $BALLER_PACKAGE_VERSION) via baller"
echo "fd $BALLER_PACKAGE_VERSION installed at $BALLER_INSTALL_PATH"
```

## Output

A hook shares baller's terminal: what it prints appears alongside baller's own
output. Under `--json` its stdout is sent to stderr instead, so the script
still runs and its output is still visible, but it never lands in the JSON
document on stdout.

## Environment Variables

All hooks receive the following environment variables:
Expand Down
5 changes: 5 additions & 0 deletions docs/inject.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,11 @@ Final confirmation: inject 'lz4c' from /usr/local/bin/lz4c? [yes/no]
Answering anything other than `yes` or `y` at any prompt **aborts immediately**
without writing anything.

The prompts are written to stderr. `--yes` skips all three. Under `--json` they
are never shown: without `--yes` the injection fails with a
`ConfirmationRequired` JSON error before the `.ball` file is read, and with it
success is reported as `{"command": "inject", "name": …, "binary": …}`.

## Validation Rules

`inject` rejects manifests that:
Expand Down
Loading
Loading