# Project Plan: Comprehensive Help Command (`help all`)
## Overview
Implement a `help all` subcommand that displays the complete CLI help hierarchy for omni-dev in a single output, eliminating the need to run multiple help commands.
## Goals
- Provide complete CLI documentation in one command
- Show all subcommands, options, and usage patterns
- Maintain clear hierarchy and formatting
- Enable easy documentation generation and golden testing
## Current CLI Structure
```
omni-dev
├── git
│ ├── commit
│ │ ├── message
│ │ │ ├── view [RANGE]
│ │ │ └── amend <YAML_FILE>
│ └── branch
│ └── info [BASE_BRANCH]
└── help [COMMAND]
```
## Implementation Plan
### Phase 1: Command Structure Design
1. **Add Help Command Category**
- Create new `HelpCommand` struct in `src/cli/mod.rs`
- Add `Help(HelpCommand)` to main `Commands` enum
- Support both `help` and `help all` syntax
2. **Command Parsing**
- `help` - show main help (existing behavior)
- `help all` - show comprehensive help tree
- `help <subcommand>` - show specific subcommand help (existing behavior)
### Phase 2: Help Generation Engine
1. **Help Tree Structure**
- Create `HelpNode` struct to represent command hierarchy
- Implement recursive help collection from clap
- Format with proper indentation and hierarchy
2. **Output Format**
```
omni-dev - A comprehensive development toolkit
USAGE:
omni-dev <COMMAND>
COMMANDS:
git Git-related operations
help Print help information
---
omni-dev git - Git-related operations
USAGE:
omni-dev git <COMMAND>
COMMANDS:
commit Commit-related operations
branch Branch-related operations
[... continues for all subcommands ...]
```
### Phase 3: Implementation Details
#### 3.1 File Structure
- `src/cli/help.rs` - New help command module
- `src/cli/mod.rs` - Updated to include help commands
- Update imports and exports
#### 3.2 Core Components
1. **HelpCommand Struct**
```rust
#[derive(Parser)]
pub struct HelpCommand {
#[command(subcommand)]
pub command: Option<HelpSubcommands>,
}
#[derive(Subcommand)]
pub enum HelpSubcommands {
All,
}
```
2. **Help Generator**
```rust
pub struct HelpGenerator {
app: Command,
}
impl HelpGenerator {
pub fn new() -> Self { ... }
pub fn generate_all_help(&self) -> String { ... }
fn collect_help_recursive(&self, cmd: &Command, prefix: &str) -> Vec<String> { ... }
}
```
3. **Help Formatting**
- Clear section separators
- Consistent indentation (2 spaces per level)
- Command path breadcrumbs
- Proper spacing between sections
### Phase 4: Integration
1. **Update Main CLI**
- Add `Help(HelpCommand)` to `Commands` enum
- Implement execution logic in `Cli::execute()`
- Maintain backward compatibility with existing help
2. **Error Handling**
- Graceful fallback if help generation fails
- Clear error messages for malformed help requests
### Phase 5: Testing & Documentation
1. **Unit Tests**
- Test help tree generation
- Verify output format consistency
- Test all command variations
2. **Integration Tests**
- Golden tests for complete help output
- Verify help content matches actual commands
3. **Documentation Updates**
- Update README.md with new help command
- Add examples to CHANGELOG.md
## Technical Considerations
### Clap Integration
- Use `clap::Command::get_subcommands()` for traversal
- Leverage `clap::Command::render_help()` for formatting
- Maintain clap's built-in help styling
### Performance
- Cache help content on first generation
- Lazy evaluation of help tree
- Minimal memory overhead
### Extensibility
- Design for easy addition of new subcommands
- Support custom help sections
- Allow help filtering/search in future
## Success Criteria
1. ✅ `omni-dev help all` shows complete CLI hierarchy
2. ✅ Output is well-formatted and readable
3. ✅ All existing help functionality preserved
4. ✅ Golden tests validate output consistency
5. ✅ Documentation updated with examples
## Future Enhancements
- `help all --format json` for machine-readable output
- `help search <term>` for command discovery
- Interactive help browser
- Man page generation from help output
## Timeline
- Phase 1-2: 1-2 hours (command structure + help engine)
- Phase 3: 2-3 hours (implementation)
- Phase 4: 1 hour (integration)
- Phase 5: 1-2 hours (testing + docs)
**Total Estimated Time: 5-8 hours**
## Dependencies
- No new external dependencies required
- Uses existing `clap` functionality
- Compatible with current CLI architecture