invar-tools 1.5.0__py3-none-any.whl → 1.7.0__py3-none-any.whl

invar/shell/commands/uninstall.py

@@ -0,0 +1,341 @@
+"""
+DX-69: Uninstall Invar from a project.
+
+Safely removes Invar files and configurations while preserving user content.
+Uses marker-based detection to identify Invar-generated content.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+
+def has_invar_marker(path: Path) -> bool:
+    """Check if a file has Invar markers (_invar: or <!--invar:)."""
+    try:
+        content = path.read_text()
+        return "_invar:" in content or "<!--invar:" in content
+    except (OSError, UnicodeDecodeError):
+        return False
+
+
+def has_invar_region_marker(path: Path) -> bool:
+    """Check if a file has # invar:begin marker."""
+    try:
+        content = path.read_text()
+        return "# invar:begin" in content
+    except (OSError, UnicodeDecodeError):
+        return False
+
+
+def has_invar_hook_marker(path: Path) -> bool:
+    """Check if a hook file has invar marker."""
+    try:
+        content = path.read_text()
+        # Invar hooks have specific patterns
+        return "invar" in content.lower() and (
+            "INVAR_" in content
+            or "invar guard" in content
+            or "invar_guard" in content
+            or "invar." in content.lower()  # wrapper files: source invar.PreToolUse.sh
+            or "invar hook" in content.lower()  # comment: # Invar hook wrapper
+        )
+    except (OSError, UnicodeDecodeError):
+        return False
+
+
+# @shell_orchestration: Regex patterns tightly coupled to file removal logic
+def remove_invar_regions(content: str) -> str:
+    """Remove <!--invar:xxx-->...<!--/invar:xxx--> regions except user region."""
+    patterns = [
+        # HTML-style regions (CLAUDE.md)
+        (r"<!--invar:critical-->.*?<!--/invar:critical-->\n?", ""),
+        (r"<!--invar:managed[^>]*-->.*?<!--/invar:managed-->\n?", ""),
+        (r"<!--invar:project-->.*?<!--/invar:project-->\n?", ""),
+        # Comment-style regions (.pre-commit-config.yaml)
+        (r"# invar:begin\n.*?# invar:end\n?", ""),
+    ]
+    for pattern, replacement in patterns:
+        content = re.sub(pattern, replacement, content, flags=re.DOTALL)
+    return content.strip()
+
+
+def remove_mcp_invar_entry(path: Path) -> tuple[bool, str]:
+    """Remove invar entry from .mcp.json, return (modified, new_content)."""
+    try:
+        content = path.read_text()
+        data = json.loads(content)
+        if "mcpServers" in data and "invar" in data["mcpServers"]:
+            del data["mcpServers"]["invar"]
+            # If no servers left, indicate file can be deleted
+            if not data["mcpServers"]:
+                return True, ""
+            return True, json.dumps(data, indent=2)
+        return False, content
+    except (OSError, json.JSONDecodeError):
+        return False, ""
+
+
+# @shell_complexity: Multi-file type detection requires comprehensive branching
+def collect_removal_targets(path: Path) -> dict:
+    """Collect files and directories to remove/modify."""
+    targets = {
+        "delete_dirs": [],
+        "delete_files": [],
+        "modify_files": [],
+        "skip": [],
+    }
+
+    # Directories to delete entirely
+    invar_dir = path / ".invar"
+    if invar_dir.exists():
+        targets["delete_dirs"].append((".invar/", "directory"))
+
+    # Files to delete entirely
+    for file_name, description in [
+        ("invar.toml", "config"),
+        ("INVAR.md", "protocol"),
+    ]:
+        file_path = path / file_name
+        if file_path.exists():
+            targets["delete_files"].append((file_name, description))
+
+    # Skills with _invar marker
+    skills_dir = path / ".claude" / "skills"
+    if skills_dir.exists():
+        for skill_dir in skills_dir.iterdir():
+            if skill_dir.is_dir():
+                skill_file = skill_dir / "SKILL.md"
+                if skill_file.exists():
+                    if has_invar_marker(skill_file):
+                        targets["delete_dirs"].append(
+                            (f".claude/skills/{skill_dir.name}/", "skill, has _invar marker")
+                        )
+                    else:
+                        targets["skip"].append(
+                            (f".claude/skills/{skill_dir.name}/", "no _invar marker")
+                        )
+
+    # Commands with _invar marker
+    commands_dir = path / ".claude" / "commands"
+    if commands_dir.exists():
+        for cmd_file in commands_dir.glob("*.md"):
+            if has_invar_marker(cmd_file):
+                targets["delete_files"].append(
+                    (f".claude/commands/{cmd_file.name}", "command, has _invar marker")
+                )
+            else:
+                targets["skip"].append(
+                    (f".claude/commands/{cmd_file.name}", "no _invar marker")
+                )
+
+    # Hooks with invar marker
+    hooks_dir = path / ".claude" / "hooks"
+    if hooks_dir.exists():
+        for hook_file in hooks_dir.glob("*.sh"):
+            if has_invar_hook_marker(hook_file):
+                targets["delete_files"].append(
+                    (f".claude/hooks/{hook_file.name}", "hook, has invar marker")
+                )
+
+    # CLAUDE.md - modify, not delete
+    claude_md = path / "CLAUDE.md"
+    if claude_md.exists():
+        content = claude_md.read_text()
+        if "<!--invar:" in content:
+            # Check if there's user content
+            has_user_region = "<!--invar:user-->" in content
+            targets["modify_files"].append(
+                ("CLAUDE.md", f"remove invar regions{', keep user region' if has_user_region else ''}")
+            )
+
+    # .mcp.json - modify or delete
+    mcp_json = path / ".mcp.json"
+    if mcp_json.exists():
+        modified, new_content = remove_mcp_invar_entry(mcp_json)
+        if modified:
+            if new_content:
+                targets["modify_files"].append((".mcp.json", "remove mcpServers.invar"))
+            else:
+                targets["delete_files"].append((".mcp.json", "only had invar config"))
+
+    # Config files with region markers (DX-69: cursor/aider removed)
+    for file_name in [".pre-commit-config.yaml"]:
+        file_path = path / file_name
+        if file_path.exists():
+            if has_invar_region_marker(file_path):
+                content = file_path.read_text()
+                cleaned = remove_invar_regions(content)
+                if cleaned:
+                    targets["modify_files"].append((file_name, "remove invar:begin..end block"))
+                else:
+                    targets["delete_files"].append((file_name, "only had invar content"))
+            else:
+                targets["skip"].append((file_name, "no invar:begin marker"))
+
+    # Empty directories to clean up
+    for dir_name in ["src/core", "src/shell"]:
+        dir_path = path / dir_name
+        if dir_path.exists() and dir_path.is_dir():
+            if not any(dir_path.iterdir()):
+                targets["delete_dirs"].append((dir_name, "empty directory"))
+
+    return targets
+
+
+# @shell_complexity: Rich output formatting for different target categories
+def show_preview(targets: dict) -> None:
+    """Display what would be removed/modified."""
+    console.print("\n[bold]Invar Uninstall Preview[/bold]")
+    console.print("=" * 40)
+
+    if targets["delete_dirs"] or targets["delete_files"]:
+        console.print("\n[red]Will DELETE:[/red]")
+        for item, desc in targets["delete_dirs"]:
+            console.print(f"  {item:40} ({desc})")
+        for item, desc in targets["delete_files"]:
+            console.print(f"  {item:40} ({desc})")
+
+    if targets["modify_files"]:
+        console.print("\n[yellow]Will MODIFY:[/yellow]")
+        for item, desc in targets["modify_files"]:
+            console.print(f"  {item:40} ({desc})")
+
+    if targets["skip"]:
+        console.print("\n[dim]Will SKIP:[/dim]")
+        for item, desc in targets["skip"]:
+            console.print(f"  {item:40} ({desc})")
+
+    console.print()
+
+
+# @shell_complexity: Different file types require different removal strategies
+def execute_removal(path: Path, targets: dict) -> None:
+    """Execute the removal/modification operations."""
+    # Delete directories
+    for dir_name, _ in targets["delete_dirs"]:
+        dir_path = path / dir_name.rstrip("/")
+        if dir_path.exists():
+            shutil.rmtree(dir_path)
+            console.print(f"[red]Deleted[/red] {dir_name}")
+
+    # Delete files
+    for file_name, _ in targets["delete_files"]:
+        file_path = path / file_name
+        if file_path.exists():
+            file_path.unlink()
+            console.print(f"[red]Deleted[/red] {file_name}")
+
+    # Modify files
+    for file_name, _desc in targets["modify_files"]:
+        file_path = path / file_name
+        if not file_path.exists():
+            continue
+
+        if file_name == ".mcp.json":
+            modified, new_content = remove_mcp_invar_entry(file_path)
+            if modified and new_content:
+                file_path.write_text(new_content)
+                console.print(f"[yellow]Modified[/yellow] {file_name}")
+        else:
+            content = file_path.read_text()
+            cleaned = remove_invar_regions(content)
+            if cleaned:
+                file_path.write_text(cleaned + "\n")
+                console.print(f"[yellow]Modified[/yellow] {file_name}")
+            else:
+                file_path.unlink()
+                console.print(f"[red]Deleted[/red] {file_name} (empty after cleanup)")
+
+    # Clean up empty .claude directory if it exists and is empty
+    claude_dir = path / ".claude"
+    if claude_dir.exists():
+        # Check subdirectories
+        for subdir in ["skills", "commands", "hooks"]:
+            subdir_path = claude_dir / subdir
+            if subdir_path.exists() and not any(subdir_path.iterdir()):
+                subdir_path.rmdir()
+                console.print(f"[dim]Removed empty[/dim] .claude/{subdir}/")
+        # Check if .claude itself is empty
+        if not any(claude_dir.iterdir()):
+            claude_dir.rmdir()
+            console.print("[dim]Removed empty[/dim] .claude/")
+
+
+def uninstall(
+    path: Path = typer.Argument(
+        Path(),
+        help="Project path",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        "-n",
+        help="Show what would be removed without removing",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Skip confirmation prompt",
+    ),
+) -> None:
+    """Remove Invar from a project.
+
+    Safely removes Invar-generated files and configurations while
+    preserving user content. Uses marker-based detection.
+
+    Examples:
+        invar uninstall --dry-run    # Preview changes
+        invar uninstall              # Remove with confirmation
+        invar uninstall --force      # Remove without confirmation
+    """
+    # Check if this is an Invar project
+    invar_toml = path / "invar.toml"
+    invar_md = path / "INVAR.md"
+    invar_dir = path / ".invar"
+
+    if not (invar_toml.exists() or invar_md.exists() or invar_dir.exists()):
+        console.print("[yellow]Warning:[/yellow] This doesn't appear to be an Invar project.")
+        console.print("No invar.toml, INVAR.md, or .invar/ directory found.")
+        raise typer.Exit(1)
+
+    # Collect targets
+    targets = collect_removal_targets(path)
+
+    # Check if there's anything to do
+    if not any([targets["delete_dirs"], targets["delete_files"], targets["modify_files"]]):
+        console.print("[green]Nothing to remove.[/green] Project is clean.")
+        raise typer.Exit(0)
+
+    # Show preview
+    show_preview(targets)
+
+    # Dry run exits here
+    if dry_run:
+        console.print("[dim]Dry run complete. No changes made.[/dim]")
+        raise typer.Exit(0)
+
+    # Confirmation
+    if not force:
+        confirm = typer.confirm("Proceed with uninstall?", default=False)
+        if not confirm:
+            console.print("[dim]Cancelled.[/dim]")
+            raise typer.Exit(0)
+
+    # Execute
+    execute_removal(path, targets)
+
+    console.print("\n[green]✓ Invar has been removed from the project.[/green]")

invar/shell/config.py

@@ -267,6 +267,52 @@ def _find_config_source(project_root: Path) -> Result[tuple[Path | None, ConfigS
         return Failure(f"Failed to find config: {e}")
 
 
+# @shell_complexity: Project root discovery requires checking multiple markers
+def find_project_root(start_path: "Path") -> "Path":  # noqa: UP037
+    """
+    Find project root by walking up from start_path looking for config files.
+
+    Looks for (in order): pyproject.toml, invar.toml, .invar/, .git/
+
+    Args:
+        start_path: Starting path (file or directory)
+
+    Returns:
+        Project root directory (absolute path), or start_path's parent if no markers found
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.TemporaryDirectory() as tmpdir:
+        ...     root = Path(tmpdir).resolve()
+        ...     (root / "pyproject.toml").touch()
+        ...     subdir = root / "src" / "core"
+        ...     subdir.mkdir(parents=True)
+        ...     found = find_project_root(subdir / "file.py")
+        ...     found == root
+        True
+    """
+    from pathlib import Path
+
+    current = Path(start_path).resolve()  # Resolve to absolute path
+    if current.is_file():
+        current = current.parent
+
+    # Walk up looking for project markers
+    for parent in [current, *current.parents]:
+        if (parent / "pyproject.toml").exists():
+            return parent
+        if (parent / "invar.toml").exists():
+            return parent
+        if (parent / ".invar").is_dir():
+            return parent
+        if (parent / ".git").exists():
+            return parent
+
+    # Fallback to the starting directory
+    return current
+
+
 def _read_toml(path: Path) -> Result[dict[str, Any], str]:
     """Read and parse a TOML file."""
     try:

invar/shell/guard_output.py

@@ -209,6 +209,16 @@ def output_rich(
         if issue_parts:
             console.print(f"[dim]Issues: {', '.join(issue_parts)}[/dim]")
 
+    # DX-66: Escape hatch summary (only show if any exist)
+    if report.escape_hatches.count > 0:
+        escape_count = report.escape_hatches.count
+        by_rule = report.escape_hatches.by_rule
+        rule_parts = [f"{count} {rule}" for rule, count in sorted(by_rule.items())]
+        console.print(
+            f"\n[bold]Escape hatches:[/bold] {escape_count} "
+            f"({', '.join(rule_parts)})"
+        )
+
     # Code Health display (only when guard passes)
     if report.passed and report.files_checked > 0:
         # Calculate health: 100% for 0 warnings, decreases by 5% per warning, min 50%

invar/shell/templates.py

@@ -187,30 +187,16 @@ def copy_skills_directory(dest: Path, console) -> Result[bool, str]:
         return Failure(f"Failed to copy skills: {e}")
 
 
-# Agent configuration for multi-agent support (DX-11, DX-17)
+# Agent configuration - Claude Code only (DX-69: simplified, cursor/aider removed)
 AGENT_CONFIGS = {
     "claude": {
         "file": "CLAUDE.md",
         "template": "CLAUDE.md.template",
-        "reference": '> **Protocol:** Follow [INVAR.md](./INVAR.md) for the Invar development methodology.\n',
-        "check_pattern": "INVAR.md",
-    },
-    "cursor": {
-        "file": ".cursorrules",
-        "template": "cursorrules.template",
-        "reference": "Follow the Invar Protocol in INVAR.md.\n\n",
-        "check_pattern": "INVAR.md",
-    },
-    "aider": {
-        "file": ".aider.conf.yml",
-        "template": "aider.conf.yml.template",
-        "reference": "# Follow the Invar Protocol in INVAR.md\nread:\n  - INVAR.md\n",
         "check_pattern": "INVAR.md",
     },
 }
 
 
-# @shell_complexity: Agent config detection across multiple locations
 def detect_agent_configs(path: Path) -> Result[dict[str, str], str]:
     """
     Detect existing agent configuration files.
@@ -244,61 +230,6 @@ def detect_agent_configs(path: Path) -> Result[dict[str, str], str]:
         return Failure(f"Failed to detect agent configs: {e}")
 
 
-# @shell_complexity: Reference addition with existing check
-def add_invar_reference(path: Path, agent: str, console) -> Result[bool, str]:
-    """Add Invar reference to an existing agent config file."""
-    if agent not in AGENT_CONFIGS:
-        return Failure(f"Unknown agent: {agent}")
-
-    config = AGENT_CONFIGS[agent]
-    config_path = path / config["file"]
-
-    if not config_path.exists():
-        return Failure(f"Config file not found: {config['file']}")
-
-    try:
-        content = config_path.read_text()
-        if config["check_pattern"] in content:
-            return Success(False)  # Already configured
-
-        # Prepend reference
-        new_content = config["reference"] + content
-        config_path.write_text(new_content)
-        console.print(f"[green]Updated[/green] {config['file']} (added Invar reference)")
-        return Success(True)
-    except OSError as e:
-        return Failure(f"Failed to update {config['file']}: {e}")
-
-
-# @shell_complexity: Config creation with template selection
-def create_agent_config(path: Path, agent: str, console) -> Result[bool, str]:
-    """
-    Create agent config from template (DX-17).
-
-    Creates full template file for agents that don't have an existing config.
-    """
-    if agent not in AGENT_CONFIGS:
-        return Failure(f"Unknown agent: {agent}")
-
-    config = AGENT_CONFIGS[agent]
-    config_path = path / config["file"]
-
-    if config_path.exists():
-        return Success(False)  # Already exists
-
-    # Use template if available
-    template_name = config.get("template")
-    if template_name:
-        result = copy_template(template_name, path, config["file"])
-        if isinstance(result, Success) and result.unwrap():
-            console.print(f"[green]Created[/green] {config['file']} (Invar workflow enforcement)")
-            return Success(True)
-        elif isinstance(result, Failure):
-            return result
-
-    return Success(False)
-
-
 # @shell_complexity: MCP server config with JSON manipulation
 def configure_mcp_server(path: Path, console) -> Result[list[str], str]:
     """

invar/templates/CLAUDE.md.template

@@ -120,18 +120,26 @@ Guard triggers `review_suggested` for: security-sensitive files, escape hatches
 
 ## Workflow Routing (MANDATORY)
 
-When user message contains these triggers, you MUST invoke the corresponding skill:
+When user message contains these triggers, you MUST use the **Skill tool** to invoke the 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 |
+| Trigger Words | Skill Tool Call | Notes |
+|---------------|-----------------|-------|
+| "review", "review and fix" | `Skill(skill="review")` | Adversarial review with fix loop |
+| "implement", "add", "fix", "update" | `Skill(skill="develop")` | Unless in review context |
+| "why", "explain", "investigate" | `Skill(skill="investigate")` | Research mode, no code changes |
+| "compare", "should we", "design" | `Skill(skill="propose")` | Decision facilitation |
+
+**⚠️ CRITICAL: You must call the Skill tool, not just follow the workflow mentally.**
+
+The Skill tool reads `.claude/skills/<skill>/SKILL.md` which contains:
+- Detailed phase instructions (USBV breakdown)
+- Error handling rules
+- Timeout policies
+- Incremental development patterns (DX-63)
 
 **Violation check (before writing ANY code):**
-- "Am I in a workflow?"
-- "Did I invoke the correct skill?"
+- "Did I call `Skill(skill="...")`?"
+- "Am I following the SKILL.md instructions?"
 
 <!--/invar:managed-->
 
@@ -146,7 +154,7 @@ When user message contains these triggers, you MUST invoke the corresponding ski
 <!-- ========================================================================
      USER REGION - EDITABLE
      Add your team conventions and project-specific rules below.
-     This section is preserved across invar update and sync-self.
+     This section is preserved across `invar update` and `invar dev sync`.
      ======================================================================== -->
 <!--/invar:user-->
 

invar/templates/commands/audit.md

@@ -1,3 +1,9 @@
+---
+_invar:
+  version: "5.0"
+  type: command
+---
+
 # Audit
 
 Read-only code review. Reports issues without fixing them.

invar/templates/commands/guard.md

@@ -1,3 +1,9 @@
+---
+_invar:
+  version: "5.0"
+  type: command
+---
+
 # Guard
 
 Run Invar verification on the project and report results.