# pyproject.toml exists with modern configuration
# Installation: uv pip install -e ".[dev]"
# ✅ Already using uv - No changes needed

Best Practice:
  Interactive: User-friendly prompts for discovery
  Non-Interactive: Flags for automation (CI/CD)
  Both: Always support both modes

SuperClaude Current State:
  ✅ Interactive: Two-stage selection (MCP + Framework)
  ✅ Non-Interactive: --components flag support
  ✅ Automation: --yes flag for CI/CD

Best Practice:
  - Validate input immediately
  - Show clear error messages
  - Retry loop until valid
  - Don't make users restart process

SuperClaude Current State:
  ⚠️ Custom validation in Menu class
  ❌ No automatic retry for invalid API keys
  ❌ Manual validation code throughout

# Manual input validation
def prompt_api_key(service_name: str, env_var: str) -> Optional[str]:
    prompt_text = f"Enter {service_name} API key ({env_var}): "
    key = getpass.getpass(prompt_text).strip()

    if not key:
        print(f"{Colors.YELLOW}No API key provided. {service_name} will not be configured.{Colors.RESET}")
        return None

    # Manual validation - no retry loop
    return key

from rich.prompt import Prompt

def prompt_api_key(service_name: str, env_var: str) -> Optional[str]:
    """Prompt for API key with automatic validation and retry"""
    key = Prompt.ask(
        f"Enter {service_name} API key ({env_var})",
        password=True,  # Hide input
        default=None  # Allow skip
    )

    if not key:
        console.print(f"[yellow]Skipping {service_name} configuration[/yellow]")
        return None

    # Automatic retry for invalid format (example for Tavily)
    if env_var == "TAVILY_API_KEY" and not key.startswith("tvly-"):
        console.print("[red]Invalid Tavily API key format (must start with 'tvly-')[/red]")
        return prompt_api_key(service_name, env_var)  # Retry

    return key

Best Practice:
  - Start simple, reveal complexity progressively
  - Group related options
  - Provide context-aware help

SuperClaude Current State:
  ✅ Two-stage selection (simple → detailed)
  ✅ Stage 1: Optional MCP servers
  ✅ Stage 2: Framework components
  🟢 Excellent progressive disclosure design

Best Practice:
  - Use colors for semantic meaning
  - Magenta/Cyan for headers
  - Green for success, Red for errors
  - Yellow for warnings
  - Gray for secondary info

SuperClaude Current State:
  ✅ Colors module with semantic colors
  ✅ Header styling with cyan
  ⚠️ Custom color codes (manual ANSI)
  🟡 Could use Rich markup for cleaner code

# Manual ANSI color codes
Colors.CYAN + "text" + Colors.RESET

# Clean markup syntax
console.print("[cyan]text[/cyan]")
console.print("[bold green]Success![/bold green]")

Best Practice:
  - Catch specific exception types
  - Avoid bare except clauses
  - Let unexpected exceptions propagate

SuperClaude Current State:
  ✅ Specific exception handling in installer.py
  ✅ ValueError for dependency errors
  ✅ Proper exception propagation

except Exception as e:
    self.logger.error(f"Error installing {component_name}: {e}")
    self.failed_components.add(component_name)
    return False

Best Practice:
  - Declarative validation over imperative
  - Type-based validation
  - Automatic error messages

SuperClaude Current State:
  ❌ Manual validation throughout
  ❌ No Pydantic models for config
  🟢 Opportunity for improvement

# Manual validation in multiple places
if not component_name:
    raise ValueError("Component name required")
if component_name not in self.components:
    raise ValueError(f"Unknown component: {component_name}")

from pydantic import BaseModel, Field, validator

class InstallationConfig(BaseModel):
    """Installation configuration with automatic validation"""
    components: List[str] = Field(..., min_items=1)
    install_dir: Path = Field(default=Path.home() / ".claude")
    force: bool = False
    dry_run: bool = False
    selected_mcp_servers: List[str] = []

    @validator('install_dir')
    def validate_install_dir(cls, v):
        """Ensure installation directory is within user home"""
        home = Path.home().resolve()
        try:
            v.resolve().relative_to(home)
        except ValueError:
            raise ValueError(f"Installation must be inside user home: {home}")
        return v

    @validator('components')
    def validate_components(cls, v):
        """Validate component names"""
        valid_components = {'core', 'modes', 'commands', 'agents', 'mcp', 'mcp_docs'}
        invalid = set(v) - valid_components
        if invalid:
            raise ValueError(f"Unknown components: {invalid}")
        return v

# Usage
config = InstallationConfig(
    components=["core", "mcp"],
    install_dir=Path("/Users/kazuki/.claude")
)  # Automatic validation on construction

Best Practice:
  - Use context managers for resource handling
  - Ensure cleanup even on error
  - try-finally or with statements

SuperClaude Current State:
  ✅ tempfile.TemporaryDirectory context manager
  ✅ Proper cleanup in backup creation

with tempfile.TemporaryDirectory() as temp_dir:
    # Backup logic
    # Automatic cleanup on exit

Strength: Interactive two-stage installation (better than all three)
Weakness: Custom UI code (300+ lines vs framework primitives)
Opportunity: Reduce maintenance burden via rich/typer

# Add to pyproject.toml
[project.dependencies]
typer = {version = ">=0.9.0", extras = ["all"]}  # Includes rich

# setup/cli/base.py - Current (argparse)
def create_parser():
    parser = argparse.ArgumentParser()
    subparsers = parser.add_subparsers()
    # ...

# New (typer)
import typer
from rich.console import Console

app = typer.Typer(
    name="superclaude",
    help="SuperClaude Framework CLI",
    add_completion=True  # Automatic shell completion
)
console = Console()

@app.command()
def install(
    components: Optional[List[str]] = typer.Option(None, help="Components to install"),
    install_dir: Path = typer.Option(Path.home() / ".claude", help="Installation directory"),
    force: bool = typer.Option(False, "--force", help="Force reinstallation"),
    dry_run: bool = typer.Option(False, "--dry-run", help="Simulate installation"),
    yes: bool = typer.Option(False, "--yes", "-y", help="Auto-confirm prompts"),
    verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose logging"),
):
    """Install SuperClaude framework components"""
    # Implementation

# Before: setup/utils/ui.py (300+ lines custom code)
display_header("Title", "Subtitle")
display_success("Message")
progress = ProgressBar(total=10)

# After: Rich native features
from rich.console import Console
from rich.progress import Progress
from rich.panel import Panel

console = Console()

# Headers
console.print(Panel("Title\nSubtitle", style="cyan bold"))

# Success
console.print("[bold green]✓[/bold green] Message")

# Progress
with Progress() as progress:
    task = progress.add_task("Installing...", total=10)
    # ...

# Before: Custom Menu class (setup/utils/ui.py:100-180)
menu = Menu("Select options:", options, multi_select=True)
selections = menu.display()

# After: typer + questionary (optional) OR rich.prompt
from rich.prompt import Prompt, Confirm
import questionary

# Simple prompt
name = Prompt.ask("Enter your name")

# Confirmation
if Confirm.ask("Continue?"):
    # ...

# Multi-select (questionary for advanced)
selected = questionary.checkbox(
    "Select components:",
    choices=["core", "modes", "commands", "agents"]
).ask()

# Before: Dict[str, Any] everywhere
config: Dict[str, Any] = {...}

# After: Pydantic models
from pydantic import BaseModel

class InstallConfig(BaseModel):
    components: List[str]
    install_dir: Path
    force: bool = False
    dry_run: bool = False

config = InstallConfig(components=["core"], install_dir=Path("/..."))
# Automatic validation, type hints, IDE completion

# New file: setup/models/config.py
from pydantic import BaseModel, Field, validator
from pathlib import Path
from typing import List, Optional

class InstallationConfig(BaseModel):
    """Type-safe installation configuration with automatic validation"""

    components: List[str] = Field(
        ...,
        min_items=1,
        description="List of components to install"
    )

    install_dir: Path = Field(
        default=Path.home() / ".claude",
        description="Installation directory"
    )

    force: bool = Field(
        default=False,
        description="Force reinstallation of existing components"
    )

    dry_run: bool = Field(
        default=False,
        description="Simulate installation without making changes"
    )

    selected_mcp_servers: List[str] = Field(
        default=[],
        description="MCP servers to configure"
    )

    no_backup: bool = Field(
        default=False,
        description="Skip backup creation"
    )

    @validator('install_dir')
    def validate_install_dir(cls, v):
        """Ensure installation directory is within user home"""
        home = Path.home().resolve()
        try:
            v.resolve().relative_to(home)
        except ValueError:
            raise ValueError(
                f"Installation must be inside user home directory: {home}"
            )
        return v

    @validator('components')
    def validate_components(cls, v):
        """Validate component names against registry"""
        valid = {'core', 'modes', 'commands', 'agents', 'mcp', 'mcp_docs'}
        invalid = set(v) - valid
        if invalid:
            raise ValueError(f"Unknown components: {', '.join(invalid)}")
        return v

    @validator('selected_mcp_servers')
    def validate_mcp_servers(cls, v):
        """Validate MCP server names"""
        valid_servers = {
            'sequential-thinking', 'context7', 'magic', 'playwright',
            'serena', 'morphllm', 'morphllm-fast-apply', 'tavily',
            'chrome-devtools', 'airis-mcp-gateway'
        }
        invalid = set(v) - valid_servers
        if invalid:
            raise ValueError(f"Unknown MCP servers: {', '.join(invalid)}")
        return v

    class Config:
        # Enable JSON schema generation
        schema_extra = {
            "example": {
                "components": ["core", "modes", "mcp"],
                "install_dir": "/Users/username/.claude",
                "force": False,
                "dry_run": False,
                "selected_mcp_servers": ["sequential-thinking", "context7"]
            }
        }

# Before: Manual validation
if not components:
    raise ValueError("No components selected")
if "unknown" in components:
    raise ValueError("Unknown component")

# After: Automatic validation
try:
    config = InstallationConfig(
        components=["core", "unknown"],  # ❌ Validation error
        install_dir=Path("/tmp/bad")  # ❌ Outside user home
    )
except ValidationError as e:
    console.print(f"[red]Configuration error:[/red]")
    console.print(e)
    # Clear, formatted error messages

# Generic errors
logger.error(f"Error installing {component_name}: {e}")

from rich.panel import Panel
from rich.text import Text

def display_installation_error(component: str, error: Exception):
    """Display detailed, actionable error message"""

    # Error context
    error_type = type(error).__name__
    error_msg = str(error)

    # Actionable suggestions based on error type
    suggestions = {
        "PermissionError": [
            "Check write permissions for installation directory",
            "Run with appropriate permissions",
            f"Try: chmod +w {install_dir}"
        ],
        "FileNotFoundError": [
            "Ensure all required files are present",
            "Try reinstalling the package",
            "Check for corrupted installation"
        ],
        "ValueError": [
            "Verify configuration settings",
            "Check component dependencies",
            "Review installation logs for details"
        ]
    }

    # Build rich error display
    error_text = Text()
    error_text.append("Installation failed for ", style="bold red")
    error_text.append(component, style="bold yellow")
    error_text.append("\n\n")
    error_text.append(f"Error type: {error_type}\n", style="cyan")
    error_text.append(f"Message: {error_msg}\n\n", style="white")

    if error_type in suggestions:
        error_text.append("💡 Suggestions:\n", style="bold cyan")
        for suggestion in suggestions[error_type]:
            error_text.append(f"  • {suggestion}\n", style="white")

    console.print(Panel(error_text, title="Installation Error", border_style="red"))

from rich.prompt import Prompt
import re

API_KEY_PATTERNS = {
    "TAVILY_API_KEY": r"^tvly-[A-Za-z0-9_-]{32,}$",
    "OPENAI_API_KEY": r"^sk-[A-Za-z0-9]{32,}$",
    "ANTHROPIC_API_KEY": r"^sk-ant-[A-Za-z0-9_-]{32,}$",
}

def prompt_api_key_with_validation(
    service_name: str,
    env_var: str,
    required: bool = False
) -> Optional[str]:
    """Prompt for API key with format validation and retry"""

    pattern = API_KEY_PATTERNS.get(env_var)

    while True:
        key = Prompt.ask(
            f"Enter {service_name} API key ({env_var})",
            password=True,
            default=None if not required else ...
        )

        if not key:
            if not required:
                console.print(f"[yellow]Skipping {service_name} configuration[/yellow]")
                return None
            else:
                console.print(f"[red]API key required for {service_name}[/red]")
                continue

        # Validate format if pattern exists
        if pattern and not re.match(pattern, key):
            console.print(
                f"[red]Invalid {service_name} API key format[/red]\n"
                f"[yellow]Expected pattern: {pattern}[/yellow]"
            )
            if not Confirm.ask("Try again?", default=True):
                return None
            continue

        # Success
        console.print(f"[green]✓[/green] {service_name} API key validated")
        return key

# tests/test_typer_cli.py
from typer.testing import CliRunner
from setup.cli.typer_cli import app

runner = CliRunner()

def test_install_command():
    """Test install command with typer"""
    result = runner.invoke(app, ["install", "--help"])
    assert result.exit_code == 0
    assert "Install SuperClaude" in result.output

def test_install_with_components():
    """Test component selection"""
    result = runner.invoke(app, [
        "install",
        "--components", "core", "modes",
        "--dry-run"
    ])
    assert result.exit_code == 0
    assert "core" in result.output
    assert "modes" in result.output

def test_pydantic_validation():
    """Test configuration validation"""
    from setup.models.config import InstallationConfig
    from pydantic import ValidationError
    import pytest

    # Valid config
    config = InstallationConfig(
        components=["core"],
        install_dir=Path.home() / ".claude"
    )
    assert config.components == ["core"]

    # Invalid component
    with pytest.raises(ValidationError):
        InstallationConfig(components=["invalid_component"])

    # Invalid install dir (outside user home)
    with pytest.raises(ValidationError):
        InstallationConfig(
            components=["core"],
            install_dir=Path("/etc/superclaude")  # ❌ Outside user home
        )

# tests/integration/test_installer_workflow.py
def test_full_installation_workflow():
    """Test complete installation flow"""
    runner = CliRunner()

    with runner.isolated_filesystem():
        # Simulate user input
        result = runner.invoke(app, [
            "install",
            "--components", "core", "modes",
            "--yes",  # Auto-confirm
            "--dry-run"  # Don't actually install
        ])

        assert result.exit_code == 0
        assert "Installation complete" in result.output

def test_api_key_validation():
    """Test API key format validation"""
    # Valid Tavily key
    key = "tvly-" + "x" * 32
    assert validate_api_key("TAVILY_API_KEY", key) == True

    # Invalid format
    key = "invalid"
    assert validate_api_key("TAVILY_API_KEY", key) == False