CLI Architecture Refactoring & UX Normalization (WIP v0.7.2)

__reports__/CLI-refactoring/05-documentation_deprecation_analysis_v0.md

@@ -0,0 +1,194 @@
+# Documentation Deprecation Analysis: CLI Refactoring Impact
+
+**Date**: 2026-01-01  
+**Phase**: Post-Implementation Documentation Review  
+**Scope**: Identifying deprecated documentation after CLI handler-based architecture refactoring  
+**Reference**: `__design__/cli-refactoring-milestone-v0.7.2-dev.1.md`
+
+---
+
+## Executive Summary
+
+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.
+
+**Architecture Change Summary:**
+```
+BEFORE:                          AFTER:
+hatch/cli_hatch.py (2,850 LOC)   hatch/cli/
+                                 ├── __init__.py      (57 LOC)
+                                 ├── __main__.py      (840 LOC)
+                                 ├── cli_utils.py     (270 LOC)
+                                 ├── cli_mcp.py       (1,222 LOC)
+                                 ├── cli_env.py       (375 LOC)
+                                 ├── cli_package.py   (552 LOC)
+                                 └── cli_system.py    (92 LOC)
+
+                                 hatch/cli_hatch.py   (136 LOC) ← backward compat shim
+```
+
+---
+
+## Affected Documentation Files
+
+### Category 1: API Documentation (HIGH PRIORITY)
+
+| File | Issue | Impact |
+|------|-------|--------|
+| `docs/articles/api/cli.md` | References `hatch.cli_hatch` only | mkdocstrings generates incomplete API docs |
+
+**Current Content:**
+```markdown
+# CLI Module
+::: hatch.cli_hatch
+```
+
+**Required Update:** Expand to document the full `hatch.cli` package structure with all submodules.
+
+---
+
+### Category 2: User Documentation (HIGH PRIORITY)
+
+| File | Line | Issue |
+|------|------|-------|
+| `docs/articles/users/CLIReference.md` | 3 | States "implemented in `hatch/cli_hatch.py`" |
+
+**Current Content (Line 3):**
+```markdown
+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.
+```
+
+**Required Update:** Reference the new `hatch/cli/` package structure.
+
+---
+
+### Category 3: Developer Implementation Guides (HIGH PRIORITY)
+
+| File | Lines | Issue |
+|------|-------|-------|
+| `docs/articles/devs/implementation_guides/mcp_host_configuration_extension.md` | 605, 613-626 | References `cli_hatch.py` for CLI integration |
+
+**Affected Sections:**
+
+1. **Line 605** - "Add CLI arguments in `cli_hatch.py`"
+2. **Lines 613-626** - CLI Integration for Host-Specific Fields section
+
+**Current Content:**
+```markdown
+4. **Add CLI arguments** in `cli_hatch.py` (see next section)
+...
+1. **Update function signature** in `handle_mcp_configure()`:
+```python
+def handle_mcp_configure(
+    # ... existing params ...
+    your_field: Optional[str] = None,  # Add your field
+):
+```
+```
+
+**Required Update:** 
+- Argument parsing → `hatch/cli/__main__.py`
+- Handler modifications → `hatch/cli/cli_mcp.py`
+
+---
+
+### Category 4: Architecture Documentation (MEDIUM PRIORITY)
+
+| File | Line | Issue |
+|------|------|-------|
+| `docs/articles/devs/architecture/mcp_host_configuration.md` | 158 | References `cli_hatch.py` |
+
+**Current Content (Line 158):**
+```markdown
+1. Extend `handle_mcp_configure()` function signature in `cli_hatch.py`
+```
+
+**Required Update:** Reference new module locations.
+
+---
+
+### Category 5: Architecture Diagrams (MEDIUM PRIORITY)
+
+| File | Line | Issue |
+|------|------|-------|
+| `docs/resources/diagrams/architecture.puml` | 9 | Shows CLI as single `cli_hatch` component |
+
+**Current Content:**
+```plantuml
+Container_Boundary(cli, "CLI Layer") {
+    Component(cli_hatch, "CLI Interface", "Python", "Command-line interface\nArgument parsing and validation")
+}
+```
+
+**Required Update:** Reflect modular CLI architecture with handler modules.
+
+---
+
+### Category 6: Instruction Templates (LOW PRIORITY)
+
+| File | Lines | Issue |
+|------|-------|-------|
+| `cracking-shells-playbook/instructions/documentation-api.instructions.md` | 37-41 | Uses `hatch/cli_hatch.py` as example |
+
+**Current Content:**
+```markdown
+**For a module `hatch/cli_hatch.py`, create `docs/articles/api/cli.md`:**
+```markdown
+# CLI Module
+::: hatch.cli_hatch
+```
+```
+
+**Required Update:** Update example to show new CLI package pattern.
+
+---
+
+## Files NOT to Modify
+
+| Category | Files | Reason |
+|----------|-------|--------|
+| Historical Analysis | `__reports__/CLI-refactoring/00-04*.md` | Document pre-refactoring state |
+| Design Documents | `__design__/cli-refactoring-*.md` | Document refactoring plan |
+| Handover Documents | `__design__/handover-*.md` | Document session context |
+
+---
+
+## Update Strategy
+
+### Handler Location Mapping
+
+| Handler/Function | Old Location | New Location |
+|------------------|--------------|--------------|
+| `main()` | `hatch.cli_hatch` | `hatch.cli.__main__` |
+| `handle_mcp_configure()` | `hatch.cli_hatch` | `hatch.cli.cli_mcp` |
+| `handle_mcp_*()` | `hatch.cli_hatch` | `hatch.cli.cli_mcp` |
+| `handle_env_*()` | `hatch.cli_hatch` | `hatch.cli.cli_env` |
+| `handle_package_*()` | `hatch.cli_hatch` | `hatch.cli.cli_package` |
+| `handle_create()`, `handle_validate()` | `hatch.cli_hatch` | `hatch.cli.cli_system` |
+| `parse_host_list()`, utilities | `hatch.cli_hatch` | `hatch.cli.cli_utils` |
+| Argument parsing | `hatch.cli_hatch` | `hatch.cli.__main__` |
+
+### Backward Compatibility Note
+
+`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.*`.
+
+---
+
+## Implementation Checklist
+
+- [x] Update `docs/articles/api/cli.md` - Expand API documentation
+- [x] Update `docs/articles/users/CLIReference.md` - Fix intro paragraph
+- [x] Update `docs/articles/devs/implementation_guides/mcp_host_configuration_extension.md` - Fix CLI integration section
+- [x] Update `docs/articles/devs/architecture/mcp_host_configuration.md` - Fix CLI reference
+- [x] Update `docs/resources/diagrams/architecture.puml` - Update CLI component
+- [x] Update `cracking-shells-playbook/instructions/documentation-api.instructions.md` - Update example
+
+---
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Broken mkdocstrings generation | High | Medium | Test docs build after changes |
+| Developer confusion from outdated guides | Medium | High | Prioritize implementation guide updates |
+| Diagram regeneration issues | Low | Low | Verify PlantUML syntax |
+

docs/articles/api/cli/env.md

@@ -0,0 +1,58 @@
+# Environment Handlers
+
+The environment handlers module (`cli_env.py`) contains handlers for environment management commands.
+
+## Overview
+
+This module provides handlers for:
+
+- **Basic Environment Management**: Create, remove, list, use, current, show
+- **Python Environment Management**: Initialize, info, remove, shell, add-hatch-mcp
+- **Environment Listings**: List hosts, list servers (deployment views)
+
+## Handler Functions
+
+### Basic Environment Management
+- `handle_env_create()`: Create new environments
+- `handle_env_remove()`: Remove environments with confirmation
+- `handle_env_list()`: List environments with table output
+- `handle_env_use()`: Set current environment
+- `handle_env_current()`: Show current environment
+- `handle_env_show()`: Detailed hierarchical environment view
+
+### Python Environment Management
+- `handle_env_python_init()`: Initialize Python virtual environment
+- `handle_env_python_info()`: Show Python environment information
+- `handle_env_python_remove()`: Remove Python virtual environment
+- `handle_env_python_shell()`: Launch interactive Python shell
+- `handle_env_python_add_hatch_mcp()`: Add hatch_mcp_server wrapper
+
+### Environment Listings
+- `handle_env_list_hosts()`: Environment/host/server deployments
+- `handle_env_list_servers()`: Environment/server/host deployments
+
+## Handler Signature
+
+All handlers follow the standard signature:
+
+```python
+def handle_env_command(args: Namespace) -> int:
+    """Handle 'hatch env command' command.
+
+    Args:
+        args: Namespace with:
+            - env_manager: HatchEnvironmentManager instance
+            - <command-specific arguments>
+
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+```
+
+## Module Reference
+
+::: hatch.cli.cli_env
+    options:
+      show_source: true
+      show_root_heading: true
+      heading_level: 2

docs/articles/api/cli/index.md

@@ -0,0 +1,135 @@
+# CLI Package
+
+The CLI package provides the command-line interface for Hatch, organized into domain-specific handler modules following a handler-based architecture pattern.
+
+## Architecture Overview
+
+The CLI underwent a significant refactoring from a monolithic structure (`cli_hatch.py`) to a modular, handler-based architecture. This design emphasizes:
+
+- **Modularity**: Commands organized into focused handler modules
+- **Consistency**: Unified output formatting across all commands
+- **Extensibility**: Easy addition of new commands and features
+- **Testability**: Clear separation of concerns for unit testing
+
+### Package Structure
+
+```
+hatch/cli/
+├── __init__.py      # Package exports and main() entry point
+├── __main__.py      # Argument parsing and command routing
+├── cli_utils.py     # Shared utilities and constants
+├── cli_mcp.py       # MCP host configuration handlers
+├── cli_env.py       # Environment management handlers
+├── cli_package.py   # Package management handlers
+└── cli_system.py    # System commands (create, validate)
+```
+
+## Module Overview
+
+### Entry Point (`__main__.py`)
+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.
+
+**Key Components**:
+- `HatchArgumentParser`: Custom argument parser with formatted error messages
+- Command routing functions
+- Manager initialization
+
+### Utilities (`cli_utils.py`)
+Shared infrastructure used across all handlers, including:
+
+- **Color System**: HCL color palette with true color support
+- **ConsequenceType**: Dual-tense action labels for prompts and results
+- **ResultReporter**: Unified rendering for mutation commands
+- **TableFormatter**: Aligned table output for list commands
+- **Error Formatting**: Structured validation and error messages
+
+### Handler Modules
+Domain-specific command implementations:
+
+- **Environment Handlers** (`cli_env.py`): Environment lifecycle and Python environment operations
+- **Package Handlers** (`cli_package.py`): Package installation, removal, and synchronization
+- **MCP Handlers** (`cli_mcp.py`): MCP host configuration, discovery, and backup
+- **System Handlers** (`cli_system.py`): System-level operations (package creation, validation)
+
+## Getting Started
+
+### Programmatic Usage
+
+```python
+from hatch.cli import main, EXIT_SUCCESS, EXIT_ERROR
+
+# Run CLI programmatically
+exit_code = main()
+
+# Or import specific handlers
+from hatch.cli.cli_env import handle_env_create
+from hatch.cli.cli_utils import ResultReporter, ConsequenceType
+```
+
+### Handler Signature Pattern
+
+All handlers follow a consistent signature:
+
+```python
+def handle_command(args: Namespace) -> int:
+    """Handle 'hatch command' command.
+
+    Args:
+        args: Namespace with:
+            - env_manager: HatchEnvironmentManager instance
+            - mcp_manager: MCPHostConfigurationManager instance (if needed)
+            - <command-specific arguments>
+
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    # Implementation
+    return EXIT_SUCCESS
+```
+
+## Output Formatting
+
+The CLI uses a unified output formatting system:
+
+### Mutation Commands
+Commands that modify state use `ResultReporter`:
+
+```python
+reporter = ResultReporter("hatch env create", dry_run=False)
+reporter.add(ConsequenceType.CREATE, "Environment 'dev'")
+reporter.report_result()
+```
+
+### List Commands
+Commands that display data use `TableFormatter`:
+
+```python
+from hatch.cli.cli_utils import TableFormatter, ColumnDef
+
+columns = [
+    ColumnDef(name="Name", width=20),
+    ColumnDef(name="Status", width=10),
+]
+formatter = TableFormatter(columns)
+formatter.add_row(["my-env", "active"])
+print(formatter.render())
+```
+
+## Backward Compatibility
+
+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:
+
+```python
+# Old (deprecated, still works):
+from hatch.cli_hatch import main, handle_mcp_configure
+
+# New (preferred):
+from hatch.cli import main
+from hatch.cli.cli_mcp import handle_mcp_configure
+```
+
+## Related Documentation
+
+- [CLI Architecture](../../devs/architecture/cli_architecture.md): Detailed architectural design and patterns
+- [Adding CLI Commands](../../devs/implementation_guides/adding_cli_commands.md): Step-by-step implementation guide
+- [CLI Reference](../../users/CLIReference.md): User-facing command documentation