@voodocs/cli 0.1.2 → 0.3.0

package/lib/darkarts/context/ai_integrations.py

@@ -0,0 +1,619 @@
+"""
+AI-specific integration templates for VooDocs Context System.
+
+This module provides native integration with different AI assistants:
+- Claude Code (skills)
+- Cursor (rules)
+- GitHub Copilot (instructions)
+- Windsurf (rules)
+- Cline (rules)
+- And more...
+"""
+
+from typing import Dict, List, Optional
+from pathlib import Path
+
+
+def generate_claude_skill(project_name: str, project_purpose: str) -> Dict[str, str]:
+    """
+    Generate Claude Code skill for VooDocs context system.
+    
+    Args:
+        project_name: Name of the project
+        project_purpose: Brief purpose of the project
+    
+    Returns:
+        Dictionary mapping file paths to content
+    """
+    skill_md = f"""---
+name: voodocs-context
+description: Access and query the VooDocs context system for project understanding, invariants, and architecture
+---
+
+# VooDocs Context System Skill
+
+## Project: {project_name}
+{project_purpose}
+
+This skill provides access to the VooDocs context system for understanding project architecture, invariants, and assumptions.
+
+## Available Commands
+
+### View Full Context
+```bash
+voodocs context view
+```
+
+### Query Context
+```bash
+voodocs context query "search term" --section invariants
+voodocs context query "auth" --format json
+```
+
+### Check Invariants
+```bash
+voodocs context check
+voodocs context check --invariant "password"
+```
+
+### Generate Diagrams
+```bash
+voodocs context diagram --type modules
+voodocs context diagram --type all --output docs/arch
+```
+
+### Update Context
+```bash
+voodocs context generate --update
+voodocs context update --description "what changed"
+```
+
+## When to Use This Skill
+
+Use this skill when:
+- User asks about project architecture or structure
+- User asks about security requirements or invariants
+- User asks about system assumptions
+- User wants to understand dependencies
+- User wants to see architecture diagrams
+- Before making significant code changes
+- When documenting new features
+
+## Workflow
+
+1. **Before Changes**: Always check context first
+   ```bash
+   voodocs context view
+   ```
+
+2. **During Development**: Update context from code
+   ```bash
+   voodocs context generate --update
+   ```
+
+3. **Before Commit**: Validate invariants
+   ```bash
+   voodocs context check
+   ```
+
+## Context File
+
+The context is stored in `.voodocs.context` (YAML format) with:
+- **Invariants**: Rules that must always hold
+- **Assumptions**: System-wide assumptions
+- **Architecture**: Modules and dependencies
+- **Critical Paths**: Important workflows
+- **Known Issues**: Bugs and limitations
+
+## Examples
+
+**Q: "What are the security requirements?"**
+```bash
+voodocs context query "security" --section invariants
+```
+
+**Q: "Show me the architecture"**
+```bash
+voodocs context diagram --type modules
+```
+
+**Q: "Are there any invariant violations?"**
+```bash
+voodocs context check
+```
+
+## Important
+
+- Context is the source of truth for project understanding
+- Always respect documented invariants
+- Update context when adding features
+- Check context before architectural decisions
+"""
+
+    return {
+        ".claude/skills/voodocs-context/SKILL.md": skill_md
+    }
+
+
+def generate_cursor_rules(project_name: str, project_purpose: str) -> Dict[str, str]:
+    """
+    Generate Cursor rules for VooDocs context system.
+    
+    Args:
+        project_name: Name of the project
+        project_purpose: Brief purpose of the project
+    
+    Returns:
+        Dictionary mapping file paths to content
+    """
+    
+    main_rule = f"""# VooDocs Context System
+
+## Project: {project_name}
+{project_purpose}
+
+This project uses the VooDocs Context System (v0.2.0+) for documentation and validation.
+
+## Context File
+- **Location**: `.voodocs.context`
+- **Format**: YAML
+- **Purpose**: Single source of truth for project understanding
+
+## Before Starting Work
+
+Always check the context first:
+
+```bash
+voodocs context view
+```
+
+This shows:
+- Global invariants (rules that must hold)
+- System assumptions
+- Architecture and modules
+- Dependencies
+- Known issues
+
+## Essential Commands
+
+### Read Context
+```bash
+voodocs context view                    # View as Markdown
+voodocs context query "term"            # Search context
+voodocs context query "security" --section invariants
+```
+
+### Validate Code
+```bash
+voodocs context check                   # Check invariants
+voodocs context validate --check-invariants
+```
+
+### Update Context
+```bash
+voodocs context generate --update       # Auto-generate from code
+voodocs context update --description "what changed"
+```
+
+### Visualize
+```bash
+voodocs context diagram --type modules  # Architecture diagram
+voodocs context diagram --type all --output docs/arch
+```
+
+## @voodocs Annotations
+
+Document your code with @voodocs annotations:
+
+**Python:**
+```python
+\"\"\"@voodocs
+module_purpose: "What this module does"
+dependencies: ["other-module", "external-lib"]
+assumptions: ["Database is initialized"]
+invariants: ["All inputs must be validated"]
+\"\"\"
+```
+
+**TypeScript:**
+```typescript
+/**@voodocs
+module_purpose: "What this module does"
+dependencies: ["react", "axios"]
+assumptions: ["API endpoint is available"]
+invariants: ["All responses must be validated"]
+*/
+```
+
+## Workflow
+
+1. **Before Changes**: `voodocs context view`
+2. **During Development**: Add @voodocs annotations
+3. **After Changes**: `voodocs context generate --update`
+4. **Before Commit**: `voodocs context check`
+5. **Update Version**: `voodocs context update --description "..."`
+
+## Invariants
+
+The context contains global invariants that must ALWAYS hold:
+- Check them: `voodocs context query "." --section invariants`
+- Validate code: `voodocs context check`
+- Never violate documented invariants
+
+## Architecture
+
+View module structure:
+```bash
+voodocs context diagram --type modules
+```
+
+Query architecture:
+```bash
+voodocs context query "module-name" --section architecture
+```
+
+## Remember
+
+- Context is your source of truth
+- Always check context before making changes
+- Respect all documented invariants
+- Update context when adding features
+- Validate before committing
+"""
+
+    return {
+        ".cursor/rules/voodocs-context.mdc": main_rule
+    }
+
+
+def generate_copilot_instructions(project_name: str, project_purpose: str) -> Dict[str, str]:
+    """
+    Generate GitHub Copilot instructions for VooDocs context system.
+    
+    Args:
+        project_name: Name of the project
+        project_purpose: Brief purpose of the project
+    
+    Returns:
+        Dictionary mapping file paths to content
+    """
+    
+    instructions = f"""# GitHub Copilot Instructions - {project_name}
+
+## Project Overview
+{project_purpose}
+
+## VooDocs Context System
+
+This project uses VooDocs Context System (v0.2.0+) for documentation and validation.
+
+### Context File
+- **Location**: `.voodocs.context` (YAML format)
+- **Purpose**: Single source of truth for project understanding
+- **Contains**: Invariants, assumptions, architecture, dependencies
+
+### Before Coding
+
+Always check the context:
+```bash
+voodocs context view
+```
+
+### Key Commands
+
+```bash
+# View context
+voodocs context view
+
+# Search context
+voodocs context query "search term"
+
+# Check invariants
+voodocs context check
+
+# Generate diagrams
+voodocs context diagram --type modules
+
+# Update context
+voodocs context generate --update
+```
+
+### @voodocs Annotations
+
+Document code with @voodocs annotations:
+
+**Python:**
+```python
+\"\"\"@voodocs
+module_purpose: "Brief description"
+dependencies: ["list", "of", "deps"]
+assumptions: ["What must be true"]
+invariants: ["Rules that must hold"]
+\"\"\"
+```
+
+**TypeScript:**
+```typescript
+/**@voodocs
+module_purpose: "Brief description"
+dependencies: ["react", "axios"]
+assumptions: ["API is available"]
+invariants: ["Responses validated"]
+*/
+```
+
+### Invariants (Must Always Hold)
+
+Check invariants before suggesting code:
+```bash
+voodocs context query "." --section invariants
+```
+
+Common invariants:
+- All passwords must be hashed
+- API keys must never be logged
+- All database queries must use parameterized statements
+- User input must be validated
+
+### Workflow
+
+1. Check context: `voodocs context view`
+2. Add @voodocs annotations to new code
+3. Update context: `voodocs context generate --update`
+4. Validate: `voodocs context check`
+5. Update version: `voodocs context update`
+
+### Architecture
+
+View module structure:
+```bash
+voodocs context diagram --type modules
+```
+
+### Remember
+
+- Context is the source of truth
+- Respect all documented invariants
+- Update context when adding features
+- Validate before committing
+"""
+
+    return {
+        ".github/copilot-instructions.md": instructions
+    }
+
+
+def generate_windsurf_rules(project_name: str, project_purpose: str) -> Dict[str, str]:
+    """
+    Generate Windsurf rules for VooDocs context system.
+    
+    Args:
+        project_name: Name of the project
+        project_purpose: Brief purpose of the project
+    
+    Returns:
+        Dictionary mapping file paths to content
+    """
+    
+    rules = f"""# Windsurf Rules - {project_name}
+
+## Project
+{project_purpose}
+
+## VooDocs Context System
+
+This project uses VooDocs (v0.2.0+) for context management.
+
+### Context Commands
+
+```bash
+voodocs context view                    # View full context
+voodocs context query "term"            # Search context
+voodocs context check                   # Validate invariants
+voodocs context diagram --type modules  # Architecture
+voodocs context generate --update       # Update from code
+```
+
+### Before Coding
+
+Check context first:
+```bash
+voodocs context view
+```
+
+### Invariants
+
+Rules that must ALWAYS hold. Check them:
+```bash
+voodocs context query "." --section invariants
+voodocs context check
+```
+
+### @voodocs Annotations
+
+```python
+\"\"\"@voodocs
+module_purpose: "What this does"
+dependencies: ["deps"]
+assumptions: ["assumptions"]
+invariants: ["rules"]
+\"\"\"
+```
+
+### Workflow
+
+1. Check: `voodocs context view`
+2. Code with @voodocs annotations
+3. Update: `voodocs context generate --update`
+4. Validate: `voodocs context check`
+5. Commit: `voodocs context update`
+
+### Remember
+
+- Context = source of truth
+- Respect invariants
+- Update context with features
+- Validate before commit
+"""
+
+    return {
+        ".windsurfrules": rules
+    }
+
+
+def generate_cline_rules(project_name: str, project_purpose: str) -> Dict[str, str]:
+    """
+    Generate Cline rules for VooDocs context system.
+    
+    Args:
+        project_name: Name of the project
+        project_purpose: Brief purpose of the project
+    
+    Returns:
+        Dictionary mapping file paths to content
+    """
+    
+    rules = f"""# Cline Rules - {project_name}
+
+## Project
+{project_purpose}
+
+## VooDocs Context System
+
+Context file: `.voodocs.context` (YAML)
+
+### Commands
+
+```bash
+voodocs context view                    # View context
+voodocs context query "term"            # Search
+voodocs context check                   # Validate
+voodocs context generate --update       # Update
+```
+
+### Before Coding
+
+```bash
+voodocs context view
+```
+
+### Invariants
+
+Check before coding:
+```bash
+voodocs context check
+```
+
+### Annotations
+
+```python
+\"\"\"@voodocs
+module_purpose: "Description"
+dependencies: ["list"]
+assumptions: ["assumptions"]
+invariants: ["rules"]
+\"\"\"
+```
+
+### Workflow
+
+1. Check context
+2. Add annotations
+3. Update context
+4. Validate
+5. Commit
+
+### Remember
+
+- Context = truth
+- Respect invariants
+- Update with features
+"""
+
+    return {
+        ".clinerules": rules
+    }
+
+
+def detect_ai_assistants(project_root: Path) -> List[str]:
+    """
+    Detect which AI assistants are already configured in the project.
+    
+    Args:
+        project_root: Path to project root
+    
+    Returns:
+        List of detected AI assistant names
+    """
+    detected = []
+    
+    checks = {
+        "claude": [".claude", ".claude/skills"],
+        "cursor": [".cursorrules", ".cursor", ".cursor/rules"],
+        "copilot": [".github/copilot-instructions.md"],
+        "windsurf": [".windsurfrules"],
+        "cline": [".clinerules"],
+        "gemini": [".gemini"],
+        "junie": [".junie"],
+    }
+    
+    for ai_name, paths in checks.items():
+        for path in paths:
+            if (project_root / path).exists():
+                detected.append(ai_name)
+                break
+    
+    return detected
+
+
+def generate_ai_integration(
+    project_name: str,
+    project_purpose: str,
+    ai_type: str
+) -> Dict[str, str]:
+    """
+    Generate AI-specific integration files.
+    
+    Args:
+        project_name: Name of the project
+        project_purpose: Brief purpose of the project
+        ai_type: AI assistant type (claude, cursor, copilot, windsurf, cline, all)
+    
+    Returns:
+        Dictionary mapping file paths to content
+    """
+    integrations = {}
+    
+    generators = {
+        "claude": generate_claude_skill,
+        "cursor": generate_cursor_rules,
+        "copilot": generate_copilot_instructions,
+        "windsurf": generate_windsurf_rules,
+        "cline": generate_cline_rules,
+    }
+    
+    if ai_type == "all":
+        for generator in generators.values():
+            integrations.update(generator(project_name, project_purpose))
+    elif ai_type in generators:
+        integrations.update(generators[ai_type](project_name, project_purpose))
+    
+    return integrations
+
+
+def get_ai_assistant_choices() -> List[tuple]:
+    """
+    Get list of AI assistant choices for user prompt.
+    
+    Returns:
+        List of (name, description) tuples
+    """
+    return [
+        ("claude", "Claude Code (uses .claude/skills/)"),
+        ("cursor", "Cursor (uses .cursor/rules/ or .cursorrules)"),
+        ("copilot", "GitHub Copilot (uses .github/copilot-instructions.md)"),
+        ("windsurf", "Windsurf (uses .windsurfrules)"),
+        ("cline", "Cline/VSCode (uses .clinerules)"),
+        ("all", "All of the above"),
+        ("none", "Skip AI integration"),
+    ]