agent-notes 2.0.4__py3-none-any.whl

agent_notes/services/fs.py

@@ -0,0 +1,195 @@
+"""Filesystem primitives."""
+
+import shutil
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+# Local color/print helpers to avoid circular import
+class _Color:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[0;33m"
+    BLUE = "\033[0;34m"
+    MAGENTA = "\033[0;35m"
+    CYAN = "\033[0;36m"
+    WHITE = "\033[0;37m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    NC = "\033[0m"  # No color
+
+    @staticmethod
+    def disable():
+        """Disable colors (for non-TTY output)."""
+        for attr in ("RED", "GREEN", "YELLOW", "BLUE", "MAGENTA", "CYAN", "WHITE", "BOLD", "DIM", "NC"):
+            setattr(_Color, attr, "")
+
+
+# Disable colors if not a TTY
+if not sys.stdout.isatty():
+    _Color.disable()
+
+# Set to True to suppress per-file LINKED/COPIED/SKIP output (e.g. during wizard)
+silent_file_ops = False
+
+
+def _info(msg: str) -> None:
+    if not silent_file_ops:
+        print(f"  {_Color.GREEN}✓{_Color.NC} {msg}")
+
+
+def _skipped(path: str, reason: str = "not a symlink — remove manually") -> None:
+    if not silent_file_ops:
+        print(f"  {_Color.YELLOW}SKIP{_Color.NC}     {path} ({reason})")
+
+
+def _linked(path: str) -> None:
+    if not silent_file_ops:
+        print(f"  {_Color.GREEN}LINKED{_Color.NC}  {path}")
+
+
+def _removed(path: str) -> None:
+    print(f"  {_Color.GREEN}REMOVED{_Color.NC}  {path}")
+
+
+def files_identical(a: Path, b: Path) -> bool:
+    """Check if two files or directories have identical content."""
+    try:
+        if a.is_dir() and b.is_dir():
+            # Compare directory contents recursively
+            a_files = {f.relative_to(a): f.read_bytes() for f in a.rglob("*") if f.is_file()}
+            b_files = {f.relative_to(b): f.read_bytes() for f in b.rglob("*") if f.is_file()}
+            return a_files == b_files
+        elif a.is_file() and b.is_file():
+            return a.read_bytes() == b.read_bytes()
+        return False
+    except OSError:
+        return False
+
+
+def handle_existing(src: Path, dst: Path) -> bool:
+    """Handle an existing non-symlink destination file.
+    
+    Returns True if install should proceed, False to skip.
+    """
+    if files_identical(src, dst):
+        _skipped(str(dst), "exists, identical content")
+        return False
+    
+    print(f"\n  {_Color.YELLOW}CONFLICT{_Color.NC}  {dst}")
+    print(f"             File exists and differs from source.")
+    response = input("             (b)ackup and replace, (s)kip? [b/s] ").strip().lower()
+    
+    if response == 'b':
+        backup_path = Path(str(dst) + ".bak")
+        if dst.is_dir():
+            if backup_path.exists():
+                shutil.rmtree(backup_path)
+            shutil.copytree(dst, backup_path)
+            shutil.rmtree(dst)
+        else:
+            if backup_path.exists():
+                backup_path.unlink()
+            dst.rename(backup_path)
+        print(f"  {_Color.CYAN}BACKUP{_Color.NC}   {backup_path}")
+        return True
+    else:
+        _skipped(str(dst), "user skipped")
+        return False
+
+
+def place_file(src: Path, dst: Path, copy_mode: bool = False) -> None:
+    """Place file as symlink or copy, handling existing files."""
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    
+    if copy_mode:
+        if dst.exists() and not dst.is_symlink():
+            if not handle_existing(src, dst):
+                return
+        if dst.is_symlink():
+            dst.unlink()
+        if src.is_dir():
+            shutil.copytree(src, dst, dirs_exist_ok=True)
+        else:
+            shutil.copy2(src, dst)
+        _info(f"COPIED  {dst}")
+    else:
+        if dst.exists() and not dst.is_symlink():
+            if not handle_existing(src, dst):
+                return
+        if dst.is_symlink():
+            dst.unlink()
+        dst.symlink_to(src)
+        _linked(str(dst))
+
+
+def place_dir_contents(src_dir: Path, dst_dir: Path, pattern: str, copy_mode: bool = False) -> None:
+    """Place all files matching pattern from src_dir to dst_dir."""
+    dst_dir.mkdir(parents=True, exist_ok=True)
+    for src_file in src_dir.glob(pattern):
+        if src_file.exists():
+            dst_file = dst_dir / src_file.name
+            place_file(src_file, dst_file, copy_mode)
+
+
+def remove_symlink(target: Path) -> None:
+    """Remove symlink if it exists, skip non-symlinks."""
+    if target.is_symlink():
+        target.unlink()
+        _removed(str(target))
+    elif target.exists():
+        _skipped(str(target))
+
+
+def remove_all_symlinks_in_dir(dir_path: Path) -> None:
+    """Remove all symlinks in a directory (files and dirs)."""
+    if not dir_path.exists():
+        return
+    for item in dir_path.iterdir():
+        if item.is_symlink():
+            item.unlink()
+            _removed(str(item))
+        elif item.exists():
+            _skipped(str(item))
+
+
+def remove_dir_if_empty(dir_path: Path) -> None:
+    """Remove directory if it exists and is empty."""
+    try:
+        if dir_path.exists() and not any(dir_path.iterdir()):
+            dir_path.rmdir()
+    except OSError:
+        pass
+
+
+def resolve_symlink(path: Path) -> Optional[Path]:
+    """Get symlink target if path is a symlink."""
+    if path.is_symlink():
+        try:
+            return path.readlink()
+        except OSError:
+            return None
+    return None
+
+
+def symlink_target_exists(path: Path) -> bool:
+    """Check if symlink target exists."""
+    if not path.is_symlink():
+        return False
+    try:
+        target = path.readlink()
+        # Handle relative targets
+        if not target.is_absolute():
+            target = path.parent / target
+        return target.exists()
+    except OSError:
+        return False
+
+
+def files_differ(file1: Path, file2: Path) -> bool:
+    """Compare file contents."""
+    try:
+        return file1.read_bytes() != file2.read_bytes()
+    except (OSError, FileNotFoundError):
+        return True

agent_notes/services/install_state_builder.py

@@ -0,0 +1,210 @@
+"""Build install state during install/uninstall flows."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from ..domain.state import State, ScopeState, BackendState, InstalledItem
+from ..services.state_store import load_state, now_iso, sha256_of, set_scope
+
+
+def git_head_short(repo_root: Path) -> str:
+    """Return short git HEAD sha, or '' on error."""
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo_root), "rev-parse", "--short", "HEAD"],
+            capture_output=True,
+            text=True,
+            timeout=10
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        pass
+    return ""
+
+
+def build_install_state(
+    mode: str,
+    scope: str,                  # "global" or "local"
+    repo_root: Path,
+    project_path: Optional[Path] = None,  # required when scope == "local"
+    role_models: Optional[dict[str, dict[str, str]]] = None,
+    # ^^ {cli_name: {role_name: model_id}}, optional — empty dict fine for now
+    selected_clis: Optional[set[str]] = None,
+    # ^^ If given, only these backends are recorded as installed. None = all
+    # backends with shipped content (legacy behavior, used by the plain
+    # `agent-notes install` non-wizard path).
+) -> State:
+    """Build a complete State snapshot.
+    
+    - Loads current state.json if present, so we can ADD the new scope without
+      clobbering other installs. E.g. installing globally doesn't erase existing
+      local installs.
+    - Constructs a ScopeState for the requested (scope, project_path).
+    - Scans dist/ for each backend; fills BackendState.installed.
+    - BackendState.role_models comes from the `role_models` arg if provided,
+      else empty dict (will be populated by wizard in Phase E).
+    - Returns the updated full State. Caller must call save().
+    """
+    # Load existing state or create fresh one
+    current_state = load_state()
+    if current_state is None:
+        state = State()
+    else:
+        state = current_state
+    
+    # Update top-level metadata
+    state.source_path = str(repo_root.resolve())
+    state.source_commit = git_head_short(repo_root)
+    
+    # Import here to avoid circular import
+    from ..registries.cli_registry import load_registry
+    from ..config import PKG_DIR, DIST_SKILLS_DIR, DIST_RULES_DIR
+
+    # Build scope-specific install
+    try:
+        registry = load_registry()
+    except Exception:
+        # Fallback to empty registry if CLI backend loading fails
+        from ..registries.cli_registry import CLIRegistry
+        registry = CLIRegistry([])
+    
+    timestamp = now_iso()
+    
+    # Build CLIs dict for this scope
+    clis = {}
+    
+    for backend in registry.all():
+        # Skip backends the user opted out of during wizard selection.
+        if selected_clis is not None and backend.name not in selected_clis:
+            continue
+        backend_state = BackendState()
+        backend_has_content = False
+        
+        # Set role_models from arg (empty dict for now)
+        if role_models and backend.name in role_models:
+            backend_state.role_models = role_models[backend.name].copy()
+        
+        # Check agents
+        if backend.supports("agents"):
+            agents_dir = PKG_DIR / "dist" / backend.name / "agents"
+            if agents_dir.exists():
+                for agent_file in agents_dir.glob("*.md"):
+                    try:
+                        sha = sha256_of(agent_file)
+                        target = _get_target_path(agent_file, backend, "agents", scope, project_path)
+                        if "agents" not in backend_state.installed:
+                            backend_state.installed["agents"] = {}
+                        backend_state.installed["agents"][agent_file.name] = InstalledItem(
+                            sha=sha, target=str(target), mode=mode
+                        )
+                        backend_has_content = True
+                    except Exception:
+                        # Skip files we can't process
+                        continue
+        
+        # Check skills
+        if backend.supports("skills"):
+            # Skills are in dist/skills/, not dist/<backend>/skills/
+            skills_dir = DIST_SKILLS_DIR
+            if skills_dir.exists():
+                for skill_dir in skills_dir.iterdir():
+                    if skill_dir.is_dir():
+                        try:
+                            # Use SKILL.md as the file to hash for consistency
+                            skill_md = skill_dir / "SKILL.md"
+                            if skill_md.exists():
+                                sha = sha256_of(skill_md)
+                            else:
+                                # If no SKILL.md, use empty string sha
+                                sha = ""
+                            target = _get_target_path(skill_dir, backend, "skills", scope, project_path)
+                            if "skills" not in backend_state.installed:
+                                backend_state.installed["skills"] = {}
+                            backend_state.installed["skills"][skill_dir.name] = InstalledItem(
+                                sha=sha, target=str(target), mode=mode
+                            )
+                            backend_has_content = True
+                        except Exception:
+                            continue
+        
+        # Check rules
+        if backend.supports("rules"):
+            # Rules come from dist/rules/
+            rules_dir = DIST_RULES_DIR
+            if rules_dir.exists():
+                for rule_file in rules_dir.glob("*.md"):
+                    try:
+                        sha = sha256_of(rule_file)
+                        target = _get_target_path(rule_file, backend, "rules", scope, project_path)
+                        if "rules" not in backend_state.installed:
+                            backend_state.installed["rules"] = {}
+                        backend_state.installed["rules"][rule_file.name] = InstalledItem(
+                            sha=sha, target=str(target), mode=mode
+                        )
+                        backend_has_content = True
+                    except Exception:
+                        continue
+        
+        # Check config files
+        config_file = PKG_DIR / "dist" / backend.name / backend.layout.get("config", "")
+        if config_file.exists():
+            try:
+                sha = sha256_of(config_file)
+                target = _get_target_path(config_file, backend, "config", scope, project_path)
+                if "config" not in backend_state.installed:
+                    backend_state.installed["config"] = {}
+                backend_state.installed["config"][config_file.name] = InstalledItem(
+                    sha=sha, target=str(target), mode=mode
+                )
+                backend_has_content = True
+            except Exception:
+                pass
+        
+        # Check commands (future enhancement)
+        # Check settings (future enhancement)
+        
+        if backend_has_content:
+            clis[backend.name] = backend_state
+    
+    # Create the new scope state
+    new_scope_state = ScopeState(
+        installed_at=timestamp,
+        updated_at=timestamp,
+        mode=mode,
+        clis=clis,
+    )
+    
+    # Set the appropriate scope
+    set_scope(state, scope, new_scope_state, project_path)
+    
+    return state
+
+
+def _get_target_path(source_path: Path, backend, component_type: str, scope: str, project_path: Optional[Path] = None) -> Path:
+    """Get the target installation path for a source file/directory."""
+    if scope == "global":
+        base_dir = backend.global_home
+    else:
+        # Local scope - relative to the provided project path or current working directory
+        if project_path:
+            base_dir = project_path / backend.local_dir
+        else:
+            base_dir = Path.cwd() / backend.local_dir
+    
+    if component_type == "config":
+        # Config files go to the root of the backend directory
+        return base_dir / source_path.name
+    elif component_type in ["agents", "rules", "skills"]:
+        # These go into subdirectories according to backend layout
+        if component_type in backend.layout:
+            subdir = backend.layout[component_type].rstrip("/")
+            return base_dir / subdir / source_path.name
+        else:
+            # Fallback
+            return base_dir / component_type / source_path.name
+    else:
+        return base_dir / source_path.name

agent_notes/services/installer.py

@@ -0,0 +1,293 @@
+"""Generic install/uninstall engine driven by the CLI backend registry."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from ..domain.cli_backend import CLIBackend
+from ..registries.cli_registry import CLIRegistry, load_registry
+from .. import config
+from .fs import (
+    place_file, place_dir_contents,
+    remove_symlink, remove_all_symlinks_in_dir, remove_dir_if_empty,
+)
+
+# Re-import the atomic helpers from install (they stay in install.py):
+# We intentionally avoid circular import by lazy-importing inside functions.
+
+COMPONENT_TYPES = ("agents", "skills", "rules", "commands", "config")
+# Note: "scripts" is handled separately, not per-backend.
+
+
+def dist_source_for(backend: CLIBackend, component: str) -> Optional[Path]:
+    """Return dist source path for a (backend, component) pair, or None if N/A.
+    
+    For "config" returns the directory containing the config file (the file
+    itself is named per backend.layout["config"]).
+    """
+    if component == "agents":
+        p = config.DIST_DIR / backend.name / "agents"
+        return p if p.exists() else None
+    if component == "config":
+        # The config FILE lives directly under DIST_DIR / backend.name / <filename>
+        # Caller resolves the filename via backend.layout["config"].
+        p = config.DIST_DIR / backend.name
+        return p if p.exists() else None
+    if component == "rules":
+        dist_rules_dir = config.DIST_RULES_DIR
+        return dist_rules_dir if dist_rules_dir.exists() else None
+    if component == "skills":
+        dist_skills_dir = config.DIST_SKILLS_DIR
+        return dist_skills_dir if dist_skills_dir.exists() else None
+    if component == "commands":
+        p = config.DIST_DIR / backend.name / "commands"
+        return p if p.exists() else None
+    return None
+
+
+def target_dir_for(backend: CLIBackend, component: str, scope: str) -> Optional[Path]:
+    """Return destination directory for a (backend, component, scope).
+
+    scope: "global" or "local"
+    Returns None if backend doesn't support this component.
+    """
+    # Special case for config: check layout instead of features
+    if component == "config":
+        if not backend.layout.get("config"):
+            return None
+    else:
+        if not backend.supports(component):
+            return None
+    
+    layout_value = backend.layout.get(component)
+    if not layout_value:
+        return None
+    home = backend.global_home if scope == "global" else Path(backend.local_dir)
+    if component == "config":
+        # config layout is a filename like "CLAUDE.md"; target is the home dir
+        return home
+    # All others are subdirectories
+    return home / layout_value.rstrip("/")
+
+
+def config_filename_for(backend: CLIBackend) -> Optional[str]:
+    """Return e.g. 'CLAUDE.md', 'AGENTS.md', 'copilot-instructions.md'."""
+    return backend.layout.get("config")
+
+
+def install_component_for_backend(
+    backend: CLIBackend,
+    component: str,
+    scope: str,
+    copy_mode: bool,
+) -> None:
+    """Install one component for one backend. No-op if unsupported or no source."""
+    src = dist_source_for(backend, component)
+    if src is None:
+        return
+    dst = target_dir_for(backend, component, scope)
+    if dst is None:
+        return
+
+    if component == "config":
+        filename = config_filename_for(backend)
+        if not filename:
+            return
+        src_file = src / filename
+        if not src_file.exists():
+            return
+        print(f"Installing {backend.label} config to {dst} ...")
+        place_file(src_file, dst / filename, copy_mode)
+    elif component in ("agents", "rules", "commands"):
+        # Directory of *.md files — flat copy
+        # Only print if there are files to install
+        files = list(src.glob("*.md"))
+        if not files:
+            return
+        print(f"Installing {backend.label} {component} to {dst} ...")
+        place_dir_contents(src, dst, "*.md", copy_mode)
+    elif component == "skills":
+        # Each top-level subdir of src is a skill — install each as a directory
+        # Only print if there are skills to install
+        skill_dirs = [d for d in src.iterdir() if d.is_dir()]
+        if not skill_dirs:
+            return
+        print(f"Installing {backend.label} skills to {dst} ...")
+        for skill_dir in sorted(skill_dirs):
+            place_file(skill_dir, dst / skill_dir.name, copy_mode)
+
+
+def uninstall_component_for_backend(
+    backend: CLIBackend,
+    component: str,
+    scope: str
+) -> None:
+    """Uninstall one component for one backend."""
+    dst = target_dir_for(backend, component, scope)
+    if dst is None or not dst.exists():
+        return
+
+    if component == "config":
+        filename = config_filename_for(backend)
+        if filename:
+            config_file = dst / filename
+            print(f"Removing {backend.label} config from {dst} ...")
+            remove_symlink(config_file)
+    else:
+        # Only print if directory exists and has content
+        if any(dst.iterdir()):
+            print(f"Removing {backend.label} {component} from {dst} ...")
+        remove_all_symlinks_in_dir(dst)
+        remove_dir_if_empty(dst)
+
+
+def install_all(scope: str, copy_mode: bool, registry: Optional[CLIRegistry] = None) -> None:
+    """Top-level: install scripts (global only) + every (backend, component) combo."""
+    if registry is None:
+        registry = load_registry()
+    
+    if scope == "global":
+        install_scripts_global()
+    
+    for backend in registry.all():
+        for component in COMPONENT_TYPES:
+            install_component_for_backend(backend, component, scope, copy_mode)
+
+    # Universal skills mirror: keep existing behavior — also install skills
+    # to ~/.agents/skills/ for any backend that supports skills, only for global scope.
+    if scope == "global":
+        _install_universal_skills(copy_mode, registry)
+
+    # SessionStart hook for Claude Code only
+    try:
+        claude_backend = registry.get("claude")
+        _install_session_hook(claude_backend, scope)
+    except KeyError:
+        pass
+
+
+def _install_universal_skills(copy_mode: bool, registry: CLIRegistry) -> None:
+    """Mirror skills to ~/.agents/skills/ for backwards compatibility."""
+    
+    dist_skills_dir = config.DIST_SKILLS_DIR
+    if not dist_skills_dir.exists():
+        return
+
+    print(f"Installing universal skills ...")
+    target = config.AGENTS_HOME / "skills"
+    target.mkdir(parents=True, exist_ok=True)
+    skill_dirs = [d for d in dist_skills_dir.iterdir() if d.is_dir()]
+    if not skill_dirs:
+        return
+    print(f"Installing universal skills to {target} ...")
+    for skill_dir in sorted(skill_dirs):
+        place_file(skill_dir, target / skill_dir.name, copy_mode)
+
+
+def uninstall_all(scope: str, registry: Optional[CLIRegistry] = None) -> None:
+    """Top-level uninstall."""
+    if registry is None:
+        registry = load_registry()
+    
+    if scope == "global":
+        uninstall_scripts_global()
+    
+    for backend in registry.all():
+        for component in COMPONENT_TYPES:
+            uninstall_component_for_backend(backend, component, scope)
+
+    if scope == "global":
+        _uninstall_universal_skills()
+
+    # Remove SessionStart hook for Claude Code only
+    try:
+        claude_backend = registry.get("claude")
+        _uninstall_session_hook(claude_backend, scope)
+    except KeyError:
+        pass
+
+
+def _uninstall_universal_skills() -> None:
+
+    target = config.AGENTS_HOME / "skills"
+    if target.exists() and any(target.iterdir()):
+        print(f"Removing universal skills from {target} ...")
+        remove_all_symlinks_in_dir(target)
+        remove_dir_if_empty(target)
+
+
+def _session_hook_paths(backend, scope: str):
+    """Return (settings_path, context_file, hook_command) for the given scope."""
+    home = backend.global_home if scope == "global" else Path(backend.local_dir)
+    if scope == "global":
+        settings_path = home / "settings.json"
+        context_file = home / "agent-notes-context.md"
+        hook_command = "cat ~/.claude/agent-notes-context.md 2>/dev/null || true"
+    else:
+        settings_path = home / "settings.json"
+        context_file = home / "agent-notes-context.md"
+        hook_command = "cat .claude/agent-notes-context.md 2>/dev/null || true"
+    return settings_path, context_file, hook_command
+
+
+def _install_session_hook(backend, scope: str) -> None:
+    """Install the SessionStart hook and write the context file for Claude Code."""
+    from .settings_writer import install_hook
+    from .session_context import write_context
+    from .. import config
+
+    settings_path, context_file, hook_command = _session_hook_paths(backend, scope)
+
+    # Gather installed agent names from dist directory
+    agents: list[str] = []
+    agents_dist = config.DIST_DIR / backend.name / backend.layout.get("agents", "agents")
+    if agents_dist.exists():
+        agents = sorted(p.stem for p in agents_dist.glob("*.md"))
+
+    version = config.get_version()
+    print(f"Installing Claude Code SessionStart hook ...")
+    write_context(context_file, agents, version)
+    install_hook(settings_path, "SessionStart", hook_command)
+
+
+def _uninstall_session_hook(backend, scope: str) -> None:
+    """Remove the SessionStart hook and context file for Claude Code."""
+    from .settings_writer import remove_hook
+
+    settings_path, context_file, hook_command = _session_hook_paths(backend, scope)
+    print(f"Removing Claude Code SessionStart hook ...")
+    context_file.unlink(missing_ok=True)
+    remove_hook(settings_path, "SessionStart", hook_command)
+
+
+def install_scripts_global() -> None:
+    """Install scripts to ~/.local/bin/."""
+    from .fs import place_file
+    
+    dist_scripts_dir = config.DIST_DIR / "scripts"
+    bin_home = Path.home() / ".local" / "bin"
+    
+    if not dist_scripts_dir.exists():
+        return
+    print(f"Installing scripts to {bin_home} ...")
+    bin_home.mkdir(parents=True, exist_ok=True)
+    for script in sorted(dist_scripts_dir.iterdir()):
+        if script.is_file():
+            place_file(script, bin_home / script.name)
+            (bin_home / script.name).chmod(0o755)
+
+
+def uninstall_scripts_global() -> None:
+    """Uninstall scripts from ~/.local/bin/."""
+    from .fs import remove_symlink
+    
+    dist_scripts_dir = config.DIST_DIR / "scripts"
+    bin_home = Path.home() / ".local" / "bin"
+    
+    if not dist_scripts_dir.exists():
+        return
+    print(f"Removing scripts from {bin_home} ...")
+    for script in sorted(dist_scripts_dir.iterdir()):
+        if script.is_file():
+            remove_symlink(bin_home / script.name)