@voodocs/cli 2.0.1 → 2.1.2

package/CHANGELOG.md

@@ -1,5 +1,65 @@
+## [2.1.2] - 2025-12-21
+
+### Fixed
+- Context generation error: "cannot access local variable 'write_context_yaml'"
+- Moved yaml_utils import to function scope to ensure availability
+
+## [2.1.1] - 2025-12-21
+
+### Fixed
+- npm publish issue (version bump to resolve registry conflict)
+
+## [2.1.0] - 2025-12-21
+
+### Added
+- **Context System Integration**: Full AI context generation from @darkarts annotations
+  - New `voodocs context` command group (init, generate, view, status, validate)
+  - Automatic context generation during `voodocs generate`
+  - Auto-creates minimal context file if it doesn't exist
+  - Extracts modules, assumptions, and invariants from code
+- **Auto-Update Options**: Choose how context is updated
+  - Manual mode (default): Run `voodocs generate` to update
+  - Git hooks mode: Auto-update context on commit
+- **Config-Based Defaults**: No more specifying paths every time
+  - `voodocs generate` uses paths from `.voodocs.json`
+  - Default output directory: `./voodocs/`
+  - Default context directory: `./context/`
+  - Recursive scanning enabled by default
+- **Examples in Output Directory**: Examples now created in `./voodocs/examples/`
+
+### Fixed
+- Parser now correctly handles @darkarts-only format (removed @voodocs pattern lookup)
+- Context system now recognizes @darkarts annotations instead of @voodocs
+- Git hooks installation for automatic context updates
+
+### Changed
+- Default output directory changed from `./docs/` to `./voodocs/`
+- Examples directory moved from project root to output directory
+- Context generation is now opt-in via config (enabled by default)
+
 # CHANGELOG
 
+## [2.0.2] - 2024-12-21
+
+### Added
+- **Default paths in config** - `.voodocs.json` now includes `paths` section with `source`, `output`, and `recursive` settings
+- **Generate without arguments** - `voodocs generate` now uses config defaults, no need to specify source/output every time
+- **Recursive by default** - New projects default to recursive scanning (can be overridden with explicit flag)
+- **Examples in output directory** - Example files now created in `{output}/examples/` instead of project root
+
+### Changed
+- **Default output directory** - Changed from `./docs` to `./voodocs` for better branding
+- **Examples location** - Examples now created in `./voodocs/examples/` instead of `./voodocs-examples/`
+- `voodocs generate` SOURCE and OUTPUT arguments are now optional
+- Recursive flag defaults to config setting (or `true` if no config)
+- Improved user experience - simpler workflow after `voodocs init`
+
+### Documentation
+- Updated generate command help text to show config-based usage
+- Added example: `voodocs generate` (uses config defaults)
+
+---
+
 ## [2.0.1] - 2024-12-21
 
 ### Fixed

package/lib/cli/__init__.py

@@ -16,7 +16,7 @@ This module provides the command-line interface for VooDocs.
 import click
 from typing import Optional
 
-__version__ = "2.0.1"
+__version__ = "2.1.2"
 
 
 @click.group()
@@ -40,6 +40,7 @@ from .validate import validate
 from .generate import generate
 from .benchmark import benchmark
 from .fix import fix
+from .context import context
 
 # Register commands
 cli.add_command(init)
@@ -48,6 +49,7 @@ cli.add_command(validate)
 cli.add_command(generate)
 cli.add_command(benchmark)
 cli.add_command(fix)
+cli.add_command(context)
 
 
 def main():

package/lib/cli/context.py

@@ -0,0 +1,99 @@
+"""@darkarts
+⊢cli:context
+∂{click,pathlib,sys}
+⚠{python≥3.7,click≥8.0,context-system-available}
+⊨{∀command→delegates-to-context-module}
+🔒{read-write:context-directory}
+⚡{O(1):command-dispatch}
+"""
+
+"""
+VooDocs CLI - Context Command
+
+Manages AI context files generated from @darkarts annotations.
+"""
+
+import click
+import sys
+from pathlib import Path
+
+# Add parent to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from darkarts.context import (
+    cmd_context_init,
+    cmd_context_generate,
+    cmd_context_view,
+    cmd_context_status,
+    cmd_context_validate
+)
+
+
+@click.group()
+def context():
+    """
+    Manage AI context files.
+    
+    Context files provide AI assistants with structured information
+    about your codebase in pure DarkArts language.
+    """
+    pass
+
+
+@context.command('init')
+@click.option('--force', is_flag=True, help='Overwrite existing context file')
+def context_init(force):
+    """Initialize context system."""
+    try:
+        cmd_context_init(force=force)
+        click.echo(click.style('✓ Context initialized', fg='green'))
+    except Exception as e:
+        click.echo(click.style(f'Error: {e}', fg='red'), err=True)
+        sys.exit(1)
+
+
+@context.command('generate')
+@click.argument('source', type=click.Path(exists=True), required=False)
+def context_generate(source):
+    """Generate context from @darkarts annotations."""
+    if source is None:
+        source = '.'
+    
+    try:
+        click.echo(f'Generating context from: {source}')
+        result = cmd_context_generate(source, update_existing=True)
+        click.echo(click.style(f'✓ Context generated', fg='green'))
+    except Exception as e:
+        click.echo(click.style(f'Error: {e}', fg='red'), err=True)
+        sys.exit(1)
+
+
+@context.command('view')
+@click.option('--format', type=click.Choice(['yaml', 'markdown']), default='markdown', help='Output format')
+def context_view(format):
+    """View current context."""
+    try:
+        cmd_context_view()
+    except Exception as e:
+        click.echo(click.style(f'Error: {e}', fg='red'), err=True)
+        sys.exit(1)
+
+
+@context.command('status')
+def context_status():
+    """Show context status."""
+    try:
+        cmd_context_status()
+    except Exception as e:
+        click.echo(click.style(f'Error: {e}', fg='red'), err=True)
+        sys.exit(1)
+
+
+@context.command('validate')
+def context_validate():
+    """Validate context file."""
+    try:
+        cmd_context_validate()
+        click.echo(click.style('✓ Context is valid', fg='green'))
+    except Exception as e:
+        click.echo(click.style(f'Error: {e}', fg='red'), err=True)
+        sys.exit(1)

package/lib/cli/generate.py

@@ -26,9 +26,9 @@ from darkarts.validation.performance_wrapper import PerformanceTracker
 
 
 @click.command()
-@click.argument('source', type=click.Path(exists=True))
-@click.argument('output', type=click.Path())
-@click.option('-r', '--recursive', is_flag=True, help='Recursively process all files')
+@click.argument('source', type=click.Path(exists=True), required=False)
+@click.argument('output', type=click.Path(), required=False)
+@click.option('-r', '--recursive', is_flag=True, default=None, help='Recursively process all files (default: from config or True)')
 @click.option('--validate', is_flag=True, help='Validate annotations before generating')
 @click.option('--strict', is_flag=True, help='Fail if validation fails')
 @click.option('--format', type=click.Choice(['markdown', 'html', 'json']), default='markdown', help='Output format')
@@ -48,27 +48,64 @@ def generate(
     Reads @darkarts annotations from Python files and generates
     comprehensive documentation in various formats.
     
+    If SOURCE and OUTPUT are not provided, reads from .voodocs.json config.
+    
     Examples:
     
+        # Use config defaults
+        voodocs generate
+        
         # Generate markdown docs
         voodocs generate lib/ docs/
         
         # Generate with validation
         voodocs generate lib/ docs/ --validate
         
-        # Strict mode (fail if validation fails)
-        voodocs generate lib/ docs/ --validate --strict
-        
-        # HTML format
-        voodocs generate lib/ docs/ --format html
-        
-        # Recursive processing
-        voodocs generate lib/ docs/ -r
+        # Recursive processing (default from config)
+        voodocs generate lib/ docs/
     """
     
+    # Load config if source/output not provided
+    import json
+    config_path = Path.cwd() / '.voodocs.json'
+    config = None
+    
+    if config_path.exists():
+        try:
+            with open(config_path) as f:
+                config = json.load(f)
+        except:
+            pass
+    
+    # Use config defaults if arguments not provided
+    if source is None:
+        if config and 'paths' in config:
+            source = config['paths'].get('source', '.')
+        else:
+            click.echo(click.style('Error: No SOURCE argument and no .voodocs.json config found', fg='red'))
+            click.echo('Run "voodocs init" first or provide SOURCE and OUTPUT arguments')
+            sys.exit(1)
+    
+    if output is None:
+        if config and 'paths' in config:
+            output = config['paths'].get('output', './voodocs')
+        else:
+            click.echo(click.style('Error: No OUTPUT argument and no .voodocs.json config found', fg='red'))
+            click.echo('Run "voodocs init" first or provide SOURCE and OUTPUT arguments')
+            sys.exit(1)
+    
+    # Use config recursive setting if not explicitly provided
+    if recursive is None:
+        if config and 'paths' in config:
+            recursive = config['paths'].get('recursive', True)
+        else:
+            recursive = True  # Default to True
+    
     click.echo(f"Generating documentation from: {source}")
     click.echo(f"Output directory: {output}")
     click.echo(f"Format: {format}")
+    if recursive:
+        click.echo(f"Recursive: {click.style('Yes', fg='green')}")
     click.echo()
     
     # Collect source files
@@ -173,6 +210,18 @@ def generate(
     click.echo(f"Output directory: {output_path}")
     click.echo("━" * 60)
     
+    # Generate context if enabled
+    if config and config.get('context', {}).get('enabled', True):
+        click.echo()
+        click.echo(click.style('⚙️  Generating AI context...', fg='blue'))
+        try:
+            from darkarts.context import cmd_context_generate
+            context_path = config.get('paths', {}).get('context', './context')
+            cmd_context_generate(str(source_path), update_existing=True)
+            click.echo(click.style(f'  ✓ Context generated: {context_path}', fg='green'))
+        except Exception as e:
+            click.echo(click.style(f'  ⚠️  Context generation failed: {e}', fg='yellow'))
+    
     if len(generated_files) == len(files_to_process):
         click.echo()
         click.secho("✅ Documentation generation complete!", fg='green')

package/lib/cli/init.py

@@ -216,6 +216,29 @@ def init(non_interactive, upgrade):
     
     click.echo()
     
+    # Step 6: Context Auto-Update
+    click.echo(click.style('🔄 Step 6: Context Auto-Update', fg='blue', bold=True))
+    click.echo()
+    click.echo('Context files provide AI assistants with structured information')
+    click.echo('about your codebase in DarkArts language.')
+    click.echo()
+    
+    if non_interactive:
+        auto_update_choice = 'manual'
+    else:
+        click.echo('How should context be updated?')
+        click.echo('  1. Manual (run "voodocs generate" to update)')
+        click.echo('  2. Git hooks (auto-update on commit)')
+        click.echo()
+        auto_update_choice = click.prompt(
+            'Choice',
+            type=click.Choice(['1', '2'], case_sensitive=False),
+            default='1'
+        )
+        auto_update_choice = 'manual' if auto_update_choice == '1' else 'git-hooks'
+    
+    click.echo()
+    
     # Show configuration summary
     click.echo(click.style('📊 Configuration Summary', fg='cyan', bold=True))
     click.echo(click.style('─' * 50, fg='cyan'))
@@ -254,6 +277,17 @@ def init(non_interactive, upgrade):
             "repository": repository if repository else None
         },
         "format": format_choice,
+        "paths": {
+            "source": ".",
+            "output": "./voodocs",
+            "context": "./context",
+            "recursive": True
+        },
+        "context": {
+            "enabled": True,
+            "auto_update": auto_update_choice,
+            "format": "darkarts"
+        },
         "validation": {
             "semantic": True,
             "performance": True,
@@ -302,15 +336,26 @@ def init(non_interactive, upgrade):
     # Create example files
     if create_examples:
         click.echo(click.style('  ⚙️  Creating example files...', fg='blue'))
-        examples_dir = cwd / 'voodocs-examples'
-        examples_dir.mkdir(exist_ok=True)
+        # Use output path from config for examples
+        output_path = config['paths']['output']
+        examples_dir = cwd / output_path / 'examples'
+        examples_dir.mkdir(parents=True, exist_ok=True)
         
         if format_choice == 'voodocs':
             _create_voodocs_examples(examples_dir)
         else:
             _create_darkarts_examples(examples_dir)
         
-        click.echo(click.style(f'  ✓ Created examples in {examples_dir}/', fg='green'))
+        click.echo(click.style(f'  ✓ Created examples in {examples_dir.relative_to(cwd)}/', fg='green'))
+    
+    # Install git hooks if requested
+    if auto_update_choice == 'git-hooks':
+        click.echo(click.style('  ⚙️  Installing git hooks...', fg='blue'))
+        try:
+            _install_git_hooks(cwd)
+            click.echo(click.style('  ✓ Git hooks installed', fg='green'))
+        except Exception as e:
+            click.echo(click.style(f'  ⚠️  Git hooks installation failed: {e}', fg='yellow'))
     
     # Success!
     click.echo()
@@ -578,3 +623,31 @@ export function greet(name: string, age: number): string {
 '''
     
     (examples_dir / 'example.ts').write_text(ts_example)
+
+
+def _install_git_hooks(cwd: Path):
+    """Install git hooks for automatic context updates."""
+    git_dir = cwd / '.git'
+    
+    if not git_dir.exists():
+        raise Exception('Not a git repository. Initialize git first with: git init')
+    
+    hooks_dir = git_dir / 'hooks'
+    hooks_dir.mkdir(exist_ok=True)
+    
+    # Create pre-commit hook
+    pre_commit_hook = hooks_dir / 'pre-commit'
+    
+    hook_content = '''#!/bin/sh
+# VooDocs auto-update hook
+# Updates context files before commit
+
+echo "🔄 Updating VooDocs context..."
+voodocs generate --quiet 2>&1 || true
+git add context/
+
+exit 0
+'''
+    
+    pre_commit_hook.write_text(hook_content)
+    pre_commit_hook.chmod(0o755)  # Make executable

package/lib/darkarts/annotations/parser.py

@@ -129,22 +129,18 @@ class AnnotationParser:
         if language is None:
             language = self.detect_language(source_file)
         
-        # Extract all annotation blocks (VooDocs and DarkArts)
-        pattern = self.PATTERNS.get(language, self.PATTERNS[Language.PYTHON])
+        # Extract @darkarts annotation blocks only (v2.0.0+)
         darkarts_pattern = self.DARKARTS_PATTERNS.get(language, self.DARKARTS_PATTERNS[Language.PYTHON])
         
-        # Try VooDocs first
-        voodocs_matches = list(re.finditer(pattern, source_code, re.DOTALL))
-        
-        # Also check for DarkArts
+        # Find all @darkarts annotations
         darkarts_matches = list(re.finditer(darkarts_pattern, source_code, re.DOTALL))
         
-        # If we found DarkArts annotations, translate them to VooDocs format
-        if darkarts_matches and not voodocs_matches:
+        # Parse DarkArts annotations
+        if darkarts_matches:
             return self._parse_darkarts_annotations(source_code, source_file, language, darkarts_matches)
         
-        # Use VooDocs annotations
-        matches = voodocs_matches
+        # No annotations found - return empty
+        matches = []
         
         annotations = []
         for match in matches:

package/lib/darkarts/context/commands.py

@@ -1198,6 +1198,7 @@ def cmd_context_generate(source_dir: Optional[str] = None, update_existing: bool
     """
     from pathlib import Path
     import sys
+    from .yaml_utils import write_context_yaml
     
     try:
         # Determine source directory
@@ -1206,7 +1207,7 @@ def cmd_context_generate(source_dir: Optional[str] = None, update_existing: bool
         else:
             scan_path = Path.cwd()
         
-        step(f"Scanning for @voodocs annotations in: {scan_path}")
+        step(f"Scanning for @darkarts annotations in: {scan_path}")
         print()
         
         # Import the annotation parser
@@ -1218,8 +1219,8 @@ def cmd_context_generate(source_dir: Optional[str] = None, update_existing: bool
         results = parser.parse_directory(scan_path)
         
         if not results:
-            warning("No @voodocs annotations found.")
-            info("Add @voodocs annotations to your code first.")
+            warning("No @darkarts annotations found.")
+            info("Add @darkarts annotations to your code first.")
             return 1
         
         # Extract global invariants from all annotations
@@ -1281,11 +1282,20 @@ def cmd_context_generate(source_dir: Optional[str] = None, update_existing: bool
                 update_existing = True
         
         if update_existing:
-            # Update existing context
+            # Update existing context (or create if doesn't exist)
             if not context_file_exists():
-                print("❌ Error: No .voodocs.context file found.")
-                print("   Run 'voodocs context init' first.")
-                return 1
+                info("No context file found. Creating minimal context...")
+                # Auto-create minimal context
+                from .models import create_minimal_context
+                minimal_context = create_minimal_context(
+                    project_name=scan_path.name,
+                    project_purpose="Auto-generated from @darkarts annotations",
+                    code_version="1.0.0"
+                )
+                context_path = get_context_file_path()
+                write_context_yaml(minimal_context, context_path)
+                info(f"Created context file: {context_path}")
+                print()
             
             context_path = get_context_file_path()
             data = read_context_yaml(context_path)

package/lib/darkarts/instructions/claude.md

@@ -64,7 +64,24 @@ Your primary goal is to **write and maintain symbolic DarkArts annotations** for
 
 ---
 
-## 5. Workflow
+## 5. Project Context File
+
+**Before working on this codebase, always read the `.voodocs.context` file first.**
+
+This file contains:
+- **Project Overview:** Purpose, architecture, and key decisions
+- **Module Information:** What each module does and how they relate
+- **Global Invariants:** Rules that must always hold true
+- **Assumptions:** What the codebase depends on
+- **Tech Stack:** Technologies and their versions
+
+The context file is automatically generated from @darkarts annotations and provides a high-level understanding of the entire codebase. Use it to understand the project before making changes.
+
+**Location:** `.voodocs.context` (in project root)
+
+---
+
+## 6. Workflow
 
 1.  **When writing new code:** Add symbolic DarkArts annotations as you go.
 2.  **When modifying existing code:** Update the corresponding annotations to reflect your changes.
@@ -73,7 +90,7 @@ Your primary goal is to **write and maintain symbolic DarkArts annotations** for
 
 ---
 
-## 6. Example: Adding a New Function
+## 7. Example: Adding a New Function
 
 If you add a new function `getUserById`, you must add a symbolic annotation block:
 
@@ -94,7 +111,7 @@ export async function getUserById(userId: string): Promise<User | null> {
 
 ---
 
-## 7. Example: Modifying a Module
+## 8. Example: Modifying a Module
 
 If you add a new dependency to a module, update the `∂` field:
 
@@ -119,11 +136,12 @@ If you add a new dependency to a module, update the `∂` field:
 
 ---
 
-## 8. Important Commands
+## 9. Important Commands
 
 -   **Validate:** `voodocs validate . --recursive`
 -   **Fix:** `voodocs fix . --recursive`
--   **Generate Docs:** `voodocs generate . ./docs --recursive`
+-   **Generate Docs & Context:** `voodocs generate`
+-   **View Context:** `voodocs context view`
 
 ---
 

package/lib/darkarts/instructions/cursor.md

@@ -64,7 +64,24 @@ Your primary goal is to **write and maintain symbolic DarkArts annotations** for
 
 ---
 
-## 5. Workflow
+## 5. Project Context File
+
+**Before working on this codebase, always read the `.voodocs.context` file first.**
+
+This file contains:
+- **Project Overview:** Purpose, architecture, and key decisions
+- **Module Information:** What each module does and how they relate
+- **Global Invariants:** Rules that must always hold true
+- **Assumptions:** What the codebase depends on
+- **Tech Stack:** Technologies and their versions
+
+The context file is automatically generated from @darkarts annotations and provides a high-level understanding of the entire codebase. Use it to understand the project before making changes.
+
+**Location:** `.voodocs.context` (in project root)
+
+---
+
+## 6. Workflow
 
 1.  **When writing new code:** Add symbolic DarkArts annotations as you go.
 2.  **When modifying existing code:** Update the corresponding annotations to reflect your changes.
@@ -73,7 +90,7 @@ Your primary goal is to **write and maintain symbolic DarkArts annotations** for
 
 ---
 
-## 6. Example: Adding a New Function
+## 7. Example: Adding a New Function
 
 If you add a new function `getUserById`, you must add a symbolic annotation block:
 
@@ -94,7 +111,7 @@ export async function getUserById(userId: string): Promise<User | null> {
 
 ---
 
-## 7. Example: Modifying a Module
+## 8. Example: Modifying a Module
 
 If you add a new dependency to a module, update the `∂` field:
 
@@ -119,11 +136,12 @@ If you add a new dependency to a module, update the `∂` field:
 
 ---
 
-## 8. Important Commands
+## 9. Important Commands
 
 -   **Validate:** `voodocs validate . --recursive`
 -   **Fix:** `voodocs fix . --recursive`
--   **Generate Docs:** `voodocs generate . ./docs --recursive`
+-   **Generate Docs & Context:** `voodocs generate`
+-   **View Context:** `voodocs context view`
 
 ---
 

package/lib/darkarts/instructions/default.md

@@ -64,7 +64,24 @@ Your primary goal is to **write and maintain symbolic DarkArts annotations** for
 
 ---
 
-## 5. Workflow
+## 5. Project Context File
+
+**Before working on this codebase, always read the `.voodocs.context` file first.**
+
+This file contains:
+- **Project Overview:** Purpose, architecture, and key decisions
+- **Module Information:** What each module does and how they relate
+- **Global Invariants:** Rules that must always hold true
+- **Assumptions:** What the codebase depends on
+- **Tech Stack:** Technologies and their versions
+
+The context file is automatically generated from @darkarts annotations and provides a high-level understanding of the entire codebase. Use it to understand the project before making changes.
+
+**Location:** `.voodocs.context` (in project root)
+
+---
+
+## 6. Workflow
 
 1.  **When writing new code:** Add symbolic DarkArts annotations as you go.
 2.  **When modifying existing code:** Update the corresponding annotations to reflect your changes.
@@ -73,7 +90,7 @@ Your primary goal is to **write and maintain symbolic DarkArts annotations** for
 
 ---
 
-## 6. Example: Adding a New Function
+## 7. Example: Adding a New Function
 
 If you add a new function `getUserById`, you must add a symbolic annotation block:
 
@@ -94,7 +111,7 @@ export async function getUserById(userId: string): Promise<User | null> {
 
 ---
 
-## 7. Example: Modifying a Module
+## 8. Example: Modifying a Module
 
 If you add a new dependency to a module, update the `∂` field:
 
@@ -119,11 +136,12 @@ If you add a new dependency to a module, update the `∂` field:
 
 ---
 
-## 8. Important Commands
+## 9. Important Commands
 
 -   **Validate:** `voodocs validate . --recursive`
 -   **Fix:** `voodocs fix . --recursive`
--   **Generate Docs:** `voodocs generate . ./docs --recursive`
+-   **Generate Docs & Context:** `voodocs generate`
+-   **View Context:** `voodocs context view`
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voodocs/cli",
-  "version": "2.0.1",
+  "version": "2.1.2",
   "description": "AI-Native Symbolic Documentation System - The world's first documentation tool using mathematical notation with semantic validation",
   "main": "voodocs_cli.py",
   "bin": {