Skip to content

Commit 1157922

Browse files
LittleCoinCoinLittleCoinCoin
authored
Merge pull request #44 from LittleCoinCoin/dev
CLI Architecture Refactoring & UX Normalization (WIP v0.7.2)
2 parents a8f546e + 12a22c0 commit 1157922

File tree

108 files changed

+15827
-13738
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

108 files changed

+15827
-13738
lines changed

‎__reports__/CLI-refactoring/05-documentation_deprecation_analysis_v0.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Documentation Deprecation Analysis: CLI Refactoring Impact
2+
3+
**Date**: 2026-01-01
4+
**Phase**: Post-Implementation Documentation Review
5+
**Scope**: Identifying deprecated documentation after CLI handler-based architecture refactoring
6+
**Reference**: `__design__/cli-refactoring-milestone-v0.7.2-dev.1.md`
7+
8+
---
9+
10+
## Executive Summary
11+
12+
The CLI refactoring from monolithic `cli_hatch.py` (2,850 LOC) to handler-based architecture in `hatch/cli/` package has rendered several documentation references outdated. This report identifies affected files and specifies required updates.
13+
14+
**Architecture Change Summary:**
15+
```
16+
BEFORE: AFTER:
17+
hatch/cli_hatch.py (2,850 LOC) hatch/cli/
18+
├── __init__.py (57 LOC)
19+
├── __main__.py (840 LOC)
20+
├── cli_utils.py (270 LOC)
21+
├── cli_mcp.py (1,222 LOC)
22+
├── cli_env.py (375 LOC)
23+
├── cli_package.py (552 LOC)
24+
└── cli_system.py (92 LOC)
25+
26+
hatch/cli_hatch.py (136 LOC) ← backward compat shim
27+
```
28+
29+
---
30+
31+
## Affected Documentation Files
32+
33+
### Category 1: API Documentation (HIGH PRIORITY)
34+
35+
| File | Issue | Impact |
36+
|------|-------|--------|
37+
| `docs/articles/api/cli.md` | References `hatch.cli_hatch` only | mkdocstrings generates incomplete API docs |
38+
39+
**Current Content:**
40+
```markdown
41+
# CLI Module
42+
::: hatch.cli_hatch
43+
```
44+
45+
**Required Update:** Expand to document the full `hatch.cli` package structure with all submodules.
46+
47+
---
48+
49+
### Category 2: User Documentation (HIGH PRIORITY)
50+
51+
| File | Line | Issue |
52+
|------|------|-------|
53+
| `docs/articles/users/CLIReference.md` | 3 | States "implemented in `hatch/cli_hatch.py`" |
54+
55+
**Current Content (Line 3):**
56+
```markdown
57+
This document is a compact reference of all Hatch CLI commands and options implemented in `hatch/cli_hatch.py` presented as tables for quick lookup.
58+
```
59+
60+
**Required Update:** Reference the new `hatch/cli/` package structure.
61+
62+
---
63+
64+
### Category 3: Developer Implementation Guides (HIGH PRIORITY)
65+
66+
| File | Lines | Issue |
67+
|------|-------|-------|
68+
| `docs/articles/devs/implementation_guides/mcp_host_configuration_extension.md` | 605, 613-626 | References `cli_hatch.py` for CLI integration |
69+
70+
**Affected Sections:**
71+
72+
1. **Line 605** - "Add CLI arguments in `cli_hatch.py`"
73+
2. **Lines 613-626** - CLI Integration for Host-Specific Fields section
74+
75+
**Current Content:**
76+
```markdown
77+
4. **Add CLI arguments** in `cli_hatch.py` (see next section)
78+
...
79+
1. **Update function signature** in `handle_mcp_configure()`:
80+
```python
81+
def handle_mcp_configure(
82+
# ... existing params ...
83+
your_field: Optional[str] = None, # Add your field
84+
):
85+
```
86+
```
87+
88+
**Required Update:**
89+
- Argument parsing → `hatch/cli/__main__.py`
90+
- Handler modifications → `hatch/cli/cli_mcp.py`
91+
92+
---
93+
94+
### Category 4: Architecture Documentation (MEDIUM PRIORITY)
95+
96+
| File | Line | Issue |
97+
|------|------|-------|
98+
| `docs/articles/devs/architecture/mcp_host_configuration.md` | 158 | References `cli_hatch.py` |
99+
100+
**Current Content (Line 158):**
101+
```markdown
102+
1. Extend `handle_mcp_configure()` function signature in `cli_hatch.py`
103+
```
104+
105+
**Required Update:** Reference new module locations.
106+
107+
---
108+
109+
### Category 5: Architecture Diagrams (MEDIUM PRIORITY)
110+
111+
| File | Line | Issue |
112+
|------|------|-------|
113+
| `docs/resources/diagrams/architecture.puml` | 9 | Shows CLI as single `cli_hatch` component |
114+
115+
**Current Content:**
116+
```plantuml
117+
Container_Boundary(cli, "CLI Layer") {
118+
Component(cli_hatch, "CLI Interface", "Python", "Command-line interface\nArgument parsing and validation")
119+
}
120+
```
121+
122+
**Required Update:** Reflect modular CLI architecture with handler modules.
123+
124+
---
125+
126+
### Category 6: Instruction Templates (LOW PRIORITY)
127+
128+
| File | Lines | Issue |
129+
|------|-------|-------|
130+
| `cracking-shells-playbook/instructions/documentation-api.instructions.md` | 37-41 | Uses `hatch/cli_hatch.py` as example |
131+
132+
**Current Content:**
133+
```markdown
134+
**For a module `hatch/cli_hatch.py`, create `docs/articles/api/cli.md`:**
135+
```markdown
136+
# CLI Module
137+
::: hatch.cli_hatch
138+
```
139+
```
140+
141+
**Required Update:** Update example to show new CLI package pattern.
142+
143+
---
144+
145+
## Files NOT to Modify
146+
147+
| Category | Files | Reason |
148+
|----------|-------|--------|
149+
| Historical Analysis | `__reports__/CLI-refactoring/00-04*.md` | Document pre-refactoring state |
150+
| Design Documents | `__design__/cli-refactoring-*.md` | Document refactoring plan |
151+
| Handover Documents | `__design__/handover-*.md` | Document session context |
152+
153+
---
154+
155+
## Update Strategy
156+
157+
### Handler Location Mapping
158+
159+
| Handler/Function | Old Location | New Location |
160+
|------------------|--------------|--------------|
161+
| `main()` | `hatch.cli_hatch` | `hatch.cli.__main__` |
162+
| `handle_mcp_configure()` | `hatch.cli_hatch` | `hatch.cli.cli_mcp` |
163+
| `handle_mcp_*()` | `hatch.cli_hatch` | `hatch.cli.cli_mcp` |
164+
| `handle_env_*()` | `hatch.cli_hatch` | `hatch.cli.cli_env` |
165+
| `handle_package_*()` | `hatch.cli_hatch` | `hatch.cli.cli_package` |
166+
| `handle_create()`, `handle_validate()` | `hatch.cli_hatch` | `hatch.cli.cli_system` |
167+
| `parse_host_list()`, utilities | `hatch.cli_hatch` | `hatch.cli.cli_utils` |
168+
| Argument parsing | `hatch.cli_hatch` | `hatch.cli.__main__` |
169+
170+
### Backward Compatibility Note
171+
172+
`hatch/cli_hatch.py` remains as a backward compatibility shim that re-exports all public symbols. External consumers can still import from `hatch.cli_hatch`, but new code should use `hatch.cli.*`.
173+
174+
---
175+
176+
## Implementation Checklist
177+
178+
- [x] Update `docs/articles/api/cli.md` - Expand API documentation
179+
- [x] Update `docs/articles/users/CLIReference.md` - Fix intro paragraph
180+
- [x] Update `docs/articles/devs/implementation_guides/mcp_host_configuration_extension.md` - Fix CLI integration section
181+
- [x] Update `docs/articles/devs/architecture/mcp_host_configuration.md` - Fix CLI reference
182+
- [x] Update `docs/resources/diagrams/architecture.puml` - Update CLI component
183+
- [x] Update `cracking-shells-playbook/instructions/documentation-api.instructions.md` - Update example
184+
185+
---
186+
187+
## Risk Assessment
188+
189+
| Risk | Likelihood | Impact | Mitigation |
190+
|------|------------|--------|------------|
191+
| Broken mkdocstrings generation | High | Medium | Test docs build after changes |
192+
| Developer confusion from outdated guides | Medium | High | Prioritize implementation guide updates |
193+
| Diagram regeneration issues | Low | Low | Verify PlantUML syntax |
194+

‎cracking-shells-playbook‎

‎docs/articles/api/cli.md‎

Lines changed: 0 additions & 3 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

0 commit comments

Comments
 (0)