agent-notes 2.8.0__tar.gz → 2.10.0__tar.gz

{agent_notes-2.8.0 → agent_notes-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-notes
-Version: 2.8.0
+Version: 2.10.0
 Summary: AI agent configuration manager for Claude Code, OpenCode, and Copilot
 Author-email: Eugene Naumov <min.verkligheten@gmail.com>
 License-Expression: MIT

agent_notes-2.10.0/agent_notes/VERSION

@@ -0,0 +1 @@
+2.10.0

{agent_notes-2.8.0 → agent_notes-2.10.0}/agent_notes/commands/wizard.py

@@ -458,9 +458,11 @@ def _select_memory(step: int, total: int, version: str = '') -> tuple:
 
 
 def _confirm_install(clis: Set[str], scope: str, copy_mode: bool, selected_skills: List[str], role_models: Dict[str, Dict[str, str]], version: str = '', memory_backend: str = 'local', memory_path: str = '') -> bool:
-    """Step 7: Confirmation."""
+    """Step 7: Confirmation — shows pre-flight summary including files to be backed up."""
+    import logging
     from ..services.ui import _clear_screen, _render_step_header
     from ..registries.cli_registry import load_registry
+    from ..services.installer import plan_install
     _clear_screen()
     _render_step_header(7, 7, version)
     skill_groups = _get_skill_groups()
@@ -469,6 +471,33 @@ def _confirm_install(clis: Set[str], scope: str, copy_mode: bool, selected_skill
     _render_install_summary(clis, scope, copy_mode, selected_skills, role_models, skill_groups, registry,
                             memory_backend=memory_backend, memory_path=memory_path)
 
+    # Pre-flight: show which existing files will be backed up
+    _tty = sys.stdout.isatty()
+    _YELLOW = "\033[0;33m" if _tty else ""
+    _DIM    = "\033[2m"    if _tty else ""
+    _NC     = "\033[0m"    if _tty else ""
+
+    try:
+        manifest = plan_install(
+            scope=scope,
+            registry=registry,
+            selected_clis=set(clis),
+            selected_skills=selected_skills if selected_skills else None,
+            copy_mode=copy_mode,
+        )
+        overwrites = [a for a in manifest if a.action == "overwrite"]
+        to_install = [a for a in manifest if a.action != "skip"]
+
+        print(f"  {_DIM}Files to install:{_NC}  {len(to_install)}")
+        if overwrites:
+            print(f"  {_YELLOW}Files to back up ({len(overwrites)}):{_NC}")
+            for a in overwrites:
+                print(f"    {_DIM}{a.dst}{_NC}  →  {a.backup_path}")
+        print("")
+    except Exception:
+        # Pre-flight is best-effort — log at debug and continue
+        logging.getLogger(__name__).debug("plan_install failed during pre-flight", exc_info=True)
+
     choice = _safe_input("Proceed? [Y/n]: ", "Y").lower()
     return choice != "n"
 

{agent_notes-2.8.0 → agent_notes-2.10.0}/agent_notes/services/fs.py

@@ -2,6 +2,7 @@
 
 import shutil
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
@@ -68,35 +69,30 @@ def files_identical(a: Path, b: Path) -> bool:
         return False
 
 
+def _timestamped_backup_path(dst: Path) -> Path:
+    """Return a timestamped backup path for dst, e.g. CLAUDE.md.bak.20260430T022500123456Z."""
+    ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+    return Path(str(dst) + f".bak.{ts}")
+
+
 def handle_existing(src: Path, dst: Path) -> bool:
     """Handle an existing non-symlink destination file.
-    
-    Returns True if install should proceed, False to skip.
+
+    Backs up the destination with a timestamped name and proceeds with install.
+    Returns True if install should proceed, False to skip (identical content).
     """
     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
+
+    backup_path = _timestamped_backup_path(dst)
+    if dst.is_dir():
+        shutil.copytree(dst, backup_path)
+        shutil.rmtree(dst)
     else:
-        _skipped(str(dst), "user skipped")
-        return False
+        dst.rename(backup_path)
+    print(f"  {_Color.CYAN}BACKUP{_Color.NC}   {backup_path}")
+    return True
 
 
 def place_file(src: Path, dst: Path, copy_mode: bool = False) -> None:

{agent_notes-2.8.0 → agent_notes-2.10.0}/agent_notes/services/installer.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Optional
+from typing import List, NamedTuple, Optional
 
 from ..domain.cli_backend import CLIBackend
 from ..registries.cli_registry import CLIRegistry, load_registry
@@ -11,9 +11,19 @@ from .. import config
 from .fs import (
     place_file, place_dir_contents,
     remove_symlink, remove_all_symlinks_in_dir, remove_dir_if_empty,
+    files_identical, _timestamped_backup_path,
 )
 from .state_store import load_state, get_scope
 
+
+class InstallAction(NamedTuple):
+    """Describes a single file placement that plan_install would perform."""
+
+    action: str          # "install", "overwrite", or "skip"
+    src: Path
+    dst: Path
+    backup_path: Optional[Path]  # set when action == "overwrite"
+
 # Re-import the atomic helpers from install (they stay in install.py):
 # We intentionally avoid circular import by lazy-importing inside functions.
 
@@ -144,6 +154,151 @@ def uninstall_component_for_backend(
         remove_dir_if_empty(dst)
 
 
+def _plan_file(src: Path, dst: Path, copy_mode: bool = False) -> InstallAction:
+    """Return the InstallAction for a single src→dst placement."""
+    if copy_mode and dst.is_symlink() and dst.resolve() == src.resolve():
+        return InstallAction(action="skip", src=src, dst=dst, backup_path=None)
+    if dst.exists() and not dst.is_symlink():
+        if files_identical(src, dst):
+            return InstallAction(action="skip", src=src, dst=dst, backup_path=None)
+        backup_path = _timestamped_backup_path(dst)
+        return InstallAction(action="overwrite", src=src, dst=dst, backup_path=backup_path)
+    return InstallAction(action="install", src=src, dst=dst, backup_path=None)
+
+
+def _plan_component(
+    backend: CLIBackend,
+    component: str,
+    scope: str,
+    copy_mode: bool = False,
+) -> List[InstallAction]:
+    """Return InstallActions for one (backend, component, scope) without writing."""
+    src = dist_source_for(backend, component)
+    if src is None:
+        return []
+    dst = target_dir_for(backend, component, scope)
+    if dst is None:
+        return []
+
+    actions: List[InstallAction] = []
+
+    if component == "config":
+        filename = config_filename_for(backend)
+        if not filename:
+            return []
+        src_file = src / filename
+        if not src_file.exists():
+            return []
+        actions.append(_plan_file(src_file, dst / filename, copy_mode))
+    elif component in ("agents", "rules", "commands"):
+        for src_file in sorted(src.glob("*.md")):
+            if src_file.exists():
+                actions.append(_plan_file(src_file, dst / src_file.name, copy_mode))
+    elif component == "skills":
+        if not src.exists():
+            return []
+        for skill_dir in sorted(d for d in src.iterdir() if d.is_dir()):
+            actions.append(_plan_file(skill_dir, dst / skill_dir.name, copy_mode))
+
+    return actions
+
+
+def _plan_session_hook(
+    backend,
+    scope: str,
+) -> List[InstallAction]:
+    """Return InstallActions for the settings.json SessionStart hook write.
+
+    The hook is injected via merge (never a full overwrite), so:
+      - If settings.json does not exist: action="install"
+      - If settings.json exists but hook is absent: action="modify"
+      - If settings.json exists and hook is already present: action="skip"
+    """
+    from .settings_writer import has_hook
+
+    settings_path, _context_file, hook_command = _session_hook_paths(backend, scope)
+
+    if not settings_path.exists():
+        # Fresh write — settings.json will be created
+        return [InstallAction(action="install", src=settings_path, dst=settings_path, backup_path=None)]
+
+    if has_hook(settings_path, "SessionStart", hook_command):
+        # Already installed — no-op
+        return [InstallAction(action="skip", src=settings_path, dst=settings_path, backup_path=None)]
+
+    # Merge inject — file exists but hook is absent; classified as modify
+    return [InstallAction(action="modify", src=settings_path, dst=settings_path, backup_path=None)]
+
+
+def plan_install(
+    scope: str,
+    registry: Optional[CLIRegistry] = None,
+    selected_clis: Optional[set] = None,
+    selected_skills: Optional[List[str]] = None,
+    copy_mode: bool = False,
+) -> List[InstallAction]:
+    """Return a manifest of what install_all would do, without writing any files.
+
+    Each entry is an InstallAction(action, src, dst, backup_path) where:
+      action == "install"   — dst does not yet exist (fresh placement)
+      action == "modify"    — dst exists and will be merge-updated (e.g. settings.json hook)
+      action == "overwrite" — dst exists and differs; backup_path is the timestamped path
+      action == "skip"      — dst exists and is byte-identical (or symlink unchanged); no write needed
+    """
+    if registry is None:
+        registry = load_registry()
+
+    actions: List[InstallAction] = []
+
+    for backend in registry.all():
+        if selected_clis is not None and backend.name not in selected_clis:
+            continue
+        for component in COMPONENT_TYPES:
+            if component == "skills" and selected_skills is not None:
+                # Skills are filtered — plan them separately below
+                continue
+            actions.extend(_plan_component(backend, component, scope, copy_mode))
+
+    # Skills: respect the selected_skills filter (mirrors wizard's install_skills_filtered)
+    if scope == "global" or selected_skills is not None:
+        dist_skills_dir = config.DIST_SKILLS_DIR
+        if dist_skills_dir.exists():
+            skill_dirs = {d.name: d for d in dist_skills_dir.iterdir() if d.is_dir()}
+            names_to_plan = selected_skills if selected_skills is not None else list(skill_dirs.keys())
+
+            # Per-backend skill targets
+            for backend in registry.all():
+                if selected_clis is not None and backend.name not in selected_clis:
+                    continue
+                if not backend.supports("skills"):
+                    continue
+                dst_dir = target_dir_for(backend, "skills", scope)
+                if dst_dir is None:
+                    continue
+                for name in sorted(names_to_plan):
+                    skill_dir = skill_dirs.get(name)
+                    if skill_dir:
+                        actions.append(_plan_file(skill_dir, dst_dir / name, copy_mode))
+
+            # Universal skills mirror (~/.agents/skills/)
+            if scope == "global":
+                target = config.AGENTS_HOME / "skills"
+                for name in sorted(names_to_plan):
+                    skill_dir = skill_dirs.get(name)
+                    if skill_dir:
+                        actions.append(_plan_file(skill_dir, target / name, copy_mode))
+
+    # SessionStart hook for Claude Code — always planned when claude backend is selected
+    try:
+        claude_backend = registry.get("claude")
+        if selected_clis is None or claude_backend.name in selected_clis:
+            actions.extend(_plan_session_hook(claude_backend, scope))
+    except KeyError:
+        pass
+
+    return actions
+
+
 def install_all(scope: str, copy_mode: bool, registry: Optional[CLIRegistry] = None) -> None:
     """Top-level: install every (backend, component) combo."""
     if registry is None:

{agent_notes-2.8.0 → agent_notes-2.10.0}/agent_notes.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-notes
-Version: 2.8.0
+Version: 2.10.0
 Summary: AI agent configuration manager for Claude Code, OpenCode, and Copilot
 Author-email: Eugene Naumov <min.verkligheten@gmail.com>
 License-Expression: MIT

{agent_notes-2.8.0 → agent_notes-2.10.0}/agent_notes.egg-info/SOURCES.txt

@@ -203,6 +203,7 @@ tests/unit/commands/__init__.py
 tests/unit/commands/test_cost_report_subcommand.py
 tests/unit/commands/test_count_agents.py
 tests/unit/commands/test_wizard_orchestrator_skip.py
+tests/unit/commands/test_wizard_preflight.py
 tests/unit/registries/__init__.py
 tests/unit/registries/test_registries.py
 tests/unit/scripts/__init__.py
@@ -213,6 +214,8 @@ tests/unit/scripts/test_time_aggregation.py
 tests/unit/services/__init__.py
 tests/unit/services/test_build_functions.py
 tests/unit/services/test_credentials.py
+tests/unit/services/test_fs.py
+tests/unit/services/test_installer_plan.py
 tests/unit/services/test_memory_backend.py
 tests/unit/services/test_memory_backend_io.py
 tests/unit/services/test_rendering_includes.py

{agent_notes-2.8.0 → agent_notes-2.10.0}/tests/conftest.py

@@ -8,13 +8,8 @@ from agent_notes.config import DIST_DIR
 REPO_ROOT = Path(__file__).resolve().parent.parent
 
 
-@pytest.fixture(scope="session", autouse=True)
-def built_dist():
-    """Build dist once at suite start. If build fails, the entire suite errors loudly — no silent skips.
-
-    Tests that need a built dist depend on this implicitly (autouse). Tests that don't
-    consume it pay only the one-time build cost.
-    """
+def pytest_sessionstart(session):
+    """Build dist before collection so module-level discovery in test files works."""
     result = subprocess.run(
         ["python3", "-m", "agent_notes", "build"],
         cwd=REPO_ROOT,
@@ -27,4 +22,13 @@ def built_dist():
             f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}",
             returncode=1,
         )
+
+
+@pytest.fixture(scope="session", autouse=True)
+def built_dist():
+    """Build dist once at suite start. If build fails, the entire suite errors loudly — no silent skips.
+
+    Tests that need a built dist depend on this implicitly (autouse). Tests that don't
+    consume it pay only the one-time build cost.
+    """
     yield DIST_DIR

agent_notes-2.10.0/tests/unit/commands/test_wizard_preflight.py

@@ -0,0 +1,232 @@
+"""Tests for _confirm_install pre-flight summary in agent_notes.commands.wizard."""
+import io
+import logging
+import sys
+import pytest
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+from agent_notes.services.installer import InstallAction
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_install_action(action: str, dst_name: str = "CLAUDE.md", backup: Path = None) -> InstallAction:
+    src = Path("/fake/src") / dst_name
+    dst = Path("/fake/dst") / dst_name
+    return InstallAction(action=action, src=src, dst=dst, backup_path=backup)
+
+
+def _run_confirm_install(monkeypatch, manifest, user_input: str = "Y"):
+    """Call _confirm_install with all heavy side-effects mocked out.
+
+    local imports inside _confirm_install:
+      from ..services.ui import _clear_screen, _render_step_header
+      from ..registries.cli_registry import load_registry
+      from ..services.installer import plan_install
+
+    We patch the source modules so the local imports pick up the stubs.
+    """
+    # Suppress screen-clearing and step headers (patched at source)
+    monkeypatch.setattr("agent_notes.services.ui._clear_screen", lambda: None)
+    monkeypatch.setattr("agent_notes.services.ui._render_step_header", lambda *a, **kw: None)
+
+    # plan_install is imported from services.installer inside the function
+    monkeypatch.setattr("agent_notes.services.installer.plan_install", lambda **kw: manifest)
+
+    # load_registry is imported from registries.cli_registry inside the function
+    monkeypatch.setattr(
+        "agent_notes.registries.cli_registry.load_registry",
+        lambda *a, **kw: MagicMock(),
+    )
+
+    # Stub out module-level helpers in wizard
+    monkeypatch.setattr("agent_notes.commands.wizard._render_install_summary", lambda *a, **kw: None)
+    monkeypatch.setattr("agent_notes.commands.wizard._get_skill_groups", lambda: {})
+
+    # Drive _safe_input (module-level import in wizard)
+    monkeypatch.setattr("agent_notes.commands.wizard._safe_input", lambda prompt, default: user_input)
+
+    # Redirect stdout to capture prints
+    buf = io.StringIO()
+    with patch("sys.stdout", buf):
+        from agent_notes.commands.wizard import _confirm_install
+        result = _confirm_install(
+            clis={"claude"},
+            scope="local",
+            copy_mode=False,
+            selected_skills=[],
+            role_models={},
+        )
+
+    return result, buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+class TestConfirmInstallFileCount:
+    def test_shows_files_to_install_count(self, monkeypatch):
+        """The 'Files to install: N' line must show the correct non-skip count."""
+        manifest = [
+            _make_install_action("install", "a.md"),
+            _make_install_action("install", "b.md"),
+            _make_install_action("install", "c.md"),
+            _make_install_action("skip", "d.md"),  # not counted
+        ]
+        _result, output = _run_confirm_install(monkeypatch, manifest, user_input="Y")
+
+        assert "Files to install:" in output
+        # The count of non-skip actions is 3
+        assert "3" in output
+
+    def test_skip_actions_excluded_from_count(self, monkeypatch):
+        """All-skip manifest reports 0 files to install."""
+        manifest = [_make_install_action("skip", f"{i}.md") for i in range(5)]
+        _result, output = _run_confirm_install(monkeypatch, manifest, user_input="Y")
+
+        assert "Files to install:" in output
+        assert "0" in output
+
+
+class TestConfirmInstallBackupLines:
+    def test_lists_each_backup_path_when_overwrites_present(self, monkeypatch, tmp_path):
+        """Each overwrite action with a backup_path must appear in its own output line."""
+        bak1 = tmp_path / "CLAUDE.md.bak.20260430T022500000001Z"
+        bak2 = tmp_path / "settings.json.bak.20260430T022500000002Z"
+        manifest = [
+            _make_install_action("install", "agents/role.md"),
+            InstallAction(
+                action="overwrite",
+                src=Path("/fake/src/CLAUDE.md"),
+                dst=tmp_path / "CLAUDE.md",
+                backup_path=bak1,
+            ),
+            InstallAction(
+                action="overwrite",
+                src=Path("/fake/src/settings.json"),
+                dst=tmp_path / "settings.json",
+                backup_path=bak2,
+            ),
+        ]
+        _result, output = _run_confirm_install(monkeypatch, manifest, user_input="Y")
+
+        assert str(bak1) in output, f"Expected backup path {bak1} in output:\n{output}"
+        assert str(bak2) in output, f"Expected backup path {bak2} in output:\n{output}"
+
+    def test_backup_section_header_present_when_overwrites_exist(self, monkeypatch, tmp_path):
+        bak = tmp_path / "CLAUDE.md.bak.20260430T022500000001Z"
+        manifest = [
+            InstallAction(
+                action="overwrite",
+                src=Path("/fake/src/CLAUDE.md"),
+                dst=tmp_path / "CLAUDE.md",
+                backup_path=bak,
+            ),
+        ]
+        _result, output = _run_confirm_install(monkeypatch, manifest, user_input="Y")
+
+        assert "back up" in output.lower() or "backup" in output.lower(), (
+            f"Expected a backup section header in output:\n{output}"
+        )
+
+    def test_no_backup_section_when_no_overwrites(self, monkeypatch):
+        """If no overwrites, the backup listing block must not appear."""
+        manifest = [
+            _make_install_action("install", "a.md"),
+            _make_install_action("skip", "b.md"),
+        ]
+        _result, output = _run_confirm_install(monkeypatch, manifest, user_input="Y")
+
+        # "back up" section only appears when there are overwrites
+        assert "→" not in output, (
+            "No backup arrow (→) should appear when there are no overwrites"
+        )
+
+
+class TestConfirmInstallPlanInstallException:
+    def test_plan_install_exception_does_not_raise_to_user(self, monkeypatch):
+        """When plan_install raises, _confirm_install must not propagate the exception."""
+        monkeypatch.setattr("agent_notes.services.ui._clear_screen", lambda: None)
+        monkeypatch.setattr("agent_notes.services.ui._render_step_header", lambda *a, **kw: None)
+        monkeypatch.setattr("agent_notes.commands.wizard._render_install_summary", lambda *a, **kw: None)
+        monkeypatch.setattr("agent_notes.commands.wizard._get_skill_groups", lambda: {})
+        monkeypatch.setattr(
+            "agent_notes.registries.cli_registry.load_registry",
+            lambda *a, **kw: MagicMock(),
+        )
+        monkeypatch.setattr("agent_notes.commands.wizard._safe_input", lambda prompt, default: "Y")
+
+        def exploding_plan_install(**kw):
+            raise RuntimeError("simulated plan_install failure")
+
+        monkeypatch.setattr("agent_notes.services.installer.plan_install", exploding_plan_install)
+
+        # Should not raise
+        from agent_notes.commands.wizard import _confirm_install
+        result = _confirm_install(
+            clis={"claude"},
+            scope="local",
+            copy_mode=False,
+            selected_skills=[],
+            role_models={},
+        )
+        # User answered Y, so result should be True (proceed)
+        assert result is True
+
+    def test_plan_install_exception_emits_debug_log(self, monkeypatch, caplog):
+        """When plan_install raises, a debug-level log must be emitted."""
+        monkeypatch.setattr("agent_notes.services.ui._clear_screen", lambda: None)
+        monkeypatch.setattr("agent_notes.services.ui._render_step_header", lambda *a, **kw: None)
+        monkeypatch.setattr("agent_notes.commands.wizard._render_install_summary", lambda *a, **kw: None)
+        monkeypatch.setattr("agent_notes.commands.wizard._get_skill_groups", lambda: {})
+        monkeypatch.setattr(
+            "agent_notes.registries.cli_registry.load_registry",
+            lambda *a, **kw: MagicMock(),
+        )
+        monkeypatch.setattr("agent_notes.commands.wizard._safe_input", lambda prompt, default: "Y")
+
+        def exploding_plan_install(**kw):
+            raise ValueError("boom")
+
+        monkeypatch.setattr("agent_notes.services.installer.plan_install", exploding_plan_install)
+
+        with caplog.at_level(logging.DEBUG, logger="agent_notes.commands.wizard"):
+            from agent_notes.commands.wizard import _confirm_install
+            _confirm_install(
+                clis={"claude"},
+                scope="local",
+                copy_mode=False,
+                selected_skills=[],
+                role_models={},
+            )
+
+        assert any(
+            "plan_install" in r.message.lower() or "pre-flight" in r.message.lower()
+            for r in caplog.records
+        ), f"Expected a debug log mentioning plan_install/pre-flight, got: {caplog.records}"
+
+
+class TestConfirmInstallAbort:
+    def test_returns_false_when_user_answers_n(self, monkeypatch):
+        """When user answers 'n', _confirm_install must return False."""
+        manifest = [_make_install_action("install", "a.md")]
+        result, _output = _run_confirm_install(monkeypatch, manifest, user_input="n")
+        assert result is False
+
+    def test_returns_true_when_user_answers_y(self, monkeypatch):
+        manifest = [_make_install_action("install", "a.md")]
+        result, _output = _run_confirm_install(monkeypatch, manifest, user_input="Y")
+        assert result is True
+
+    def test_no_install_called_when_user_aborts(self, monkeypatch):
+        """Confirming 'n' must not trigger any install side-effects.
+        _confirm_install only returns a bool — actual install is the caller's job.
+        We verify the return value is False (caller must check it).
+        """
+        manifest = [_make_install_action("install", "a.md")]
+        result, _output = _run_confirm_install(monkeypatch, manifest, user_input="n")
+        assert result is False, "Return value False signals caller should not proceed"