Skip to content

Commit a3152e1

Browse files
LittleCoinCoinLittleCoinCoin
committed
docs(devs): add CLI architecture and implementation guide
- Add cli_architecture.md documenting modular CLI design - Add adding_cli_commands.md with step-by-step implementation guide - Update architecture index to link CLI architecture - Update implementation guides index to link CLI commands guide - Add CLI components section to component_architecture.md All content based on actual codebase analysis (no assumptions). Addresses critical gaps identified in gap analysis report 26.
1 parent 2ac1058 commit a3152e1

File tree

5 files changed

+925
-0
lines changed

5 files changed

+925
-0
lines changed

‎docs/articles/devs/architecture/cli_architecture.md‎

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,295 @@
1+
# CLI Architecture
2+
3+
This article documents the architectural design of Hatch's command-line interface, which underwent a significant refactoring from a monolithic structure to a modular, handler-based architecture.
4+
5+
## Overview
6+
7+
The Hatch CLI provides a comprehensive interface for managing MCP server packages, environments, and host configurations. The architecture emphasizes:
8+
9+
- **Modularity**: Commands organized into focused handler modules
10+
- **Consistency**: Unified output formatting across all commands
11+
- **Extensibility**: Easy addition of new commands and features
12+
- **Testability**: Clear separation of concerns for unit testing
13+
14+
## Architecture Components
15+
16+
### Entry Point (`hatch/cli/__main__.py`)
17+
18+
The entry point module serves as the routing layer:
19+
20+
1. **Argument Parsing**: Uses `argparse` with custom `HatchArgumentParser` for formatted error messages
21+
2. **Manager Initialization**: Creates shared `HatchEnvironmentManager` and `MCPHostConfigurationManager` instances
22+
3. **Manager Attachment**: Attaches managers to the `args` namespace for handler access
23+
4. **Command Routing**: Routes parsed commands to appropriate handler modules
24+
25+
**Key Pattern**:
26+
```python
27+
# Managers initialized once and shared across handlers
28+
env_manager = HatchEnvironmentManager(...)
29+
mcp_manager = MCPHostConfigurationManager()
30+
31+
# Attached to args for handler access
32+
args.env_manager = env_manager
33+
args.mcp_manager = mcp_manager
34+
35+
# Routed to handlers
36+
return _route_env_command(args)
37+
```
38+
39+
### Handler Modules
40+
41+
Commands are organized into four domain-specific handler modules:
42+
43+
#### `cli_env.py` - Environment Management
44+
Handles environment lifecycle and Python environment operations:
45+
- `handle_env_create()`: Create new environments
46+
- `handle_env_remove()`: Remove environments with confirmation
47+
- `handle_env_list()`: List environments with table output
48+
- `handle_env_use()`: Set current environment
49+
- `handle_env_current()`: Show current environment
50+
- `handle_env_show()`: Detailed hierarchical environment view
51+
- `handle_env_list_hosts()`: Environment/host/server deployments
52+
- `handle_env_list_servers()`: Environment/server/host deployments
53+
- `handle_env_python_*()`: Python environment operations
54+
55+
#### `cli_package.py` - Package Management
56+
Handles package installation and synchronization:
57+
- `handle_package_add()`: Add packages to environments
58+
- `handle_package_remove()`: Remove packages with confirmation
59+
- `handle_package_list()`: List packages (deprecated - use `env list`)
60+
- `handle_package_sync()`: Synchronize package MCP servers to hosts
61+
- `_configure_packages_on_hosts()`: Shared configuration logic
62+
63+
#### `cli_mcp.py` - MCP Host Configuration
64+
Handles MCP host platform configuration and backup:
65+
- `handle_mcp_discover_hosts()`: Detect available host platforms
66+
- `handle_mcp_list_hosts()`: Host-centric server listing
67+
- `handle_mcp_list_servers()`: Server-centric host listing
68+
- `handle_mcp_show_hosts()`: Detailed host configurations
69+
- `handle_mcp_show_servers()`: Detailed server configurations
70+
- `handle_mcp_configure()`: Configure servers on hosts
71+
- `handle_mcp_backup_*()`: Backup management operations
72+
- `handle_mcp_remove_*()`: Server and host removal
73+
- `handle_mcp_sync()`: Synchronize configurations
74+
75+
#### `cli_system.py` - System Operations
76+
Handles package creation and validation:
77+
- `handle_create()`: Generate package templates
78+
- `handle_validate()`: Validate package structure
79+
80+
### Shared Utilities (`cli_utils.py`)
81+
82+
The utilities module provides infrastructure used across all handlers:
83+
84+
#### Color System
85+
- **`Color` enum**: HCL color palette with true color support and 16-color fallback
86+
- **Dual-tense colors**: Dim colors for prompts (present tense), bright colors for results (past tense)
87+
- **Semantic mapping**: Colors mapped to action categories (green=constructive, red=destructive, etc.)
88+
- **`_colors_enabled()`**: Respects `NO_COLOR` environment variable and TTY detection
89+
90+
#### ConsequenceType System
91+
- **`ConsequenceType` enum**: Action types with dual-tense labels
92+
- **Prompt labels**: Present tense for confirmation (e.g., "CREATE")
93+
- **Result labels**: Past tense for execution (e.g., "CREATED")
94+
- **Color association**: Each type has prompt and result colors
95+
- **Categories**: Constructive, Recovery, Destructive, Modification, Transfer, Informational, No-op
96+
97+
#### ResultReporter
98+
Unified rendering system for all CLI output:
99+
100+
**Key Features**:
101+
- Tracks consequences (actions to be performed)
102+
- Generates confirmation prompts (present tense, dim colors)
103+
- Reports execution results (past tense, bright colors)
104+
- Supports nested consequences (resource → field level)
105+
- Handles dry-run mode with suffix labels
106+
- Provides error and partial success reporting
107+
108+
**Usage Pattern**:
109+
```python
110+
reporter = ResultReporter("hatch env create", dry_run=False)
111+
reporter.add(ConsequenceType.CREATE, "Environment 'dev'")
112+
reporter.add(ConsequenceType.CREATE, "Python environment (3.11)")
113+
114+
# Show prompt and get confirmation
115+
prompt = reporter.report_prompt()
116+
if prompt:
117+
print(prompt)
118+
if not request_confirmation("Proceed?"):
119+
return EXIT_SUCCESS
120+
121+
# Execute operation...
122+
123+
# Report results
124+
reporter.report_result()
125+
```
126+
127+
#### TableFormatter
128+
Aligned table output for list commands:
129+
130+
**Features**:
131+
- Fixed and auto-calculated column widths
132+
- Left/right/center alignment support
133+
- Automatic truncation with ellipsis
134+
- Consistent header and separator rendering
135+
136+
**Usage Pattern**:
137+
```python
138+
columns = [
139+
ColumnDef(name="Name", width=20),
140+
ColumnDef(name="Status", width=10),
141+
ColumnDef(name="Count", width="auto", align="right"),
142+
]
143+
formatter = TableFormatter(columns)
144+
formatter.add_row(["my-env", "active", "5"])
145+
print(formatter.render())
146+
```
147+
148+
#### Error Formatting
149+
- **`ValidationError`**: Structured validation errors with field and suggestion
150+
- **`format_validation_error()`**: Formatted error output with color
151+
- **`format_info()`**: Info messages with [INFO] prefix
152+
- **`format_warning()`**: Warning messages with [WARNING] prefix
153+
154+
#### Parsing Utilities
155+
- **`parse_env_vars()`**: Parse KEY=VALUE environment variables
156+
- **`parse_header()`**: Parse KEY=VALUE HTTP headers
157+
- **`parse_input()`**: Parse VS Code input variable definitions
158+
- **`parse_host_list()`**: Parse comma-separated hosts or 'all'
159+
- **`get_package_mcp_server_config()`**: Extract MCP config from package metadata
160+
161+
## Handler Signature Convention
162+
163+
All handlers follow a consistent signature:
164+
165+
```python
166+
def handle_command(args: Namespace) -> int:
167+
"""Handle 'hatch command' command.
168+
169+
Args:
170+
args: Namespace with:
171+
- env_manager: HatchEnvironmentManager instance
172+
- mcp_manager: MCPHostConfigurationManager instance (if needed)
173+
- <command-specific arguments>
174+
175+
Returns:
176+
Exit code (0 for success, 1 for error)
177+
"""
178+
```
179+
180+
**Key Invariants**:
181+
- Managers accessed via `args.env_manager` and `args.mcp_manager`
182+
- Return `EXIT_SUCCESS` (0) on success, `EXIT_ERROR` (1) on failure
183+
- Use `ResultReporter` for unified output
184+
- Handle dry-run mode consistently
185+
- Request confirmation for destructive operations
186+
187+
## Output Formatting Standards
188+
189+
### Mutation Commands
190+
Commands that modify state follow this pattern:
191+
192+
1. **Build consequences**: Add all actions to `ResultReporter`
193+
2. **Show prompt**: Display present-tense preview with dim colors
194+
3. **Request confirmation**: Use `request_confirmation()` unless auto-approved
195+
4. **Execute**: Perform the actual operations
196+
5. **Report results**: Display past-tense results with bright colors
197+
198+
### List Commands
199+
Commands that display data use `TableFormatter`:
200+
201+
1. **Define columns**: Specify widths and alignment
202+
2. **Add rows**: Populate with data
203+
3. **Render**: Print formatted table with headers and separator
204+
205+
### Show Commands
206+
Commands that display detailed views use hierarchical output:
207+
208+
1. **Header**: Entity name with `highlight()` for emphasis
209+
2. **Metadata**: Key-value pairs with indentation
210+
3. **Sections**: Grouped related information
211+
4. **Separators**: Use `═` for visual separation between entities
212+
213+
## Exit Code Standards
214+
215+
- **`EXIT_SUCCESS` (0)**: Operation completed successfully
216+
- **`EXIT_ERROR` (1)**: Operation failed or validation error
217+
- **Partial success**: Return `EXIT_ERROR` but use `report_partial_success()`
218+
219+
## Design Principles
220+
221+
### Separation of Concerns
222+
- **Routing**: `__main__.py` handles argument parsing and routing only
223+
- **Business logic**: Handler modules implement command logic
224+
- **Presentation**: `cli_utils.py` provides formatting infrastructure
225+
- **Domain logic**: Managers (`HatchEnvironmentManager`, `MCPHostConfigurationManager`) handle state
226+
227+
### DRY (Don't Repeat Yourself)
228+
- Shared utilities in `cli_utils.py` eliminate duplication
229+
- `ResultReporter` provides consistent output across all commands
230+
- `TableFormatter` standardizes list output
231+
- Parsing utilities handle common argument formats
232+
233+
### Consistency
234+
- All handlers follow the same signature pattern
235+
- All mutation commands use `ResultReporter`
236+
- All list commands use `TableFormatter`
237+
- All errors use structured formatting
238+
239+
### Testability
240+
- Handlers are pure functions (input → output)
241+
- Managers injected via `args` namespace (dependency injection)
242+
- Clear separation between CLI and business logic
243+
- Utilities are independently testable
244+
245+
## Command Organization
246+
247+
### Namespace Structure
248+
```
249+
hatch
250+
├── create <name> # System: Package template creation
251+
├── validate <path> # System: Package validation
252+
├── env # Environment management
253+
│ ├── create <name>
254+
│ ├── remove <name>
255+
│ ├── list [hosts|servers]
256+
│ ├── use <name>
257+
│ ├── current
258+
│ ├── show <name>
259+
│ └── python
260+
│ ├── init
261+
│ ├── info
262+
│ ├── remove
263+
│ ├── shell
264+
│ └── add-hatch-mcp
265+
├── package # Package management
266+
│ ├── add <name>
267+
│ ├── remove <name>
268+
│ ├── list (deprecated)
269+
│ └── sync <name>
270+
└── mcp # MCP host configuration
271+
├── discover
272+
│ ├── hosts
273+
│ └── servers
274+
├── list
275+
│ ├── hosts
276+
│ └── servers
277+
├── show
278+
│ ├── hosts
279+
│ └── servers
280+
├── configure <host> <server>
281+
├── remove
282+
│ ├── server <name>
283+
│ └── host <name>
284+
├── sync
285+
└── backup
286+
├── restore <host>
287+
├── list <host>
288+
└── clean <host>
289+
```
290+
291+
## Related Documentation
292+
293+
- [Adding CLI Commands](../implementation_guides/adding_cli_commands.md): Step-by-step guide for adding new commands
294+
- [Component Architecture](./component_architecture.md): Overall system architecture
295+
- [CLI Reference](../../users/CLIReference.md): User-facing command documentation

‎docs/articles/devs/architecture/component_architecture.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,71 @@ This article is about:
108108
- Multiple registry source support
109109
- Package relationship analysis
110110

111+
### CLI Components
112+
113+
#### Entry Point (`hatch/cli/__main__.py`)
114+
115+
**Responsibilities:**
116+
117+
- Command-line argument parsing and validation
118+
- Manager initialization and dependency injection
119+
- Command routing to appropriate handler modules
120+
- Top-level error handling and exit code management
121+
122+
**Key Features:**
123+
124+
- Custom `HatchArgumentParser` with formatted error messages
125+
- Shared manager instances (HatchEnvironmentManager, MCPHostConfigurationManager)
126+
- Modular command routing to handler modules
127+
- Consistent argument structure across all commands
128+
129+
#### Handler Modules (`hatch/cli/cli_*.py`)
130+
131+
**Responsibilities:**
132+
133+
- Domain-specific command implementation
134+
- Business logic orchestration using managers
135+
- User interaction and confirmation prompts
136+
- Output formatting using shared utilities
137+
138+
**Handler Modules:**
139+
140+
- **cli_env.py** - Environment lifecycle and Python environment operations
141+
- **cli_package.py** - Package installation, removal, and synchronization
142+
- **cli_mcp.py** - MCP host configuration, discovery, and backup
143+
- **cli_system.py** - System-level operations (package creation, validation)
144+
145+
**Key Features:**
146+
147+
- Consistent handler signature: `(args: Namespace) -> int`
148+
- Unified output formatting via ResultReporter
149+
- Dry-run mode support for mutation commands
150+
- Confirmation prompts for destructive operations
151+
152+
#### Shared Utilities (`hatch/cli/cli_utils.py`)
153+
154+
**Responsibilities:**
155+
156+
- Unified output formatting infrastructure
157+
- Color system with true color support and TTY detection
158+
- Table formatting for list commands
159+
- Error formatting and validation utilities
160+
161+
**Key Components:**
162+
163+
- **Color System** - HCL color palette with semantic mapping
164+
- **ConsequenceType** - Dual-tense action labels (prompt/result)
165+
- **ResultReporter** - Unified rendering for mutation commands
166+
- **TableFormatter** - Aligned table output for list commands
167+
- **Error Formatting** - Structured validation and error messages
168+
169+
**Key Features:**
170+
171+
- Respects NO_COLOR environment variable
172+
- True color (24-bit) with 16-color fallback
173+
- Consistent output across all commands
174+
- Nested consequence support (resource → field level)
175+
111176
### Installation System Components
112177

113178
#### DependencyInstallerOrchestrator (`hatch/installers/dependency_installation_orchestrator.py`)
@@ -157,6 +222,18 @@ This article is about:
157222

158223
## Component Data Flow
159224

225+
### CLI Command Flow
226+
227+
`User Input → __main__.py (Argument Parsing) → Handler Module → Manager(s) → Business Logic → ResultReporter → User Output`
228+
229+
1. User executes CLI command with arguments
230+
2. `__main__.py` parses arguments using argparse
231+
3. Managers (HatchEnvironmentManager, MCPHostConfigurationManager) are initialized
232+
4. Command is routed to appropriate handler module
233+
5. Handler orchestrates business logic using manager methods
234+
6. ResultReporter formats output with consistent styling
235+
7. Exit code returned to shell
236+
160237
### Environment Creation Flow
161238

162239
`CLI Command → HatchEnvironmentManager → PythonEnvironmentManager → Environment Metadata`
@@ -287,5 +364,6 @@ This article is about:
287364
## Related Documentation
288365

289366
- [System Overview](./system_overview.md) - High-level architecture introduction
367+
- [CLI Architecture](./cli_architecture.md) - Detailed CLI design and patterns
290368
- [Implementation Guides](../implementation_guides/index.md) - Technical implementation guidance for specific components
291369
- [Development Processes](../development_processes/index.md) - Development workflow and testing standards

0 commit comments

Comments
 (0)