Repository navigation
docs(minimal): T32 — One command model, its help, completions and reference - #3700
mitodrummer merged 7 commits into
Conversation
…ence Five tests check that every min box, session and task verb and flag is in the one command model, in --help and in the shell completions. They also check the CLI reference and the one migration note. The noun help lines now say what each noun does.
Add a reference section for each box verb and each type-noun alias, and one migration note in the sessions concept page for the old spellings.
The task puts the old spellings in one migration note in docs/concepts/sessions.md. The T31 docs check now skips only that section and still rejects the old spellings everywhere else.
|
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.
|
|
/arch-review |
|
Reviewed: no findings; approval withheld, 7 threads unresolved at APPROVE withheld: 7 unresolved threads — minimal-arch[bot] crates/minimal/src/tests.rs:26141, minimal-arch[bot] crates/minimal/src/tests.rs:26144, minimal-arch[bot] docs/reference/cli-min.md:434, minimal-arch[bot] docs/reference/cli-min.md:471, minimal-arch[bot] crates/minimal/src/tests.rs:26096, …. Resolving the last thread releases the approval on this head. Resolve the open threads. Resolving the last one releases the approval on this head; no new review is required. Verdict APPROVE, posted as a comment: the App cannot review its own pull request; the check and the label carry it. Clobber: none seen. |
There was a problem hiding this comment.
arch-review: CONDITIONS · 3 conditions · the full ruling
The help and completions come from one command model, and the new reference sections are complete. BCLI-026 is not met yet. Architecture lines 488 and 493 give box run the flags --name, --loadout and --ingress, and give box list the flags --type and --parent. The model does not have them. box_verbs_exist_with_arch_flags hides this gap, so C1 makes the test name each deferred flag with its issue. C2 files the issues that do not exist and lists every gap as a residual in the PR body. C3 removes the session attach picker text, because architecture line 511 and the code refuse with exit 2.
Ruled at 3d25bc3 against gominimal/arch@4f2eb87d5d12 by claude-opus-5-5.
| ], | ||
| ), | ||
| ( | ||
| "run", |
| "run", | ||
| &["--detach", "--network", "--no-loadouts", "--no-hooks"], | ||
| ), | ||
| ("list", &["--all", "--output"]), |
There was a problem hiding this comment.
C1 · Architecture line 493 gives box list the flags --type <name> and --parent <box>. The Non-goals exempt only self. Put both in DEFERRED_ARCH_FLAGS with the issue that C2 files.
There was a problem hiding this comment.
Addressed in 2312cce31bcd: Added box list --type and --parent (#3714) to DEFERRED_ARCH_FLAGS. The test asserts that both are absent.
| | Flag | Description | | ||
| |------|-------------| | ||
| | `--detach` | Start the box, print its id and return. The box gets no input | | ||
| | `--path <PATH>` | The project directory. The default is the directory that `-C` names, else the current directory | |
There was a problem hiding this comment.
C2 · Architecture line 488 gives box run no --path, and the global -C names the project. The row stays while the flag is in the model. File an issue to remove the flag from BoxRunArgs and cmd_box_run, and list it as a residual in the PR body.
There was a problem hiding this comment.
Addressed in 2312cce31bcd: No code change in this round. #3715 tracks removing --path from BoxRunArgs and cmd_box_run. The PR body lists it as a residual, and the row stays while the flag is in the model.
| attaches to the running box of this project that has a terminal. When no such | ||
| box runs, it attaches to the project's only stopped or exited box that has a | ||
| terminal, which starts again. When more than one box can match, the command | ||
| lists them and exits with code 2. |
There was a problem hiding this comment.
C3 · This line agrees with architecture line 511. The session attach section at lines 332–334 does not: it says an ambiguous bare attach opens a picker. The code refuses with exit 2. Change that section and docs/concepts/sessions.md lines 123–126 to say the command lists the candidates and exits with code 2.
There was a problem hiding this comment.
Addressed in 2312cce31bcd: The session attach section of cli-min.md and docs/concepts/sessions.md now say: when more than one session can match, the command lists them and exits with code 2.
|
/revise Arch's ruling at 3d25bc3 (CONDITIONS): C1 and C3. C2 is done: #3714 and #3715 are filed, and the PR body lists the residuals.
Change nothing else, and do not edit |
…d-model-its-help-completions-and-refer
The box_verbs_exist_with_arch_flags test now lists the architecture's box run and box list flags that the model does not have yet, each with its issue, and fails when one of them lands. The session attach docs say an ambiguous bare attach lists the sessions and exits with code 2.
|
Round 1 of 10 on a /revise note, pushed as
Verify Converted to a draft: verify exited 100. Review threads the coder judged:
Notes from the agent: Revise round 1: C1 and C3 are done. C2 needed no change in this round. cli.rs and the PR body are unchanged. I ran the five test lines in two combined nextest invocations, and each test is named in them. I did not run the wider verify suite, so I did not check the known flake #3483. |
|
/arch-review |
There was a problem hiding this comment.
arch-review: PASS_WITH_CONDITIONS · 1 condition · the full ruling
The three earlier conditions are met. The test now pins each deferred architecture flag as absent, with its issue. The PR body lists each gap as a residual. The attach docs say an ambiguous attach exits 2, as architecture line 511 requires. The flags that lines 488 and 493 give and the model lacks stay open as filed residuals. C1 records that follow-up work.
Ruled at 2312cce against gominimal/arch@4f2eb87d5d12 by claude-opus-5-5.
| // The architecture's flags that are not in the model yet, each with the | ||
| // issue that delivers it. When one of them lands, this test fails until | ||
| // the flag moves from this table to `expected`. | ||
| const DEFERRED_ARCH_FLAGS: [(&str, &str, &str); 5] = [ |
There was a problem hiding this comment.
There was a problem hiding this comment.
Disputed — not addressed: Nothing to change in this PR. --path is still in BoxRunArgs, so it cannot be asserted absent yet. #3715 removes it from BoxRunArgs and cmd_box_run and adds that assertion when it lands.
| for flag in visible_long_flags(&model_verb(noun, verb)) { | ||
| let documented = | ||
| section.contains(&flag) || (points_to_start && session_start.contains(&flag)); | ||
| if !documented { |
There was a problem hiding this comment.
LOW · tests · confidence 0.55 · in cli_reference_documents_box_grammar
cli_reference_documents_box_grammar checks a flag with section.contains(&flag), a substring match. A flag such as --all or --network passes when the section only names a longer flag such as --all-providers. The test can pass while the flag is undocumented. Match the flag as a whole word, for example in backticks.
What the reviewer checked
tests.rs:26401 section.contains(&flag) || (points_to_start && session_start.contains(&flag))
Hand this to an agent
Act on a code-review finding.
File: crates/minimal/src/tests.rs
Lines: 26399-26402
Category: tests
Severity: low (reviewer confidence 0.55)
Finding:
`cli_reference_documents_box_grammar` checks a flag with `section.contains(&flag)`, a substring match. A flag such as `--all` or `--network` passes when the section only names a longer flag such as `--all-providers`. The test can pass while the flag is undocumented. Match the flag as a whole word, for example in backticks.
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.
Addressed in 7be346c14265: cli_reference_documents_box_grammar now uses names_flag, a whole-word match, so --all does not match inside --all-providers. A unit test pins the helper.
A flag such as --all no longer passes on a section that names only --all-providers.
|
Round 2 of 10 on the runtime's review findings, pushed as
Verify Converted to a draft: verify exited 100. Review threads the coder judged:
Notes from the agent: Revise round 2. The reference test now matches each flag as a whole word through a new names_flag helper, with its own unit test. All flags in docs/reference/cli-min.md still pass, so the docs needed no change. The --path removal stays with #3715, as the earlier reply on that thread says. |
There was a problem hiding this comment.
arch-review: PASS_WITH_CONDITIONS · 1 condition · the full ruling
The new commit makes the reference test match each flag as a whole word. That is a stricter proof of BCLI-044, and it conforms. C1 from the last ruling stays open. The flags that architecture.md lines 488 and 493 list are still deferred to the filed issues. The change can merge with C1 open. Close C1 through issues #3196, #3163, #3237, #3714 and #3715.
Ruled at 7be346c against gominimal/arch@4f2eb87d5d12 by claude-opus-5-5.
| // The architecture's flags that are not in the model yet, each with the | ||
| // issue that delivers it. When one of them lands, this test fails until | ||
| // the flag moves from this table to `expected`. | ||
| const DEFERRED_ARCH_FLAGS: [(&str, &str, &str); 5] = [ |
There was a problem hiding this comment.
C1 · C1 stays open. architecture.md lines 488 and 493 list --name, --ingress, --loadout, --type and --parent. Each issue moves its flag from this table to expected when it lands. Issue #3715 removes --path from BoxRunArgs.
There was a problem hiding this comment.
minimal-review — approval withheld
Verdict COMMENT — APPROVE withheld: 7 unresolved threads — minimal-arch[bot] crates/minimal/src/tests.rs:26141, minimal-arch[bot] crates/minimal/src/tests.rs:26144, minimal-arch[bot] docs/reference/cli-min.md:434, minimal-arch[bot] docs/reference/cli-min.md:471, minimal-arch[bot] crates/minimal/src/tests.rs:26096, …. No findings.
Panel: 3 of 3 personas ran (correctness, security, supply-chain).
|
/arch-review |
There was a problem hiding this comment.
arch-review: PASS_WITH_CONDITIONS · 3 conditions · the full ruling
The help, the completions and the CLI reference now come from one command model, and the tests pin them. BCLI-028, BCLI-043 and BCLI-044 conform. The command model still differs from the architecture's min box run, min task run and min box list lines (488, 473, 493). This change pins each gap in DEFERRED_ARCH_FLAGS, and each gap has a filed issue. C1, C2 and C3 name the edits. They can stay open at merge as the filed residuals. Make sure that CI is green before the merge, because the verify run failed on an otel test outside this diff.
Ruled at 7be346c against gominimal/arch@4f2eb87d5d12 by claude-opus-5-5.
| // The architecture's flags that are not in the model yet, each with the | ||
| // issue that delivers it. When one of them lands, this test fails until | ||
| // the flag moves from this table to `expected`. | ||
| const DEFERRED_ARCH_FLAGS: [(&str, &str, &str); 5] = [ |
| "https://github.com/gominimal/minimal/issues/3237", | ||
| ), | ||
| ( | ||
| "list", |
There was a problem hiding this comment.
C2 · Line 493 gives min box list the flags --type <name> and --parent <box>. When #3714 adds them to BoxListArgs, move these two rows to expected.
There was a problem hiding this comment.
Left open as a residual, as the ruling at 7be346c1 allows: #3714, listed under Residuals in the PR body. DEFERRED_ARCH_FLAGS pins the gap until that issue lands.
| | Flag | Description | | ||
| |------|-------------| | ||
| | `--detach` | Start the box, print its id and return. The box gets no input | | ||
| | `--path <PATH>` | The project directory. The default is the directory that `-C` names, else the current directory | |
There was a problem hiding this comment.
C3 · Line 488 gives min box run no --path, and the global -C names the project. When #3715 removes the path field from BoxRunArgs, remove this row and add an absence check in box_verbs_exist_with_arch_flags.
There was a problem hiding this comment.
Left open as a residual, as the ruling at 7be346c1 allows: #3715, listed under Residuals in the PR body. DEFERRED_ARCH_FLAGS pins the gap until that issue lands.
T32 — One command model, its help, completions and reference
slice: S8
kind: task
covers: BCLI-026, BCLI-028, BCLI-044, BCLI-043
size: M
est: 150 code, 300 tests
executor: agent
difficulty: routine
model: standard
diagnostics:
min box --helplists every verb with one line on what it does, andmin box <verb> --helplists its flags, pinned by help_and_completions_from_one_modelobservability: the command's existing tracing span records the verb, the box id it resolved and the outcome
layers:
- client:
- crates/minimal/src/cli.rs: the verb's arguments and help in the one command model
- crates/minimal/src/completions.rs: completions come from the same command model as the help
- crates/minimal/src/tests.rs: the in-process minimald test harness gains this layer's tests
test: cargo nextest run -p minimal box_verbs_exist_with_arch_flags
test: cargo nextest run -p minimal help_and_completions_from_one_model
test: cargo nextest run -p minimal cli_reference_documents_box_grammar
test: cargo nextest run -p minimal docs_name_aliases_only_in_one_migration_note
test: cargo nextest run -p minimal setup_zed_unchanged
- docs:
- docs/reference/cli-min.md: documents every
min box< 10000 /code>, session and task verb- docs/concepts/sessions.md: carries the one migration note that names the old spellings
produces: none
consumes: none
proof:
min box --helpand the shell completions list every verb and flag, and the CLI reference documents each one.depends on:
- blocked by #2913
- blocked by #2893
- blocked by #2915
- blocked by #2908
- blocked by #2909
- blocked by #2921
- blocked by #2917
Proof
min box --help,min session --helpandmin task --helplist every verb with one line on what it does. Eachmin <noun> <verb> --helpand the shell completion ofmin <noun> <verb> --list the same flags, because both come from the one clap command model. docs/reference/cli-min.md now has a section for all 17min boxverbs and for eachmin sessionandmin taskalias, and the tests fail if a verb or flag goes missing from any of them. docs/concepts/sessions.md has the one migration note for the old spellings and--provider local-minimald.Notes from the agent: The verbs and flags were already in the command model, so the code change in cli.rs is only the help lines of
min box,min sessionandmin task. completions.rs needed no change: completions already run through clap_complete overCli::command, the same model as the help, and help_and_completions_from_one_model now pins that. Gap against BCLI-026:min box runstill has no--name(BCLI-069). The comment on TaskRunArgs defers it to #3196, becauseRunEntryin task.rs takes no name, and task.rs is outside this task's layers. box_verbs_exist_with_arch_flags does not assert--nameonbox run. Observability: the task asks for the verb, the resolved box id and the outcome on the command's tracing span. The dispatch code is in main.rs and cmd/boxes, outside the layers, so I did not change it. Not done:just lint-prose(vale is not installed on this box) andjust clippy-strict.cargo clippy -p minimal --all-targetsis clean. Docs drift I saw but did not fix: thesession attachsection in cli-min.md still says an ambiguous bare attach opens a picker. BCLI-032 says it fails with exit 2 and lists the candidates. I did not check which behaviour the code has.Tests
cargo nextest run -p minimal box_verbs_exist_with_arch_flagscargo nextest run -p minimal help_and_completions_from_one_modelcargo nextest run -p minimal cli_reference_documents_box_grammarcargo nextest run -p minimal docs_name_aliases_only_in_one_migration_notecargo nextest run -p minimal setup_zed_unchangedVerify
min task run agent-verifyexited 100, so this PR is a draft.Residuals
BCLI-026 gaps (arch C2 at 3d25bc3).
box_verbs_exist_with_arch_flagslists each one inDEFERRED_ARCH_FLAGS:min box runandmin task run--name: BCLI: min box start of a task entry takes --name and refuses a held name (T10 residual, arch C1) #3196min box runandmin task run--ingress: min task run: add --ingress #3163min box runandmin task run--loadout: BCLI: --loadout on the run path (min task run, min box run, task-entry start) (T11 residual, arch C2) #3237min box list --typeand--parent: min box list takes --type and --parent #3714--pathfrommin box run: Remove --path from min box run #3715Closes #2922