8000 T65 — The CLI reference lists every min/v1/error code and its exit code · Issue #3402 · gominimal/minimal · GitHub
[go: up one dir, main page]

Skip to content

T65 — The CLI reference lists every min/v1/error code and its exit code #3402

Closed

Description

@norrietaylor

Task

slice size difficulty model who estimated lines
Docs S routine standard an agent 120 (0 code, 40 tests, 80 docs)

docs/reference/cli-min.md lists every min/v1/error code with its exit code, and a test keeps the list matching the code.

Made a plan task on 2026-11-19 from the docs ask in this issue. In a machine output mode, min writes a min/v1/error object on stderr whose code names the error kind (BCLI-033). Scripts match on that string. docs/reference/cli-min.md has an exit-code table (line 427) but does not list the codes.

What to do:

  • docs/reference/cli-min.md: add a section on the min/v1/error object, next to the exit-code table. Give its fields (schema, code, message, hint), and a table of every code with its exit code and when it is given. State that a code is stable once it is listed here.
  • Find the codes from the code, not from this issue: machine_mode_answer in crates/minimal/src/main.rs, and the code() functions in crates/minimal/src/cli.rs, crates/minimal/src/cmd/box_audit.rs, crates/minimal/src/cmd/boxes/address.rs and crates/minimal/src/cmd/boxes/wait.rs. Include unspecified, and say it is the code for a failure with no kind of its own.
  • crates/minimal/src/tests.rs: add cli_reference_lists_every_error_code. It collects every code the CLI can give and fails when the reference's table is missing one, or lists one that the code never gives. Prefer one list in the code that machine_mode_answer and the test both read over a second hand-kept list in the test.
  • Change no code or exit code. A code with no exit code that matches the architecture's exit-code table goes in Notes for the runner, not into a fix.

Covers:

  • BCLI-033 (the error object's code)

Layers:

  • client:
    • docs/reference/cli-min.md: the min/v1/error section and its code table
    • crates/minimal/src/tests.rs: cli_reference_lists_every_error_code
    • crates/minimal/src/main.rs: only if the test needs one list of the codes to read
    • cargo nextest run -p minimal cli_reference_lists_every_error_code
Original issue

Problem

min in a machine output mode (-o json) prints a min/v1/error object whose code names the error kind. Scripts match on that string. docs/reference/cli-min.md does not list the codes, so a script author cannot tell which codes exist or which exit code each stands for.

#3386 adds the box address refusal codes:

Exit code When
2 usage the address matches more than one box, or an id start is ambiguous
4 not_found the address matches no box
7 host_unreachable the box's host does not answer

usage is new. No other code or document defined a kind for exit 2. The review on #3386 flagged that a later rename would break scripts.

Ask

Document the min/v1/error object in docs/reference/cli-min.md: its fields (code, message, hint), and every code the CLI emits with the exit code it goes with. Include the three above and the ones emitted elsewhere (BoxAddressRefusal::code in crates/minimal/src/cmd/boxes/address.rs, and machine_mode_answer in crates/minimal/src/main.rs). State that a code is stable once documented.


This is a residual of epic #2879 (BCLI).

Plan block
### 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/error` object, its fields, and every `code` with 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.md` lists `usage` (2), `not_found` (4) and `host_unreachable` (7) among the others, and the test fails when a code is added in the code but not in the reference.

Activity

  1. added
    priority:nice-to-haveNice to have. Applied by the inbox-route classifier or a human.
    and removed
    priority:should-haveShould be done. Applied by the inbox-route classifier or a human.
    on Nov 18, 2026
  2. changed the title [-]docs: list the min/v1/error codes and their exit codes in cli-min.md[/-] [+]T65 — The CLI reference lists every min/v1/error code and its exit code[/+] on Nov 19, 2026
  3. agent-137 commented on Nov 19, 2026

    @agent-137
    Member

    /implement

  4. minimal-foundry commented on Nov 19, 2026

    @minimal-foundry
    Contributor

    Pull request #3667 is open for T65.

    branch agent/3402-the-cli-reference-lists-every-min-v1-error-code

    round outcome job
    1 pushed 3ab5d81b
    2 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. 9de861a6
    3 pushed 73434021
    test exit tail
    cargo nextest run -p minimal cli_reference_lists_every_error_code 0 warning: unknown fields in task runtime-implement-test-0: network help: do you need to update to a newer version of minimal? Running task runtime-implement-test-0 in box runtime-implement-test-0-1... Compiling paths v0.0.1 (/workbench/crates/paths) Compiling ot v0.0.1 (/workbench/crates/ot)

    Verify min task run agent-verify: exit 100 — FAIL [ 12.934s] (1251/1251) minimal::otel_cli exec_run_attach_and_task_run_share_the_commands_trace thread 'exec_run_attach_and_task_run_share_the_commands_trace' (11132) panicked at crates/minimal/tests/otel_cli.rs:807:13: exec: no daemon exec span under cmd b727735bc2b29c31: [

    Updated 2026-11-20T06:36:51.491Z.

  5. agent-137 commented on Nov 19, 2026

    @agent-137
    Member

    /implement

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:nice-to-haveNice to have. Applied by the inbox-route classifier or a human.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      0