feat(cli): command help + output ergonomics (did-you-mean, per-subcommand help, ai UX)

[jmagar]

Rebased onto current main (813ee80) — conflict-free except one import-list merge (kept both AiOutputDetail and DbIntegrityStatusArgs). 1293 tests pass; clippy + fmt clean.

What this adds

• "Did you mean?" suggestions (src/cli/suggest.rs): Levenshtein fuzzy-matching so a mistyped command, subcommand, or flag suggests the nearest valid one (e.g. cortex serach → "unknown CLI command: serach — Did you mean search?"). Threshold scales with token length.
• Per-subcommand --help: extends the grouped help catalog with detailed usage: lines for the individual subcommands (ai *, db *, compose *, setup *, sig *), so e.g. cortex ai search --help / cortex db vacuum --help show their own flags.
• Wires up 3 ai subcommands through parse + help + output: ai similar, ai ask-history, ai incident-context (arg types already existed; now exposed).
• Output ergonomics for the AI/log surfaces (output_ai_more.rs, output_logs.rs), incl. an AiOutputDetail mode.
• Tests for all of the above (suggest_tests, parse_ai_tests, parse_ai_more_tests, parse_tests, main_tests).

Notes

• Builds on top of the axon-style grouped --help already on main; complements (doesn't replace) it.
• 37 files, +908/-70.

---

Summary by cubic

Adds “Did you mean?” suggestions, nested per-subcommand help (now aware of --server/--token), and compact/full output controls with UTF‑8 byte-accurate truncation to make the CLI easier to use. Also exposes ai similar, ai ask-history, and ai incident-context, updates docs, and bumps to 1.7.0.

• New Features

  • Per-subcommand help for nested paths, including setup doctor; resolves correctly with global flags (e.g., cortex --server URL db status --help).
  • Fuzzy suggestions for mistyped commands, subcommands, and options; supports equals-style flags (--projct=foo → --project); shown for top-level commands too.
  • Output controls for ai investigate and ai blocks: --detail compact|full, --include-transcript, --max-bytes (UTF‑8 byte-accurate), and --limit; terminal and JSON honor --detail (compact JSON when compact); ai blocks caps to 25 in compact mode unless overridden.

• Bug Fixes

  • ai investigate terminal output now honors --detail and --include-transcript.
  • --max-bytes truncates by UTF‑8 bytes on char boundaries; tiny budgets return a prefix instead of empty.
  • CLI guidance and errors: host-state requires --host-id/--hostname with usage; unknown top-level commands now include suggestions; docs reference cortex instead of syslog.
  • Stabilized the agent spool wrapper test by serializing it to avoid $SHELL env races.

^{Written for commit 97f4153. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Added nested subcommand help support (e.g., help ai search).
  • Added "Did you mean...?" suggestions for mistyped commands and options.
  • Added compact/full output controls for cortex ai investigate and cortex ai blocks commands.

• Bug Fixes

  • Updated diagnostic guidance to reference cortex instead of legacy syslog naming.
  • Improved cortex host-state error messages to require explicit host selector with usage hints.

• Documentation

  • Updated changelog, rollout playbook, and deployment runbooks to reflect CLI command changes.

[coderabbitai]

📝 Walkthrough

Walkthrough

This release delivers CLI 1.2.0 with improved error handling, AI command output controls, and multi-token help support. It introduces a Levenshtein distance-based suggestion system for "Did you mean?" error messages, adds compact output modes for investigation results with byte-truncation, and enables nested command help queries like cortex ai search --help.

Changes

Cortex CLI 1.2.0 Release

Layer / File(s)	Summary
Release infrastructure and documentation updates CHANGELOG.md, Cargo.toml, mcpb/manifest.json, server.json, docs/rollout.md, docs/runbooks/deploy.md, src/cli/dispatch_db.rs	Version bumped to 1.2.0 across manifest, cargo config, and MCP server. CHANGELOG documents the new features. Deployment and rollout docs updated from syslog to cortex CLI references. Error message guidance in dispatch_db.rs corrected.
Suggestion system infrastructure src/cli/suggest.rs, src/cli/suggest_tests.rs	New module implementing did_you_mean (Levenshtein distance matching with normalized inputs), unknown_command, and unknown_option error formatters. Tests cover typo suggestions, dissimilar input handling, and --flag=value parsing edge cases.
AI output control types and arguments src/cli/args/ai.rs	New AiOutputDetail enum (Compact/Full) with parse and is_compact methods. AiBlocksArgs gains limit: Option<usize> and detail: AiOutputDetail. AiInvestigateArgs gains detail, include_transcript, and max_bytes for controlling output volume and formatting.
Output formatting and truncation implementation src/cli/output_common.rs, src/cli/output_common_tests.rs, src/cli/output_ai_more.rs, src/cli/output_logs.rs	truncate_bytes function truncates UTF-8 strings by byte budget while preserving character boundaries and appending ellipsis. AiInvestigatePrintOptions and UsageBlocksPrintOptions structs enable option-driven output. Compact JSON generation includes per-evidence counts, optional transcript, truncated messages by max_bytes. Block responses capped at 25 in compact mode or explicitly by limit.
Nested help system for multi-token queries src/cli/help.rs, src/cli/help_tests.rs	NestedCommandDoc type and NESTED_CATALOG map nested command paths (ai search, db backup, etc.) to summaries and usage text. render_command serves nested help when matched. classify_help detects two-token help requests and returns HelpRequest::Command("ai search") style classification. New test validates subcommand-specific usage rendering.
Error handling improvements across parsers src/cli/parse.rs, src/cli/parse_admin.rs, src/cli/parse_ai.rs, src/cli/parse_ai_more.rs, src/cli/parse_command_log.rs, src/cli/commands/host_state.rs, src/cli/commands/notify.rs, src/cli/commands/sig.rs, src/main.rs	parse.rs introduces TOP_LEVEL_COMMANDS and switches to suggestion-based errors. parse_admin.rs uses unknown_command for service/db/compose/setup subcommands. parse_ai.rs and parse_ai_more.rs recognize new output flags and provide suggestion-based option errors. host_state.rs includes full usage hint when host selector is missing. notify.rs and sig.rs use suggestion helpers. main.rs attempts CLI parse to produce specific errors instead of generic fallback.
Dispatcher wiring and module organization src/cli.rs, src/cli/args.rs, src/cli/dispatch_ai.rs, src/cli/dispatch_tests.rs	cli.rs declares new suggest module. dispatch_ai.rs wires run_ai_blocks and run_ai_investigate through options-based output functions, extracting detail/limit/include_transcript/max_bytes from parsed args. Tests updated to use ..Default::default() for expanded struct fields.
Tests and validation coverage src/cli/parse_ai_tests.rs, src/cli/parse_ai_more_tests.rs, src/cli/parse_tests.rs, src/main_tests.rs	New tests verify parse_ai_blocks with --limit and --detail, parse_ai suggestion for serach→search, parse_ai_investigate output controls, host-state missing-selector usage errors. main_tests.rs updated to expect new error wording and suggestion text in fallback messages.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 A rabbit hops through version bumps and flags so new,
With "Did you mean?" now whispered when typos come through,
Compact output blooms and nested help takes flight,
The cortex CLI sparkles in the upgrade light!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 58.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding CLI command help ergonomics, did-you-mean suggestions, per-subcommand help, and AI UX improvements.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch lavra/cli-ux-beads

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e81ca167b6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR improves the cortex CLI UX by adding fuzzy “did you mean?” suggestions for unknown commands/options, enabling per-subcommand nested --help output (e.g. ai search --help), and introducing new AI output/detail controls while wiring additional ai subcommands through parsing/help/dispatch. It also updates operator-facing docs to consistently reference the cortex binary and bumps the project version to 1.2.0.

Changes:

• Add Levenshtein-based suggestions for unknown commands/subcommands/options across the hand-rolled CLI parser.
• Extend help rendering to support nested subcommand help entries (e.g. db status, compose logs, ai investigate) with dedicated usage lines.
• Add AI output ergonomics (--detail, --limit, --include-transcript, --max-bytes) and expose additional ai subcommands through parse/help/output/dispatch; update docs + version metadata accordingly.

Reviewed changes

Copilot reviewed 36 out of 37 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/main.rs	Routes unknown top-level commands through the CLI parser to surface improved errors/suggestions.
src/main_tests.rs	Updates top-level mode parsing tests to reflect new error text and host-state selector requirements.
src/cli/suggest.rs	Introduces suggestion utilities (did-you-mean + unknown command/option formatting).
src/cli/suggest_tests.rs	Adds unit tests for suggestion matching behavior.
src/cli/parse.rs	Adds top-level command candidate list + suggestion-backed unknown-command/option errors.
src/cli/parse_tests.rs	Expands parser tests for suggestion output and host-state selector validation.
src/cli/parse_command_log.rs	Adds suggestion-backed errors for shell and agent-command subcommands.
src/cli/parse_ai.rs	Adds AI subcommand candidate list + suggestion-backed errors; extends ai blocks flags (--limit, --detail).
src/cli/parse_ai_tests.rs	Adds tests for new AI flags and “did you mean?” behavior on unknown AI subcommands.
src/cli/parse_ai_more.rs	Extends ai investigate parsing with output control flags and suggestion-backed unknown-option errors.
src/cli/parse_ai_more_tests.rs	Adds tests for ai investigate output control flags parsing.
src/cli/parse_admin.rs	Adds suggestion-backed errors for service, db, compose, and setup subcommands.
src/cli/output_logs.rs	Adds print options + truncation behavior for ai blocks output (detail/limit aware).
src/cli/output_ai_more.rs	Adds compact-vs-full JSON behavior and truncation controls for ai investigate output.
src/cli/help.rs	Adds nested help catalog + nested lookup/classification to support per-subcommand --help.
src/cli/help_tests.rs	Adds tests ensuring nested help renders focused usage and classify_help returns nested paths.
src/cli/dispatch_tests.rs	Updates dispatch test snapshots for expanded/defaulted AI args.
src/cli/dispatch_db.rs	Updates operator guidance text to reference cortex instead of syslog.
src/cli/dispatch_ai.rs	Wires new AI print options into ai blocks and ai investigate dispatch paths.
src/cli/commands/silent_hosts.rs	Updates CLI docs/comments to reference cortex binary.
src/cli/commands/sig.rs	Adds suggestion-backed error for unknown sig subcommands.
src/cli/commands/notify.rs	Adds suggestion-backed error for unknown notify subcommands.
src/cli/commands/host_state.rs	Adds suggestion-backed unknown-option errors and enforces required host selector with usage.
src/cli/commands/compare.rs	Updates CLI docs/comments to reference cortex binary.
src/cli/commands/clock_skew.rs	Updates CLI docs/comments to reference cortex binary.
src/cli/commands/apps.rs	Updates CLI docs/comments to reference cortex binary.
src/cli/commands/anomalies.rs	Updates CLI docs/comments to reference cortex binary.
src/cli/args/ai.rs	Adds AiOutputDetail and new AI args fields for output/detail controls.
src/cli/args.rs	Re-exports AiOutputDetail from the args module.
src/cli.rs	Registers the new suggest module and re-exports updated CLI types.
server.json	Bumps server/package metadata to 1.2.0 and updates container tag.
mcpb/manifest.json	Bumps MCP bundle manifest version to 1.2.0.
docs/runbooks/deploy.md	Updates runbook commands to consistently use cortex binary.
docs/rollout.md	Updates rollout instructions to consistently use cortex binary.
CHANGELOG.md	Adds 1.2.0 release notes covering new help/suggestions/output ergonomics and doc fixes.
Cargo.toml	Bumps crate version to 1.2.0.
Cargo.lock	Updates lockfile to reflect the new crate version.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cubic-dev-ai]

4 issues found across 37 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/cli/parse_ai_more.rs">

<violation number="1" location="src/cli/parse_ai_more.rs:275">
P2: Did-you-mean matching uses the full `--flag=value` token, so typo suggestions frequently fail for equals-style options in `ai investigate`.</violation>
</file>

<file name="src/cli/help.rs">

<violation number="1" location="src/cli/help.rs:359">
P3: This usage line is misleading: `--detail full` is only honored in JSON mode right now, so terminal output does not become full-detail. Scope the note to JSON mode or update the terminal renderer to honor `detail`.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

src/cli/help.rs (1)

197-217: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add the new AI subcommands to cortex ai --help.

render_command("ai") reads this usage list, and it still omits ai similar, ai ask-history, and ai incident-context even though those commands are documented in NESTED_CATALOG below. Right now the new commands are only discoverable if the user already knows their exact names.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli/help.rs` around lines 197 - 217, The AI subcommands list in the usage
array used by render_command("ai") is missing the new commands (ai similar, ai
ask-history, ai incident-context), so add those three strings into the usage
array (the same format as the other entries) so render_command("ai") will
include them; verify that the entries match their names in NESTED_CATALOG to
keep help in sync with the implemented commands.

src/cli/help_tests.rs (1)

112-137: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add regressions for the uncovered nested-help cases.

These spot checks still pass while cortex ai --help hides the new AI subcommands, setup doctor --help resolves to the generic setup banner, and --server URL db status --help falls back to top-level help. A couple more assertions here would pin the intended behavior and prevent the catalog/classifier drift that slipped in.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli/help_tests.rs` around lines 112 - 137, Add regression assertions
around classify_help to lock in nested-help behavior: using the same v helper,
assert that classify_help(&v(&["ai", "--help"])) returns HelpRequest::TopLevel;
assert that classify_help(&v(&["setup", "doctor", "--help"])) returns
HelpRequest::Command("setup doctor".to_string()); and assert that
classify_help(&v(&["--server", "URL", "db", "status", "--help"])) returns
HelpRequest::TopLevel; place these next to the existing classify_help assertions
in the classify_help_distinguishes_top_level_command_and_none test.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@Cargo.toml`:
- Line 3: Cargo.toml currently pins version = "1.2.0" but other version-bearing
manifests are missing or inconsistent; update all manifests to match this
release: add or update the "version": "1.2.0" field in package.json,
pyproject.toml (project.version or tool.poetry/version),
.codex-plugin/plugin.json, gemini-extension.json and add a "version": "1.2.0"
key to .claude-plugin/plugin.json; also update README.md to reference 1.2.0 and
add/update the version-.*-blue badge to reflect 1.2.0; keep existing entries in
CHANGELOG.md, mcpb/manifest.json and server.json as-is if they already show
1.2.0.

In `@src/cli/help.rs`:
- Around line 515-534: classify_help only recognizes two-token nested paths from
NESTED_CATALOG, but CATALOG includes "cortex setup doctor [--json]" and there is
no corresponding NestedCommandDoc for the "setup doctor" path, so "setup doctor
--help" falls back to generic help; add a NestedCommandDoc entry for the "setup
doctor" path (matching the usage string in CATALOG) to NESTED_CATALOG (or update
classify_help to accept single-token subcommands under "setup"), ensuring the
new NestedCommandDoc has path "setup doctor", summary and usage matching the
advertised CATALOG entry so classify_help can return the nested target for that
subcommand.
- Around line 826-838: The positionals collection logic incorrectly treats
option values as positional arguments; update the code that builds positionals
(the scan iterator used to produce positionals) to first consume recognized
pre-command global options and their values (e.g., "--server" and "--token"
which take a following value) as well as standalone flags, so that values like
"http://127.0.0.1:3100" are not included; then run the existing nested lookup
(nested_lookup) and single-command branch (is_known => HelpRequest::Command) on
the filtered positionals. Ensure you reference the same symbols: scan,
positionals, nested_lookup, is_known, and HelpRequest::Command when implementing
the pre-scan/filtering.

---

Outside diff comments:
In `@src/cli/help_tests.rs`:
- Around line 112-137: Add regression assertions around classify_help to lock in
nested-help behavior: using the same v helper, assert that
classify_help(&v(&["ai", "--help"])) returns HelpRequest::TopLevel; assert that
classify_help(&v(&["setup", "doctor", "--help"])) returns
HelpRequest::Command("setup doctor".to_string()); and assert that
classify_help(&v(&["--server", "URL", "db", "status", "--help"])) returns
HelpRequest::TopLevel; place these next to the existing classify_help assertions
in the classify_help_distinguishes_top_level_command_and_none test.

In `@src/cli/help.rs`:
- Around line 197-217: The AI subcommands list in the usage array used by
render_command("ai") is missing the new commands (ai similar, ai ask-history, ai
incident-context), so add those three strings into the usage array (the same
format as the other entries) so render_command("ai") will include them; verify
that the entries match their names in NESTED_CATALOG to keep help in sync with
the implemented commands.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: f4177597-8ed4-4cb8-b7d2-d134dca38f38

📥 Commits

Reviewing files that changed from the base of the PR and between 813ee80 and f8d18fc.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock and included by **/*

📒 Files selected for processing (38)

• CHANGELOG.md
• Cargo.toml
• docs/rollout.md
• docs/runbooks/deploy.md
• mcpb/manifest.json
• server.json
• src/cli.rs
• src/cli/args.rs
• src/cli/args/ai.rs
• src/cli/commands/anomalies.rs
• src/cli/commands/apps.rs
• src/cli/commands/clock_skew.rs
• src/cli/commands/compare.rs
• src/cli/commands/host_state.rs
• src/cli/commands/notify.rs
• src/cli/commands/sig.rs
• src/cli/commands/silent_hosts.rs
• src/cli/dispatch_ai.rs
• src/cli/dispatch_db.rs
• src/cli/dispatch_tests.rs
• src/cli/help.rs
• src/cli/help_tests.rs
• src/cli/output_ai_more.rs
• src/cli/output_common.rs
• src/cli/output_common_tests.rs
• src/cli/output_logs.rs
• src/cli/parse.rs
• src/cli/parse_admin.rs
• src/cli/parse_ai.rs
• src/cli/parse_ai_more.rs
• src/cli/parse_ai_more_tests.rs
• src/cli/parse_ai_tests.rs
• src/cli/parse_command_log.rs
• src/cli/parse_tests.rs
• src/cli/suggest.rs
• src/cli/suggest_tests.rs
• src/main.rs
• src/main_tests.rs

[cubic-dev-ai]

1 issue found across 6 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>