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

invar/shell/{init_cmd.py → commands/init.py}

@@ -3,6 +3,8 @@ Init command for Invar.
 
 Shell module: handles project initialization.
 DX-21B: Added --claude flag for Claude Code integration.
+DX-55: Unified idempotent init command with smart merge.
+DX-56: Uses unified template sync engine for file generation.
 """
 
 from __future__ import annotations
@@ -15,18 +17,23 @@ import typer
 from returns.result import Failure, Success
 from rich.console import Console
 
+from invar.core.sync_helpers import SyncConfig
+from invar.core.template_parser import ClaudeMdState
+from invar.shell.commands.merge import (
+    ProjectState,
+    detect_project_state,
+)
+from invar.shell.commands.template_sync import sync_templates
 from invar.shell.mcp_config import (
     detect_available_methods,
     generate_mcp_json,
     get_method_by_name,
     get_recommended_method,
 )
+from invar.shell.template_engine import generate_from_manifest
 from invar.shell.templates import (
     add_config,
     add_invar_reference,
-    copy_commands_directory,
-    copy_examples_directory,
-    copy_template,
     create_agent_config,
     create_directories,
     detect_agent_configs,
@@ -104,10 +111,10 @@ def append_invar_reference_to_claude_md(path: Path) -> bool:
 Your first message MUST display:
 
 ```
-✓ Check-In: guard PASS | top: <entry1>, <entry2>
+✓ Check-In: [project] | [branch] | [clean/dirty]
 ```
 
-Execute `invar guard --changed` and `invar map --top 10`, then show this one-line summary.
+Read `.invar/context.md` first. Do NOT run guard/map at Check-In.
 
 ### Final
 
@@ -194,12 +201,32 @@ def init(
     hooks: bool = typer.Option(
         True, "--hooks/--no-hooks", help="Install pre-commit hooks (default: ON)"
     ),
+    skills: bool = typer.Option(
+        True, "--skills/--no-skills", help="Create .claude/skills/ (default: ON, use --no-skills for Cursor)"
+    ),
     yes: bool = typer.Option(
         False, "--yes", "-y", help="Accept defaults without prompting"
     ),
+    check: bool = typer.Option(
+        False, "--check", help="Preview changes without applying (DX-55)"
+    ),
+    force: bool = typer.Option(
+        False, "--force", help="Update even if already current (DX-55)"
+    ),
+    reset: bool = typer.Option(
+        False, "--reset", help="Dangerous: discard all user content (DX-55)"
+    ),
 ) -> None:
     """
-    Initialize Invar configuration in a project.
+    Initialize or update Invar configuration (idempotent).
+
+    DX-55: This command is idempotent - safe to run multiple times.
+    It detects current state and does the right thing:
+
+    \b
+    - New project: Full setup
+    - Existing project: Update managed regions, preserve user content
+    - Corrupted/overwritten: Smart recovery with content preservation
 
     Works with or without pyproject.toml:
 
@@ -207,13 +234,74 @@ def init(
     - If pyproject.toml exists: adds tool.invar section
     - Otherwise: creates invar.toml
 
-    Use --claude to run 'claude /init' first (recommended for Claude Code users).
+    Use --check to preview changes without applying.
+    Use --force to update even if already current.
+    Use --reset to discard all user content (dangerous).
+    Use --claude to run 'claude /init' first.
     Use --mcp-method to specify MCP execution method (uvx, command, python).
     Use --dirs to always create directories, --no-dirs to skip.
     Use --no-hooks to skip pre-commit hooks installation.
+    Use --no-skills to skip .claude/skills/ creation (for Cursor users).
     Use --yes to accept defaults without prompting.
     """
-    # DX-21B: Run claude /init if requested
+    from invar import __version__
+
+    # DX-55: Detect project state first
+    state = detect_project_state(path)
+
+    # --check mode: preview only
+    if check:
+        _show_check_preview(state, path, __version__)
+        return
+
+    # --reset mode: dangerous full reset
+    if reset:
+        if not yes and not typer.confirm(
+            "[red]This will DELETE all user customizations. Continue?[/red]",
+            default=False,
+        ):
+            console.print("[yellow]Cancelled[/yellow]")
+            return
+        # Fall through to full init with reset flag
+        state = ProjectState(
+            initialized=False,
+            claude_md_state=ClaudeMdState(state="absent"),
+            version="",
+            needs_update=True,
+        )
+
+    # DX-55: Handle based on detected state
+    action = state.action if not force else "update"
+
+    if action == "none" and not force:
+        # DX-55: Check for missing required files before declaring "no changes needed"
+        missing_files = []
+        if skills:
+            skill_files = [
+                ".claude/skills/develop/SKILL.md",
+                ".claude/skills/investigate/SKILL.md",
+                ".claude/skills/propose/SKILL.md",
+                ".claude/skills/review/SKILL.md",
+            ]
+            for skill_file in skill_files:
+                if not (path / skill_file).exists():
+                    missing_files.append(skill_file)
+
+        if not missing_files:
+            console.print(f"[green]✓[/green] Invar v{__version__} configured (no changes needed)")
+            console.print("[dim]Use --force to refresh managed regions[/dim]")
+            return
+        else:
+            # Recreate missing files
+            console.print(f"[yellow]Detected:[/yellow] {len(missing_files)} missing file(s)")
+            result = generate_from_manifest(path, syntax="cli", files_to_generate=missing_files)
+            if isinstance(result, Success):
+                for generated_file in result.unwrap():
+                    console.print(f"[green]Restored[/green] {generated_file}")
+            console.print(f"[green]✓[/green] Invar v{__version__} configured")
+            return
+
+    # DX-21B: Run claude /init if requested (before sync)
     if claude:
         claude_success = run_claude_init(path)
         if claude_success:
@@ -226,26 +314,49 @@ def init(
         raise typer.Exit(1)
     config_added = config_result.unwrap()
 
-    # Create INVAR.md (protocol)
-    result = copy_template("INVAR.md", path)
-    if isinstance(result, Success) and result.unwrap():
-        console.print("[green]Created[/green] INVAR.md (Invar Protocol)")
-
-    # Copy examples directory
-    copy_examples_directory(path, console)
-
-    # Create .invar directory structure
+    # DX-56: Use unified sync engine for file generation
+    console.print("\n[bold]Creating Invar files...[/bold]")
+
+    # Check for project-additions.md
+    has_project_additions = (path / ".invar" / "project-additions.md").exists()
+
+    # Build skip patterns for --no-skills
+    skip_patterns: list[str] = []
+    if not skills:
+        skip_patterns.append(".claude/skills/*")
+
+    sync_config = SyncConfig(
+        syntax="cli",
+        inject_project_additions=has_project_additions,
+        force=force,
+        check=False,  # Already handled above
+        reset=reset,
+        skip_patterns=skip_patterns,
+    )
+
+    # DX-56: Run unified sync engine (handles DX-55 state detection internally)
+    result = sync_templates(path, sync_config)
+    if isinstance(result, Failure):
+        console.print(f"[yellow]Warning:[/yellow] {result.failure()}")
+    else:
+        report = result.unwrap()
+        for file in report.created:
+            console.print(f"[green]Created[/green] {file}")
+        for file in report.updated:
+            console.print(f"[cyan]Updated[/cyan] {file}")
+        for error in report.errors:
+            console.print(f"[yellow]Warning:[/yellow] {error}")
+
+    # Create .invar directory structure (for proposals template - not in manifest)
     invar_dir = path / ".invar"
     if not invar_dir.exists():
         invar_dir.mkdir()
-        result = copy_template("context.md.template", invar_dir, "context.md")
-        if isinstance(result, Success) and result.unwrap():
-            console.print("[green]Created[/green] .invar/context.md (context management)")
 
     # Create proposals directory for protocol governance
     proposals_dir = invar_dir / "proposals"
     if not proposals_dir.exists():
         proposals_dir.mkdir()
+        from invar.shell.templates import copy_template
         result = copy_template("proposal.md.template", proposals_dir, "TEMPLATE.md")
         if isinstance(result, Success) and result.unwrap():
             console.print("[green]Created[/green] .invar/proposals/TEMPLATE.md")
@@ -273,9 +384,6 @@ def init(
             # Create full template with workflow enforcement (DX-17)
             create_agent_config(path, agent, console)
 
-    # Copy Claude commands (DX-32: /review skill with Mode Detection)
-    copy_commands_directory(path, console)
-
     # Configure MCP server (DX-16, DX-21B)
     configure_mcp_with_method(path, mcp_method)
 
@@ -301,9 +409,53 @@ def init(
     if not config_added and not (path / "INVAR.md").exists():
         console.print("[yellow]Invar already configured.[/yellow]")
 
-    # Summary
-    console.print("\n[bold green]Invar initialized successfully![/bold green]")
+    # DX-55: Summary based on action taken
+    if action == "full_init":
+        console.print(f"\n[bold green]✓ Initialized Invar v{__version__}[/bold green]")
+        console.print("[dim]Note: If you run 'claude /init' later, just run 'invar init' again.[/dim]")
+    elif action == "recover":
+        console.print(f"\n[bold green]✓ Recovered Invar v{__version__}[/bold green]")
+        console.print("[dim]Review the merged content in CLAUDE.md[/dim]")
+    elif action == "update" or force:
+        console.print(f"\n[bold green]✓ Updated Invar v{__version__}[/bold green]")
+        console.print("[dim]Refreshed managed regions, preserved user content[/dim]")
+    else:
+        console.print("\n[bold green]Invar initialized successfully![/bold green]")
+
     if claude:
         console.print("[dim]Next: Review CLAUDE.md and start coding with Claude Code[/dim]")
-    else:
-        console.print("[dim]Tip: Use --claude for Claude Code integration[/dim]")
+
+
+# @shell_complexity: Preview display requires multiple state-specific branches
+def _show_check_preview(state: ProjectState, path: Path, version: str) -> None:
+    """Show preview of what would change (--check mode)."""
+    console.print(f"\n[bold]Invar v{version} - Preview Mode[/bold]\n")
+
+    console.print(f"Project state: [cyan]{state.claude_md_state.state}[/cyan]")
+    console.print(f"Initialized: [cyan]{state.initialized}[/cyan]")
+    console.print(f"Current version: [cyan]{state.version or 'N/A'}[/cyan]")
+    console.print(f"Needs update: [cyan]{state.needs_update}[/cyan]")
+    console.print(f"Action: [cyan]{state.action}[/cyan]\n")
+
+    match state.action:
+        case "none":
+            console.print("[green]No changes needed[/green]")
+        case "full_init":
+            console.print("Would create:")
+            console.print("  - INVAR.md")
+            console.print("  - CLAUDE.md")
+            console.print("  - .invar/context.md")
+            console.print("  - .claude/skills/")
+            console.print("  - .pre-commit-config.yaml")
+        case "update":
+            console.print("Would update:")
+            console.print(f"  - CLAUDE.md (managed section v{state.version} → v{version})")
+            console.print("  - .claude/skills/* (refresh)")
+        case "recover":
+            console.print("[yellow]Would recover:[/yellow]")
+            console.print("  - CLAUDE.md (restore regions, preserve content)")
+        case "create":
+            console.print("Would create:")
+            console.print("  - CLAUDE.md")
+
+    console.print("\n[dim]Run 'invar init' to apply.[/dim]")

invar/shell/commands/merge.py

@@ -0,0 +1,256 @@
+"""
+DX-55: Smart merge logic for CLAUDE.md recovery.
+
+Shell module: handles merging and recovering CLAUDE.md content.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from typing import TYPE_CHECKING, Literal
+
+from returns.result import Failure, Result, Success
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+from invar.core.template_parser import (
+    ClaudeMdState,
+    detect_claude_md_state,
+    format_preserved_content,
+    parse_invar_regions,
+    reconstruct_file,
+    strip_invar_markers,
+)
+from invar.shell.template_engine import generate_from_manifest
+
+# =============================================================================
+# DX-55: Project State Detection
+# =============================================================================
+
+
+@dataclass
+class ProjectState:
+    """Overall project initialization state.
+
+    DX-55: Captures full state for idempotent init decision.
+    """
+
+    initialized: bool
+    claude_md_state: ClaudeMdState
+    version: str
+    needs_update: bool
+
+    @property
+    def action(self) -> Literal["full_init", "update", "recover", "create", "none"]:
+        """Determine what action to take."""
+        if not self.initialized:
+            return "full_init"
+
+        match self.claude_md_state.state:
+            case "intact":
+                return "update" if self.needs_update else "none"
+            case "partial" | "missing":
+                return "recover"
+            case "absent":
+                return "create"
+            case _:
+                return "none"
+
+
+# @shell_complexity: State detection requires multiple file existence checks
+def detect_project_state(path: Path) -> ProjectState:
+    """Detect Invar initialization state.
+
+    DX-55: Core state detection for idempotent init.
+    """
+    from invar import __protocol_version__
+
+    invar_md = path / "INVAR.md"
+    invar_dir = path / ".invar"
+    claude_md = path / "CLAUDE.md"
+
+    initialized = invar_md.exists() and invar_dir.exists()
+
+    # Detect CLAUDE.md state
+    if claude_md.exists():
+        try:
+            content = claude_md.read_text()
+            claude_state = detect_claude_md_state(content)
+        except UnicodeDecodeError:
+            # Binary or non-UTF-8 content - treat as corrupt, will be replaced
+            claude_state = ClaudeMdState(state="partial")
+    else:
+        claude_state = ClaudeMdState(state="absent")
+
+    # Extract protocol version from existing INVAR.md
+    version = ""
+    if invar_md.exists():
+        content = invar_md.read_text()
+        import re
+
+        match = re.search(r"Invar (?:Protocol )?v([\d.]+)", content)
+        if match:
+            version = match.group(1)
+
+    # Check if update needed (compare protocol versions, not package versions)
+    needs_update = initialized and version != __protocol_version__
+
+    return ProjectState(
+        initialized=initialized,
+        claude_md_state=claude_state,
+        version=version,
+        needs_update=needs_update,
+    )
+
+
+# =============================================================================
+# DX-55: Smart Merge Functions
+# =============================================================================
+
+
+# @shell_complexity: Smart merge with multiple state handling paths
+def merge_claude_md(path: Path, state: ClaudeMdState) -> Result[str, str]:
+    """Smart merge CLAUDE.md based on detected state.
+
+    DX-55: Preserves user content while restoring Invar regions.
+    """
+    from pathlib import Path as PathLib  # Runtime import for Path operations
+
+    claude_md = PathLib(path) / "CLAUDE.md"
+
+    # Read existing content (handle binary/corrupt files)
+    existing_content = ""
+    if claude_md.exists():
+        try:
+            existing_content = claude_md.read_text()
+        except UnicodeDecodeError:
+            # Binary content - delete and recreate
+            claude_md.unlink()
+            state = ClaudeMdState(state="absent")
+
+    match state.state:
+        case "intact":
+            # Just update managed region, preserve user exactly
+            return _update_managed_only(path, existing_content)
+
+        case "partial":
+            # Corruption: try to salvage user content
+            return _recover_from_partial(path, existing_content, state)
+
+        case "missing":
+            # No Invar markers - treat entire file as user content
+            return _merge_with_preserved(path, existing_content)
+
+        case "absent":
+            # Just create new file
+            return Success("create_new")
+
+    return Success("no_action")
+
+
+# @shell_complexity: Template regeneration with region extraction
+def _update_managed_only(path: Path, existing_content: str) -> Result[str, str]:
+    """Update only the managed region, preserve user content."""
+    # Parse existing
+    parsed = parse_invar_regions(existing_content)
+
+    if "user" not in parsed.regions:
+        return Failure("No user region found")
+
+    # Generate fresh template
+    template_result = generate_from_manifest(
+        path, syntax="cli", files_to_generate=["CLAUDE.md"]
+    )
+    if isinstance(template_result, Failure):
+        return template_result
+
+    # Re-read and extract managed
+    new_content = (path / "CLAUDE.md").read_text()
+    new_parsed = parse_invar_regions(new_content)
+
+    if "managed" not in new_parsed.regions:
+        return Failure("Template missing managed region")
+
+    # Reconstruct with new managed but old user
+    updates = {"managed": new_parsed.regions["managed"].content}
+    final_content = reconstruct_file(parsed, updates)
+
+    (path / "CLAUDE.md").write_text(final_content)
+    return Success("updated_managed")
+
+
+# @shell_complexity: Recovery with content salvage logic
+def _recover_from_partial(
+    path: Path, existing_content: str, state: ClaudeMdState
+) -> Result[str, str]:
+    """Recover from partial corruption."""
+    from pathlib import Path as PathLib  # Runtime import for Path operations
+
+    # Try to salvage user content
+    if state.user_content:
+        user_content = state.user_content
+    else:
+        # Strip markers and treat rest as user content
+        user_content = strip_invar_markers(existing_content)
+        if user_content:
+            user_content = format_preserved_content(
+                user_content, date.today().isoformat()
+            )
+
+    # Remove existing CLAUDE.md so generate_from_manifest creates fresh template
+    claude_md = PathLib(path) / "CLAUDE.md"
+    if claude_md.exists():
+        claude_md.unlink()
+
+    # Generate fresh template
+    result = generate_from_manifest(
+        path, syntax="cli", files_to_generate=["CLAUDE.md"]
+    )
+    if isinstance(result, Failure):
+        return result
+
+    # Inject recovered user content
+    if user_content:
+        new_content = claude_md.read_text()
+        parsed = parse_invar_regions(new_content)
+        if "user" in parsed.regions:
+            updates = {"user": "\n" + user_content + "\n"}
+            final_content = reconstruct_file(parsed, updates)
+            claude_md.write_text(final_content)
+
+    return Success("recovered")
+
+
+def _merge_with_preserved(path: Path, existing_content: str) -> Result[str, str]:
+    """Merge overwritten content as preserved user content."""
+    from pathlib import Path as PathLib  # Runtime import for Path operations
+
+    # Format existing content as preserved
+    preserved = format_preserved_content(
+        existing_content, date.today().isoformat()
+    )
+
+    # Remove existing CLAUDE.md so generate_from_manifest creates fresh template
+    claude_md = PathLib(path) / "CLAUDE.md"
+    if claude_md.exists():
+        claude_md.unlink()
+
+    # Generate fresh template
+    result = generate_from_manifest(
+        path, syntax="cli", files_to_generate=["CLAUDE.md"]
+    )
+    if isinstance(result, Failure):
+        return result
+
+    # Inject preserved content into user region
+    new_content = claude_md.read_text()
+    parsed = parse_invar_regions(new_content)
+
+    if "user" in parsed.regions:
+        updates = {"user": "\n" + preserved + "\n"}
+        final_content = reconstruct_file(parsed, updates)
+        claude_md.write_text(final_content)
+
+    return Success("merged")

invar/shell/commands/sync_self.py

@@ -0,0 +1,113 @@
+"""
+DX-56: Developer sync command for Invar (unified sync engine).
+
+Shell module: Special command for updating Invar's own project files.
+Uses MCP syntax and injects project-additions.md content.
+
+CLI: `invar dev sync` (formerly `invar sync-self`)
+
+This is a thin wrapper around the unified template_sync engine.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from returns.result import Failure
+from rich.console import Console
+
+from invar.core.sync_helpers import SyncConfig
+from invar.shell.commands.template_sync import sync_templates
+from invar.shell.template_engine import is_invar_project
+
+console = Console()
+
+
+# @shell_complexity: CLI command with result display and multiple output branches
+def sync_self(
+    path: Path = typer.Argument(Path(), help="Invar project root"),
+    check: bool = typer.Option(
+        False, "--check", help="Preview changes without applying"
+    ),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Update even if already current"
+    ),
+) -> None:
+    """
+    Synchronize Invar's own project files from templates.
+
+    DX-56: Now uses unified sync engine with manifest-driven file lists.
+
+    This command is for the Invar project only. It:
+    - Uses MCP syntax (invar_guard, invar_map, etc.)
+    - Injects .invar/project-additions.md into project region
+    - Updates managed regions while preserving user content
+    - Handles DX-55 state recovery (intact/partial/missing/absent)
+
+    Use --check to preview changes without applying them.
+    Use --force to update even if already current.
+    """
+    # Verify this is the Invar project
+    if not is_invar_project(path):
+        console.print("[red]Error:[/red] This command is only for the Invar project itself.")
+        console.print("[dim]Use 'invar init' for other projects.[/dim]")
+        raise typer.Exit(1)
+
+    console.print("[bold]Syncing Invar project files...[/bold]")
+    console.print("[dim]Using MCP syntax for templates[/dim]")
+    console.print()
+
+    # Configure for Invar project
+    config = SyncConfig(
+        syntax="mcp",
+        inject_project_additions=True,
+        force=force,
+        check=check,
+    )
+
+    # Run unified sync engine
+    result = sync_templates(path, config)
+
+    if isinstance(result, Failure):
+        console.print(f"[red]Error:[/red] {result.failure()}")
+        raise typer.Exit(1)
+
+    report = result.unwrap()
+
+    # Display results
+    if check:
+        console.print("[bold]Preview mode - no changes applied[/bold]")
+        console.print()
+
+    for file in report.created:
+        action = "Would create" if check else "Created"
+        console.print(f"[green]{action}[/green] {file}")
+
+    for file in report.updated:
+        action = "Would update" if check else "Updated"
+        console.print(f"[cyan]{action}[/cyan] {file}")
+
+    for file in report.skipped:
+        console.print(f"[dim]Skipped[/dim] {file} (unchanged)")
+
+    for error in report.errors:
+        console.print(f"[yellow]Warning:[/yellow] {error}")
+
+    # Summary
+    console.print()
+    if check:
+        console.print("[bold]Dry run complete.[/bold]")
+        console.print(f"  Would create: {len(report.created)} files")
+        console.print(f"  Would update: {len(report.updated)} files")
+        console.print(f"  Would skip: {len(report.skipped)} files (unchanged)")
+    else:
+        console.print("[bold green]Sync complete![/bold green]")
+        console.print(f"  Created: {len(report.created)} files")
+        console.print(f"  Updated: {len(report.updated)} files")
+        console.print(f"  Skipped: {len(report.skipped)} files (unchanged)")
+
+    console.print()
+    console.print("[dim]MCP syntax applied:[/dim]")
+    console.print("[dim]  invar_guard(changed=true) instead of invar guard --changed[/dim]")
+    console.print("[dim]  invar_map(top=10) instead of invar map --top 10[/dim]")