agentpeek 0.9.0__py3-none-any.whl

agentpeek/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("agentpeek")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

agentpeek/__main__.py

@@ -0,0 +1,3 @@
+from agentpeek.cli import main
+
+raise SystemExit(main())

agentpeek/cli.py

@@ -0,0 +1,42 @@
+import argparse
+import importlib.metadata
+from pathlib import Path
+
+from agentpeek.logging_setup import configure_logging
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agentpeek",
+        description="TUI inspector for agent CLI configuration directories.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"agentpeek {importlib.metadata.version('agentpeek')}",
+    )
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=None,
+        help="Config root to scan. Default: ~/.claude.",
+    )
+    parser.add_argument(
+        "--source",
+        default=None,
+        help="Force a source by name. Default: auto-detect.",
+    )
+    parser.add_argument(
+        "--log-level",
+        default="WARNING",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+    )
+    args = parser.parse_args(argv)
+    configure_logging(args.log_level)
+
+    # Defer Textual import so --version and --help are fast and don't drag the
+    # TUI into module-load time when only the CLI surface is exercised.
+    from agentpeek.tui.app import AgentViewApp  # noqa: PLC0415
+
+    AgentViewApp(scan_root=args.root, source_name=args.source).run()
+    return 0

agentpeek/health.py

@@ -0,0 +1,136 @@
+from collections import defaultdict
+
+from agentpeek.models import ScanReport, ScanResult, ScanWarning
+
+
+def run_health_checks(result: ScanResult) -> list[ScanWarning]:
+    issues: list[ScanWarning] = []
+    issues.extend(_check_conflicting_keybindings(result))
+    issues.extend(_check_orphan_hooks(result))
+    issues.extend(_check_plugin_state(result))
+    return issues
+
+
+def _check_conflicting_keybindings(result: ScanResult) -> list[ScanWarning]:
+    if result.keybindings is None:
+        return []
+    seen: defaultdict[tuple[str, str], list[str]] = defaultdict(list)
+    for entry in result.keybindings.entries:
+        seen[(entry.context, entry.key)].append(entry.action)
+    issues: list[ScanWarning] = []
+    for (context, key), actions in sorted(seen.items()):
+        unique = sorted(set(actions))
+        if len(unique) > 1:
+            issues.append(
+                ScanWarning(
+                    path=result.keybindings.path,
+                    category="conflicting_binding",
+                    reason=(
+                        f"context {context!r} key {key!r} maps to multiple "
+                        f"actions: {unique}"
+                    ),
+                )
+            )
+    return issues
+
+
+def _check_orphan_hooks(result: ScanResult) -> list[ScanWarning]:
+    hooks_dir = result.root / "hooks"
+    if not hooks_dir.is_dir():
+        return []
+    referenced = {
+        h.referenced_script.resolve()
+        for h in result.hooks
+        if h.referenced_script is not None
+    }
+    issues: list[ScanWarning] = []
+    for f in sorted(hooks_dir.iterdir()):
+        if f.is_file() and f.resolve() not in referenced:
+            issues.append(
+                ScanWarning(
+                    path=f,
+                    category="orphan_hook",
+                    reason=(
+                        f"script {f.name} is not referenced from any settings hook"
+                    ),
+                )
+            )
+    return issues
+
+
+def _check_plugin_state(result: ScanResult) -> list[ScanWarning]:
+    issues: list[ScanWarning] = []
+    for plugin in result.plugins:
+        if plugin.enabled and not plugin.installations:
+            issues.append(
+                ScanWarning(
+                    path=None,
+                    category="plugin_state",
+                    reason=(
+                        f"plugin {plugin.qualified_id} is enabled but has "
+                        "no installations on disk"
+                    ),
+                )
+            )
+    return issues
+
+
+def run_cross_scope_checks(report: ScanReport) -> list[ScanWarning]:
+    """Cross-scope diagnostics: comparing user-level and project-level scans
+    for overlaps, overrides, and layered configuration."""
+    if report.user is None or report.project is None:
+        return []
+    issues: list[ScanWarning] = []
+    issues.extend(_check_scope_override_command(report))
+    issues.extend(_check_scope_override_plugin(report))
+    issues.extend(_check_scope_layered_memory(report))
+    return issues
+
+
+def _check_scope_override_command(report: ScanReport) -> list[ScanWarning]:
+    assert report.user is not None and report.project is not None
+    user_names = {c.name for c in report.user.commands}
+    project_names = {c.name for c in report.project.commands}
+    return [
+        ScanWarning(
+            path=None,
+            category="scope_override_command",
+            reason=(
+                f"slash command /{name} exists in both user and project scope; "
+                "project version takes precedence"
+            ),
+        )
+        for name in sorted(user_names & project_names)
+    ]
+
+
+def _check_scope_override_plugin(report: ScanReport) -> list[ScanWarning]:
+    assert report.user is not None and report.project is not None
+    user_ids = {p.qualified_id for p in report.user.plugins}
+    project_ids = {p.qualified_id for p in report.project.plugins}
+    return [
+        ScanWarning(
+            path=None,
+            category="scope_override_plugin",
+            reason=(f"plugin {qid} has installations in both user and project scope"),
+        )
+        for qid in sorted(user_ids & project_ids)
+    ]
+
+
+def _check_scope_layered_memory(report: ScanReport) -> list[ScanWarning]:
+    assert report.user is not None and report.project is not None
+    user_claude = any(m.kind == "claude_md" for m in report.user.memory)
+    project_claude = any(m.kind == "claude_md" for m in report.project.memory)
+    if not (user_claude and project_claude):
+        return []
+    return [
+        ScanWarning(
+            path=None,
+            category="scope_layered_memory",
+            reason=(
+                "CLAUDE.md exists at both user and project scope; "
+                "project memory layers on top of user memory"
+            ),
+        )
+    ]

agentpeek/logging_setup.py

@@ -0,0 +1,8 @@
+import logging
+
+
+def configure_logging(level: str) -> None:
+    logging.basicConfig(
+        level=getattr(logging, level),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )

agentpeek/models.py

@@ -0,0 +1,196 @@
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+
+@dataclass(frozen=True, slots=True)
+class ScanWarning:
+    path: Path | None
+    category: str
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class SettingsBundle:
+    user_settings_path: Path | None
+    local_settings_path: Path | None
+    model: str | None
+    theme: str | None
+    editor_mode: str | None
+    effort_level: str | None
+    env: Mapping[str, str]
+    permissions_allow: tuple[str, ...]
+    permissions_deny: tuple[str, ...]
+    permissions_ask: tuple[str, ...]
+    enabled_plugins: tuple[str, ...]
+    hooks_raw: Mapping[str, tuple[Mapping[str, object], ...]]
+    hooks_dir_files: int
+
+
+@dataclass(frozen=True, slots=True)
+class HookSpec:
+    event: str
+    matcher: str | None
+    type: str
+    command: str
+    timeout: int | None
+    referenced_script: Path | None
+    script_exists: bool
+    # `source_plugin` is the qualified id of a plugin (`name@market`) when
+    # this hook was contributed by an installed plugin. None for hooks
+    # declared in a user or project settings file.
+    source_plugin: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SlashCommand:
+    path: Path
+    name: str
+    description: str | None
+    argument_hint: str | None
+    allowed_tools: tuple[str, ...]
+    body: str
+    source_plugin: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PluginInstallation:
+    scope: str
+    install_path: Path
+    version: str
+    installed_at: str
+    last_updated: str
+    git_commit_sha: str | None
+    project_path: Path | None
+
+
+@dataclass(frozen=True, slots=True)
+class PluginManifest:
+    description: str | None
+    version: str | None
+    author_name: str | None
+    author_email: str | None
+    homepage: str | None
+    license: str | None
+    keywords: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class PluginSkill:
+    path: Path
+    name: str
+    description: str | None
+    body: str
+    source_plugin: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PluginAgent:
+    path: Path
+    name: str
+    description: str | None
+    body: str
+    source_plugin: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Plugin:
+    id: str
+    marketplace: str
+    qualified_id: str
+    enabled: bool
+    installations: tuple[PluginInstallation, ...]
+    # Contents enumerated from the first installation's `install_path`.
+    # All-optional / empty-default so existing test constructors and
+    # future non-Claude sources (e.g. a CodexSource) can build Plugin
+    # without populating these.
+    manifest: PluginManifest | None = None
+    skills: tuple[PluginSkill, ...] = ()
+    agents: tuple[PluginAgent, ...] = ()
+    commands: tuple[SlashCommand, ...] = ()
+    hooks: tuple[HookSpec, ...] = ()
+    mcps: tuple["MCPServer", ...] = ()
+
+
+MemoryKind = Literal["claude_md", "memory_index", "memory_entry"]
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryFile:
+    path: Path
+    body: str
+    has_frontmatter: bool
+    kind: MemoryKind
+    project_label: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class KeybindingEntry:
+    context: str
+    key: str
+    action: str
+
+
+@dataclass(frozen=True, slots=True)
+class KeybindingsBundle:
+    path: Path | None
+    entries: tuple[KeybindingEntry, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class MCPServer:
+    name: str
+    source_path: Path
+    command: str | None
+    args: tuple[str, ...]
+    env: Mapping[str, str]
+    source_plugin: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ScanResult:
+    source: str
+    root: Path
+    settings: SettingsBundle | None
+    hooks: tuple[HookSpec, ...]
+    commands: tuple[SlashCommand, ...]
+    plugins: tuple[Plugin, ...]
+    memory: tuple[MemoryFile, ...]
+    keybindings: KeybindingsBundle | None
+    mcp: tuple[MCPServer, ...]
+    warnings: tuple[ScanWarning, ...]
+
+    @classmethod
+    def empty(
+        cls, *, root: Path | None = None, reason: str | None = None
+    ) -> "ScanResult":
+        ws: tuple[ScanWarning, ...] = (
+            (ScanWarning(path=None, category="source", reason=reason),)
+            if reason
+            else ()
+        )
+        return cls(
+            source="",
+            root=root or Path("/"),
+            settings=None,
+            hooks=(),
+            commands=(),
+            plugins=(),
+            memory=(),
+            keybindings=None,
+            mcp=(),
+            warnings=ws,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ScanReport:
+    user: ScanResult | None
+    project: ScanResult | None
+    project_root: Path | None
+    cross_scope_warnings: tuple[ScanWarning, ...] = ()
+
+    @property
+    def primary(self) -> ScanResult | None:
+        return self.project or self.user

agentpeek/parsers/__init__.py

@@ -0,0 +1,4 @@
+from agentpeek.parsers.frontmatter_parser import FrontmatterFile, load_frontmatter
+from agentpeek.parsers.json_parser import load_json
+
+__all__ = ["FrontmatterFile", "load_frontmatter", "load_json"]

agentpeek/parsers/frontmatter_parser.py

@@ -0,0 +1,51 @@
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+import frontmatter
+import yaml
+
+from agentpeek.models import ScanWarning
+
+
+@dataclass(frozen=True, slots=True)
+class FrontmatterFile:
+    metadata: Mapping[str, object]
+    body: str
+
+
+def load_frontmatter(
+    path: Path, *, category: str
+) -> tuple[FrontmatterFile | None, ScanWarning | None]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None, ScanWarning(
+            path=path, category=category, reason=f"file not found: {path}"
+        )
+    except UnicodeDecodeError as e:
+        return None, ScanWarning(
+            path=path,
+            category=category,
+            reason=f"could not decode utf-8: {e.reason}",
+        )
+    except OSError as e:
+        return None, ScanWarning(
+            path=path, category=category, reason=f"could not read: {e.strerror}"
+        )
+
+    try:
+        post = frontmatter.loads(text)
+    except yaml.YAMLError as e:
+        return None, ScanWarning(
+            path=path, category=category, reason=f"invalid frontmatter YAML: {e}"
+        )
+    except Exception as e:
+        return None, ScanWarning(
+            path=path, category=category, reason=f"unexpected error: {e!r}"
+        )
+
+    metadata = cast("Mapping[str, object]", dict(post.metadata))  # type: ignore[reportUnknownArgumentType]
+    body = cast("str", post.content)  # type: ignore[reportUnknownMemberType]
+    return FrontmatterFile(metadata=metadata, body=body), None

agentpeek/parsers/json_parser.py

@@ -0,0 +1,33 @@
+import json
+from pathlib import Path
+
+from agentpeek.models import ScanWarning
+
+
+def load_json(path: Path, *, category: str) -> tuple[object | None, ScanWarning | None]:
+    try:
+        return json.loads(path.read_text(encoding="utf-8")), None
+    except FileNotFoundError:
+        return None, ScanWarning(
+            path=path, category=category, reason=f"file not found: {path}"
+        )
+    except json.JSONDecodeError as e:
+        return None, ScanWarning(
+            path=path,
+            category=category,
+            reason=f"invalid JSON at line {e.lineno} col {e.colno}: {e.msg}",
+        )
+    except UnicodeDecodeError as e:
+        return None, ScanWarning(
+            path=path,
+            category=category,
+            reason=f"could not decode utf-8: {e.reason}",
+        )
+    except OSError as e:
+        return None, ScanWarning(
+            path=path, category=category, reason=f"could not read: {e.strerror}"
+        )
+    except Exception as e:
+        return None, ScanWarning(
+            path=path, category=category, reason=f"unexpected error: {e!r}"
+        )