@voodocs/cli 0.1.1 → 0.2.0

package/lib/darkarts/context/commands.py

@@ -0,0 +1,1688 @@
+"""
+Context System Commands
+
+Implements the command-line interface for the context system.
+"""
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+from .models import create_minimal_context
+from .yaml_utils import (
+    write_context_yaml,
+    read_context_yaml,
+    add_to_gitignore,
+    format_context_as_markdown
+)
+
+
+def get_project_root() -> Path:
+    """
+    Get the project root directory (current working directory).
+    
+    Returns:
+        Path to the project root
+    """
+    return Path.cwd()
+
+
+def get_context_file_path() -> Path:
+    """
+    Get the path to the .voodocs.context file.
+    
+    Returns:
+        Path to .voodocs.context in the project root
+    """
+    return get_project_root() / '.voodocs.context'
+
+
+def context_file_exists() -> bool:
+    """
+    Check if a .voodocs.context file already exists.
+    
+    Returns:
+        True if file exists, False otherwise
+    """
+    return get_context_file_path().exists()
+
+
+def prompt_user(question: str, default: Optional[str] = None, required: bool = True) -> str:
+    """
+    Prompt the user for input with an optional default value.
+    
+    Args:
+        question: The question to ask
+        default: Optional default value
+        required: Whether the field is required
+    
+    Returns:
+        User's response or default value
+    """
+    if default is not None:
+        response = input(f"{question} [{default}]: ").strip()
+        return response if response else default
+    else:
+        response = input(f"{question}: ").strip()
+        if required:
+            while not response:
+                print("This field is required.")
+                response = input(f"{question}: ").strip()
+        return response
+
+
+def prompt_yes_no(question: str, default: bool = True) -> bool:
+    """
+    Prompt the user for a yes/no answer.
+    
+    Args:
+        question: The question to ask
+        default: Default value (True for yes, False for no)
+    
+    Returns:
+        True for yes, False for no
+    """
+    default_str = "Y/n" if default else "y/N"
+    response = input(f"{question} [{default_str}]: ").strip().lower()
+    
+    if not response:
+        return default
+    
+    return response in ['y', 'yes']
+
+
+def detect_code_version() -> Optional[str]:
+    """
+    Try to detect the code version from common files.
+    
+    Checks:
+    - package.json (version field)
+    - pyproject.toml (version field)
+    - setup.py (version argument)
+    - VERSION file
+    
+    Returns:
+        Detected version string or None
+    """
+    project_root = get_project_root()
+    
+    # Try package.json
+    package_json = project_root / 'package.json'
+    if package_json.exists():
+        try:
+            import json
+            with open(package_json, 'r') as f:
+                data = json.load(f)
+                if 'version' in data:
+                    return data['version']
+        except:
+            pass
+    
+    # Try pyproject.toml
+    pyproject_toml = project_root / 'pyproject.toml'
+    if pyproject_toml.exists():
+        try:
+            with open(pyproject_toml, 'r') as f:
+                for line in f:
+                    if line.startswith('version'):
+                        # Extract version from: version = "1.0.0"
+                        version = line.split('=')[1].strip().strip('"\'')
+                        return version
+        except:
+            pass
+    
+    # Try VERSION file
+    version_file = project_root / 'VERSION'
+    if version_file.exists():
+        try:
+            with open(version_file, 'r') as f:
+                return f.read().strip()
+        except:
+            pass
+    
+    return None
+
+
+def detect_repository() -> Optional[str]:
+    """
+    Try to detect the repository URL from git config.
+    
+    Returns:
+        Repository URL or None
+    """
+    try:
+        import subprocess
+        result = subprocess.run(
+            ['git', 'config', '--get', 'remote.origin.url'],
+            capture_output=True,
+            text=True,
+            cwd=get_project_root()
+        )
+        if result.returncode == 0:
+            url = result.stdout.strip()
+            # Convert SSH URL to HTTPS
+            if url.startswith('git@github.com:'):
+                url = url.replace('git@github.com:', 'https://github.com/')
+            if url.endswith('.git'):
+                url = url[:-4]
+            return url
+    except:
+        pass
+    
+    return None
+
+
+def cmd_context_init(force: bool = False) -> int:
+    """
+    Initialize a new .voodocs.context file for the project.
+    
+    Args:
+        force: If True, overwrite existing context file
+    
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    print("🎯 VooDocs Context Initialization")
+    print()
+    
+    # Check if context file already exists
+    if context_file_exists() and not force:
+        print("❌ Error: .voodocs.context already exists in this directory.")
+        print("   Use --force to overwrite the existing file.")
+        return 1
+    
+    # Detect project information
+    detected_version = detect_code_version()
+    detected_repo = detect_repository()
+    
+    print("Let's set up your project context. This will create a .voodocs.context file.")
+    print()
+    
+    # Prompt for project information
+    project_name = prompt_user("Project name")
+    
+    project_purpose = prompt_user("Project purpose (one sentence)")
+    
+    if detected_version:
+        code_version = prompt_user("Current code version", detected_version)
+    else:
+        code_version = prompt_user("Current code version", "1.0.0")
+    
+    # Validate version format
+    if not code_version.count('.') >= 2:
+        print(f"⚠️  Warning: '{code_version}' doesn't look like semantic versioning (MAJOR.MINOR.PATCH)")
+        if not prompt_yes_no("Continue anyway?", default=False):
+            print("Aborted.")
+            return 1
+    
+    if detected_repo:
+        repository = prompt_user("Repository URL (leave empty to skip)", detected_repo, required=False)
+    else:
+        repository = prompt_user("Repository URL (leave empty to skip)", "", required=False)
+    
+    license_name = prompt_user("License (leave empty to skip)", "", required=False)
+    
+    print()
+    print("📝 Configuration Summary:")
+    print(f"  Project Name:    {project_name}")
+    print(f"  Purpose:         {project_purpose}")
+    print(f"  Code Version:    {code_version}")
+    if repository:
+        print(f"  Repository:      {repository}")
+    if license_name:
+        print(f"  License:         {license_name}")
+    print()
+    
+    if not prompt_yes_no("Create context file?", default=True):
+        print("Aborted.")
+        return 1
+    
+    # Create context file
+    try:
+        context = create_minimal_context(
+            project_name=project_name,
+            project_purpose=project_purpose,
+            code_version=code_version,
+            repository=repository if repository else None,
+            license=license_name if license_name else None
+        )
+        
+        context_path = get_context_file_path()
+        write_context_yaml(context, context_path)
+        
+        print()
+        print(f"✅ Created .voodocs.context")
+        print(f"   Context version: {context.versioning.context_version}")
+        print()
+        
+        # Ask about .gitignore
+        if prompt_yes_no("Add .voodocs.context to .gitignore? (recommended for private projects)", default=True):
+            if add_to_gitignore(get_project_root()):
+                print("✅ Added to .gitignore")
+            else:
+                print("ℹ️  Already in .gitignore")
+        
+        print()
+        print("🎉 Context initialized successfully!")
+        print()
+        print("Next steps:")
+        print("  1. Review the context file: voodocs context view")
+        print("  2. Add global invariants to the 'invariants.global' section")
+        print("  3. Document architecture decisions in the 'architecture.decisions' section")
+        print("  4. Update context when making changes: voodocs context update")
+        print()
+        
+        return 0
+        
+    except Exception as e:
+        print(f"❌ Error creating context file: {e}")
+        return 1
+
+
+def cmd_context_view(output_file: Optional[str] = None) -> int:
+    """
+    View the context file as human-readable Markdown.
+    
+    Args:
+        output_file: Optional path to write Markdown output
+    
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    if not context_file_exists():
+        print("❌ Error: No .voodocs.context file found in this directory.")
+        print("   Run 'voodocs context init' to create one.")
+        return 1
+    
+    try:
+        # Read context file
+        context_path = get_context_file_path()
+        data = read_context_yaml(context_path)
+        
+        if not data:
+            print("❌ Error: Failed to read .voodocs.context file.")
+            return 1
+        
+        # Parse and format as Markdown
+        from .yaml_utils import parse_context_file
+        context = parse_context_file(data)
+        markdown = format_context_as_markdown(context)
+        
+        if output_file:
+            # Write to file
+            output_path = Path(output_file)
+            with open(output_path, 'w', encoding='utf-8') as f:
+                f.write(markdown)
+            print(f"✅ Context exported to {output_file}")
+            return 0
+        else:
+            # Print to console
+            print(markdown)
+            return 0
+            
+    except Exception as e:
+        print(f"❌ Error viewing context: {e}")
+        return 1
+
+
+def cmd_context_status() -> int:
+    """
+    Show the current status of the context file.
+    
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    if not context_file_exists():
+        print("❌ No context file found")
+        print("   Run 'voodocs context init' to create one.")
+        return 1
+    
+    try:
+        # Read context file
+        context_path = get_context_file_path()
+        data = read_context_yaml(context_path)
+        
+        if not data:
+            print("❌ Error: Failed to read .voodocs.context file.")
+            return 1
+        
+        # Extract key information
+        versioning = data.get('versioning', {})
+        project = data.get('project', {})
+        invariants = data.get('invariants', {})
+        
+        print("📊 Context Status")
+        print()
+        print(f"Project:         {project.get('name', 'Unknown')}")
+        print(f"Code Version:    {versioning.get('code_version', 'Unknown')}")
+        print(f"Context Version: {versioning.get('context_version', 'Unknown')}")
+        print(f"Last Updated:    {versioning.get('last_updated', 'Unknown')}")
+        print()
+        
+        # Count sections
+        global_invariants = invariants.get('global', [])
+        print(f"Global Invariants:     {len(global_invariants)}")
+        
+        arch_decisions = data.get('architecture', {}).get('decisions', [])
+        print(f"Architecture Decisions: {len(arch_decisions)}")
+        
+        critical_paths = data.get('critical_paths', [])
+        print(f"Critical Paths:        {len(critical_paths)}")
+        
+        known_issues = data.get('known_issues', [])
+        print(f"Known Issues:          {len(known_issues)}")
+        
+        print()
+        print("Use 'voodocs context view' to see the full context.")
+        
+        return 0
+        
+    except Exception as e:
+        print(f"❌ Error reading context: {e}")
+        return 1
+
+
+def cmd_context_update(description: Optional[str] = None) -> int:
+    """
+    Update the context file and increment the minor version.
+    
+    Args:
+        description: Optional description of the changes
+    
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    if not context_file_exists():
+        print("❌ Error: No .voodocs.context file found in this directory.")
+        print("   Run 'voodocs context init' to create one.")
+        return 1
+    
+    try:
+        from datetime import date
+        from .models import Change
+        
+        # Read current context
+        context_path = get_context_file_path()
+        data = read_context_yaml(context_path)
+        
+        if not data:
+            print("❌ Error: Failed to read .voodocs.context file.")
+            return 1
+        
+        # Get current versions
+        versioning = data.get('versioning', {})
+        current_context_version = versioning.get('context_version', '0.0')
+        code_version = versioning.get('code_version', '0.0.0')
+        
+        # Parse context version
+        parts = current_context_version.split('.')
+        if len(parts) != 2:
+            print(f"❌ Error: Invalid context version format: {current_context_version}")
+            return 1
+        
+        major, minor = parts
+        new_minor = int(minor) + 1
+        new_context_version = f"{major}.{new_minor}"
+        
+        print(f"📝 Updating Context")
+        print()
+        print(f"Current version: {current_context_version}")
+        print(f"New version:     {new_context_version}")
+        print()
+        
+        # Prompt for description if not provided
+        if not description:
+            description = prompt_user("Change description", "", required=False)
+            if not description:
+                description = "Context updated"
+        
+        # Update versioning
+        today = date.today().isoformat()
+        data['versioning']['context_version'] = new_context_version
+        data['versioning']['last_updated'] = today
+        
+        # Add change entry
+        if 'changes' not in data:
+            data['changes'] = []
+        
+        # Get Git information if available
+        commit_hash = get_git_commit_hash()
+        author = get_git_author()
+        
+        change_entry = {
+            'type': 'context',
+            'description': description,
+            'date': today,
+            'context_version': new_context_version,
+            'code_version': code_version
+        }
+        
+        if commit_hash:
+            change_entry['commit'] = commit_hash
+        if author:
+            change_entry['author'] = author
+        
+        data['changes'].append(change_entry)
+        
+        # Write updated context
+        from .yaml_utils import parse_context_file
+        context = parse_context_file(data)
+        write_context_yaml(context, context_path)
+        
+        print(f"✅ Context updated to version {new_context_version}")
+        print(f"   Description: {description}")
+        print()
+        
+        return 0
+        
+    except Exception as e:
+        print(f"❌ Error updating context: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+
+
+def cmd_context_sync(code_version: Optional[str] = None, force: bool = False) -> int:
+    """
+    Sync context version with code version (handles major version bumps).
+    
+    Args:
+        code_version: New code version (e.g., "2.0.0")
+        force: Skip confirmation prompt
+    
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    if not context_file_exists():
+        print("❌ Error: No .voodocs.context file found in this directory.")
+        print("   Run 'voodocs context init' to create one.")
+        return 1
+    
+    try:
+        from datetime import date
+        
+        # Read current context
+        context_path = get_context_file_path()
+        data = read_context_yaml(context_path)
+        
+        if not data:
+            print("❌ Error: Failed to read .voodocs.context file.")
+            return 1
+        
+        # Get current versions
+        versioning = data.get('versioning', {})
+        current_code_version = versioning.get('code_version', '0.0.0')
+        current_context_version = versioning.get('context_version', '0.0')
+        
+        # If no code version provided, try to detect it
+        if not code_version:
+            detected_version = detect_code_version()
+            if detected_version:
+                code_version = prompt_user(
+                    "New code version",
+                    detected_version,
+                    required=True
+                )
+            else:
+                code_version = prompt_user(
+                    "New code version",
+                    required=True
+                )
+        
+        # Validate version format
+        if code_version.count('.') < 2:
+            print(f"❌ Error: Invalid version format: {code_version}")
+            print("   Expected: MAJOR.MINOR.PATCH (e.g., 2.0.0)")
+            return 1
+        
+        # Extract major versions
+        current_major = current_code_version.split('.')[0]
+        new_major = code_version.split('.')[0]
+        context_major = current_context_version.split('.')[0]
+        
+        print(f"🔄 Syncing Context with Code Version")
+        print()
+        print(f"Current code version:    {current_code_version}")
+        print(f"New code version:        {code_version}")
+        print(f"Current context version: {current_context_version}")
+        print()
+        
+        # Check if major version changed
+        if current_major != new_major:
+            # Major version bump - reset context version
+            new_context_version = f"{new_major}.0"
+            
+            print(f"⚠️  MAJOR version change detected ({current_major}.x.x → {new_major}.0.0)")
+            print(f"   Context version will be reset: {current_context_version} → {new_context_version}")
+            print()
+            
+            if not force:
+                if not prompt_yes_no("Continue with reset?", default=True):
+                    print("Aborted.")
+                    return 1
+            
+            # Update versions
+            today = date.today().isoformat()
+            data['versioning']['code_version'] = code_version
+            data['versioning']['context_version'] = new_context_version
+            data['versioning']['last_updated'] = today
+            
+            # Add change entry
+            if 'changes' not in data:
+                data['changes'] = []
+            
+            # Get Git information if available
+            commit_hash = get_git_commit_hash()
+            author = get_git_author()
+            
+            change_entry = {
+                'type': 'context',
+                'description': f"Reset for v{code_version} release",
+                'date': today,
+                'context_version': new_context_version,
+                'code_version': code_version
+            }
+            
+            if commit_hash:
+                change_entry['commit'] = commit_hash
+            if author:
+                change_entry['author'] = author
+            
+            data['changes'].append(change_entry)
+            
+            # Write updated context
+            from .yaml_utils import parse_context_file
+            context = parse_context_file(data)
+            write_context_yaml(context, context_path)
+            
+            print(f"✅ Context version reset to {new_context_version}")
+            print(f"   Code version updated to {code_version}")
+            print()
+            
+        elif context_major != new_major:
+            # Context major doesn't match new code major - this shouldn't happen
+            print(f"⚠️  Warning: Context MAJOR ({context_major}) doesn't match code MAJOR ({new_major})")
+            print(f"   Updating context to match...")
+            
+            new_context_version = f"{new_major}.0"
+            
+            # Update versions
+            today = date.today().isoformat()
+            data['versioning']['code_version'] = code_version
+            data['versioning']['context_version'] = new_context_version
+            data['versioning']['last_updated'] = today
+            
+            # Add change entry
+            if 'changes' not in data:
+                data['changes'] = []
+            
+            # Get Git information if available
+            commit_hash = get_git_commit_hash()
+            author = get_git_author()
+            
+            change_entry = {
+                'type': 'context',
+                'description': f"Synced with v{code_version}",
+                'date': today,
+                'context_version': new_context_version,
+                'code_version': code_version
+            }
+            
+            if commit_hash:
+                change_entry['commit'] = commit_hash
+            if author:
+                change_entry['author'] = author
+            
+            data['changes'].append(change_entry)
+            
+            # Write updated context
+            from .yaml_utils import parse_context_file
+            context = parse_context_file(data)
+            write_context_yaml(context, context_path)
+            
+            print(f"✅ Context synced to {new_context_version}")
+            print(f"   Code version updated to {code_version}")
+            print()
+            
+        else:
+            # No major version change - just update code version
+            data['versioning']['code_version'] = code_version
+            data['versioning']['last_updated'] = date.today().isoformat()
+            
+            # Write updated context
+            from .yaml_utils import parse_context_file
+            context = parse_context_file(data)
+            write_context_yaml(context, context_path)
+            
+            print(f"✅ Code version updated to {code_version}")
+            print(f"   Context version unchanged: {current_context_version}")
+            print()
+        
+        return 0
+        
+    except Exception as e:
+        print(f"❌ Error syncing context: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+
+
+def cmd_context_history() -> int:
+    """
+    Show the version history of the context file.
+    
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    if not context_file_exists():
+        print("❌ Error: No .voodocs.context file found in this directory.")
+        print("   Run 'voodocs context init' to create one.")
+        return 1
+    
+    try:
+        # Read current context
+        context_path = get_context_file_path()
+        data = read_context_yaml(context_path)
+        
+        if not data:
+            print("❌ Error: Failed to read .voodocs.context file.")
+            return 1
+        
+        # Get changes
+        changes = data.get('changes', [])
+        
+        if not changes:
+            print("📜 No change history found.")
+            print("   Changes will be recorded when you run 'voodocs context update'.")
+            return 0
+        
+        print("📜 Context Version History")
+        print()
+        
+        # Display changes in reverse chronological order
+        for change in reversed(changes):
+            change_type = change.get('type', 'unknown')
+            description = change.get('description', 'No description')
+            date = change.get('date', 'Unknown date')
+            context_version = change.get('context_version', '?')
+            code_version = change.get('code_version', '?')
+            commit = change.get('commit', '')
+            author = change.get('author', '')
+            
+            # Format output
+            print(f"📌 Context v{context_version} (Code v{code_version})")
+            print(f"   Date: {date}")
+            print(f"   Type: {change_type}")
+            print(f"   Description: {description}")
+            
+            if commit:
+                print(f"   Commit: {commit}")
+            if author:
+                print(f"   Author: {author}")
+            
+            print()
+        
+        return 0
+        
+    except Exception as e:
+        print(f"❌ Error reading history: {e}")
+        return 1
+
+
+def cmd_context_diff(version1: Optional[str] = None, version2: Optional[str] = None) -> int:
+    """
+    Compare two versions of the context (currently shows change log between versions).
+    
+    Args:
+        version1: First version to compare (older)
+        version2: Second version to compare (newer, default: current)
+    
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    if not context_file_exists():
+        print("❌ Error: No .voodocs.context file found in this directory.")
+        print("   Run 'voodocs context init' to create one.")
+        return 1
+    
+    try:
+        # Read current context
+        context_path = get_context_file_path()
+        data = read_context_yaml(context_path)
+        
+        if not data:
+            print("❌ Error: Failed to read .voodocs.context file.")
+            return 1
+        
+        # Get current version
+        versioning = data.get('versioning', {})
+        current_version = versioning.get('context_version', '0.0')
+        
+        # Default version2 to current
+        if not version2:
+            version2 = current_version
+        
+        # If no version1 provided, show changes from previous version
+        if not version1:
+            changes = data.get('changes', [])
+            if len(changes) < 2:
+                print("📊 Not enough version history to compare.")
+                print("   Need at least 2 versions. Run 'voodocs context history' to see available versions.")
+                return 0
+            
+            # Get the two most recent versions
+            recent_changes = list(reversed(changes))[:2]
+            version2 = recent_changes[0].get('context_version', '?')
+            version1 = recent_changes[1].get('context_version', '?')
+        
+        print(f"📊 Context Diff: v{version1} → v{version2}")
+        print()
+        
+        # Get changes between versions
+        changes = data.get('changes', [])
+        relevant_changes = []
+        
+        for change in changes:
+            change_version = change.get('context_version', '')
+            
+            # Parse versions for comparison
+            try:
+                v1_parts = [int(x) for x in version1.split('.')]
+                v2_parts = [int(x) for x in version2.split('.')]
+                cv_parts = [int(x) for x in change_version.split('.')]
+                
+                # Check if change is between v1 and v2
+                if v1_parts < cv_parts <= v2_parts:
+                    relevant_changes.append(change)
+            except (ValueError, AttributeError):
+                # Skip if version parsing fails
+                continue
+        
+        if not relevant_changes:
+            print(f"No changes found between v{version1} and v{version2}")
+            return 0
+        
+        print(f"Changes ({len(relevant_changes)}):")
+        print()
+        
+        for change in relevant_changes:
+            change_type = change.get('type', 'unknown')
+            description = change.get('description', 'No description')
+            date = change.get('date', 'Unknown date')
+            context_version = change.get('context_version', '?')
+            code_version = change.get('code_version', '?')
+            
+            print(f"  • v{context_version} ({date})")
+            print(f"    {description}")
+            if code_version:
+                print(f"    Code: v{code_version}")
+            print()
+        
+        print(f"💡 Tip: Use 'voodocs context history' to see the full timeline.")
+        
+        return 0
+        
+    except Exception as e:
+        print(f"❌ Error comparing versions: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+
+
+def cmd_context_validate(check_version: bool = False, check_invariants: bool = False) -> int:
+    """
+    Validate the context file for correctness and consistency.
+    
+    Args:
+        check_version: Check if code version matches detected version
+        check_invariants: Check if code respects documented invariants (future)
+    
+    Returns:
+        Exit code (0 for success, 1 for warnings, 2 for errors)
+    """
+    if not context_file_exists():
+        print("❌ Error: No .voodocs.context file found in this directory.")
+        print("   Run 'voodocs context init' to create one.")
+        return 2
+    
+    try:
+        # Read current context
+        context_path = get_context_file_path()
+        data = read_context_yaml(context_path)
+        
+        if not data:
+            print("❌ Error: Failed to read .voodocs.context file.")
+            return 2
+        
+        print("🔍 Validating Context File")
+        print()
+        
+        errors = []
+        warnings = []
+        
+        # Check required fields
+        versioning = data.get('versioning', {})
+        if not versioning:
+            errors.append("Missing 'versioning' section")
+        else:
+            if not versioning.get('code_version'):
+                errors.append("Missing 'versioning.code_version'")
+            if not versioning.get('context_version'):
+                errors.append("Missing 'versioning.context_version'")
+            if not versioning.get('last_updated'):
+                warnings.append("Missing 'versioning.last_updated'")
+        
+        project = data.get('project', {})
+        if not project:
+            errors.append("Missing 'project' section")
+        else:
+            if not project.get('name'):
+                errors.append("Missing 'project.name'")
+            if not project.get('purpose'):
+                warnings.append("Missing 'project.purpose'")
+        
+        # Check version format
+        code_version = versioning.get('code_version', '')
+        if code_version:
+            if code_version.count('.') < 2:
+                errors.append(f"Invalid code version format: '{code_version}' (expected MAJOR.MINOR.PATCH)")
+        
+        context_version = versioning.get('context_version', '')
+        if context_version:
+            if context_version.count('.') != 1:
+                errors.append(f"Invalid context version format: '{context_version}' (expected MAJOR.MINOR)")
+        
+        # Check version consistency
+        if code_version and context_version:
+            code_major = code_version.split('.')[0]
+            context_major = context_version.split('.')[0]
+            
+            if code_major != context_major:
+                warnings.append(
+                    f"Version mismatch: code MAJOR ({code_major}) != context MAJOR ({context_major})"
+                )
+        
+        # Check if code version matches detected version
+        if check_version:
+            detected_version = detect_code_version()
+            if detected_version and detected_version != code_version:
+                warnings.append(
+                    f"Code version mismatch: context has '{code_version}' but detected '{detected_version}'"
+                )
+        
+        # Check invariants using the checker
+        if check_invariants:
+            invariants = data.get('invariants', {}).get('global', [])
+            if invariants:
+                from .checker import InvariantChecker
+                checker = InvariantChecker()
+                results = checker.check_invariants(invariants, get_project_root(), None)
+                
+                failed = sum(1 for r in results if not r.passed)
+                if failed > 0:
+                    warnings.append(f"{failed} invariant(s) have potential violations")
+                    warnings.append("Run 'voodocs context check' for details")
+        
+        # Display results
+        if errors:
+            print("❌ Errors:")
+            for error in errors:
+                print(f"   • {error}")
+            print()
+        
+        if warnings:
+            print("⚠️  Warnings:")
+            for warning in warnings:
+                print(f"   • {warning}")
+            print()
+        
+        # Add smart suggestions
+        suggestions = []
+        
+        # Completeness suggestions
+        if not data.get('architecture', {}).get('modules'):
+            suggestions.append("Consider adding 'architecture.modules' section")
+        
+        if not data.get('invariants', {}).get('global'):
+            suggestions.append("Consider adding 'invariants.global' section")
+        
+        if not data.get('critical_paths'):
+            suggestions.append("Consider adding 'critical_paths' section")
+        
+        if not data.get('dependencies'):
+            suggestions.append("Consider adding 'dependencies' section")
+        
+        # Quality suggestions
+        invariants = data.get('invariants', {}).get('global', [])
+        for inv in invariants:
+            if len(inv) < 20:
+                suggestions.append(f"Invariant '{inv}' is too vague - be more specific")
+                break
+        
+        # Consistency suggestions
+        modules = data.get('architecture', {}).get('modules', {})
+        critical_paths = data.get('critical_paths', [])
+        
+        # Check if critical paths reference modules
+        for path in critical_paths:
+            path_name = path.get('name', '')
+            steps = path.get('steps', [])
+            for step in steps:
+                step_text = str(step).lower()
+                for module_name in modules.keys():
+                    if module_name.lower() in step_text:
+                        break
+        
+        if not errors and not warnings:
+            print("✅ Context file is valid!")
+            print()
+            
+            # Show summary
+            print("Summary:")
+            print(f"  Project:         {project.get('name', '?')}")
+            print(f"  Code Version:    {code_version}")
+            print(f"  Context Version: {context_version}")
+            print(f"  Last Updated:    {versioning.get('last_updated', '?')}")
+            print()
+            
+            # Show suggestions if any
+            if suggestions:
+                print("💡 Suggestions:")
+                for suggestion in suggestions[:5]:  # Limit to 5
+                    print(f"   • {suggestion}")
+                print()
+            
+            return 0
+        elif errors:
+            print(f"❌ Validation failed with {len(errors)} error(s) and {len(warnings)} warning(s)")
+            return 2
+        else:
+            print(f"⚠️  Validation passed with {len(warnings)} warning(s)")
+            return 1
+        
+    except Exception as e:
+        print(f"❌ Error validating context: {e}")
+        import traceback
+        traceback.print_exc()
+        return 2
+
+
+def cmd_context_generate(source_dir: Optional[str] = None, update_existing: bool = False) -> int:
+    """
+    Generate or update context by extracting information from code annotations.
+    
+    Args:
+        source_dir: Directory to scan for annotations (default: current directory)
+        update_existing: Update existing context file instead of creating new one
+    
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    from pathlib import Path
+    import sys
+    
+    # Determine source directory
+    if source_dir:
+        scan_path = Path(source_dir).resolve()
+    else:
+        scan_path = Path.cwd()
+    
+    if not scan_path.exists():
+        print(f"❌ Error: Directory not found: {scan_path}")
+        return 1
+    
+    print(f"🔍 Scanning for @voodocs annotations in: {scan_path}")
+    print()
+    
+    try:
+        # Import the annotation parser
+        sys.path.insert(0, str(Path(__file__).parent.parent))
+        from annotations.parser import AnnotationParser
+        
+        # Scan for annotations
+        parser = AnnotationParser()
+        results = parser.parse_directory(scan_path)
+        
+        if not results:
+            print("⚠️  No @voodocs annotations found.")
+            print("   Add @voodocs annotations to your code first.")
+            return 1
+        
+        # Extract global invariants from all annotations
+        global_invariants = set()
+        assumptions = []
+        modules_info = {}
+        
+        for parsed in results:
+            # Get module annotation
+            module_ann = parsed.module
+            
+            # Extract module-level invariants
+            if hasattr(module_ann, 'invariants') and module_ann.invariants:
+                for inv in module_ann.invariants:
+                    global_invariants.add(inv)
+            
+            # Extract assumptions
+            if hasattr(module_ann, 'assumptions') and module_ann.assumptions:
+                for assumption in module_ann.assumptions:
+                    assumptions.append({
+                        'description': assumption,
+                        'source': Path(parsed.source_file).relative_to(scan_path).as_posix()
+                    })
+            
+            # Store module info
+            if hasattr(module_ann, 'module_purpose') and module_ann.module_purpose:
+                rel_path = Path(parsed.source_file).relative_to(scan_path).as_posix()
+                modules_info[rel_path] = {
+                    'purpose': module_ann.module_purpose,
+                    'dependencies': getattr(module_ann, 'dependencies', [])
+                }
+            
+            # Extract function-level invariants that might be global
+            for func_ann in module_ann.functions:
+                if hasattr(func_ann, 'invariants') and func_ann.invariants:
+                    for inv in func_ann.invariants:
+                        # Check if invariant looks global (mentions system-wide concepts)
+                        if any(keyword in inv.lower() for keyword in ['system', 'all', 'every', 'global', '∀']):
+                            global_invariants.add(inv)
+            
+            # Extract class-level invariants
+            for cls_ann in module_ann.classes:
+                if hasattr(cls_ann, 'class_invariants') and cls_ann.class_invariants:
+                    for inv in cls_ann.class_invariants:
+                        # Check if invariant looks global
+                        if any(keyword in inv.lower() for keyword in ['system', 'all', 'every', 'global', '∀']):
+                            global_invariants.add(inv)
+        
+        # Display findings
+        print(f"📊 Extraction Results:")
+        print(f"   Files scanned:      {len(results)}")
+        print(f"   Global invariants:  {len(global_invariants)}")
+        print(f"   Assumptions:        {len(assumptions)}")
+        print(f"   Modules documented: {len(modules_info)}")
+        print()
+        
+        if not update_existing:
+            # Check if context already exists
+            if context_file_exists():
+                print("⚠️  Context file already exists.")
+                response = prompt_user("Update existing context?", "y", required=False)
+                if response.lower() not in ['y', 'yes']:
+                    print("Cancelled.")
+                    return 0
+                update_existing = True
+        
+        if update_existing:
+            # Update existing context
+            if not context_file_exists():
+                print("❌ Error: No .voodocs.context file found.")
+                print("   Run 'voodocs context init' first.")
+                return 1
+            
+            context_path = get_context_file_path()
+            data = read_context_yaml(context_path)
+            
+            if not data:
+                print("❌ Error: Failed to read .voodocs.context file.")
+                return 1
+            
+            # Update invariants
+            if 'invariants' not in data:
+                data['invariants'] = {}
+            if 'global' not in data['invariants']:
+                data['invariants']['global'] = []
+            
+            # Merge new invariants (avoid duplicates)
+            existing_invs = set(data['invariants']['global'])
+            new_invs = global_invariants - existing_invs
+            data['invariants']['global'].extend(sorted(new_invs))
+            
+            # Update assumptions
+            if 'assumptions' not in data:
+                data['assumptions'] = []
+            
+            # Merge new assumptions
+            existing_assumption_texts = {a.get('description', '') for a in data['assumptions']}
+            for assumption in assumptions:
+                if assumption['description'] not in existing_assumption_texts:
+                    data['assumptions'].append(assumption)
+            
+            # Update modules
+            if 'architecture' not in data:
+                data['architecture'] = {}
+            if 'modules' not in data['architecture']:
+                data['architecture']['modules'] = {}
+            
+            data['architecture']['modules'].update(modules_info)
+            
+            # Update last_updated
+            from datetime import date
+            data['versioning']['last_updated'] = date.today().isoformat()
+            
+            # Write updated context
+            from .yaml_utils import parse_context_file
+            context = parse_context_file(data)
+            write_context_yaml(context, context_path)
+            
+            print(f"✅ Context updated from code annotations")
+            print(f"   Added {len(new_invs)} new invariants")
+            print(f"   Added {len(assumptions) - len(existing_assumption_texts)} new assumptions")
+            print()
+            print("💡 Tip: Run 'voodocs context view' to see the updated context")
+            
+        else:
+            # Create new context (should not reach here, but handle gracefully)
+            print("❌ Error: Context generation requires an existing context file.")
+            print("   Run 'voodocs context init' first, then use 'voodocs context generate --from-code'")
+            return 1
+        
+        return 0
+        
+    except ImportError as e:
+        print(f"❌ Error: Failed to import annotation parser: {e}")
+        print("   Make sure VooDocs is properly installed.")
+        return 1
+    except Exception as e:
+        print(f"❌ Error generating context: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+
+
+def cmd_context_query(query: str, section: Optional[str] = None, format: str = 'text') -> int:
+    """
+    Query the context file like a database.
+    
+    Args:
+        query: Search query (keyword or regex pattern)
+        section: Specific section to search (invariants, assumptions, etc.)
+        format: Output format ('text', 'json', 'yaml')
+    
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    if not context_file_exists():
+        print("❌ Error: No .voodocs.context file found in this directory.")
+        print("   Run 'voodocs context init' to create one.")
+        return 1
+    
+    try:
+        import re
+        import json
+        
+        # Read context
+        context_path = get_context_file_path()
+        data = read_context_yaml(context_path)
+        
+        if not data:
+            print("❌ Error: Failed to read .voodocs.context file.")
+            return 1
+        
+        # Compile regex pattern (case-insensitive)
+        try:
+            pattern = re.compile(query, re.IGNORECASE)
+        except re.error as e:
+            print(f"❌ Error: Invalid regex pattern: {e}")
+            return 1
+        
+        # Define searchable sections
+        searchable_sections = {
+            'invariants': data.get('invariants', {}),
+            'assumptions': data.get('assumptions', []),
+            'known_issues': data.get('known_issues', []),
+            'architecture': data.get('architecture', {}),
+            'critical_paths': data.get('critical_paths', []),
+            'roadmap': data.get('roadmap', []),
+            'changes': data.get('changes', []),
+            'performance': data.get('performance', {}),
+            'security': data.get('security', {}),
+            'dependencies': data.get('dependencies', {}),
+            'testing': data.get('testing', {}),
+            'deployment': data.get('deployment', {}),
+            'team': data.get('team', {})
+        }
+        
+        # Filter by section if specified
+        if section:
+            if section not in searchable_sections:
+                print(f"❌ Error: Unknown section '{section}'")
+                print(f"   Available sections: {', '.join(searchable_sections.keys())}")
+                return 1
+            searchable_sections = {section: searchable_sections[section]}
+        
+        # Search function
+        def search_value(value, path=""):
+            """Recursively search through data structures."""
+            results = []
+            
+            if isinstance(value, str):
+                if pattern.search(value):
+                    results.append((path, value))
+            elif isinstance(value, list):
+                for i, item in enumerate(value):
+                    results.extend(search_value(item, f"{path}[{i}]"))
+            elif isinstance(value, dict):
+                for key, val in value.items():
+                    new_path = f"{path}.{key}" if path else key
+                    results.extend(search_value(val, new_path))
+            
+            return results
+        
+        # Perform search
+        all_results = []
+        for section_name, section_data in searchable_sections.items():
+            results = search_value(section_data, section_name)
+            all_results.extend(results)
+        
+        # Display results
+        if not all_results:
+            print(f"🔍 No results found for: {query}")
+            if section:
+                print(f"   (searched in: {section})")
+            return 0
+        
+        if format == 'json':
+            # JSON output
+            output = {
+                'query': query,
+                'section': section,
+                'count': len(all_results),
+                'results': [{'path': path, 'value': value} for path, value in all_results]
+            }
+            print(json.dumps(output, indent=2))
+        
+        elif format == 'yaml':
+            # YAML output
+            import yaml
+            output = {
+                'query': query,
+                'section': section,
+                'count': len(all_results),
+                'results': [{'path': path, 'value': value} for path, value in all_results]
+            }
+            print(yaml.dump(output, default_flow_style=False))
+        
+        else:
+            # Text output (default)
+            print(f"🔍 Query Results: '{query}'")
+            if section:
+                print(f"   Section: {section}")
+            print(f"   Found: {len(all_results)} match(es)")
+            print()
+            
+            for path, value in all_results:
+                print(f"📍 {path}")
+                # Highlight the match
+                highlighted = pattern.sub(lambda m: f"**{m.group()}**", value)
+                print(f"   {highlighted}")
+                print()
+        
+        return 0
+        
+    except Exception as e:
+        print(f"❌ Error querying context: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+
+
+def get_git_commit_hash() -> Optional[str]:
+    """
+    Get the current Git commit hash.
+    
+    Returns:
+        Commit hash (short form) or None if not in a Git repository
+    """
+    try:
+        import subprocess
+        result = subprocess.run(
+            ['git', 'rev-parse', '--short', 'HEAD'],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return result.stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
+def get_git_author() -> Optional[str]:
+    """
+    Get the Git author name and email.
+    
+    Returns:
+        Author string in format "Name <email>" or None if not in a Git repository
+    """
+    try:
+        import subprocess
+        result = subprocess.run(
+            ['git', 'config', 'user.name'],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        name = result.stdout.strip()
+        
+        result = subprocess.run(
+            ['git', 'config', 'user.email'],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        email = result.stdout.strip()
+        
+        if name and email:
+            return f"{name} <{email}>"
+        elif name:
+            return name
+        else:
+            return None
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
+def is_git_repository() -> bool:
+    """
+    Check if the current directory is inside a Git repository.
+    
+    Returns:
+        True if in a Git repository, False otherwise
+    """
+    try:
+        import subprocess
+        subprocess.run(
+            ['git', 'rev-parse', '--git-dir'],
+            capture_output=True,
+            check=True
+        )
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+
+def cmd_context_check(
+    module_filter: Optional[str] = None,
+    invariant_filter: Optional[str] = None,
+    output_format: str = 'text'
+) -> int:
+    """
+    Check that code respects documented invariants.
+    
+    Args:
+        module_filter: Optional module name to filter checks
+        invariant_filter: Optional invariant text to filter checks
+        output_format: Output format ('text', 'json')
+    
+    Returns:
+        Exit code (0 for all passed, 1 for violations found, 2 for error)
+    """
+    if not context_file_exists():
+        print("❌ Error: No .voodocs.context file found in this directory.")
+        print("   Run 'voodocs context init' to create one.")
+        return 2
+    
+    try:
+        from .checker import InvariantChecker, ViolationSeverity
+        import json
+        
+        # Read context
+        context_path = get_context_file_path()
+        data = read_context_yaml(context_path)
+        
+        if not data:
+            print("❌ Error: Failed to read .voodocs.context file.")
+            return 2
+        
+        # Get invariants
+        invariants_data = data.get('invariants', {})
+        global_invariants = invariants_data.get('global', [])
+        
+        if not global_invariants:
+            print("⚠️  No invariants found in context file.")
+            print("   Add invariants to the 'invariants.global' section.")
+            return 0
+        
+        # Filter invariants if specified
+        if invariant_filter:
+            global_invariants = [
+                inv for inv in global_invariants
+                if invariant_filter.lower() in inv.lower()
+            ]
+            
+            if not global_invariants:
+                print(f"⚠️  No invariants match filter: {invariant_filter}")
+                return 0
+        
+        # Get source directory
+        source_dir = get_project_root()
+        
+        # Initialize checker
+        checker = InvariantChecker()
+        
+        if output_format == 'text':
+            print("🔍 Checking Invariants")
+            print()
+        
+        # Check each invariant
+        results = checker.check_invariants(
+            global_invariants,
+            source_dir,
+            module_filter
+        )
+        
+        # Output results
+        if output_format == 'json':
+            output = {
+                'total': len(results),
+                'passed': sum(1 for r in results if r.passed),
+                'failed': sum(1 for r in results if not r.passed),
+                'results': []
+            }
+            
+            for result in results:
+                output['results'].append({
+                    'invariant': result.invariant,
+                    'passed': result.passed,
+                    'checked_files': result.checked_files,
+                    'violations': [
+                        {
+                            'file': v.file_path,
+                            'line': v.line_number,
+                            'content': v.line_content,
+                            'severity': v.severity.value,
+                            'explanation': v.explanation
+                        }
+                        for v in result.violations
+                    ]
+                })
+            
+            print(json.dumps(output, indent=2))
+        
+        else:
+            # Text output
+            passed_count = 0
+            failed_count = 0
+            warning_count = 0
+            
+            for result in results:
+                if result.passed:
+                    passed_count += 1
+                    print(f"✅ {result.invariant}")
+                    print(f"   No violations found (checked {result.checked_files} files)")
+                    print()
+                else:
+                    # Count by severity
+                    errors = [v for v in result.violations if v.severity == ViolationSeverity.ERROR]
+                    warnings = [v for v in result.violations if v.severity == ViolationSeverity.WARNING]
+                    infos = [v for v in result.violations if v.severity == ViolationSeverity.INFO]
+                    
+                    if errors:
+                        failed_count += 1
+                        print(f"❌ {result.invariant}")
+                    elif warnings:
+                        warning_count += 1
+                        print(f"⚠️  {result.invariant}")
+                    else:
+                        print(f"ℹ️  {result.invariant}")
+                    
+                    print(f"   Found {len(result.violations)} potential violation(s):")
+                    print()
+                    
+                    # Show first 5 violations
+                    for violation in result.violations[:5]:
+                        print(f"   📍 {violation.file_path}:{violation.line_number}")
+                        print(f"      {violation.line_content}")
+                        print(f"      → {violation.explanation}")
+                        print()
+                    
+                    if len(result.violations) > 5:
+                        print(f"   ... and {len(result.violations) - 5} more")
+                        print()
+            
+            # Summary
+            print("=" * 60)
+            print("Summary:")
+            print(f"  ✅ Passed:   {passed_count}")
+            if failed_count > 0:
+                print(f"  ❌ Failed:   {failed_count}")
+            if warning_count > 0:
+                print(f"  ⚠️  Warnings: {warning_count}")
+            print()
+        
+        # Return exit code
+        if any(not r.passed for r in results):
+            return 1
+        return 0
+        
+    except ImportError as e:
+        print(f"❌ Error: Failed to import checker: {e}")
+        return 2
+    except Exception as e:
+        print(f"❌ Error checking invariants: {e}")
+        import traceback
+        traceback.print_exc()
+        return 2
+
+
+
+def cmd_context_diagram(
+    diagram_type: str = 'modules',
+    output_format: str = 'mermaid',
+    output_file: Optional[str] = None,
+    render_png: bool = False
+) -> int:
+    """
+    Generate architecture diagrams from context.
+    
+    Args:
+        diagram_type: Type of diagram ('modules', 'dependencies', 'flow', 'all')
+        output_format: Output format ('mermaid', 'd2')
+        output_file: Output file path (optional)
+        render_png: Render to PNG using manus-render-diagram
+    
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    if not context_file_exists():
+        print("❌ Error: No .voodocs.context file found in this directory.")
+        print("   Run 'voodocs context init' to create one.")
+        return 1
+    
+    try:
+        from .diagram import DiagramGenerator
+        
+        # Read context
+        context_path = get_context_file_path()
+        data = read_context_yaml(context_path)
+        
+        if not data:
+            print("❌ Error: Failed to read .voodocs.context file.")
+            return 1
+        
+        # Initialize generator
+        generator = DiagramGenerator()
+        
+        # Generate diagrams
+        diagrams = {}
+        
+        if diagram_type in ['modules', 'all']:
+            print(f"📊 Generating module diagram...")
+            diagrams['modules'] = generator.generate_module_diagram(data, output_format)
+        
+        if diagram_type in ['dependencies', 'all']:
+            print(f"📊 Generating dependency diagram...")
+            diagrams['dependencies'] = generator.generate_dependency_diagram(data, output_format)
+        
+        if diagram_type in ['flow', 'all']:
+            print(f"📊 Generating flow diagram...")
+            diagrams['flow'] = generator.generate_flow_diagram(data, output_format)
+        
+        if not diagrams:
+            print(f"❌ Error: Unknown diagram type: {diagram_type}")
+            print("   Valid types: modules, dependencies, flow, all")
+            return 1
+        
+        # Output diagrams
+        if output_file:
+            output_path = Path(output_file)
+            
+            if diagram_type == 'all':
+                # Save multiple diagrams
+                for dtype, diagram_source in diagrams.items():
+                    dtype_path = output_path.parent / f"{output_path.stem}_{dtype}{output_path.suffix}"
+                    
+                    if render_png:
+                        # Render to PNG
+                        png_path = dtype_path.with_suffix('.png')
+                        success = generator.render_to_png(diagram_source, png_path, output_format)
+                        
+                        if success:
+                            print(f"✅ {dtype.capitalize()} diagram saved to: {png_path}")
+                        else:
+                            print(f"❌ Failed to render {dtype} diagram")
+                            # Still save source
+                            dtype_path.write_text(diagram_source)
+                            print(f"   Source saved to: {dtype_path}")
+                    else:
+                        # Save source only
+                        dtype_path.write_text(diagram_source)
+                        print(f"✅ {dtype.capitalize()} diagram saved to: {dtype_path}")
+            else:
+                # Save single diagram
+                if render_png:
+                    # Render to PNG
+                    png_path = output_path.with_suffix('.png')
+                    success = generator.render_to_png(diagrams[diagram_type], png_path, output_format)
+                    
+                    if success:
+                        print(f"✅ Diagram saved to: {png_path}")
+                    else:
+                        print(f"❌ Failed to render diagram")
+                        # Still save source
+                        output_path.write_text(diagrams[diagram_type])
+                        print(f"   Source saved to: {output_path}")
+                else:
+                    # Save source only
+                    output_path.write_text(diagrams[diagram_type])
+                    print(f"✅ Diagram saved to: {output_path}")
+        else:
+            # Print to console
+            for dtype, diagram_source in diagrams.items():
+                if len(diagrams) > 1:
+                    print(f"\n{'=' * 60}")
+                    print(f"{dtype.upper()} DIAGRAM")
+                    print('=' * 60)
+                print(diagram_source)
+                print()
+        
+        return 0
+        
+    except ImportError as e:
+        print(f"❌ Error: Failed to import diagram generator: {e}")
+        return 1
+    except Exception as e:
+        print(f"❌ Error generating diagram: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1