@voodocs/cli 0.3.2 → 0.4.0

package/lib/darkarts/context/ui.py

@@ -0,0 +1,337 @@
+"""@darkarts
+⊢ui:ctx.interactive
+∂{tqdm,contextlib}
+⚠{term:ansi,tqdm:installed,users:visual-feedback}
+⊨{colors→reset,progress→close,confirm→bool,∀output→safe}
+🔒{no-implications}
+⚡{O(1)}
+
+User Interface Utilities
+
+Provides progress indicators, colored output, and user interaction utilities.
+"""
+
+from typing import Optional, Iterator, Any
+from contextlib import contextmanager
+import sys
+
+
+# Check if tqdm is available
+try:
+    from tqdm import tqdm
+    TQDM_AVAILABLE = True
+except ImportError:
+    TQDM_AVAILABLE = False
+    # Fallback: no-op progress bar
+    class tqdm:
+        def __init__(self, *args, **kwargs):
+            self.total = kwargs.get('total', 0)
+            self.n = 0
+        
+        def update(self, n=1):
+            self.n += n
+        
+        def close(self):
+            pass
+        
+        def __enter__(self):
+            return self
+        
+        def __exit__(self, *args):
+            self.close()
+
+
+class Colors:
+    """ANSI color codes for terminal output."""
+    RESET = '\033[0m'
+    RED = '\033[91m'
+    GREEN = '\033[92m'
+    YELLOW = '\033[93m'
+    BLUE = '\033[94m'
+    MAGENTA = '\033[95m'
+    CYAN = '\033[96m'
+    WHITE = '\033[97m'
+    BOLD = '\033[1m'
+    DIM = '\033[2m'
+
+
+def success(message: str) -> None:
+    """
+    Print success message with green checkmark.
+    
+    Args:
+        message: Success message to display
+        
+    Example:
+        >>> success("Context initialized successfully!")
+        ✅ Context initialized successfully!
+    """
+    print(f"{Colors.GREEN}✅ {message}{Colors.RESET}")
+
+
+def error(message: str) -> None:
+    """
+    Print error message with red X.
+    
+    Args:
+        message: Error message to display
+        
+    Example:
+        >>> error("Context file not found")
+        ❌ Context file not found
+    """
+    print(f"{Colors.RED}❌ {message}{Colors.RESET}", file=sys.stderr)
+
+
+def warning(message: str) -> None:
+    """
+    Print warning message with yellow warning sign.
+    
+    Args:
+        message: Warning message to display
+        
+    Example:
+        >>> warning("Git not available, some features disabled")
+        ⚠️  Git not available, some features disabled
+    """
+    print(f"{Colors.YELLOW}⚠️  {message}{Colors.RESET}")
+
+
+def info(message: str) -> None:
+    """
+    Print info message with blue info icon.
+    
+    Args:
+        message: Info message to display
+        
+    Example:
+        >>> info("Context file created at: .voodocs.context")
+        ℹ️  Context file created at: .voodocs.context
+    """
+    print(f"{Colors.BLUE}ℹ️  {message}{Colors.RESET}")
+
+
+def step(message: str) -> None:
+    """
+    Print step message with cyan arrow.
+    
+    Args:
+        message: Step message to display
+        
+    Example:
+        >>> step("Initializing VooDocs context...")
+        ▶️  Initializing VooDocs context...
+    """
+    print(f"{Colors.CYAN}▶️  {message}{Colors.RESET}")
+
+
+def debug(message: str, verbose: bool = False) -> None:
+    """
+    Print debug message (only if verbose=True).
+    
+    Args:
+        message: Debug message to display
+        verbose: If True, print the message
+        
+    Example:
+        >>> debug("Loaded 10 modules from context", verbose=True)
+        🐛 Loaded 10 modules from context
+    """
+    if verbose:
+        print(f"{Colors.DIM}🐛 {message}{Colors.RESET}")
+
+
+@contextmanager
+def progress(description: str, total: Optional[int] = None, verbose: bool = True):
+    """
+    Context manager for progress indication.
+    
+    Args:
+        description: Description of the operation
+        total: Total number of items (None for indeterminate)
+        verbose: If True, show progress bar; if False, just print step
+        
+    Yields:
+        tqdm progress bar or None
+        
+    Example:
+        >>> with progress("Scanning files", total=100, verbose=True) as pbar:
+        ...     for file in files:
+        ...         process(file)
+        ...         if pbar:
+        ...             pbar.update(1)
+    """
+    if verbose and total is not None and TQDM_AVAILABLE:
+        pbar = tqdm(total=total, desc=description, unit="item", ncols=80)
+        try:
+            yield pbar
+        finally:
+            pbar.close()
+    else:
+        # No progress bar, just print the step
+        step(description)
+        yield None
+
+
+def confirm(message: str, default: bool = True) -> bool:
+    """
+    Ask user for confirmation.
+    
+    Args:
+        message: Confirmation message
+        default: Default value if user just presses Enter
+        
+    Returns:
+        True if confirmed, False otherwise
+        
+    Example:
+        >>> if confirm("Overwrite existing file?", default=False):
+        ...     overwrite_file()
+        ❓ Overwrite existing file? [y/N]: y
+        True
+    """
+    default_str = "Y/n" if default else "y/N"
+    try:
+        response = input(f"{Colors.YELLOW}❓ {message} [{default_str}]: {Colors.RESET}").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print()  # New line after ^C
+        return False
+    
+    if not response:
+        return default
+    
+    return response in ['y', 'yes']
+
+
+def prompt(message: str, default: Optional[str] = None, required: bool = True) -> str:
+    """
+    Prompt user for input.
+    
+    Args:
+        message: Prompt message
+        default: Default value if user just presses Enter
+        required: If True, keep asking until non-empty input
+        
+    Returns:
+        User's response or default value
+        
+    Raises:
+        KeyboardInterrupt: If user presses Ctrl+C
+        
+    Example:
+        >>> name = prompt("Project name", default="my-project")
+        Project name [my-project]: 
+        'my-project'
+    """
+    if default is not None:
+        response = input(f"{message} [{default}]: ").strip()
+        return response if response else default
+    else:
+        response = input(f"{message}: ").strip()
+        if required:
+            while not response:
+                warning("This field is required.")
+                response = input(f"{message}: ").strip()
+        return response
+
+
+def print_header(title: str) -> None:
+    """
+    Print a formatted header.
+    
+    Args:
+        title: Header title
+        
+    Example:
+        >>> print_header("VooDocs Context System")
+        
+        ═══════════════════════════════════════════════════════════════
+        VooDocs Context System
+        ═══════════════════════════════════════════════════════════════
+    """
+    width = 80
+    print()
+    print(f"{Colors.BOLD}{'═' * width}{Colors.RESET}")
+    print(f"{Colors.BOLD}{title.center(width)}{Colors.RESET}")
+    print(f"{Colors.BOLD}{'═' * width}{Colors.RESET}")
+    print()
+
+
+def print_section(title: str) -> None:
+    """
+    Print a formatted section header.
+    
+    Args:
+        title: Section title
+        
+    Example:
+        >>> print_section("Project Information")
+        
+        ─── Project Information ────────────────────────────────────────
+    """
+    width = 80
+    title_with_spaces = f" {title} "
+    line = "─" * ((width - len(title_with_spaces)) // 2)
+    print()
+    print(f"{Colors.BOLD}{line}{title_with_spaces}{line}{Colors.RESET}")
+
+
+def print_key_value(key: str, value: str, indent: int = 2) -> None:
+    """
+    Print a key-value pair.
+    
+    Args:
+        key: Key name
+        value: Value
+        indent: Number of spaces to indent
+        
+    Example:
+        >>> print_key_value("Name", "my-project")
+          Name: my-project
+    """
+    spaces = " " * indent
+    print(f"{spaces}{Colors.BOLD}{key}:{Colors.RESET} {value}")
+
+
+def print_list(items: list, indent: int = 2, bullet: str = "•") -> None:
+    """
+    Print a bulleted list.
+    
+    Args:
+        items: List of items to print
+        indent: Number of spaces to indent
+        bullet: Bullet character
+        
+    Example:
+        >>> print_list(["Item 1", "Item 2", "Item 3"])
+          • Item 1
+          • Item 2
+          • Item 3
+    """
+    spaces = " " * indent
+    for item in items:
+        print(f"{spaces}{bullet} {item}")
+
+
+def clear_line() -> None:
+    """Clear the current line in the terminal."""
+    print('\r\033[K', end='')
+
+
+def spinner_frames():
+    """
+    Generator for spinner animation frames.
+    
+    Yields:
+        Spinner frame characters
+        
+    Example:
+        >>> frames = spinner_frames()
+        >>> for _ in range(4):
+        ...     print(next(frames), end='\\r')
+        ...     time.sleep(0.1)
+    """
+    frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+    while True:
+        for frame in frames:
+            yield frame

package/lib/darkarts/context/validation.py

@@ -0,0 +1,311 @@
+"""@darkarts
+⊢validation:ctx.comprehensive
+∂{re,pathlib,errors}
+⚠{name∈fs-safe,v∈semver,path∈rel∨abs}
+⊨{∀validate_*→(⊥⇒raise)∧(⊤⇒norm),deterministic,msg:actionable}
+🔒{validate-input,¬injection,¬fs-attack}
+⚡{O(1)|regex-fast-on-short-str}
+
+Input Validation Utilities
+
+Provides comprehensive validation for user inputs with helpful error messages.
+"""
+
+import re
+from pathlib import Path
+from typing import Optional, List
+from .errors import (
+    InvalidProjectNameError,
+    InvalidVersionError,
+    InvalidPathError
+)
+
+
+def validate_project_name(name: str) -> str:
+    """
+    Validate and normalize project name.
+    
+    Project names must be:
+    - Non-empty
+    - 100 characters or less
+    - Contain only letters, numbers, hyphens, and underscores
+    
+    Args:
+        name: Project name to validate
+        
+    Returns:
+        Normalized project name (stripped of whitespace)
+        
+    Raises:
+        InvalidProjectNameError: If name is invalid
+        
+    Examples:
+        >>> validate_project_name("my-project")
+        'my-project'
+        >>> validate_project_name("  my_project  ")
+        'my_project'
+        >>> validate_project_name("my project!")
+        InvalidProjectNameError: Invalid project name: 'my project!'
+    """
+    name = name.strip()
+    
+    if not name:
+        raise InvalidProjectNameError(name, "Project name cannot be empty")
+    
+    if len(name) > 100:
+        raise InvalidProjectNameError(name, "Project name too long (max 100 characters)")
+    
+    if not re.match(r'^[a-zA-Z0-9_-]+$', name):
+        raise InvalidProjectNameError(
+            name,
+            "Can only contain letters, numbers, hyphens, and underscores"
+        )
+    
+    return name
+
+
+def validate_version(version: str, allow_empty: bool = True) -> str:
+    """
+    Validate version number (semantic versioning).
+    
+    Accepts:
+    - MAJOR.MINOR (e.g., "1.0")
+    - MAJOR.MINOR.PATCH (e.g., "1.0.0")
+    - Empty string if allow_empty=True
+    
+    Args:
+        version: Version string to validate
+        allow_empty: If True, empty string is valid
+        
+    Returns:
+        Validated version string (stripped of whitespace)
+        
+    Raises:
+        InvalidVersionError: If version is invalid
+        
+    Examples:
+        >>> validate_version("1.0.0")
+        '1.0.0'
+        >>> validate_version("1.0")
+        '1.0'
+        >>> validate_version("")
+        ''
+        >>> validate_version("v1.0.0")
+        InvalidVersionError: Invalid version: 'v1.0.0'
+    """
+    version = version.strip()
+    
+    # Allow empty version if specified
+    if not version and allow_empty:
+        return version
+    
+    if not version and not allow_empty:
+        raise InvalidVersionError(version)
+    
+    # Check semantic versioning format (MAJOR.MINOR or MAJOR.MINOR.PATCH)
+    if not re.match(r'^\d+\.\d+(\.\d+)?$', version):
+        raise InvalidVersionError(version)
+    
+    return version
+
+
+def validate_path(path: str, must_exist: bool = False, must_be_dir: bool = False, must_be_file: bool = False) -> Path:
+    """
+    Validate and normalize file path.
+    
+    Args:
+        path: Path string to validate
+        must_exist: If True, path must exist
+        must_be_dir: If True, path must be a directory
+        must_be_file: If True, path must be a file
+        
+    Returns:
+        Normalized Path object (resolved to absolute path)
+        
+    Raises:
+        InvalidPathError: If path is invalid
+        
+    Examples:
+        >>> validate_path("./src")
+        PosixPath('/home/user/project/src')
+        >>> validate_path("", must_exist=True)
+        InvalidPathError: Invalid path: ''
+    """
+    if not path:
+        raise InvalidPathError(path, "Path cannot be empty")
+    
+    try:
+        path_obj = Path(path).resolve()
+    except Exception as e:
+        raise InvalidPathError(path, f"Invalid path format: {e}")
+    
+    if must_exist and not path_obj.exists():
+        raise InvalidPathError(path, "Path does not exist")
+    
+    if must_be_dir and path_obj.exists() and not path_obj.is_dir():
+        raise InvalidPathError(path, "Path must be a directory")
+    
+    if must_be_file and path_obj.exists() and not path_obj.is_file():
+        raise InvalidPathError(path, "Path must be a file")
+    
+    return path_obj
+
+
+def validate_context_structure(data: dict) -> None:
+    """
+    Validate context file structure.
+    
+    Checks for required sections and fields:
+    - versioning.code_version
+    - versioning.context_version
+    - project.name
+    - project.purpose
+    
+    Args:
+        data: Parsed context data dictionary
+        
+    Raises:
+        ValueError: If structure is invalid (with descriptive message)
+        
+    Examples:
+        >>> validate_context_structure({'versioning': {'code_version': '1.0', 'context_version': '1.0'}, 'project': {'name': 'test', 'purpose': 'testing'}})
+        # No exception - valid structure
+        >>> validate_context_structure({})
+        ValueError: Missing required section: versioning
+    """
+    required_sections = ['versioning', 'project']
+    
+    for section in required_sections:
+        if section not in data:
+            raise ValueError(f"Missing required section: {section}")
+    
+    # Validate versioning section
+    versioning = data['versioning']
+    if not isinstance(versioning, dict):
+        raise ValueError("Section 'versioning' must be a dictionary")
+    
+    if 'code_version' not in versioning:
+        raise ValueError("Missing required field: versioning.code_version")
+    if 'context_version' not in versioning:
+        raise ValueError("Missing required field: versioning.context_version")
+    
+    # Validate project section
+    project = data['project']
+    if not isinstance(project, dict):
+        raise ValueError("Section 'project' must be a dictionary")
+    
+    if 'name' not in project:
+        raise ValueError("Missing required field: project.name")
+    if 'purpose' not in project:
+        raise ValueError("Missing required field: project.purpose")
+
+
+def validate_url(url: str, allow_empty: bool = True) -> Optional[str]:
+    """
+    Validate URL format.
+    
+    Args:
+        url: URL string to validate
+        allow_empty: If True, empty string is valid
+        
+    Returns:
+        Validated URL or None if empty and allow_empty=True
+        
+    Raises:
+        ValueError: If URL is invalid
+        
+    Examples:
+        >>> validate_url("https://github.com/user/repo")
+        'https://github.com/user/repo'
+        >>> validate_url("")
+        None
+        >>> validate_url("not-a-url")
+        ValueError: Invalid URL format
+    """
+    url = url.strip()
+    
+    if not url and allow_empty:
+        return None
+    
+    if not url and not allow_empty:
+        raise ValueError("URL cannot be empty")
+    
+    # Basic URL validation (http/https)
+    if not re.match(r'^https?://', url):
+        raise ValueError("Invalid URL format (must start with http:// or https://)")
+    
+    return url
+
+
+def validate_email(email: str, allow_empty: bool = True) -> Optional[str]:
+    """
+    Validate email format.
+    
+    Args:
+        email: Email string to validate
+        allow_empty: If True, empty string is valid
+        
+    Returns:
+        Validated email or None if empty and allow_empty=True
+        
+    Raises:
+        ValueError: If email is invalid
+        
+    Examples:
+        >>> validate_email("user@example.com")
+        'user@example.com'
+        >>> validate_email("")
+        None
+        >>> validate_email("not-an-email")
+        ValueError: Invalid email format
+    """
+    email = email.strip()
+    
+    if not email and allow_empty:
+        return None
+    
+    if not email and not allow_empty:
+        raise ValueError("Email cannot be empty")
+    
+    # Basic email validation
+    if not re.match(r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$', email):
+        raise ValueError("Invalid email format")
+    
+    return email
+
+
+def validate_choice(value: str, choices: List[str], case_sensitive: bool = False) -> str:
+    """
+    Validate that value is one of the allowed choices.
+    
+    Args:
+        value: Value to validate
+        choices: List of allowed values
+        case_sensitive: If True, comparison is case-sensitive
+        
+    Returns:
+        Validated value (original case)
+        
+    Raises:
+        ValueError: If value is not in choices
+        
+    Examples:
+        >>> validate_choice("python", ["python", "typescript", "javascript"])
+        'python'
+        >>> validate_choice("Python", ["python", "typescript"], case_sensitive=False)
+        'Python'
+        >>> validate_choice("rust", ["python", "typescript"])
+        ValueError: Invalid choice: 'rust'. Must be one of: python, typescript
+    """
+    value = value.strip()
+    
+    if case_sensitive:
+        if value not in choices:
+            raise ValueError(f"Invalid choice: '{value}'. Must be one of: {', '.join(choices)}")
+    else:
+        value_lower = value.lower()
+        choices_lower = [c.lower() for c in choices]
+        if value_lower not in choices_lower:
+            raise ValueError(f"Invalid choice: '{value}'. Must be one of: {', '.join(choices)}")
+    
+    return value