feat(cli): plane-grouped --help + clap 4.6.1 (RFC-010 Slice 2) (#220)

* chore(deps): bump clap to 4.6.1

Workspace constraint "4" → "4.6" so the resolver picks up the 4.6 line
(a plain `cargo update` stayed on 4.5.x). clap 4.5.58 → 4.6.1
(clap_builder 4.6.0, clap_derive 4.6.1). Minor bump, no API breakage; the
workspace builds and all CLI suites pass unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(cli): group --help by plane (RFC-010 Slice 2)

Slice 1 declared the planes (the command_plane table + the wrong-plane
guard); this makes them visible in `--help`. clap can't print labeled
heading rows between subcommand groups (verified against the source —
help_heading is args-only, {subcommands} is one flat block), so per the
chosen approach: cluster + legend.

- Reorder the `Command` enum into plane bands (clap lists subcommands in
  declaration order): data (query, mutate, load, branch, snapshot, export,
  commit, schema, graphs) → storage/local-graph ops (init, optimize,
  repair, cleanup, lint, queries) → control (cluster) → session (policy,
  embed, login, logout, config, version). No magic display_order numbers —
  the source order IS the help order, with band comments for readers. The
  band placement matches `command_plane` (lint/queries are storage-plane:
  they reject --server), so the help grouping and the guard agree.
- Add an `after_help` legend on `Cli` naming the planes. Written to
  describe the planes (not enumerate every command) so it doesn't drift.

Help-polish (post-review): hide the deprecated `ingest` from the list
(still a valid command); trim the long `login` and `--as` descriptions to
one line each so the columns don't blow up.

The behavioral source of truth for planes stays `planes::command_plane`;
this ordering is its cosmetic counterpart.

Test: `help_groups_commands_by_plane` pins the legend phrase + the cluster
ordering (query < optimize < cluster). Doc: a line under cli-reference's
*Command planes* section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(cli): qualify mixed-plane commands in the --help legend

Addresses the Greptile P2 on #220: the legend placed `schema` entirely in
Data and `queries` entirely in Storage, but per `command_plane` the
subcommands differ — `schema plan` is storage-plane (rejects --server) and
`queries list` is session (no graph). A user reading the legend then running
`schema plan --server` would hit a rejection contradicting it. The Commands
list is one entry per top-level command (necessarily coarse), so the legend
carries the nuance: `schema [plan: storage]` and `queries [list: session]`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Andrew Altshuler 2026-06-14 01:49:40 +03:00 committed by GitHub
parent 4187d56f8a
commit d6cf5b298c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 239 additions and 191 deletions

View file

@ -24,6 +24,38 @@ fn version_command_prints_current_cli_version() {
);
}
#[test]
fn help_groups_commands_by_plane() {
// RFC-010 Slice 2: `--help` clusters commands by plane (declaration order
// in the Command enum) and explains the planes in an after_help legend.
// Pinned lightly — the legend phrase + the cluster ordering — to avoid
// brittle full-text assertions on clap's help body.
let output = output_success(cli().arg("--help"));
let stdout = stdout_string(&output);
assert!(
stdout.contains("COMMANDS BY PLANE"),
"plane legend (after_help) missing from --help:\n{stdout}"
);
// The Commands list precedes the legend, so first occurrences sit in the
// list and must appear in plane order: a data verb, then a storage verb,
// then the control verb.
let pos = |needle: &str| {
stdout
.find(needle)
.unwrap_or_else(|| panic!("'{needle}' not found in --help:\n{stdout}"))
};
assert!(
pos("query") < pos("optimize"),
"data commands should be listed before storage commands"
);
assert!(
pos("optimize") < pos("cluster"),
"storage commands should be listed before the control command"
);
}
#[test]
fn init_creates_graph_successfully_on_missing_local_directory() {
let temp = tempdir().unwrap();