Skip to content

Commit 60e3c3e

Browse files
LittleCoinCoinLittleCoinCoin
committed
Merge branch 'docs/cli-ux-update' into dev
2 parents 724c968 + a3ae286 commit 60e3c3e

20 files changed

Lines changed: 1453 additions & 94 deletions

File tree

‎docs/articles/api/cli.md‎

Lines changed: 0 additions & 84 deletions
This file was deleted.

‎docs/articles/api/cli/env.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Environment Handlers
2+
3+
The environment handlers module (`cli_env.py`) contains handlers for environment management commands.
4+
5+
## Overview
6+
7+
This module provides handlers for:
8+
9+
- **Basic Environment Management**: Create, remove, list, use, current, show
10+
- **Python Environment Management**: Initialize, info, remove, shell, add-hatch-mcp
11+
- **Environment Listings**: List hosts, list servers (deployment views)
12+
13+
## Handler Functions
14+
15+
### Basic Environment Management
16+
- `handle_env_create()`: Create new environments
17+
- `handle_env_remove()`: Remove environments with confirmation
18+
- `handle_env_list()`: List environments with table output
19+
- `handle_env_use()`: Set current environment
20+
- `handle_env_current()`: Show current environment
21+
- `handle_env_show()`: Detailed hierarchical environment view
22+
23+
### Python Environment Management
24+
- `handle_env_python_init()`: Initialize Python virtual environment
25+
- `handle_env_python_info()`: Show Python environment information
26+
- `handle_env_python_remove()`: Remove Python virtual environment
27+
- `handle_env_python_shell()`: Launch interactive Python shell
28+
- `handle_env_python_add_hatch_mcp()`: Add hatch_mcp_server wrapper
29+
30+
### Environment Listings
31+
- `handle_env_list_hosts()`: Environment/host/server deployments
32+
- `handle_env_list_servers()`: Environment/server/host deployments
33+
34+
## Handler Signature
35+
36+
All handlers follow the standard signature:
37+
38+
```python
39+
def handle_env_command(args: Namespace) -> int:
40+
"""Handle 'hatch env command' command.
41+
42+
Args:
43+
args: Namespace with:
44+
- env_manager: HatchEnvironmentManager instance
45+
- <command-specific arguments>
46+
47+
Returns:
48+
Exit code (0 for success, 1 for error)
49+
"""
50+
```
51+
52+
## Module Reference
53+
54+
::: hatch.cli.cli_env
55+
options:
56+
show_source: true
57+
show_root_heading: true
58+
heading_level: 2

‎docs/articles/api/cli/index.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# CLI Package
2+
3+
The CLI package provides the command-line interface for Hatch, organized into domain-specific handler modules following a handler-based architecture pattern.
4+
5+
## Architecture Overview
6+
7+
The CLI underwent a significant refactoring from a monolithic structure (`cli_hatch.py`) to a modular, handler-based architecture. This design 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+
### Package Structure
15+
16+
```
17+
hatch/cli/
18+
├── __init__.py # Package exports and main() entry point
19+
├── __main__.py # Argument parsing and command routing
20+
├── cli_utils.py # Shared utilities and constants
21+
├── cli_mcp.py # MCP host configuration handlers
22+
├── cli_env.py # Environment management handlers
23+
├── cli_package.py # Package management handlers
24+
└── cli_system.py # System commands (create, validate)
25+
```
26+
27+
## Module Overview
28+
29+
### Entry Point (`__main__.py`)
30+
The routing layer that parses command-line arguments and delegates to appropriate handler modules. Initializes shared managers and attaches them to the args namespace for handler access.
31+
32+
**Key Components**:
33+
- `HatchArgumentParser`: Custom argument parser with formatted error messages
34+
- Command routing functions
35+
- Manager initialization
36+
37+
### Utilities (`cli_utils.py`)
38+
Shared infrastructure used across all handlers, including:
39+
40+
- **Color System**: HCL color palette with true color support
41+
- **ConsequenceType**: Dual-tense action labels for prompts and results
42+
- **ResultReporter**: Unified rendering for mutation commands
43+
- **TableFormatter**: Aligned table output for list commands
44+
- **Error Formatting**: Structured validation and error messages
45+
46+
### Handler Modules
47+
Domain-specific command implementations:
48+
49+
- **Environment Handlers** (`cli_env.py`): Environment lifecycle and Python environment operations
50+
- **Package Handlers** (`cli_package.py`): Package installation, removal, and synchronization
51+
- **MCP Handlers** (`cli_mcp.py`): MCP host configuration, discovery, and backup
52+
- **System Handlers** (`cli_system.py`): System-level operations (package creation, validation)
53+
54+
## Getting Started
55+
56+
### Programmatic Usage
57+
58+
```python
59+
from hatch.cli import main, EXIT_SUCCESS, EXIT_ERROR
60+
61+
# Run CLI programmatically
62+
exit_code = main()
63+
64+
# Or import specific handlers
65+
from hatch.cli.cli_env import handle_env_create
66+
from hatch.cli.cli_utils import ResultReporter, ConsequenceType
67+
```
68+
69+
### Handler Signature Pattern
70+
71+
All handlers follow a consistent signature:
72+
73+
```python
74+
def handle_command(args: Namespace) -> int:
75+
"""Handle 'hatch command' command.
76+
77+
Args:
78+
args: Namespace with:
79+
- env_manager: HatchEnvironmentManager instance
80+
- mcp_manager: MCPHostConfigurationManager instance (if needed)
81+
- <command-specific arguments>
82+
83+
Returns:
84+
Exit code (0 for success, 1 for error)
85+
"""
86+
# Implementation
87+
return EXIT_SUCCESS
88+
```
89+
90+
## Output Formatting
91+
92+
The CLI uses a unified output formatting system:
93+
94+
### Mutation Commands
95+
Commands that modify state use `ResultReporter`:
96+
97+
```python
98+
reporter = ResultReporter("hatch env create", dry_run=False)
99+
reporter.add(ConsequenceType.CREATE, "Environment 'dev'")
100+
reporter.report_result()
101+
```
102+
103+
### List Commands
104+
Commands that display data use `TableFormatter`:
105+
106+
```python
107+
from hatch.cli.cli_utils import TableFormatter, ColumnDef
108+
109+
columns = [
110+
ColumnDef(name="Name", width=20),
111+
ColumnDef(name="Status", width=10),
112+
]
113+
formatter = TableFormatter(columns)
114+
formatter.add_row(["my-env", "active"])
115+
print(formatter.render())
116+
```
117+
118+
## Backward Compatibility
119+
120+
The old monolithic `hatch.cli_hatch` module has been refactored into the modular structure. For backward compatibility, imports from `hatch.cli_hatch` are still supported but deprecated:
121+
122+
```python
123+
# Old (deprecated, still works):
124+
from hatch.cli_hatch import main, handle_mcp_configure
125+
126+
# New (preferred):
127+
from hatch.cli import main
128+
from hatch.cli.cli_mcp import handle_mcp_configure
129+
```
130+
131+
## Related Documentation
132+
133+
- [CLI Architecture](../../devs/architecture/cli_architecture.md): Detailed architectural design and patterns
134+
- [Adding CLI Commands](../../devs/implementation_guides/adding_cli_commands.md): Step-by-step implementation guide
135+
- [CLI Reference](../../users/CLIReference.md): User-facing command documentation

‎docs/articles/api/cli/main.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Entry Point Module
2+
3+
The entry point module (`__main__.py`) serves as the routing layer for the Hatch CLI, handling argument parsing and command delegation.
4+
5+
## Overview
6+
7+
This module provides:
8+
9+
- Command-line argument parsing using `argparse`
10+
- Custom `HatchArgumentParser` with formatted error messages
11+
- Manager initialization (HatchEnvironmentManager, MCPHostConfigurationManager)
12+
- Command routing to appropriate handler modules
13+
14+
## Module Reference
15+
16+
::: hatch.cli.__main__
17+
options:
18+
show_source: true
19+
show_root_heading: true
20+
heading_level: 2

‎docs/articles/api/cli/mcp.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# MCP Handlers
2+
3+
The MCP handlers module (`cli_mcp.py`) contains handlers for MCP host configuration commands.
4+
5+
## Overview
6+
7+
This module provides handlers for:
8+
9+
- **Discovery**: Detect available MCP host platforms and servers
10+
- **Listing**: Host-centric and server-centric views
11+
- **Show Commands**: Detailed hierarchical views
12+
- **Configuration**: Configure servers on hosts
13+
- **Backup Management**: Restore, list, and clean backups
14+
- **Removal**: Remove servers and hosts
15+
- **Synchronization**: Sync configurations between environments and hosts
16+
17+
## Supported Hosts
18+
19+
- claude-desktop: Claude Desktop application
20+
- claude-code: Claude Code extension
21+
- cursor: Cursor IDE
22+
- vscode: Visual Studio Code with Copilot
23+
- kiro: Kiro IDE
24+
- codex: OpenAI Codex
25+
- lm-studio: LM Studio
26+
- gemini: Google Gemini
27+
28+
## Handler Functions
29+
30+
### Discovery
31+
- `handle_mcp_discover_hosts()`: Detect available MCP host platforms
32+
- `handle_mcp_discover_servers()`: Find MCP servers in packages (deprecated)
33+
34+
### Listing
35+
- `handle_mcp_list_hosts()`: Host-centric server listing (shows all servers on hosts)
36+
- `handle_mcp_list_servers()`: Server-centric host listing (shows all hosts for servers)
37+
38+
### Show Commands
39+
- `handle_mcp_show_hosts()`: Detailed hierarchical view of host configurations
40+
- `handle_mcp_show_servers()`: Detailed hierarchical view of server configurations
41+
42+
### Configuration
43+
- `handle_mcp_configure()`: Configure MCP server on host with all host-specific arguments
44+
45+
### Backup Management
46+
- `handle_mcp_backup_restore()`: Restore configuration from backup
47+
- `handle_mcp_backup_list()`: List available backups
48+
- `handle_mcp_backup_clean()`: Clean old backups based on criteria
49+
50+
### Removal
51+
- `handle_mcp_remove_server()`: Remove server from hosts
52+
- `handle_mcp_remove_host()`: Remove entire host configuration
53+
54+
### Synchronization
55+
- `handle_mcp_sync()`: Synchronize configurations between environments and hosts
56+
57+
## Handler Signature
58+
59+
All handlers follow the standard signature:
60+
61+
```python
62+
def handle_mcp_command(args: Namespace) -> int:
63+
"""Handle 'hatch mcp command' command.
64+
65+
Args:
66+
args: Namespace with:
67+
- env_manager: HatchEnvironmentManager instance
68+
- mcp_manager: MCPHostConfigurationManager instance
69+
- <command-specific arguments>
70+
71+
Returns:
72+
Exit code (0 for success, 1 for error)
73+
"""
74+
```
75+
76+
## Module Reference
77+
78+
::: hatch.cli.cli_mcp
79+
options:
80+
show_source: true
81+
show_root_heading: true
82+
heading_level: 2

0 commit comments

Comments
 (0)