claude-code-capabilities 0.1.2__py3-none-any.whl

capdisc/report/sections.py

@@ -0,0 +1,154 @@
+"""Section bodies: each tab's HTML, assembled from cards over one slice of the report."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..catalog import CatalogMcpServer, CatalogTool
+from ..html import e, pill, preview, redact_home
+from ..scope import ArtifactKind, CapturedArtifact, ScanRoot, ScopeInventory
+from .cards import entry_card, plugin_card
+from .components import plugin_components
+from .html import (
+    card_block,
+    empty_block,
+    group_label,
+    id_span,
+    kind_class,
+    kv_line,
+    path_block,
+    ref_span,
+    row_block,
+    search_key,
+    stat_block,
+)
+from .models import EnvironmentReport, IndexedPlugin, IndexedSkill
+
+_PREVIEW_LEN = 600
+
+
+def render_roots_section(scan_roots: list[ScanRoot], plugin_dirs: list[Path]) -> str:
+    cards: list[str] = []
+    for root in scan_roots:
+        exists = root.base.exists()
+        head = (
+            pill(root.scope.value)
+            + f'<span class="ref mono" style="font-size:12.5px">{e(redact_home(root.base))}</span>'
+            + (pill("exists", "eff-b") if exists else pill("missing"))
+        )
+        if root.kinds is not None:
+            head += id_span("kinds: " + ", ".join(sorted(k.value for k in root.kinds)))
+        cards.append(
+            card_block(
+                search_key(root.scope.value, redact_home(root.base)),
+                row_block(head),
+                "eff" if exists else "shadow",
+            )
+        )
+    if plugin_dirs:
+        cards.append(group_label(f"plugin install dirs ({len(plugin_dirs)})"))
+        cards.extend(f'<div class="card">{path_block(p)}</div>' for p in plugin_dirs)
+    return "".join(cards)
+
+
+def _capture_card(capture: CapturedArtifact, is_effective: bool) -> str:
+    head = (
+        pill(capture.kind.value, kind_class(capture.kind))
+        + ref_span(capture.name)
+        + pill(f"{capture.scope.value}/{capture.shareable.value}")
+        + (
+            pill("effective", "eff-b")
+            if is_effective
+            else id_span(f"rank {capture.precedence} (shadowed)")
+        )
+        + pill(capture.resolution.value)
+    )
+    inner = row_block(head) + path_block(capture.path) + preview(capture.contents[:_PREVIEW_LEN])
+    search = search_key(
+        capture.name, capture.kind.value, capture.scope.value, redact_home(capture.path)
+    )
+    return card_block(search, inner, "eff" if is_effective else "shadow")
+
+
+def render_inventory_section(inventory: ScopeInventory) -> str:
+    effective = set(inventory.effective)
+    captures = sorted(inventory.artifacts, key=lambda c: (c.kind.value, c.name, c.precedence))
+    by_kind: dict[ArtifactKind, list[str]] = {}
+    for capture in captures:
+        by_kind.setdefault(capture.kind, []).append(_capture_card(capture, capture in effective))
+    out: list[str] = []
+    for kind in ArtifactKind:
+        cards = by_kind.get(kind, [])
+        if cards:
+            out.append(group_label(f"{kind.value} ({len(cards)})"))
+            out.extend(cards)
+    return "".join(out) or empty_block("nothing captured on disk")
+
+
+def render_skills_section(skills: list[IndexedSkill]) -> str:
+    cards = [entry_card(s.card, s.path) for s in sorted(skills, key=lambda s: s.card.ref)]
+    return "".join(cards) or empty_block("no skills found")
+
+
+def render_tools_section(tools: list[CatalogTool]) -> str:
+    return "".join(entry_card(tool, None) for tool in tools) or empty_block("no builtin tools")
+
+
+def render_plugins_section(
+    plugins: list[IndexedPlugin],
+    inventory: ScopeInventory,
+    mcp_servers: list[CatalogMcpServer],
+) -> str:
+    cards = [
+        plugin_card(p.card, plugin_components(p, inventory, mcp_servers))
+        for p in sorted(plugins, key=lambda p: p.card.ref)
+    ]
+    return "".join(cards) or empty_block("no plugins found")
+
+
+def render_mcp_section(servers: list[CatalogMcpServer]) -> str:
+    cards = [entry_card(s, None) for s in sorted(servers, key=lambda s: s.ref)]
+    return "".join(cards) or empty_block("no MCP servers reachable")
+
+
+def render_overview_section(report: EnvironmentReport) -> str:
+    top = (
+        '<div class="bigstat">'
+        + stat_block(report.skill_count, "skills")
+        + stat_block(report.tool_count, "builtin tools")
+        + stat_block(report.plugin_count, "plugins")
+        + stat_block(report.mcp_server_count, "mcp servers")
+        + stat_block(report.capture_count, "captures on disk")
+        + stat_block(report.hook_config_count, "hook configs")
+        + stat_block(report.scan_root_count, "scan roots")
+        + "</div>"
+    )
+    env_block = (
+        group_label("environment")
+        + '<div class="card">'
+        + kv_line("cwd", report.cwd)
+        + kv_line("home", report.home)
+        + kv_line("plugins root", report.plugins_root)
+        + kv_line("managed dir", report.managed_dir or "(none on this OS)")
+        + kv_line("mcp source", report.mcp_source)
+        + "</div>"
+    )
+    by_kind: dict[ArtifactKind, int] = {}
+    for capture in report.inventory.artifacts:
+        by_kind[capture.kind] = by_kind.get(capture.kind, 0) + 1
+    kinds = (
+        group_label("captures by kind")
+        + '<div class="bigstat">'
+        + "".join(stat_block(n, kind.value) for kind, n in by_kind.items())
+        + "</div>"
+    )
+    events = sorted({ev.value for cfg in report.inventory.hook_configs for ev in cfg.root})
+    hooks = ""
+    if events:
+        hooks = (
+            group_label("hook events in effect")
+            + '<div class="eventbar">'
+            + "".join(f'<span class="event">{e(ev)}</span>' for ev in events)
+            + "</div>"
+        )
+    return top + env_block + kinds + hooks

capdisc/report/types.py

@@ -0,0 +1,43 @@
+"""Domain-primitive aliases for the report package."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import Field
+
+ComponentCount = Annotated[
+    int,
+    Field(
+        ge=0,
+        title="Component count",
+        description="Number of components (skills, agents, hooks, or MCP servers) in a group.",
+    ),
+]
+SectionId = Annotated[
+    str,
+    Field(
+        pattern=r"^[a-z]+$",
+        title="Section id",
+        description="Nav/anchor id of one report tab.",
+        examples=["overview", "skills"],
+    ),
+]
+SectionLabel = Annotated[
+    str,
+    Field(
+        min_length=1,
+        max_length=40,
+        title="Section label",
+        description="Human-readable nav label of one report tab.",
+        examples=["Scan roots"],
+    ),
+]
+SectionCount = Annotated[
+    int,
+    Field(
+        ge=0,
+        title="Section count",
+        description="Item count shown next to a report tab's nav label.",
+    ),
+]

capdisc/scope/__init__.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from .inventory import (
+    CapturedArtifact,
+    ScanRoot,
+    ScopeInventory,
+    ScopeRoots,
+    artifact_kinds,
+    default_managed_dir,
+    parse_frontmatter_hooks,
+    parse_hooks,
+    render_inventory,
+    render_inventory_html,
+)
+from .locations import (
+    Artifact,
+    CaptureHit,
+    Command,
+    Hook,
+    HostFrontmatter,
+    InMemoryFlag,
+    Location,
+    SettingsEntry,
+    Skill,
+    StandaloneFile,
+    Storage,
+    Subagent,
+)
+from .types import (
+    ArtifactContents,
+    ArtifactKind,
+    ArtifactName,
+    ArtifactPath,
+    ArtifactSubdir,
+    CliFlag,
+    GlobPattern,
+    JsonKey,
+    ResolutionMode,
+    ResolutionRank,
+    ScopeKind,
+    ScopeRoot,
+    SettingsFile,
+    Shareability,
+)
+
+__all__ = [
+    "Artifact",
+    "ArtifactContents",
+    "ArtifactKind",
+    "ArtifactName",
+    "ArtifactPath",
+    "ArtifactSubdir",
+    "CaptureHit",
+    "CapturedArtifact",
+    "CliFlag",
+    "Command",
+    "GlobPattern",
+    "Hook",
+    "HostFrontmatter",
+    "InMemoryFlag",
+    "JsonKey",
+    "Location",
+    "ResolutionMode",
+    "ResolutionRank",
+    "ScanRoot",
+    "ScopeInventory",
+    "ScopeKind",
+    "ScopeRoot",
+    "ScopeRoots",
+    "SettingsEntry",
+    "SettingsFile",
+    "Shareability",
+    "Skill",
+    "StandaloneFile",
+    "Storage",
+    "Subagent",
+    "artifact_kinds",
+    "default_managed_dir",
+    "parse_frontmatter_hooks",
+    "parse_hooks",
+    "render_inventory",
+    "render_inventory_html",
+]

capdisc/scope/inventory/__init__.py

@@ -0,0 +1,20 @@
+"""Scan every artifact location under a set of scope roots into a `ScopeInventory` snapshot."""
+
+from __future__ import annotations
+
+from .capture import CapturedArtifact, ScopeInventory, parse_frontmatter_hooks, parse_hooks
+from .render import render_inventory, render_inventory_html
+from .roots import ScanRoot, ScopeRoots, artifact_kinds, default_managed_dir
+
+__all__ = [
+    "CapturedArtifact",
+    "ScanRoot",
+    "ScopeInventory",
+    "ScopeRoots",
+    "artifact_kinds",
+    "default_managed_dir",
+    "parse_frontmatter_hooks",
+    "parse_hooks",
+    "render_inventory",
+    "render_inventory_html",
+]

capdisc/scope/inventory/assets.py

@@ -0,0 +1,54 @@
+"""Inline CSS and JS for the inventory's self-contained HTML render — no external resources."""
+
+from __future__ import annotations
+
+# How many characters of a capture's contents the HTML preview shows.
+PREVIEW_CHARS = 600
+
+INVENTORY_STYLE = """
+:root{--bg:#0d1117;--panel:#161b22;--panel2:#1c2430;--bd:#2d3440;--fg:#e6edf3;--mut:#8b949e;
+--ac:#58a6ff;--gn:#3fb950;--yl:#d29922;--pu:#bc8cff;--cy:#39c5cf;}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--fg);
+font:14px/1.5 ui-sans-serif,system-ui,"Segoe UI",Roboto,sans-serif}
+header{padding:20px 24px;border-bottom:1px solid var(--bd);background:var(--panel)}
+h1{margin:0 0 4px;font-size:20px}
+.meta{color:var(--mut);font-size:12px}.meta b{color:var(--fg)}
+main{padding:20px 24px}
+.search{width:100%;max-width:480px;padding:9px 12px;background:var(--panel2);
+border:1px solid var(--bd);border-radius:8px;color:var(--fg);font-size:13px;margin-bottom:16px}
+.search:focus{outline:none;border-color:var(--ac)}
+.card{background:var(--panel);border:1px solid var(--bd);border-radius:10px;
+padding:14px 16px;margin-bottom:10px}
+.card.eff{border-left:3px solid var(--gn)}.card.shadow{opacity:.62}
+.row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
+.ref{font-weight:600;font-size:14px}.id{color:var(--mut);font-size:11px}
+.path{color:var(--mut);font-size:11.5px;margin-top:6px;word-break:break-all}
+.pill{font-size:10.5px;font-weight:700;letter-spacing:.4px;text-transform:uppercase;
+padding:2px 8px;border-radius:5px}
+.k-skill{background:#1f2d3d;color:var(--ac)}.k-agent{background:#2d1f3d;color:var(--pu)}
+.k-command{background:#1f3d2a;color:var(--gn)}.k-hook{background:#3d2f1f;color:var(--yl)}
+.sc{background:var(--panel2);border:1px solid var(--bd);color:var(--mut)}
+.eff-b{background:#16341f;color:var(--gn)}
+.preview{margin-top:8px;background:var(--bg);border:1px solid var(--bd);border-radius:6px;
+padding:8px 10px;color:var(--mut);font-size:11.5px;white-space:pre-wrap;
+max-height:160px;overflow:auto;display:none}
+.card.open .preview{display:block}
+.toggle{cursor:pointer;color:var(--ac);font-size:11px;background:none;border:none;padding:0;margin-top:6px}
+.grp{color:var(--mut);font-size:11px;text-transform:uppercase;letter-spacing:.5px;margin:18px 0 8px}
+.empty{color:var(--mut);padding:24px;text-align:center}
+.eventbar{display:flex;gap:6px;flex-wrap:wrap;margin-bottom:14px}
+.event{background:#3d2f1f;color:var(--yl);border-radius:5px;padding:2px 9px;font-size:11.5px}
+"""
+
+INVENTORY_SCRIPT = """
+const search=document.querySelector('.search');
+if(search){
+  search.addEventListener('input',()=>{
+    const q=search.value.toLowerCase().trim();
+    document.querySelectorAll('.card[data-s]').forEach(c=>{
+      c.style.display=(!q||c.dataset.s.includes(q))?'':'none';
+    });
+  });
+}
+"""

capdisc/scope/inventory/capture.py

@@ -0,0 +1,219 @@
+"""The capture engine: scans artifact locations into `CapturedArtifact` records, parses each
+capture's hook config, and resolves the effective (collision-winning) set."""
+
+from __future__ import annotations
+
+from pydantic import JsonValue, ValidationError
+
+from ...base import FrozenModel, InputModel
+from ...frontmatter import read_frontmatter
+from ...hooks import HookConfig
+from ..locations import Artifact, Location
+from ..types import (
+    ArtifactContents,
+    ArtifactKind,
+    ArtifactName,
+    ArtifactPath,
+    ResolutionMode,
+    ResolutionRank,
+    ScopeKind,
+    Shareability,
+)
+from .roots import ScanRoot, ScopeRoots, artifact_kinds
+
+
+class CapturedArtifact(FrozenModel):
+    """One definition found on disk: its placement, exact path, contents, and resolution rank."""
+
+    kind: ArtifactKind
+    scope: ScopeKind
+    shareable: Shareability
+    resolution: ResolutionMode
+    name: ArtifactName
+    path: ArtifactPath
+    contents: ArtifactContents
+    precedence: ResolutionRank
+
+
+class _WrappedHooks(InputModel):
+    """A plugin hooks.json body: the event map under a `hooks` key (description etc. ignored)."""
+
+    hooks: JsonValue = None
+
+
+def parse_hooks(captured: CapturedArtifact) -> HookConfig | None:
+    """Parse a captured hook artifact into a typed `HookConfig`.
+
+    Ingest is fail-soft: a config using an event, handler type, or structure newer than we model
+    skips rather than crashing the scan — unknown *fields* are already tolerated by
+    `FrozenWireModel`, so this only trips on shape we cannot represent at all.
+
+    Args:
+        captured: A captured hook artifact; its contents are a settings.json `hooks` slice
+            (the bare event map) or a plugin hooks.json (that same map under a `hooks` key).
+
+    Returns:
+        The typed config, or None if it cannot be parsed.
+    """
+    try:
+        return HookConfig.model_validate_json(captured.contents)
+    except ValidationError:
+        pass
+    try:
+        wrapped = _WrappedHooks.model_validate_json(captured.contents).hooks
+        return None if wrapped is None else HookConfig.model_validate(wrapped)
+    except ValidationError:
+        return None
+
+
+def _frontmatter_hooks_value(text: str) -> JsonValue | None:
+    """The `hooks` value from a markdown file's frontmatter, or None if absent or not a mapping."""
+    data = read_frontmatter(text)
+    return None if data is None else data.get("hooks")
+
+
+def parse_frontmatter_hooks(captured: CapturedArtifact) -> HookConfig | None:
+    """Parse the hooks a host agent or skill declares in its frontmatter.
+
+    These are the component-scope hooks, active while their host is. Fail-soft like `parse_hooks`.
+
+    Args:
+        captured: A captured agent or skill artifact whose frontmatter may declare `hooks`.
+
+    Returns:
+        The typed config, or None if it declares none or they cannot be parsed.
+    """
+    hooks = _frontmatter_hooks_value(captured.contents)
+    if hooks is None:
+        return None
+    try:
+        return HookConfig.model_validate(hooks)
+    except ValidationError:
+        return None
+
+
+def _ranked_roots(artifact: Artifact, roots: list[ScanRoot]) -> list[ScanRoot]:
+    """The scan roots an artifact loads from, ordered by its own precedence.
+
+    Roots are keyed by the artifact's scope order, then by scan position so a nearer project dir
+    outranks a farther one. Position in the result is the collision rank (0 wins).
+
+    Args:
+        artifact: The artifact descriptor whose scope order and kind-filter apply.
+        roots: All scan roots to filter and rank.
+
+    Returns:
+        The applicable roots, highest precedence first; roots whose scope the artifact has no
+        location for (e.g. a managed dir for a command), or whose `kinds` exclude it, are dropped.
+    """
+    order = {location.scope: index for index, location in enumerate(artifact.locations)}
+    ranked = [
+        (position, root)
+        for position, root in enumerate(roots)
+        if root.scope in order and (root.kinds is None or artifact.kind in root.kinds)
+    ]
+    ranked.sort(key=lambda pair: (order[pair[1].scope], pair[0]))
+    return [root for _, root in ranked]
+
+
+class ScopeInventory(FrozenModel):
+    """A single snapshot of every definition across every scanned location — the concrete
+    grounding of the abstract location taxonomy. One instance holds the lot."""
+
+    artifacts: list[CapturedArtifact] = []
+
+    @staticmethod
+    def _scan_artifact(artifact: Artifact, roots: ScopeRoots) -> list[CapturedArtifact]:
+        """Capture every on-disk definition for one artifact descriptor.
+
+        A scope can hold more than one location (a hook lives in both `settings.json` and
+        `settings.local.json`), so every location for the matched scope is scanned, not just one.
+
+        Args:
+            artifact: The artifact descriptor to scan for.
+            roots: The scan roots to look under.
+
+        Returns:
+            Every capture found, each carrying its location's scope/shareability and the
+            artifact's collision rank.
+        """
+        by_scope: dict[ScopeKind, list[Location]] = {}
+        for location in artifact.locations:
+            by_scope.setdefault(location.scope, []).append(location)
+
+        captured: list[CapturedArtifact] = []
+        for precedence, root in enumerate(_ranked_roots(artifact, roots.roots)):
+            for location in by_scope[root.scope]:
+                captured.extend(
+                    CapturedArtifact(
+                        kind=artifact.kind,
+                        scope=location.scope,
+                        shareable=location.shareable,
+                        resolution=artifact.resolution,
+                        name=hit.name,
+                        path=hit.path,
+                        contents=hit.contents,
+                        precedence=precedence,
+                    )
+                    for hit in location.storage.discover(root.base)
+                )
+
+        return captured
+
+    @property
+    def hook_configs(self) -> list[HookConfig]:
+        """Every hook config in effect across the snapshot: settings/plugin `hooks` entries plus
+        those declared in an agent's or skill's frontmatter. Unparseable captures are skipped.
+
+        Reads from `effective`, not `artifacts` — an agent or skill shadowed by a
+        higher-precedence same-named capture never loads, so its frontmatter hooks never run."""
+        configs: list[HookConfig] = []
+        for captured in self.effective:
+            if captured.kind is ArtifactKind.hook:
+                config = parse_hooks(captured)
+            elif captured.kind in (ArtifactKind.agent, ArtifactKind.skill):
+                config = parse_frontmatter_hooks(captured)
+            else:
+                config = None
+            if config is not None:
+                configs.append(config)
+        return configs
+
+    @property
+    def effective(self) -> list[CapturedArtifact]:
+        """What takes effect: for each name-collision (kind, name) the lowest-rank capture, plus
+        every additive capture (hooks) unchanged. A plain property — derived from the precedence
+        rank on each capture, so it is order-independent rather than relying on scan order."""
+        best: dict[tuple[ArtifactKind, ArtifactName], CapturedArtifact] = {}
+        additive: list[CapturedArtifact] = []
+        for captured in self.artifacts:
+            if captured.resolution is ResolutionMode.additive:
+                additive.append(captured)
+                continue
+            identity = (captured.kind, captured.name)
+            current = best.get(identity)
+            if current is None or captured.precedence < current.precedence:
+                best[identity] = captured
+        return list(best.values()) + additive
+
+    @classmethod
+    def scan(cls, roots: ScopeRoots) -> ScopeInventory:
+        """Scan every artifact's locations under `roots` into one snapshot.
+
+        Walks each artifact's locations under every applicable root, dispatching to each storage
+        shape's `discover`. Each capture's rank is its position in that artifact's own precedence
+        order, so the right scope wins per kind (skills rank user over project, subagents the
+        reverse) and nearer project dirs win on collision.
+
+        Args:
+            roots: The scan roots, as resolved by `ScopeRoots.discover`.
+
+        Returns:
+            The inventory snapshot of every captured artifact.
+        """
+        captured = [
+            capture
+            for artifact in artifact_kinds()
+            for capture in cls._scan_artifact(artifact, roots)
+        ]
+        return cls(artifacts=captured)