Repository navigation
docs(minimal): T65 — The CLI reference lists every min/v1/error code and its exit code - #3667
Conversation
The CLI reference gets an Errors in JSON output section with the error object's fields and each code with its exit code. A test scans the product source for every code and fails when the reference and the source disagree.
The error code table named min session policy, a removed spelling that the reference check refuses. min box show --network carries the case.
|
Important Review skippedBot user detected. Ask an organization administrator to verify that this bot has an active assigned CodeRabbit review seat. See the seat-assignment guide. After the seat is confirmed, request a review again.
|
|
Reviewed: 1 finding, none blocking at Address the comments on the diff. Clobber: none seen. |
…ference-lists-every-min-v1-error-code # Conflicts: # crates/minimal/src/tests.rs # docs/reference/cli-min.md
A changed exit code in the reference now fails the test, not only the three named codes.
|
Round 1 of 10 on the runtime's review findings, pushed as Resolved conflicts in:
Verify Converted to a draft: verify exited 100. Review threads the coder judged:
docs/reference/cli-min.md has an Notes from the agent: Revise round 1. The runner merged origin/main. I resolved both conflicts by keeping both sides: in cli-min.md the new |
| | `not_found` | 4 | No box matches the box name or id, the box is on a VM that is stopped, or `min type show` names no box type. When `min box show --network -o json` finds no box, the exit code is 1 | | ||
| | `host_unreachable` | 7 | A host that the command must ask does not answer | | ||
| | `insufficient_resources` | 8 | The VM host has no network address left for another box | | ||
| | `github_sign_in_required` | 3 | The box spec needs a GitHub sign-in, and you are not signed in. Run `min auth login` | |
There was a problem hiding this comment.
LOW · correctness · confidence 0.50 · in github_sign_in_required
The row says github_sign_in_required exits 3. ActivationRefused::exit_code returns 5 when any refusal is UnenrolledNode. machine_mode_answer picks the first refusal that has a code. A spec with both problems can give code github_sign_in_required with exit 5. Say so in the row. The test pins 3 and cannot see this case.
What the reviewer checked
bep.rs:926 exit_code: any UnenrolledNode => 5 else 3; main.rs:~517 find_map over refusals for first code
Hand this to an agent
Act on a code-review finding.
File: docs/reference/cli-min.md
Lines: 102-102
Category: correctness
Severity: low (reviewer confidence 0.50)
Finding:
The row says `github_sign_in_required` exits 3. `ActivationRefused::exit_code` returns 5 when any refusal is `UnenrolledNode`. `machine_mode_answer` picks the first refusal that has a code. A spec with both problems can give code `github_sign_in_required` with exit 5. Say so in the row. The test pins 3 and cannot see this case.
First verify this against the code yourself. It is model output and
may be wrong. If it is wrong, or the tradeoff was deliberate, say so
and change nothing.
👍 useful · 👎 noise — react to tell the reviewer. Replying works too, and says more.
There was a problem hiding this comment.
Disputed — not addressed: No path puts both refusals in one ActivationRefused. SignInRequired comes only from require_sign_in, and UnenrolledNode only from unenrolled_node/require_proxy (crates/boxes/src/core/bep.rs:1182-1262). Each of those returns a vec of one refusal. refusals() and store_refusals(), the multi-refusal builders, emit neither kind, and no code extends a refusal list. So github_sign_in_required always exits 3, and the row is correct.
|
Round 2 of 10 on the runtime's review findings: the coder changed nothing. Revise round 2: the one review thread did not hold, so this round adds no commit. The branch head 5d4ca53 is unchanged and its test line passes. Review threads the coder judged:
|
|
/arch-review |
There was a problem hiding this comment.
arch-review: PASS_WITH_CONDITIONS · 2 conditions · the full ruling
The new Errors in JSON output section matches the design's min/v1/error object and the codes the source gives. The test fails both ways, and that proves the rule. The reference documents two gaps against the design, but the PR files no issue for them. One gap is plain-text parse errors under -o json (architecture line 383), and C1 files it. The other gap is min box show --network -o json not-found at exit 1 (line 365), and C2 files it. Link both issues in the PR body.
Ruled at 5d4ca53 against gominimal/arch@8b824707cde6 by claude-opus-5-5.
| | `output_failed` | 1 | The command did not write its JSON output to stdout, for example on a full disk | | ||
| | `unspecified` | 1, or the exit code of the failure | Any other failure. The exit code is the one the command gives without `-o` | | ||
|
|
||
| A command line that `min` cannot parse, such as an unknown flag, exits 2 |
There was a problem hiding this comment.
C1 · This paragraph describes a gap. Architecture line 383 says errors in machine modes are one JSON object on stderr. A parse failure under -o json prints plain text from Cli::try_parse().exit() in main.rs. File an issue for the usage object and link it from the PR body.
There was a problem hiding this comment.
Filed as #3680 and linked from the PR body under Residuals.
There was a problem hiding this comment.
Disputed — not addressed: The action this finding asks for is already done: #3680 tracks the plain-text parse error under -o json, and the PR body links it. The fix is in main.rs parse handling, outside this merge-only round, so this round changes nothing for it.
| | `code` | Exit code | When the command gives it | | ||
| |--------|-----------|---------------------------| | ||
| | `ambiguous` | 2 | A box name or id prefix matches more than one box | | ||
| | `not_found` | 4 | No box matches the box name or id, the box is on a VM that is stopped, or `min type show` names no box type. When `min box show --network -o json` finds no box, the exit code is 1 | |
There was a problem hiding this comment.
C2 · Exit 1 for not_found does not match architecture line 365, which gives 4. PolicyJsonFailure::SessionNotFound becomes a bare MachineModeFailure, and failure_exit_code has no arm for it. File an issue for the fix and link it from the PR body.
There was a problem hiding this comment.
Filed as #3681 and linked from the PR body under Residuals.
There was a problem hiding this comment.
Disputed — not addressed: The action this finding asks for is already done: #3681 tracks the exit 1 for not_found from min box show --network -o json, and the PR body links it. The reference row states the exit 1 as it is today. The code fix is outside this task's layers.
|
/revise Merge main into this branch. The merge queue ejected this PR after #3670 landed, and the merge now conflicts in Run |
…ference-lists-every-min-v1-error-code # Conflicts: # crates/minimal/src/tests.rs
|
Round 3 of 10 on a /revise note, pushed as Resolved conflicts in:
Verify Converted to a draft: verify exited 100. Review threads the coder judged:
docs/reference/cli-min.md lists every min/v1/error code with its exit code, including not_found (4) and host_unreachable (7), and cli_reference_lists_every_error_code still passes after the merge of main. The test fails when the product source gives a code that the reference does not list. Notes from the agent: This round only merged origin/main. The one conflict was in crates/minimal/src/tests.rs. I kept this PR's cli_reference_lists_every_error_code and main's daemon_only_broker_refusal_exits_5, and changed nothing else. The other files in the merge commit come from main as they are. The reference has no |
|
/arch-review |
There was a problem hiding this comment.
arch-review: PASS · the full ruling
The merge from main changes no line of this PR, and it adds no error code that the reference does not list. C1 is met: the PR body links #3680 for the missing usage object on a parse failure. C2 is met: the PR body links #3681 for the exit 1 of min box show --network when no box matches. The reference agrees with architecture.md lines 361–383. BCLI-033 conforms.
Ruled at b46cf2c against gominimal/arch@8b824707cde6 by claude-opus-5-5.
T65 — The CLI reference lists every min/v1/error code and its exit code
slice: S3
kind: task
covers: BCLI-033
size: S
est: 0 code, 40 tests, 80 docs
executor: agent
difficulty: routine
model: standard
diagnostics: none new
observability: none new
layers:
- client:
- docs/reference/cli-min.md: the
min/v1/errorobject, its fields, and everycodewith its exit code and when it is given- crates/minimal/src/tests.rs:
cli_reference_lists_every_error_code- crates/minimal/src/main.rs: one list of the codes, only if the test needs it
test: cargo nextest run -p minimal cli_reference_lists_every_error_code
produces: none
consumes: none
proof:
docs/reference/cli-min.mdlistsusage(2),not_found(4) andhost_unreachable(7) among the others, and the test fails when a code is added in the code but not in the reference.Proof
docs/reference/cli-min.md has a new section, Errors in JSON output. It describes the min/v1/error object and its schema, code, message and hint fields. It lists every code that the source gives, each with its exit code and when it is given: ambiguous (2), not_found (4), host_unreachable (7), insufficient_resources (8), github_sign_in_required (3), gatehouse_unenrolled_node (5), audit_self_unsupported_unenrolled (1), timeout (124), wait_timeout (124), daemon_unreachable (1), policy_unavailable (1), output_failed (1) and unspecified (1, or the exit code of the failure). The reference does not list
usage(2), because no code gives it. A command line that min cannot parse exits 2 with the argument parser's plain-text error, and the reference says so. The test cli_reference_lists_every_error_code fails when the source has a code that the reference does not list. It also fails when the reference lists a code that the source does not give. I checked the first case: I removed the policy_unavailable row, and the test failed.Notes from the agent: The proof is only partly delivered. The proof names
usage(2), but no code path in crates/minimal gives ausagecode. Clap parse errors exit 2 through Cli::try_parse(...).exit() before the output mode is known, so they print text and no object. Listingusagewould document a code that the CLI never prints, so I described the plain-text exit 2 instead. Adding a realusageobject is a code change for a separate task. The code that maps to exit 2 in machine mode isambiguous. main.rs did not change: tests.rs is in the lib target, so it cannot read a list in the bin target. The test scans the product source instead. It reads the literal in each MachineModeFailure::new call, each CODE constant and code: field, and each literal or string constant that a fn code returns. It also reads crates/boxes/src/core/bep.rs for the sign-in and enrollment codes. Facts for a later task: in machine mode, several refusals that ha…[truncated]Tests
cargo nextest run -p minimal cli_reference_lists_every_error_codeVerify
min task run agent-verifyexited 100, so this PR is a draft.Residuals
-o jsongives nomin/v1/errorobject (arch C1).min box show --network -o jsonnot found exits 1, not 4 (arch C2).Closes #3402