invar-tools 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

invar/shell/template_engine.py

@@ -0,0 +1,345 @@
+"""DX-49: Template engine with I/O operations and Jinja2 support.
+
+This module provides:
+- File update with region preservation
+- Jinja2 template rendering
+- Manifest loading
+
+Pure parsing logic is in core/template_parser.py.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from deal import pre
+from returns.result import Failure, Result, Success
+
+# Import pure logic from Core
+from invar.core.template_parser import (
+    ParsedFile,
+    Region,
+    get_syntax_for_command,
+    parse_invar_regions,
+    reconstruct_file,
+)
+
+# Re-export for convenience
+__all__ = [
+    "ParsedFile",
+    "Region",
+    "generate_from_manifest",
+    "get_syntax_for_command",
+    "get_templates_dir",
+    "is_invar_project",
+    "load_manifest",
+    "parse_invar_regions",
+    "reconstruct_file",
+    "render_template",
+    "render_template_file",
+    "update_file_with_regions",
+]
+
+
+# =============================================================================
+# File Update Logic
+# =============================================================================
+
+
+# @shell_complexity: File handling requires branching for exists/has_regions/new_project cases
+@pre(lambda path, new_managed: isinstance(path, Path) and isinstance(new_managed, str))
+def update_file_with_regions(
+    path: Path,
+    new_managed: str,
+    new_project: str | None = None,
+) -> Result[str, str]:
+    """Update file preserving user regions and unmarked content.
+
+    Args:
+        path: File path to update
+        new_managed: New content for managed region
+        new_project: New content for project region (sync-self only)
+
+    Returns:
+        Success with updated content, or Failure with error message
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+        ...     _ = f.write('''<!--invar:managed-->
+        ... old
+        ... <!--/invar:managed-->
+        ... <!--invar:user-->
+        ... keep this
+        ... <!--/invar:user-->''')
+        ...     path = Path(f.name)
+        >>> result = update_file_with_regions(path, "NEW")
+        >>> isinstance(result, Success)
+        True
+        >>> "NEW" in result.unwrap()
+        True
+        >>> "keep this" in result.unwrap()
+        True
+        >>> path.unlink()  # cleanup
+    """
+    if not path.exists():
+        # New file - just wrap in managed region
+        content = f"<!--invar:managed-->\n{new_managed}\n<!--/invar:managed-->\n"
+        if new_project:
+            content += f"\n<!--invar:project-->\n{new_project}\n<!--/invar:project-->\n"
+        content += "\n<!--invar:user-->\n\n<!--/invar:user-->\n"
+        return Success(content)
+
+    try:
+        current = path.read_text()
+    except OSError as e:
+        return Failure(f"Failed to read {path}: {e}")
+
+    parsed = parse_invar_regions(current)
+
+    if not parsed.has_regions:
+        # No markers - insert at top, preserve rest
+        content = f"<!--invar:managed-->\n{new_managed}\n<!--/invar:managed-->\n\n"
+        content += current
+        return Success(content)
+
+    # Build updates dict
+    updates: dict[str, str] = {"managed": new_managed}
+    if new_project is not None and "project" in parsed.regions:
+        updates["project"] = new_project
+
+    result = reconstruct_file(parsed, updates)
+    return Success(result)
+
+
+# =============================================================================
+# Jinja2 Template Rendering
+# =============================================================================
+
+
+def render_template(
+    template_content: str,
+    variables: dict[str, str],
+) -> Result[str, str]:
+    """Render a Jinja2 template with given variables.
+
+    Args:
+        template_content: Jinja2 template string
+        variables: Variables to inject (syntax, version, project_name, etc.)
+
+    Returns:
+        Success with rendered content, or Failure with error
+
+    Examples:
+        >>> result = render_template("Hello {{ name }}", {"name": "World"})
+        >>> result.unwrap()
+        'Hello World'
+
+        >>> result = render_template("{% if x %}yes{% endif %}", {"x": True})
+        >>> result.unwrap()
+        'yes'
+    """
+    try:
+        from jinja2 import BaseLoader, Environment, StrictUndefined
+
+        env = Environment(
+            loader=BaseLoader(),
+            undefined=StrictUndefined,
+            keep_trailing_newline=True,
+        )
+        template = env.from_string(template_content)
+        rendered = template.render(**variables)
+        return Success(rendered)
+    except ImportError:
+        return Failure("Jinja2 not installed. Run: pip install jinja2")
+    except Exception as e:
+        return Failure(f"Template rendering failed: {e}")
+
+
+def render_template_file(
+    template_path: Path,
+    variables: dict[str, str],
+) -> Result[str, str]:
+    """Render a Jinja2 template file.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.jinja', delete=False) as f:
+        ...     _ = f.write("Version: {{ version }}")
+        ...     path = Path(f.name)
+        >>> result = render_template_file(path, {"version": "5.0"})
+        >>> result.unwrap()
+        'Version: 5.0'
+        >>> path.unlink()
+    """
+    try:
+        content = template_path.read_text()
+    except OSError as e:
+        return Failure(f"Failed to read template {template_path}: {e}")
+
+    return render_template(content, variables)
+
+
+# =============================================================================
+# Manifest Loading
+# =============================================================================
+
+
+# @shell_complexity: TOML loading with Python version fallback (tomllib vs tomli)
+def load_manifest(templates_dir: Path) -> Result[dict, str]:
+    """Load manifest.toml from templates directory.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> # Will fail if manifest doesn't exist
+        >>> result = load_manifest(Path("/nonexistent"))
+        >>> isinstance(result, Failure)
+        True
+    """
+    manifest_path = templates_dir / "manifest.toml"
+
+    if not manifest_path.exists():
+        return Failure(f"Manifest not found: {manifest_path}")
+
+    try:
+        import tomllib
+
+        content = manifest_path.read_text()
+        data = tomllib.loads(content)
+        return Success(data)
+    except ImportError:
+        # Python < 3.11
+        try:
+            import tomli as tomllib  # type: ignore
+
+            content = manifest_path.read_text()
+            data = tomllib.loads(content)
+            return Success(data)
+        except ImportError:
+            return Failure("tomllib/tomli not available")
+    except Exception as e:
+        return Failure(f"Failed to parse manifest: {e}")
+
+
+# =============================================================================
+# Template Generation
+# =============================================================================
+
+
+def get_templates_dir() -> Path:
+    """Get the templates directory path."""
+    return Path(__file__).parent.parent / "templates"
+
+
+# @shell_complexity: Template generation has multiple paths for copy/jinja/copy_dir types
+def generate_from_manifest(
+    dest_root: Path,
+    syntax: str = "cli",
+    files_to_generate: list[str] | None = None,
+) -> Result[list[str], str]:
+    """Generate files from manifest.toml templates.
+
+    Args:
+        dest_root: Destination project root
+        syntax: "cli" or "mcp" for command syntax
+        files_to_generate: Optional list of files to generate (None = all from manifest)
+
+    Returns:
+        Success with list of generated files, or Failure with error
+    """
+    templates_dir = get_templates_dir()
+    manifest_result = load_manifest(templates_dir)
+    if isinstance(manifest_result, Failure):
+        return manifest_result
+
+    manifest = manifest_result.unwrap()
+    templates = manifest.get("templates", {})
+    # Copy to avoid mutating cached manifest
+    variables = {**manifest.get("variables", {}), "syntax": syntax}
+
+    generated: list[str] = []
+
+    for dest_path, config in templates.items():
+        # Skip if not in files_to_generate list
+        if files_to_generate is not None and dest_path not in files_to_generate:
+            continue
+
+        src = config.get("src", "")
+        template_type = config.get("type", "copy")
+        src_path = templates_dir / src
+
+        # Resolve destination
+        full_dest = dest_root / dest_path
+
+        # Ensure parent directories exist
+        full_dest.parent.mkdir(parents=True, exist_ok=True)
+
+        if template_type == "copy":
+            # Direct file copy
+            if not src_path.exists():
+                continue
+            if full_dest.exists():
+                continue  # Don't overwrite existing
+            try:
+                full_dest.write_text(src_path.read_text())
+                generated.append(dest_path)
+            except OSError as e:
+                print(f"Warning: Failed to copy {dest_path}: {e}", file=sys.stderr)
+                continue
+
+        elif template_type == "jinja":
+            # Jinja2 template rendering
+            if not src_path.exists():
+                continue
+            if full_dest.exists():
+                continue  # Don't overwrite existing
+            result = render_template_file(src_path, variables)
+            if isinstance(result, Success):
+                try:
+                    full_dest.write_text(result.unwrap())
+                    generated.append(dest_path)
+                except OSError as e:
+                    print(f"Warning: Failed to write {dest_path}: {e}", file=sys.stderr)
+                    continue
+
+        elif template_type == "copy_dir":
+            # Directory copy
+            if not src_path.exists() or not src_path.is_dir():
+                continue
+            if full_dest.exists():
+                continue  # Don't overwrite existing directory
+            try:
+                import shutil
+                shutil.copytree(src_path, full_dest)
+                generated.append(dest_path)
+            except OSError as e:
+                print(f"Warning: Failed to copy directory {dest_path}: {e}", file=sys.stderr)
+                continue
+
+    return Success(generated)
+
+
+# =============================================================================
+# Utility Functions
+# =============================================================================
+
+
+def is_invar_project(project_root: Path) -> bool:
+    """Check if this is the Invar project itself.
+
+    The Invar project has special handling via sync-self.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> is_invar_project(Path("/some/random/project"))
+        False
+    """
+    # Check for Invar-specific markers
+    invar_markers = [
+        project_root / "src" / "invar" / "__init__.py",
+        project_root / "runtime" / "src" / "invar_runtime" / "__init__.py",
+    ]
+    return all(marker.exists() for marker in invar_markers)

invar/shell/templates.py

@@ -168,6 +168,25 @@ def copy_commands_directory(dest: Path, console) -> Result[bool, str]:
         return Failure(f"Failed to copy commands: {e}")
 
 
+# @shell_complexity: Directory copy for Claude skills (DX-36)
+def copy_skills_directory(dest: Path, console) -> Result[bool, str]:
+    """Copy skills directory to .claude/skills/. Returns Success(True) if copied."""
+    import shutil
+    skills_dest = dest / ".claude" / "skills"
+    if skills_dest.exists():
+        return Success(False)
+    try:
+        skills_src = Path(str(resources.files("invar.templates").joinpath("skills")))
+        if not skills_src.exists():
+            return Failure("Skills template directory not found")
+        (dest / ".claude").mkdir(exist_ok=True)
+        shutil.copytree(skills_src, skills_dest)
+        console.print("[green]Created[/green] .claude/skills/ (workflow skills)")
+        return Success(True)
+    except OSError as e:
+        return Failure(f"Failed to copy skills: {e}")
+
+
 # Agent configuration for multi-agent support (DX-11, DX-17)
 AGENT_CONFIGS = {
     "claude": {

invar/shell/testing.py

@@ -18,10 +18,12 @@ from pathlib import Path
 from returns.result import Failure, Result, Success
 from rich.console import Console
 
+from invar.shell.prove.cache import ProveCache
+
 # DX-12: Import from prove module
 # DX-13: Added get_files_to_prove, run_crosshair_parallel
-# DX-13: ProveCache extracted to prove_cache.py
-from invar.shell.prove import (
+# DX-48b: Relocated to shell/prove/
+from invar.shell.prove.crosshair import (
     CrossHairStatus,
     get_files_to_prove,
     run_crosshair_on_files,
@@ -29,7 +31,7 @@ from invar.shell.prove import (
     run_hypothesis_fallback,
     run_prove_with_fallback,
 )
-from invar.shell.prove_cache import ProveCache
+from invar.shell.subprocess_env import build_subprocess_env
 
 console = Console()
 
@@ -113,7 +115,10 @@ def get_available_verifiers() -> list[str]:
 
 # @shell_complexity: Doctest execution with subprocess and result parsing
 def run_doctests_on_files(
-    files: list[Path], verbose: bool = False
+    files: list[Path],
+    verbose: bool = False,
+    timeout: int = 60,
+    collect_coverage: bool = False,
 ) -> Result[dict, str]:
     """
     Run doctests on a list of Python files.
@@ -121,6 +126,8 @@ def run_doctests_on_files(
     Args:
         files: List of Python file paths to test
         verbose: Show verbose output
+        timeout: Maximum time in seconds (default: 60, from RuleConfig.timeout_doctest)
+        collect_coverage: DX-37: If True, run with coverage.py and return coverage data
 
     Returns:
         Success with test results or Failure with error message
@@ -129,21 +136,45 @@ def run_doctests_on_files(
         return Success({"status": "skipped", "reason": "no files", "files": []})
 
     # Filter to Python files only
-    py_files = [f for f in files if f.suffix == ".py" and f.exists()]
+    # Exclude: conftest.py (pytest config), templates/examples/ (source templates, not user examples)
+    py_files = [
+        f for f in files
+        if f.suffix == ".py"
+        and f.exists()
+        and f.name != "conftest.py"
+        and "templates/examples" not in str(f)
+    ]
     if not py_files:
         return Success({"status": "skipped", "reason": "no Python files", "files": []})
 
-    # Build pytest command
-    cmd = [
-        sys.executable, "-m", "pytest",
-        "--doctest-modules", "-x", "--tb=short",
-    ]
+    # DX-37: Build command with optional coverage
+    if collect_coverage:
+        # Use coverage run to wrap pytest
+        cmd = [
+            sys.executable, "-m", "coverage", "run",
+            "--branch",  # Enable branch coverage
+            "--parallel-mode",  # For merging with hypothesis later
+            "-m", "pytest",
+            "--doctest-modules", "-x", "--tb=short",
+        ]
+    else:
+        cmd = [
+            sys.executable, "-m", "pytest",
+            "--doctest-modules", "-x", "--tb=short",
+        ]
     cmd.extend(str(f) for f in py_files)
     if verbose:
         cmd.append("-v")
 
     try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+        # DX-52: Inject project venv site-packages for uvx compatibility
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=build_subprocess_env(),
+        )
         # Pytest exit codes: 0=passed, 5=no tests collected (also OK)
         is_passed = result.returncode in (0, 5)
         return Success({
@@ -152,16 +183,17 @@ def run_doctests_on_files(
             "exit_code": result.returncode,
             "stdout": result.stdout,
             "stderr": result.stderr,
+            "coverage_collected": collect_coverage,  # DX-37: Flag for caller
         })
     except subprocess.TimeoutExpired:
-        return Failure("Doctest timeout (120s)")
+        return Failure(f"Doctest timeout ({timeout}s)")
     except Exception as e:
         return Failure(f"Doctest error: {e}")
 
 
 # @shell_complexity: Property test orchestration with subprocess
 def run_test(
-    target: str, json_output: bool = False, verbose: bool = False
+    target: str, json_output: bool = False, verbose: bool = False, timeout: int = 300
 ) -> Result[dict, str]:
     """
     Run property-based tests using Hypothesis via deal.cases.
@@ -170,6 +202,7 @@ def run_test(
         target: File path or module to test
         json_output: Output as JSON
         verbose: Show verbose output
+        timeout: Maximum time in seconds (default: 300, from RuleConfig.timeout_hypothesis)
 
     Returns:
         Success with test results or Failure with error message
@@ -188,7 +221,14 @@ def run_test(
         cmd.append("-v")
 
     try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+        # DX-52: Inject project venv site-packages for uvx compatibility
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=build_subprocess_env(),
+        )
         test_result = {
             "status": "passed" if result.returncode == 0 else "failed",
             "target": str(target_path),
@@ -212,14 +252,17 @@ def run_test(
 
         return Success(test_result)
     except subprocess.TimeoutExpired:
-        return Failure(f"Test timeout (300s): {target}")
+        return Failure(f"Test timeout ({timeout}s): {target}")
     except Exception as e:
         return Failure(f"Test error: {e}")
 
 
 # @shell_complexity: CrossHair verification with subprocess
 def run_verify(
-    target: str, json_output: bool = False, timeout: int = 30
+    target: str,
+    json_output: bool = False,
+    total_timeout: int = 300,
+    per_condition_timeout: int = 30,
 ) -> Result[dict, str]:
     """
     Run symbolic verification using CrossHair.
@@ -227,7 +270,8 @@ def run_verify(
     Args:
         target: File path or module to verify
         json_output: Output as JSON
-        timeout: Timeout per function in seconds
+        total_timeout: Total timeout in seconds (default: 300, from RuleConfig.timeout_crosshair)
+        per_condition_timeout: Per-contract timeout (default: 30, from RuleConfig.timeout_crosshair_per_condition)
 
     Returns:
         Success with verification results or Failure with error message
@@ -248,11 +292,18 @@ def run_verify(
 
     cmd = [
         sys.executable, "-m", "crosshair", "check",
-        str(target_path), f"--per_condition_timeout={timeout}",
+        str(target_path), f"--per_condition_timeout={per_condition_timeout}",
     ]
 
     try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout * 10)
+        # DX-52: Inject project venv site-packages for uvx compatibility
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=total_timeout,
+            env=build_subprocess_env(),
+        )
 
         # CrossHair format: "file:line: error: Err when calling func(...)"
         counterexamples = [
@@ -281,6 +332,6 @@ def run_verify(
 
         return Success(verify_result)
     except subprocess.TimeoutExpired:
-        return Failure(f"Verification timeout ({timeout * 10}s): {target}")
+        return Failure(f"Verification timeout ({total_timeout}s): {target}")
     except Exception as e:
         return Failure(f"Verification error: {e}")

invar/templates/CLAUDE.md.template

@@ -7,21 +7,24 @@
 Your first message MUST display:
 
 ```
-✓ Check-In: guard PASS | top: <entry1>, <entry2>
+✓ Check-In: [project] | [branch] | [clean/dirty]
 ```
 
-Execute `invar_guard(changed=true)` and `invar_map(top=10)`, then show this one-line summary.
+Actions:
+1. Read `.invar/context.md` (Key Rules + Current State + Lessons Learned)
+2. Show one-line status
 
 Example:
 ```
-✓ Check-In: guard PASS | top: parse_file, check_rules
+✓ Check-In: MyProject | main | clean
 ```
 
+**Do NOT execute guard or map at Check-In.**
+Guard is for VALIDATE phase and Final only.
+
 This is your sign-in. The user sees it immediately.
 No visible check-in = Session not started.
 
-Then read `.invar/context.md` for project state and lessons learned.
-
 ---
 
 ## Final
@@ -80,27 +83,45 @@ For complex tasks (3+ functions), show 3 checkpoints in TodoList:
 
 ---
 
-## Agent Roles
+## Commands (User-Invokable)
 
-| Command | Role | Purpose |
-|---------|------|---------|
-| `/review` | Reviewer | Adversarial code review (DX-31) |
+| Command | Purpose |
+|---------|---------|
+| `/audit` | Read-only code review (reports issues, no fixes) |
+| `/guard` | Run Invar verification (reports results) |
 
-### Review Modes (Auto-Selected)
+## Skills (Agent-Invoked)
 
-`/review` automatically selects mode based on Guard output:
+| Skill | Triggers | Purpose |
+|-------|----------|---------|
+| `/investigate` | "why", "explain", vague tasks | Research mode, no code changes |
+| `/propose` | "should we", "compare" | Decision facilitation |
+| `/develop` | "add", "fix", "implement" | USBV implementation workflow |
+| `/review` | After /develop, `review_suggested` | Adversarial review with fix loop |
 
-| Condition | Mode | Behavior |
-|-----------|------|----------|
-| `review_suggested` triggered | **Isolated** | Task tool sub-agent (fresh context) |
-| No trigger | **Quick** | Same-context adversarial review |
-| `--isolated` flag | **Isolated** | Force isolation |
-| `--quick` flag | **Quick** | Force same-context |
+**Note:** Skills are invoked by agent based on context. Use `/audit` for user-initiated review.
 
 Guard triggers `review_suggested` for: security-sensitive files, escape hatches >= 3, contract coverage < 50%.
 
 ---
 
+## Workflow Routing (MANDATORY)
+
+When user message contains these triggers, you MUST invoke the corresponding skill:
+
+| Trigger Words | Skill | Notes |
+|---------------|-------|-------|
+| "review", "review and fix" | `/review` | Adversarial review with fix loop |
+| "implement", "add", "fix", "update" | `/develop` | Unless in review context |
+| "why", "explain", "investigate" | `/investigate` | Research mode, no code changes |
+| "compare", "should we", "design" | `/propose` | Decision facilitation |
+
+**Violation check (before writing ANY code):**
+- "Am I in a workflow?"
+- "Did I invoke the correct skill?"
+
+---
+
 ## Project-Specific Rules
 
 <!-- Add your team conventions below -->

invar/templates/aider.conf.yml.template

@@ -14,9 +14,9 @@ system-prompt: |
 
   ## Check-In
   Your first message MUST display:
-  ✓ Check-In: guard PASS | top: <entry1>, <entry2>
+  ✓ Check-In: [project] | [branch] | [clean/dirty]
 
-  Execute: invar guard --changed && invar map --top 10
+  Read .invar/context.md first. Do NOT run guard/map at Check-In.
   This is your sign-in. No visible check-in = Session not started.
 
   ## Final