8000 docs(minimal): T32 — One command model, its help, completions and reference by minimal-foundry[bot] · Pull Request #3700 · gominimal/minimal · GitHub
[go: up one dir, main page]

Skip to content

docs(minimal): T32 — One command model, its help, completions and reference - #3700

Draft
minimal-foundry[bot] wants to merge 3 commits into
mainfrom
agent/2922-one-command-model-its-help-completions-and-refer
Draft

minimal-foundry[bot] wants to merge 3 commits into
mainfrom
agent/2922-one-command-model-its-help-completions-and-refer

Conversation

@minimal-foundry
Copy link
Copy Markdown
Contributor

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 --help lists every verb with one line on what it does, and min box <verb> --help lists its flags, pinned by help_and_completions_from_one_model
observability: 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, 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 --help and 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 --help and min task --help list every verb with one line on what it does. Each min <noun> <verb> --help and the shell completion of min <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 17 min box verbs and for each min session and min task alias, 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 session and min task. completions.rs needed no change: completions already run through clap_complete over Cli::command, the same model as the help, and help_and_completions_from_one_model now pins that. Gap against BCLI-026: min box run still has no --name (BCLI-069). The comment on TaskRunArgs defers it to #3196, because RunEntry in task.rs takes no name, and task.rs is outside this task's layers. box_verbs_exist_with_arch_flags does not assert --name on box 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) and just clippy-strict. cargo clippy -p minimal --all-targets is clean. Docs drift I saw but did not fix: the session attach section 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

line exit tail
cargo nextest run -p minimal box_verbs_exist_with_arch_flags 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal help_and_completions_from_one_model 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal cli_reference_documents_box_grammar 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal docs_name_aliases_only_in_one_migration_note 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal setup_zed_unchanged 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt

Verify

min task run agent-verify exited 100, so this PR is a draft.

/1232) minimal::bin/min tests::invalid_project_file_prints_toml_error_once
        PASS [   0.004s] (1207/1232) minimal::bin/min tests::invalid_project_file_prints_toml_error_once_for_io
        PASS [   0.004s] (1208/1232) minimal::bin/min tests::loadout_not_found_exits_4
        PASS [   0.005s] (1209/1232) minimal::bin/min tests::local_host_not_found_exits_4
        PASS [   0.005s] (1210/1232) minimal::bin/min tests::machine_mode_answers_write_failures
        PASS [   0.005s] (1211/1232) minimal::bin/min tests::machine_mode_error_line_keeps_an_empty_hint
        PASS [   0.005s] (1212/1232) minimal::bin/min tests::machine_mode_error_object_is_one_stamped_line
        PASS [   0.004s] (1213/1232) minimal::bin/min tests::machine_mode_error_object_on_stderr
        PASS [   0.005s] (1214/1232) minimal::bin/min tests::machine_mode_names_the_grant_refusal_code
        PASS [   0.005s] (1215/1232) minimal::bin/min tests::machine_output_mode_keys_on_the_output_flag
        PASS [   0.005s] (1216/1232) minimal::bin/min tests::misplaced_run_flag_exits_2
        PASS [   0.005s] (1217/1232) minimal::bin/min tests::network_flag_refusal_exits_2
        PASS [   0.005s] (1218/1232) minimal::bin/min tests::project_file_not_found_exits_4
        PASS [   0.005s] (1219/1232) minimal::bin/min tests::prune_off_tty_needs_yes_exits_2
        PASS [   0.005s] (1220/1232) minimal::bin/min tests::resume_and_session_attach_refusals_map_to_exit_codes
        PASS [   0.004s] (1221/1232) minimal::bin/min tests::rm_running_box_refuses_naming_force_with_exit_2
        PASS [   0.005s] (1222/1232) minimal::bin/min tests::row_not_back_exit_codes
        PASS [   0.005s] (1223/1232) minimal::bin/min tests::run_verbs_and_wait_timeout_return_124_with_code_timeout
        PASS [   0.005s] (1224/1232) minimal::bin/min tests::start_entry_refusals_exit_with_their_codes
        PASS [   0.005s] (1225/1232) minimal::bin/min tests::task_file_invalid_exits_3
        PASS [   0.005s] (1226/1232) minimal::bin/min tests::task_network_key_a_task_does_not_apply_exits_3
        PASS [   0.005s] (1227/1232) minimal::bin/min tests::task_not_found_exits_4
        PASS [   0.004s] (1228/1232) minimal::bin/min tests::task_run_is_a_stdout_contract
        PASS [   0.005s] (1229/1232) minimal::bin/min tests::type_refusals_exit_3_and_4
        PASS [   0.904s] (1230/1232) minimal::otel_cli a_silent_collector_costs_min_ls_little_and_prints_nothing
        PASS [   2.058s] (1231/1232) minimal::named_vm named_vm_reaches_autospawn
  stdout ───

    running 1 test
    test exec_run_attach_and_task_run_share_the_commands_trace ... FAILED

    failures:

    failures:
        exec_run_attach_and_task_run_share_the_commands_trace

    test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 5 filtered out; finished in 13.00s

  stderr ───

    ]
    note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

  Cancelling due to test failure: 
────────────
error: test run failed

Closes #2922

…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.
@coderabbitai
coderabbitai Bot commented Nov 20, 2026
Copy link
Copy Markdown
Contributor

Important

Review skipped

Bot 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.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: b2332ff0-95b3-4af7-94d1-6e38a2ef8833

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

T32 — One command model, its help, completions and reference

0 participants

0