agent-notes 2.0.4__py3-none-any.whl

agent_notes/VERSION

@@ -0,0 +1 @@
+2.0.4

agent_notes/__init__.py

@@ -0,0 +1 @@
+"""agent-notes — AI agent configuration manager."""

agent_notes/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as: python3 -m agent_notes"""
+from agent_notes.cli import main
+
+main()

agent_notes/cli.py

@@ -0,0 +1,348 @@
+"""CLI entry point with argument parsing."""
+
+import argparse
+import sys
+
+from .config import Color
+
+
+DESCRIPTION = "AgentNotes is a hub for installing AI best-practices (agents, skills, rules) across AI CLIs."
+
+# Pre-colored usage line: "agent-notes <command> [options]"
+# - "agent-notes" magenta (violet)
+# - "<command>"   cyan (matches the command-name color in the Commands section)
+# - "[options]"   green (matches the flag color)
+USAGE = (
+    f"{Color.MAGENTA}agent-notes{Color.NC} "
+    f"{Color.CYAN}<command>{Color.NC} "
+    f"{Color.GREEN}[options]{Color.NC}"
+)
+
+# Per-command default-behavior hints shown inline next to the description.
+# These describe what happens when the command is run with no flags.
+COMMAND_DEFAULTS = {
+    "install":   "default: interactive wizard",
+    "uninstall": "default: global",
+    "update":    "default: pull, show diff, ask to apply",
+    "doctor":    "default: global scope, read-only",
+}
+
+# (command, explanation) pairs — rendered with color in _build_epilog()
+EXAMPLES = [
+    ("agent-notes install",                    "Interactive wizard (recommended)"),
+    ("agent-notes install --local",            "Install into current project (Claude + OpenCode, symlinks)"),
+    ("agent-notes install --local --copy",     "Same, but copy files (allows local edits)"),
+    ("agent-notes update --dry-run",           "Show what would change, don't apply"),
+    ("agent-notes update --only agents --yes", "Apply only agent changes, no prompt"),
+    ("agent-notes doctor --fix",               "Check and repair installation"),
+    ("agent-notes list agents",                "List all configured agents"),
+]
+
+
+def _heading(label: str) -> str:
+    """Section heading — no color (terminal default)."""
+    return label
+
+
+def _colorize_command(cmd: str) -> str:
+    """Color a command line with the same scheme as the Usage: line.
+
+    - "agent-notes" → magenta
+    - tokens starting with "-" → green (flags, including their values when joined)
+    - other tokens → cyan (subcommand names, positional values)
+    """
+    parts = cmd.split(" ")
+    out = []
+    for tok in parts:
+        if tok == "agent-notes":
+            out.append(f"{Color.MAGENTA}{tok}{Color.NC}")
+        elif tok.startswith("-"):
+            out.append(f"{Color.GREEN}{tok}{Color.NC}")
+        else:
+            out.append(f"{Color.CYAN}{tok}{Color.NC}")
+    return " ".join(out)
+
+
+def _build_epilog() -> str:
+    """Render the Examples section with ANSI colors (auto-stripped on non-TTY)."""
+    # Width is based on the visible (uncolored) length so columns align.
+    width = max(len(cmd) for cmd, _ in EXAMPLES)
+    lines = [_heading("Examples:")]
+    for cmd, note in EXAMPLES:
+        padding = " " * (width - len(cmd))
+        colored = _colorize_command(cmd)
+        lines.append(
+            f"  {colored}{padding}  {Color.DIM}{note}{Color.NC}"
+        )
+    return "\n".join(lines)
+
+
+def _collect_flags(sub_parser: argparse.ArgumentParser) -> list[tuple[str, str, str]]:
+    """Extract (flag_string, help_text, default_repr) tuples from a subparser.
+
+    - Skips -h/--help.
+    - Joins short/long forms: `-y, --yes`.
+    - Positionals become `<name>` or `[{choice1|choice2}]`.
+    - default_repr is `(default: X)` for positionals with a non-None default, else "".
+    """
+    items: list[tuple[str, str, str]] = []
+    for action in sub_parser._actions:
+        if isinstance(action, argparse._HelpAction):
+            continue
+
+        default_repr = ""
+        if action.default is not None and action.default is not False and not isinstance(action, argparse._StoreTrueAction):
+            # Show default only if it is a real value (not False from store_true).
+            default_repr = f"(default: {action.default})"
+
+        if action.option_strings:
+            flag = ", ".join(action.option_strings)
+            # Show what value the flag accepts (choices or free-form metavar)
+            if action.choices:
+                flag = f"{flag} {{{','.join(map(str, action.choices))}}}"
+            elif action.nargs != 0 and not isinstance(action, argparse._StoreTrueAction) \
+                    and not isinstance(action, argparse._StoreFalseAction) \
+                    and not isinstance(action, argparse._StoreConstAction):
+                metavar = action.metavar or f"<{action.dest}>"
+                flag = f"{flag} {metavar}"
+            items.append((flag, action.help or "", default_repr))
+        else:
+            if action.choices:
+                name = "{" + "|".join(map(str, action.choices)) + "}"
+            else:
+                name = f"<{action.dest}>"
+            if action.nargs == "?":
+                name = f"[{name}]"
+            items.append((name, action.help or "", default_repr))
+    return items
+
+
+def _render_commands_section(subparsers_action: argparse._SubParsersAction) -> str:
+    """Build the Commands section manually, with per-command flags inlined."""
+    lines = [_heading("Commands:")]
+    for name, sub in subparsers_action.choices.items():
+        help_text = ""
+        for action in subparsers_action._choices_actions:
+            if action.dest == name:
+                help_text = action.help or ""
+                break
+        default_hint = COMMAND_DEFAULTS.get(name, "")
+        suffix = f" {Color.DIM}({default_hint}){Color.NC}" if default_hint else ""
+        lines.append(
+            f"  {Color.CYAN}{name:<11}{Color.NC} {help_text}{suffix}"
+        )
+        flags = _collect_flags(sub)
+        # Compute per-command flag column width (min 20 for visual rhythm).
+        flag_col = max([20, *(len(flag) for flag, _, _ in flags)])
+        for flag, flag_help, default_repr in flags:
+            default_tail = f" {Color.DIM}{default_repr}{Color.NC}" if default_repr else ""
+            padding = " " * (flag_col - len(flag))
+            lines.append(
+                f"              {Color.GREEN}{flag}{Color.NC}{padding} "
+                f"{Color.DIM}{flag_help}{Color.NC}{default_tail}"
+            )
+        lines.append("")
+    while lines and lines[-1] == "":
+        lines.pop()
+    return "\n".join(lines)
+
+
+class _AgentNotesHelp(argparse.RawDescriptionHelpFormatter):
+    """Help formatter: plain 'Usage:' prefix and colored global options."""
+
+    def add_usage(self, usage, actions, groups, prefix=None):
+        if prefix is None:
+            prefix = "Usage: "
+        return super().add_usage(usage, actions, groups, prefix)
+
+    def _format_action_invocation(self, action):
+        """Colorize -h/--help and -v/--version in green."""
+        text = super()._format_action_invocation(action)
+        if action.option_strings and any(
+            opt in ("-h", "--help", "-v", "--version") for opt in action.option_strings
+        ):
+            text = f"{Color.GREEN}{text}{Color.NC}"
+        return text
+
+
+class _AgentNotesParser(argparse.ArgumentParser):
+    """Parser with custom help layout: description → usage → commands → options → examples."""
+
+    def format_help(self) -> str:
+        formatter = self._get_formatter()
+
+        # 1. Description (blue)
+        if self.description:
+            formatter.add_text(f"{Color.BLUE}{self.description}{Color.NC}")
+
+        # 2. Usage (plain "Usage:" prefix; usage line has its parts colored)
+        formatter.add_usage(
+            self.usage, self._actions, self._mutually_exclusive_groups,
+            prefix="Usage: ",
+        )
+
+        # 3. Commands — hand-rolled to show per-command flags
+        subparsers_action = next(
+            (a for a in self._actions if isinstance(a, argparse._SubParsersAction)),
+            None,
+        )
+        if subparsers_action is not None:
+            formatter.add_text(_render_commands_section(subparsers_action))
+
+        # 4. Options (global) — custom heading color
+        optional_group = next(
+            (g for g in self._action_groups
+             if g.title in ("options", "optional arguments") and g._group_actions),
+            None,
+        )
+        if optional_group is not None:
+            formatter.start_section(_heading("Options"))
+            formatter.add_text(optional_group.description)
+            formatter.add_arguments(optional_group._group_actions)
+            formatter.end_section()
+
+        # 5. Examples
+        formatter.add_text(_build_epilog())
+
+        return formatter.format_help()
+
+
+def main():
+    parser = _AgentNotesParser(
+        prog="agent-notes",
+        description=DESCRIPTION,
+        usage=USAGE,
+        formatter_class=_AgentNotesHelp,
+    )
+    parser.add_argument("-v", "--version", action="store_true", help="Show version")
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        title="Commands",
+        metavar="",
+        parser_class=argparse.ArgumentParser,  # subparsers use default formatting
+    )
+    
+    # install
+    p_install = subparsers.add_parser("install", help="Build and install components")
+    p_install.add_argument("--local", action="store_true", help="Install to current project")
+    p_install.add_argument("--copy", action="store_true", help="Copy instead of symlink (with --local)")
+    p_install.add_argument("--reconfigure", action="store_true",
+        help="Clear existing state for this scope and re-run the wizard")
+    
+    # build
+    subparsers.add_parser("build", help="Build agent configuration files from source")
+    
+    # uninstall
+    p_uninstall = subparsers.add_parser("uninstall", help="Remove installed components")
+    p_uninstall.add_argument("--local", action="store_true", help="Remove from current project")
+    
+    # update
+    p_update = subparsers.add_parser("update", help="Pull latest, show diff, reinstall")
+    p_update.add_argument("--dry-run", action="store_true", help="Show diff only, do not reinstall")
+    p_update.add_argument("-y", "--yes", action="store_true", help="Skip confirmation prompt")
+    p_update.add_argument("--only", action="append", choices=["agents","skills","rules","commands","config","settings"],
+        help="Filter diff to these component types (repeatable)")
+    p_update.add_argument("--since", help="Override 'before' commit label (cosmetic only for now)")
+    p_update.add_argument("--skip-pull", action="store_true", help="Skip git pull")
+    
+    # doctor
+    p_doctor = subparsers.add_parser("doctor", help="Check installation health")
+    p_doctor.add_argument("--local", action="store_true", help="Check local installation")
+    p_doctor.add_argument("--fix", action="store_true", help="Fix found issues")
+    
+    # info
+    subparsers.add_parser("info", help="Show status and component counts")
+    
+    # list
+    p_list = subparsers.add_parser("list", help="List installed components")
+    p_list.add_argument("filter", nargs="?", default="all",
+        choices=["agents", "skills", "rules", "clis", "models", "roles", "all"],
+        help="Which components to list")
+    
+    # validate
+    subparsers.add_parser("validate", help="Lint source configuration files")
+    
+    # set
+    p_set = subparsers.add_parser("set", help="Configure installation")
+    p_set_subparsers = p_set.add_subparsers(dest="entity", help="What to configure")
+    p_set_role = p_set_subparsers.add_parser("role", help="Set role→model assignment")
+    p_set_role.add_argument("role_name", help="Role name")
+    p_set_role.add_argument("model_id", help="Model ID")
+    p_set_role.add_argument("--cli", help="Target CLI (auto-detect if omitted)")
+    p_set_role.add_argument("--scope", choices=["global", "local"], help="Install scope")
+    p_set_role.add_argument("--local", action="store_true", help="Use local scope")
+    
+    # regenerate 
+    p_regen = subparsers.add_parser("regenerate", help="Rebuild files from state")
+    p_regen.add_argument("--scope", choices=["global", "local"], help="Install scope")
+    p_regen.add_argument("--cli", help="Regenerate specific CLI only")
+    p_regen.add_argument("--local", action="store_true", help="Use local scope")
+    
+    # memory
+    p_memory = subparsers.add_parser("memory", help="Manage agent memory")
+    p_memory.add_argument("action", nargs="?", default="list",
+        choices=["init", "list", "vault", "index", "add", "size", "show", "reset", "export", "import"],
+        help="Memory action")
+    p_memory.add_argument("name", nargs="?", help="Agent name / note title (for show/reset/add)")
+    p_memory.add_argument("extra", nargs="*", help="Additional args (for add: body [type] [agent] [project])")
+    
+    args = parser.parse_args()
+    
+    if args.version:
+        from .config import get_version
+        print(f"agent-notes {get_version()}")
+        return
+    
+    if not args.command:
+        parser.print_help()
+        return
+    
+    # Route to modules
+    if args.command == "build":
+        from .commands.build import build
+        build()
+    elif args.command == "install":
+        if args.local or args.copy:
+            from .commands.install import install
+            install(local=args.local, copy=args.copy, reconfigure=args.reconfigure)
+        else:
+            from .commands.wizard import interactive_install
+            interactive_install()
+    elif args.command == "uninstall":
+        from .commands.install import uninstall
+        uninstall(local=args.local)
+    elif args.command == "update":
+        from .commands.update import update
+        update(
+            dry_run=args.dry_run,
+            yes=args.yes,
+            only=args.only,
+            since=args.since,
+            skip_pull=args.skip_pull,
+        )
+    elif args.command == "doctor":
+        from .commands.doctor import doctor
+        doctor(local=args.local, fix=args.fix)
+    elif args.command == "info":
+        from .commands.info import show_info
+        show_info()
+    elif args.command == "list":
+        from .commands.list import list_components
+        list_components(args.filter)
+    elif args.command == "validate":
+        from .commands.validate import validate
+        validate()
+    elif args.command == "set":
+        if args.entity == "role":
+            from .commands.set_role import set_role
+            set_role(args.role_name, args.model_id, cli=args.cli, scope=args.scope, local=args.local)
+    elif args.command == "regenerate":
+        from .commands.regenerate import regenerate
+        regenerate(scope=args.scope, cli=args.cli, local=args.local)
+    elif args.command == "memory":
+        from .commands.memory import memory
+        memory(args.action, args.name, getattr(args, "extra", None))
+
+if __name__ == "__main__":
+    main()

agent_notes/commands/__init__.py

@@ -0,0 +1,27 @@
+"""User-facing commands. Each module is a thin orchestrator.
+
+Commands may import from: services/, registries/, domain/, config.
+Commands MUST NOT import other commands (use services to share logic).
+
+Exception: install/uninstall/info share helpers via _install_helpers.py since
+they are sibling members of one logical command group.
+"""
+from .install import install
+from .uninstall import uninstall
+from .info import show_info
+from .build import build
+from .doctor import doctor
+from .validate import validate
+from .update import update
+from .regenerate import regenerate
+from .set_role import set_role
+from .wizard import interactive_install
+from . import list as list_cmd
+from . import memory as memory_cmd
+
+__all__ = [
+    "install", "uninstall", "show_info",
+    "build", "doctor", "validate", "update",
+    "regenerate", "set_role", "interactive_install",
+    "list_cmd", "memory_cmd",
+]

agent_notes/commands/_install_helpers.py

@@ -0,0 +1,262 @@
+"""Shared installation helpers for install/uninstall/info commands."""
+
+import shutil
+from pathlib import Path
+from typing import List
+
+from ..config import (
+    ROOT, DIST_CLAUDE_DIR, DIST_OPENCODE_DIR, DIST_GITHUB_DIR, DIST_RULES_DIR, DIST_SKILLS_DIR, DIST_SCRIPTS_DIR,
+    CLAUDE_HOME, OPENCODE_HOME, GITHUB_HOME, AGENTS_HOME, BIN_HOME,
+    linked, removed, skipped, info, get_version, Color, PKG_DIR
+)
+from ..services.fs import (
+    files_identical as _files_identical,
+    handle_existing as _handle_existing,
+    place_file, place_dir_contents, remove_symlink, 
+    remove_all_symlinks_in_dir, remove_dir_if_empty
+)
+
+
+def install_scripts_global() -> None:
+    """Install scripts to ~/.local/bin/."""
+    from ..services.installer import install_scripts_global as _service_impl
+    _service_impl()
+
+
+def _install_skills_to(targets: List[Path], dist_skills_dir: Path, copy_mode: bool) -> None:
+    """Install skills from dist_skills_dir to each directory in targets."""
+    if not dist_skills_dir.exists():
+        return
+    for target_dir in targets:
+        print(f"Installing skills to {target_dir} ...")
+        target_dir.mkdir(parents=True, exist_ok=True)
+        for skill_dir in sorted(dist_skills_dir.iterdir()):
+            if skill_dir.is_dir():
+                place_file(skill_dir, target_dir / skill_dir.name, copy_mode)
+
+
+def install_skills_global(copy_mode: bool = False) -> None:
+    """Install skills globally."""
+    targets = [CLAUDE_HOME / "skills", OPENCODE_HOME / "skills", AGENTS_HOME / "skills"]
+    _install_skills_to(targets, DIST_SKILLS_DIR, copy_mode)
+
+
+def install_skills_local(copy_mode: bool = False) -> None:
+    """Install skills locally."""
+    targets = [Path(".claude/skills"), Path(".opencode/skills")]
+    _install_skills_to(targets, DIST_SKILLS_DIR, copy_mode)
+
+
+def install_agents_global(copy_mode: bool = False) -> None:
+    """Install agents globally."""
+    print("Installing Claude Code agents to ~/.claude/agents/ ...")
+    place_dir_contents(DIST_CLAUDE_DIR / "agents", CLAUDE_HOME / "agents", "*.md", copy_mode)
+
+    print("Installing OpenCode agents to ~/.config/opencode/agents/ ...")
+    place_dir_contents(DIST_OPENCODE_DIR / "agents", OPENCODE_HOME / "agents", "*.md", copy_mode)
+
+
+def install_agents_local(copy_mode: bool = False) -> None:
+    """Install agents locally."""
+    print("Installing Claude Code agents to .claude/agents/ ...")
+    place_dir_contents(DIST_CLAUDE_DIR / "agents", Path(".claude/agents"), "*.md", copy_mode)
+
+    print("Installing OpenCode agents to .opencode/agents/ ...")
+    place_dir_contents(DIST_OPENCODE_DIR / "agents", Path(".opencode/agents"), "*.md", copy_mode)
+
+
+def install_rules_global(copy_mode: bool = False) -> None:
+    """Install global config and rules."""
+    print("Installing global config ...")
+
+    # CLAUDE.md → ~/.claude/CLAUDE.md
+    claude_global = DIST_CLAUDE_DIR / "CLAUDE.md"
+    if claude_global.exists():
+        place_file(claude_global, CLAUDE_HOME / "CLAUDE.md", copy_mode)
+
+    # AGENTS.md → ~/.config/opencode/AGENTS.md
+    agents_global = DIST_OPENCODE_DIR / "AGENTS.md"
+    if agents_global.exists():
+        place_file(agents_global, OPENCODE_HOME / "AGENTS.md", copy_mode)
+
+    # Rules → ~/.claude/rules/
+    if DIST_RULES_DIR.exists():
+        place_dir_contents(DIST_RULES_DIR, CLAUDE_HOME / "rules", "*.md", copy_mode)
+
+    # Copilot → ~/.github/copilot-instructions.md
+    copilot_global = DIST_GITHUB_DIR / "copilot-instructions.md"
+    if copilot_global.exists():
+        place_file(copilot_global, GITHUB_HOME / "copilot-instructions.md", copy_mode)
+
+
+def install_rules_local(copy_mode: bool = False) -> None:
+    """Install local config and rules."""
+    print("Installing project rules ...")
+
+    # CLAUDE.md → ./CLAUDE.md
+    claude_global = DIST_CLAUDE_DIR / "CLAUDE.md"
+    if claude_global.exists():
+        place_file(claude_global, Path("./CLAUDE.md"), copy_mode)
+
+    # AGENTS.md → ./AGENTS.md
+    agents_global = DIST_OPENCODE_DIR / "AGENTS.md"
+    if agents_global.exists():
+        place_file(agents_global, Path("./AGENTS.md"), copy_mode)
+
+    # Rules → .claude/rules/
+    if DIST_RULES_DIR.exists():
+        place_dir_contents(DIST_RULES_DIR, Path(".claude/rules"), "*.md", copy_mode)
+
+
+def uninstall_scripts_global() -> None:
+    """Uninstall scripts from ~/.local/bin/."""
+    from ..services.installer import uninstall_scripts_global as _service_impl
+    _service_impl()
+
+
+def _uninstall_skills_from(targets: List[Path]) -> None:
+    """Remove skills from each directory in targets."""
+    for target_dir in targets:
+        if target_dir.exists():
+            print(f"Removing skills from {target_dir} ...")
+            remove_all_symlinks_in_dir(target_dir)
+            remove_dir_if_empty(target_dir)
+
+
+def uninstall_skills_global() -> None:
+    """Uninstall skills globally."""
+    from .. import config
+    targets = [config.CLAUDE_HOME / "skills", config.OPENCODE_HOME / "skills", config.AGENTS_HOME / "skills"]
+    _uninstall_skills_from(targets)
+
+
+def uninstall_skills_local() -> None:
+    """Uninstall skills locally."""
+    _uninstall_skills_from([Path(".claude/skills"), Path(".opencode/skills")])
+
+
+def _uninstall_agents_from(dirs: List[Path]) -> None:
+    """Remove agent symlinks from each directory in dirs."""
+    for agents_dir in dirs:
+        print(f"Removing agents from {agents_dir} ...")
+        remove_all_symlinks_in_dir(agents_dir)
+        remove_dir_if_empty(agents_dir)
+
+
+def uninstall_agents_global() -> None:
+    """Uninstall agents globally."""
+    from .. import config
+    _uninstall_agents_from([config.CLAUDE_HOME / "agents", config.OPENCODE_HOME / "agents"])
+
+
+def uninstall_agents_local() -> None:
+    """Uninstall agents locally."""
+    _uninstall_agents_from([Path(".claude/agents"), Path(".opencode/agents")])
+
+
+def _uninstall_rules_from(config_symlinks: List[Path], rules_dir: Path, label: str) -> None:
+    """Remove config symlinks and rules directory."""
+    print(label)
+    for symlink in config_symlinks:
+        remove_symlink(symlink)
+    if rules_dir.exists():
+        remove_all_symlinks_in_dir(rules_dir)
+        remove_dir_if_empty(rules_dir)
+
+
+def uninstall_rules_global() -> None:
+    """Uninstall global config and rules."""
+    from .. import config
+    _uninstall_rules_from(
+        [config.CLAUDE_HOME / "CLAUDE.md", config.OPENCODE_HOME / "AGENTS.md", config.GITHUB_HOME / "copilot-instructions.md"],
+        config.CLAUDE_HOME / "rules",
+        "Removing global config ...",
+    )
+
+
+def uninstall_rules_local() -> None:
+    """Uninstall local config and rules."""
+    _uninstall_rules_from(
+        [Path("./CLAUDE.md"), Path("./AGENTS.md")],
+        Path(".claude/rules"),
+        "Removing project rules ...",
+    )
+
+
+def count_scripts() -> int:
+    """Count script files."""
+    return len([f for f in DIST_SCRIPTS_DIR.iterdir() if f.is_file()]) if DIST_SCRIPTS_DIR.exists() else 0
+
+
+def count_skills() -> int:
+    """Count skill directories."""
+    if not DIST_SKILLS_DIR.exists():
+        return 0
+    return len([d for d in DIST_SKILLS_DIR.iterdir() if d.is_dir()])
+
+
+def count_agents(backend) -> int:
+    """Count agent *.md files in backend's dist directory. Returns 0 if backend
+    doesn't support agents."""
+    from ..services import installer
+    from ..domain.cli_backend import CLIBackend
+    if not backend.supports("agents"):
+        return 0
+    src = installer.dist_source_for(backend, "agents")
+    if src is None or not src.exists():
+        return 0
+    return len(list(src.glob("*.md")))
+
+
+def count_global() -> int:
+    """Count global config files."""
+    count = 0
+
+    # Check each potential global config file (maintaining backward compatibility)
+    if (DIST_CLAUDE_DIR / "CLAUDE.md").exists():
+        count += 1
+    if (DIST_OPENCODE_DIR / "AGENTS.md").exists():
+        count += 1
+    if (DIST_GITHUB_DIR / "copilot-instructions.md").exists():
+        count += 1
+
+    # Count rules files
+    if DIST_RULES_DIR.exists():
+        count += len(list(DIST_RULES_DIR.glob("*.md")))
+
+    return count
+
+
+def _verify_install(scope_state, scope, project_path, registry) -> list[str]:
+    """Check each file recorded in scope_state.installed exists. Return list of missing issues."""
+    from pathlib import Path
+    issues = []
+    for cli_name, backend_state in scope_state.clis.items():
+        try:
+            backend = registry.get(cli_name)
+        except KeyError:
+            issues.append(f"CLI '{cli_name}' no longer in registry")
+            continue
+        # Print per-component counts
+        for component_type, items in backend_state.installed.items():
+            present = 0
+            missing_names = []
+            for name, item in items.items():
+                if Path(item.target).exists() or Path(item.target).is_symlink():
+                    present += 1
+                else:
+                    missing_names.append(name)
+            total = len(items)
+            if missing_names:
+                comp_label = f"{backend.label} {component_type}"
+                print(f"  ✗ {comp_label}: {len(missing_names)} missing ({', '.join(missing_names[:3])}{'...' if len(missing_names) > 3 else ''})")
+                for m in missing_names:
+                    issues.append(f"{comp_label}: {m} missing")
+            else:
+                if total > 0:
+                    if component_type == "config":
+                        comp_label = f"{backend.label} config"
+                    else:
+                        comp_label = f"{backend.label} {component_type}"
+                    print(f"  ✓ {total} {comp_label} present")
+    return issues