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

[LittleCoinCoin]

This PR introduces a comprehensive refactoring of the Hatch CLI system, delivering three major improvements: a modular backend architecture, a unified user experience with consistent output formatting, and complete documentation alignment with the new implementation.

---

🏗️ Architecture Backend Refactoring

Modular CLI Architecture

Transformation: Monolithic cli_hatch.py (2,994 LOC) → Modular package structure

The CLI has been restructured from a single 3,000-line file into a structured package:

hatch/cli/
├── __init__.py          # Package exports
├── __main__.py          # Entry point & routing
├── cli_env.py           # Environment commands
├── cli_mcp.py           # MCP host configuration commands
├── cli_package.py       # Package management commands
├── cli_system.py        # System commands (create, validate)
└── cli_utils.py         # Shared utilities & infrastructure

Benefits:

• Clear separation of concerns by command domain
• Simplified testing with isolated handler modules
• Easier maintenance and feature additions
• Reduced cognitive load for contributors

Unified Adapter Architecture (MCP Host Configuration)

Transformation: Inheritance-based host models → Adapter-based unified model

Replaced the legacy inheritance hierarchy with a modern adapter pattern:

Before:

• 8 host-specific model classes (ClaudeServerConfig, VSCodeServerConfig, etc.)
• from_omni() conversion methods scattered across models
• HOST_MODEL_REGISTRY for dynamic model lookup
• 10-step extension process for new hosts

After:

• Single MCPServerConfig unified model with all fields
• BaseAdapter protocol with 3 core methods: validate(), serialize(), get_supported_fields()
• AdapterRegistry for host-adapter mapping
• 4-step extension process for new hosts
• Clean separation: CLI → Adapter → Strategy → Files

Impact:

• Eliminated: 28 legacy test files (8,902 lines)
• Created: 48 new tests in 3-tier structure (unit/integration/regression)
• Simplified: Host extension process reduced from 10 to 4 steps
• Documented: 742 lines of architecture and extension guides

---

🎨 User-Facing UX Normalization

Unified Output Rendering System

Core Infrastructure: ResultReporter class handles ALL CLI output for consistency

Key Features:

• Tense-aware output: Present tense for prompts ([CREATE]), past tense for results ([CREATED])
• Semantic color coding: HCL color palette with 8 semantic categories (Green=constructive, Red=destructive, etc.)
• True color support: 24-bit RGB with automatic 16-color fallback
• Accessibility: NO_COLOR environment variable, TTY detection, Unicode fallback (✓/✗ → +/x)
• Nested consequences: Resource-level and field-level change tracking

Standardized Command Outputs

List Commands (Tabular Format)

All list commands now use TableFormatter for consistent, aligned output:

hatch mcp list servers

MCP Servers:
  Server               Host                 Hatch     Environment
  ──────────────────────────────────────────────────────────────────
  ac-context-engine    kiro                 ❌        -
  weather              claude-desktop       ❌        -
  database             claude-desktop       ✅        dev

Features:

• Auto-width calculation with 2-space column separation
• JSON output support (--json)
• Regex filtering (--pattern for env/server, --host for host filtering)
• Consistent column ordering across all list commands
• Hatch-managed status shown with ✅/❌ emojis

Show Commands (Hierarchical Format)

New detailed view commands with hierarchical structure:

hatch mcp show servers --host claude-desktop

═══════════════════════════════════════════════════════════════════════════════
MCP Host: claude-desktop
  Config Path: ~/.config/Claude/claude_desktop_config.json
  Last Modified: 2026-02-04 14:30:22
  Backup Available: Yes (3 backups)

  Configured Servers (2):
    weather (Not Hatch-managed)
      Command: python -m weather_server
      Environment Variables:
        API_KEY: ****** (hidden)
    
    database (Hatch-managed: dev)
      Command: node db-server.js
      Args: --port 5432

Features:

• Bold + amber highlighting for entity names (weather, database, claude-desktop)
• 2-space indentation hierarchy
• Sensitive data masking (KEY, SECRET, TOKEN, PASSWORD, CREDENTIAL patterns)
• 79-character separator line (═)
• Comprehensive detail display with backup information

Mutation Commands (Preview → Confirm → Result)

Consistent flow for all mutation operations:

hatch mcp configure weather --command "python" --args "-m weather" --host claude-desktop

hatch mcp configure:
  [CONFIGURE] Server 'weather' on 'claude-desktop'
    [UPDATE] command: None → 'python'
    [UPDATE] args: None → ['-m', 'weather']
Proceed? [y/N]: y
[SUCCESS] Operation completed:
  [CONFIGURED] Server 'weather' on 'claude-desktop'
    [UPDATED] command: None → 'python'
    [UPDATED] args: None → ['-m', 'weather']
  [CREATED] Backup: ~/.hatch/mcp_host_config_backups/claude-desktop/claude_desktop_config.json.claude-desktop.YYYYMMDD_HHMMSS_NNNNNN

Error & Warning Formatting

Unified error handling across all commands:

• ValidationError exception class for structured validation errors
• HatchArgumentParser with formatted error messages
• format_validation_error(), format_warning(), format_info() utilities
• Consistent [ERROR], [WARNING], [INFO] prefixes with semantic colors

Coverage: 77 error/warning/info instances normalized across 4 CLI modules

New Commands & Features

New Commands:

• hatch env show <name> - Detailed environment view with hierarchical structure
• hatch env list hosts - List environment/host/server deployments
• hatch env list servers - List environment servers with deployment status
• hatch mcp show hosts [<host>] - Detailed host configuration view
• hatch mcp show servers [<server>] - Detailed server view across hosts

New Flags:

• --dry-run - Preview changes without execution (env use, env create, package add commands)
• --json - Machine-readable JSON output (all list commands)
• --pattern - Regex filtering for environments (env list)
• --env / -e - Filter by environment name (env list hosts/servers)
• --host - Filter by host name (mcp list servers, env list servers)
• --server - Filter by server name (mcp list hosts, env list hosts)

New Confirmation Prompts:

• hatch env remove - Requires confirmation before deletion
• hatch package remove - Requires confirmation before deletion
• All mutation commands support --yes / -y for auto-approval

Deprecated Commands (with stderr warnings and migration guidance):

• hatch mcp discover servers → Use hatch mcp list servers
• hatch package list → Use hatch env list (shows packages inline with environment info)

HCL Color Palette

Semantic color categories with true color support:

Color	Hex	Usage
Green	#80C990	CREATE, ADD, CONFIGURE, INSTALL, INITIALIZE
Blue	#A3B8EF	RESTORE
Red	#EFA6A2	REMOVE, DELETE, CLEAN
Yellow	#C8C874	SET, UPDATE
Magenta	#E6A3DC	SYNC
Cyan	#50CACD	VALIDATE
Gray	#808080	SKIP, EXISTS, UNCHANGED
Amber	#A69460	Entity name highlighting

Accessibility:

• Equal perceived brightness across all colors
• Automatic fallback to 16-color palette when true color unavailable
• NO_COLOR environment variable support
• TTY detection for automatic color disabling

---

📚 Documentation Updates

Comprehensive Documentation Alignment

Scope: 31 files updated across tutorials, guides, and API reference

Categories:

1. CLI Reference (CLIReference.md)

   • Updated all command syntax to match current implementation
   • Added new commands: env show, env list hosts/servers, mcp show hosts/servers
   • Marked deprecated commands with migration guidance
   • Fixed all output format examples

2. Tutorials (4 tutorial series)

   • 01-getting-started: Fixed env list output format, package verification commands
   • 02-environments: Updated env list output, added new list hosts/servers commands
   • 03-author-package: Fixed validation output format
   • 04-mcp-host-configuration: Fixed command syntax, environment synchronization examples

3. Getting Started Guide

   • Added quick reference section for viewing commands
   • Updated command examples with current syntax

4. MCP Host Configuration Guide

   • Added section on viewing host configurations
   • Updated with new show commands

5. Developer Documentation

   • CLI Architecture (new): 295-line guide covering modular architecture, handler patterns, testing
   • Adding CLI Commands (new): 550-line implementation guide with step-by-step examples
   • Component Architecture: Updated with CLI module structure
   • API Reference: Restructured from monolithic to modular (7 new module docs)

Verification: All command syntax and output formats verified against implementation code

---

🧪 Testing

Test Coverage

CLI UX Tests:

• Regression: 119 tests (color logic, consequence types, result reporter, table formatter, error formatting)
• Integration: 47 tests (CLI handler integration with ResultReporter)
• Total: 166 tests, all passing

MCP Architecture Tests:

• Unit: 20 tests (adapter protocol, config model, registry)
• Integration: 14 tests (adapter serialization for all 8 hosts)
• Regression: 14 tests (field filtering invariants)
• Total: 48 tests, all passing

Overall: 214 tests passing

Test Strategy

Behavioral contracts over output strings:

# ✅ Good: Test behavior
assert reporter.consequences[0].type == ConsequenceType.CREATE
assert len(reporter.consequences) == 2

# ❌ Bad: Test output strings
assert "[CREATE]" in output

---

🎯 Migration Guide

Breaking Changes

None - All existing commands remain functional. Deprecated commands emit warnings to stderr but continue to work.

For Users

User-Facing Commands (emit warnings, still functional):

1. hatch mcp discover servers → Migrate to hatch mcp list servers
2. hatch package list → Migrate to hatch env list (shows packages inline)

New capabilities:

• Colored output in TTY (disable with NO_COLOR=1)
• --dry-run flag for preview mode
• --json flag for machine-readable output
• Better error messages with suggestions
• New show commands for detailed views
• Confirmation prompts for destructive operations (env remove, package remove)

For Developers

Developer APIs (emit DeprecationWarning):

1. hatch.cli_hatch module → Import from hatch.cli package instead (removal in v0.9.0)
2. display_report() function → Use ResultReporter.add_from_conversion_report() instead

Handler Pattern (all handlers follow this):

def handle_command(args: Namespace) -> int:
    # 1. Create reporter
    reporter = ResultReporter("hatch command", dry_run=args.dry_run)
    
    # 2. Add consequences
    reporter.add(ConsequenceType.CREATE, "Resource 'name'")
    
    # 3. Dry-run early exit
    if dry_run:
        reporter.report_result()
        return EXIT_SUCCESS
    
    # 4. Confirmation prompt
    if not request_confirmation("Proceed?", args.auto_approve):
        format_info("Operation cancelled")
        return EXIT_SUCCESS
    
    # 5. Execute operation
    result = perform_operation()
    
    # 6. Report result or error
    if result.success:
        reporter.report_result()
        return EXIT_SUCCESS
    else:
        reporter.report_error("Operation failed", details=[...])
        return EXIT_ERROR

Adapter Pattern (for new MCP hosts):

@register_adapter("new-host")
class NewHostAdapter(BaseAdapter):
    def validate(self, config: MCPServerConfig) -> None:
        # Host-specific validation
        pass
    
    def serialize(self, config: MCPServerConfig) -> Dict[str, Any]:
        # Convert to host format
        return {...}
    
    def get_supported_fields(self) -> Set[str]:
        # Declare field support
        return UNIVERSAL_FIELDS | {"custom_field"}

---

🔗 Related Documentation

• Architecture: docs/articles/devs/architecture/cli_architecture.md
• Implementation Guide: docs/articles/devs/implementation_guides/adding_cli_commands.md
• MCP Architecture: docs/articles/devs/architecture/mcp_host_configuration.md
• Extension Guide: docs/articles/devs/implementation_guides/mcp_host_configuration_extension.md
• CLI Reference: docs/articles/users/CLIReference.md