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

capdisc/report/components.py

@@ -0,0 +1,144 @@
+"""Per-plugin component inventory and token-cost estimation."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import TypeAdapter, ValidationError, computed_field
+
+from ..base import FrozenModel, InputModel
+from ..catalog import CatalogMcpServer
+from ..frontmatter import read_frontmatter
+from ..html import e
+from ..scope import ArtifactKind, CapturedArtifact, ScopeInventory
+from ..tokens import TokenCount, estimate_tokens
+from .html import group_label
+from .models import IndexedPlugin
+from .types import ComponentCount
+
+GroupName = Literal["Skills", "Agents", "Hooks", "MCP servers"]
+
+
+class _Frontmatter(InputModel):
+    """Just the description from an artifact's frontmatter — the part that loads every session."""
+
+    description: str | None = None
+
+
+_FRONTMATTER: TypeAdapter[_Frontmatter] = TypeAdapter(_Frontmatter)
+
+
+def _description_tokens(contents: str) -> int:
+    """The always-on cost of one artifact: the tokens of its frontmatter description (what loads
+    into every session), or 0 when it declares none."""
+    data = read_frontmatter(contents)
+    if data is None:
+        return 0
+    try:
+        return estimate_tokens(_FRONTMATTER.validate_python(data).description or "")
+    except ValidationError:
+        return 0
+
+
+class ComponentGroup(FrozenModel):
+    """One component group a plugin contributes — its count and estimated token cost split into
+    always-on (loaded every session) and on-demand (loaded only when a component is invoked)."""
+
+    name: GroupName
+    count: ComponentCount
+    always_on_tokens: TokenCount
+    on_demand_tokens: TokenCount
+
+
+class PluginComponents(FrozenModel):
+    """A plugin's component inventory: the per-group counts and token estimates."""
+
+    groups: list[ComponentGroup]
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def total_always_on(self) -> TokenCount:
+        """Tokens this plugin adds to every session — the sum of its groups' always-on cost."""
+        return sum(group.always_on_tokens for group in self.groups)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def total_on_demand(self) -> TokenCount:
+        """Tokens loaded only when this plugin's components are invoked."""
+        return sum(group.on_demand_tokens for group in self.groups)
+
+
+def _capture_group(name: GroupName, captures: list[CapturedArtifact]) -> ComponentGroup:
+    """A group from captured artifacts: always-on is each one's frontmatter description, on-demand
+    is its full body."""
+    return ComponentGroup(
+        name=name,
+        count=len(captures),
+        always_on_tokens=sum(_description_tokens(c.contents) for c in captures),
+        on_demand_tokens=sum(estimate_tokens(c.contents) for c in captures),
+    )
+
+
+def _mcp_group(servers: list[CatalogMcpServer]) -> ComponentGroup:
+    """The MCP-servers group: always-on is each server's tool names (what a deferred-tool setup
+    loads), on-demand is each tool's full serialized schema (loaded when fetched)."""
+    names = sum(estimate_tokens(" ".join(t.name for t in s.tools)) for s in servers)
+    schemas = sum(estimate_tokens(t.model_dump_json()) for s in servers for t in s.tools)
+    return ComponentGroup(
+        name="MCP servers", count=len(servers), always_on_tokens=names, on_demand_tokens=schemas
+    )
+
+
+def plugin_components(
+    plugin: IndexedPlugin, inventory: ScopeInventory, mcp_servers: list[CatalogMcpServer]
+) -> PluginComponents:
+    """The component inventory one plugin contributes, grouped and token-costed.
+
+    Components are attributed by install directory: a captured artifact belongs to the plugin when
+    its path sits under the plugin's install path. Skills and commands fold into one "Skills" group
+    (the user-facing grouping); agents and hooks each get their own; MCP servers are the plugin's
+    declared servers found in the harvest.
+
+    Args:
+        plugin: The plugin and its install directory.
+        inventory: The full disk inventory; its captures are attributed by path.
+        mcp_servers: The harvested MCP servers, matched to the plugin's declared refs.
+
+    Returns:
+        The grouped, token-costed component inventory.
+    """
+    owned = [c for c in inventory.artifacts if plugin.path in c.path.parents]
+    skills = [c for c in owned if c.kind in (ArtifactKind.skill, ArtifactKind.command)]
+    agents = [c for c in owned if c.kind is ArtifactKind.agent]
+    hooks = [c for c in owned if c.kind is ArtifactKind.hook]
+    servers = [s for s in mcp_servers if s.ref in plugin.card.mcp_servers]
+    return PluginComponents(
+        groups=[
+            _capture_group("Skills", skills),
+            _capture_group("Agents", agents),
+            _capture_group("Hooks", hooks),
+            _mcp_group(servers),
+        ]
+    )
+
+
+def components_block(components: PluginComponents) -> str:
+    """The component-cost block appended inside a plugin card: a clean per-group table of counts
+    and token estimates, with a totals row."""
+    rows = "".join(
+        f"<tr><td>{e(g.name)}</td><td class='num'>{e(g.count)}</td>"
+        f"<td class='num'>~{e(g.always_on_tokens)}</td>"
+        f"<td class='num'>~{e(g.on_demand_tokens)}</td></tr>"
+        for g in components.groups
+    )
+    total = (
+        "<tr class='total'><td>Total</td><td class='num'></td>"
+        f"<td class='num'>~{e(components.total_always_on)}</td>"
+        f"<td class='num'>~{e(components.total_on_demand)}</td></tr>"
+    )
+    return (
+        group_label("context cost") + "<div class='tblwrap'><table class='tbl'><thead><tr>"
+        "<th>component</th><th class='num'>count</th>"
+        "<th class='num'>tok/session</th><th class='num'>on-demand</th>"
+        f"</tr></thead><tbody>{rows}{total}</tbody></table></div>"
+    )

capdisc/report/harvest.py

@@ -0,0 +1,150 @@
+"""The impure harvest: scans this machine into an `EnvironmentReport` and persists it."""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+
+from ..catalog import CatalogMcpServer
+from ..discovery import BUILTIN_TOOLS, scan_indexed_skills
+from ..mcp_catalog import enumerate_mcp_servers
+from ..mcp_harvest import cache_is_stale, read_mcp_cache, refresh_mcp_cache
+from ..plugin_catalog import enumerate_plugins_with_paths, installed_plugin_dirs
+from ..scope import ScopeInventory, ScopeRoots, default_managed_dir
+from ..settings import get_settings
+from .models import EnvironmentReport, IndexedPlugin, IndexedSkill, McpSource
+from .page import render_environment_html
+
+logger = logging.getLogger(__name__)
+
+REPORT_JSON_NAME = "discovery-report.json"
+REPORT_HTML_NAME = "discovery-report.html"
+
+_MCP_SOURCE_CACHE: McpSource = "tool-enriched cache"
+_MCP_SOURCE_FRESH: McpSource = "fresh harvest"
+_MCP_SOURCE_STALE: McpSource = "stale cache (refresh failed)"
+_MCP_SOURCE_LIVE: McpSource = "live (claude mcp list)"
+
+
+def _harvest_mcp_servers(oauth: bool = False) -> tuple[list[CatalogMcpServer], McpSource]:
+    """Return the MCP server cards and the source they came from.
+
+    Fresh cache → use it. Stale or missing cache → synchronous refresh (this runs in a
+    short-lived CLI process, so a background thread would die before finishing). Refresh
+    failure → the stale cache if any, else the unenriched live listing. `oauth` always
+    refreshes — the point of passing it is to reach servers the cached run could not.
+    """
+    cached = read_mcp_cache()
+    if cached and not cache_is_stale() and not oauth:
+        return cached, _MCP_SOURCE_CACHE
+    try:
+        return refresh_mcp_cache(oauth=oauth), _MCP_SOURCE_FRESH
+    except Exception:
+        logger.exception("MCP cache refresh failed")
+    if cached:
+        return cached, _MCP_SOURCE_STALE
+    return enumerate_mcp_servers(), _MCP_SOURCE_LIVE
+
+
+def build_report(oauth: bool = False) -> EnvironmentReport:
+    """Scan this machine's discovery surface into one `EnvironmentReport`.
+
+    Runs exactly what the runtime runs — scope discovery, the disk inventory, the skill index,
+    the built-in tools, the plugin catalog, and the MCP harvest (cache first, live fallback).
+
+    Args:
+        oauth: Allow the interactive OAuth flow for HTTP MCP servers with a pre-registered
+            client (settings `mcp_oauth_clients`); forces a fresh harvest. Never set this on
+            a background path — it may open a browser.
+
+    Returns:
+        The gathered harvest, ready to render or persist.
+    """
+    cwd = Path.cwd()
+    home = Path.home()
+    managed_dir = default_managed_dir()
+    plugins_root = get_settings().plugins_root
+    plugin_dirs = installed_plugin_dirs(plugins_root)
+    roots = ScopeRoots.discover(
+        start=cwd,
+        home_dir=home,
+        managed_dir=managed_dir,
+        plugin_dirs=plugin_dirs,
+    )
+    inventory = ScopeInventory.scan(roots)
+    skills = [IndexedSkill(card=card, path=path) for card, path in scan_indexed_skills(roots)]
+    plugins = [
+        IndexedPlugin(card=card, path=path)
+        for card, path in enumerate_plugins_with_paths(plugins_root)
+    ]
+    mcp_servers, mcp_source = _harvest_mcp_servers(oauth)
+    return EnvironmentReport(
+        generated_at=datetime.now(UTC),
+        cwd=cwd,
+        home=home,
+        plugins_root=plugins_root,
+        managed_dir=managed_dir,
+        mcp_source=mcp_source,
+        scan_roots=roots.roots,
+        plugin_dirs=plugin_dirs,
+        inventory=inventory,
+        skills=skills,
+        builtin_tools=BUILTIN_TOOLS,
+        plugins=plugins,
+        mcp_servers=mcp_servers,
+    )
+
+
+def write_report(
+    report: EnvironmentReport,
+    *,
+    json_path: Path | None = None,
+    html_path: Path | None = None,
+) -> None:
+    """Persist a report as both its JSON snapshot and its rendered HTML.
+
+    Args:
+        report: The report to persist.
+        json_path: Destination for the machine-readable snapshot; parent dirs are created.
+            Under the settings' `report_dir` when None.
+        html_path: Destination for the rendered document; parent dirs are created.
+            Under the settings' `report_dir` when None.
+    """
+    json_path = (
+        json_path if json_path is not None else get_settings().report_dir / REPORT_JSON_NAME
+    )
+    html_path = (
+        html_path if html_path is not None else get_settings().report_dir / REPORT_HTML_NAME
+    )
+    # The report can embed raw scanned file contents (e.g. a hook's command string), so its
+    # directory is kept private the same way mcp_harvest.auth.ensure_private_dir locks down
+    # the OAuth token store — mkdir(mode=...) alone only applies to a dir it newly creates.
+    for parent in {json_path.parent, html_path.parent}:
+        parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        parent.chmod(0o700)
+    json_path.write_text(report.model_dump_json(indent=2), encoding="utf-8")
+    html_path.write_text(render_environment_html(report), encoding="utf-8")
+
+
+def write_report_on_start() -> EnvironmentReport | None:
+    """Build and persist the discovery report to the default paths, best-effort.
+
+    Called from always-on startup paths, so it never raises or blocks — any failure is logged and
+    swallowed. Local writes only; no network, no threads.
+
+    Returns:
+        The built report (so a caller can also stash it, e.g. to serve it), or None when the build
+        failed. A write failure is logged but does not affect the return value — the report is
+        still returned so a caller can serve it even when the on-disk copy is stale or missing.
+    """
+    try:
+        report = build_report()
+    except Exception:
+        logger.exception("discovery report generation failed")
+        return None
+    try:
+        write_report(report)
+    except Exception:
+        logger.exception("discovery report write failed")
+    return report

capdisc/report/html.py

@@ -0,0 +1,79 @@
+"""HTML-fragment builders shared by the report's card and section renderers.
+
+Every dynamic value passed through `e` is escaped, so callers never need to escape by hand.
+"""
+
+from __future__ import annotations
+
+from ..html import e, redact_home
+from ..scope import ArtifactKind
+
+CLASS_SKILL = "k-skill"
+_CLASS_AGENT = "k-agent"
+_CLASS_COMMAND = "k-command"
+_CLASS_HOOK = "k-hook"
+CLASS_TOOL = "k-tool"
+CLASS_MCP = "k-mcp_server"
+
+
+def ref_span(text: str) -> str:
+    return f'<span class="ref">{e(text)}</span>'
+
+
+def id_span(text: str) -> str:
+    return f'<span class="id">{e(text)}</span>'
+
+
+def desc_block(text: str) -> str:
+    return f'<div class="desc">{e(text)}</div>'
+
+
+def path_block(value: object) -> str:
+    return f'<div class="path">{e(redact_home(value))}</div>'
+
+
+def row_block(inner: str) -> str:
+    return f'<div class="row">{inner}</div>'
+
+
+def group_label(label: str) -> str:
+    return f'<div class="grp">{e(label)}</div>'
+
+
+def empty_block(label: str) -> str:
+    return f'<div class="empty">{e(label)}</div>'
+
+
+def kv_line(label: str, value: object) -> str:
+    return f'<div class="path"><b>{e(label)}:</b> {e(redact_home(value))}</div>'
+
+
+def stat_block(n: object, label: str) -> str:
+    return f'<div class="stat"><div class="n">{e(n)}</div><div class="l">{e(label)}</div></div>'
+
+
+def tag_chips(items: list[str]) -> str:
+    if not items:
+        return ""
+    chips = "".join(f'<span class="tag">{e(t)}</span>' for t in items)
+    return f'<div class="tags">{chips}</div>'
+
+
+def search_key(*parts: object) -> str:
+    return e(" ".join(str(p) for p in parts if p).lower())
+
+
+def card_block(search: str, inner: str, extra_class: str = "") -> str:
+    return f'<div class="card {extra_class}" data-s="{search}">{inner}</div>'
+
+
+def kind_class(kind: ArtifactKind) -> str:
+    match kind:
+        case ArtifactKind.skill:
+            return CLASS_SKILL
+        case ArtifactKind.agent:
+            return _CLASS_AGENT
+        case ArtifactKind.command:
+            return _CLASS_COMMAND
+        case ArtifactKind.hook:
+            return _CLASS_HOOK

capdisc/report/models.py

@@ -0,0 +1,82 @@
+"""The report's own typed models: the machine-readable snapshot and its indexed-artifact pairs."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Literal
+
+from ..base import FrozenModel
+from ..catalog import CatalogMcpServer, CatalogPlugin, CatalogSkill, CatalogTool
+from ..scope import ScanRoot, ScopeInventory
+
+McpSource = Literal[
+    "tool-enriched cache", "fresh harvest", "stale cache (refresh failed)", "live (claude mcp list)"
+]
+
+
+class IndexedSkill(FrozenModel):
+    """One indexed skill card paired with the SKILL.md path it was loaded from."""
+
+    card: CatalogSkill
+    path: Path
+
+
+class IndexedPlugin(FrozenModel):
+    """One plugin card paired with its install directory — the directory the plugin's bundled
+    agents/skills/commands/hooks are captured under, so its components can be attributed to it."""
+
+    card: CatalogPlugin
+    path: Path
+
+
+class EnvironmentReport(FrozenModel):
+    """The full discovery harvest of one machine, composed of the existing typed models. The
+    machine-readable snapshot the renderer draws from — round-trips through Pydantic JSON, so it
+    can be persisted and served as-is. Effective set and hook events are derived from `inventory`
+    at render time, not stored."""
+
+    generated_at: datetime
+    cwd: Path
+    home: Path
+    plugins_root: Path
+    managed_dir: Path | None
+    mcp_source: McpSource
+    scan_roots: list[ScanRoot]
+    plugin_dirs: list[Path]
+    inventory: ScopeInventory
+    skills: list[IndexedSkill]
+    builtin_tools: list[CatalogTool]
+    plugins: list[IndexedPlugin]
+    mcp_servers: list[CatalogMcpServer]
+
+    @property
+    def skill_count(self) -> int:
+        """Not a `computed_field`: it would round-trip into the persisted JSON as an `extra`
+        key that `model_validate_json(model_dump_json())` then rejects under `extra="forbid"`,
+        and it adds no information beyond `len(skills)` a reader can already see."""
+        return len(self.skills)
+
+    @property
+    def tool_count(self) -> int:
+        return len(self.builtin_tools)
+
+    @property
+    def plugin_count(self) -> int:
+        return len(self.plugins)
+
+    @property
+    def mcp_server_count(self) -> int:
+        return len(self.mcp_servers)
+
+    @property
+    def capture_count(self) -> int:
+        return len(self.inventory.artifacts)
+
+    @property
+    def hook_config_count(self) -> int:
+        return len(self.inventory.hook_configs)
+
+    @property
+    def scan_root_count(self) -> int:
+        return len(self.scan_roots)

capdisc/report/page.py

@@ -0,0 +1,129 @@
+"""Page assembly: sections into tabs, tabs into one self-contained HTML document."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from ..base import FrozenModel
+from ..html import e, redact_home
+from .assets import SCRIPT, STYLE
+from .models import EnvironmentReport
+from .sections import (
+    render_inventory_section,
+    render_mcp_section,
+    render_overview_section,
+    render_plugins_section,
+    render_roots_section,
+    render_skills_section,
+    render_tools_section,
+)
+from .types import SectionCount, SectionId, SectionLabel
+
+
+class _Section(FrozenModel):
+    """One tab: its nav id and label, the rendered body, an optional count, and whether it gets a
+    client-side filter box (the overview does not)."""
+
+    id: SectionId
+    label: SectionLabel
+    body: str
+    count: SectionCount | None = None
+    searchable: bool = True
+
+
+def _nav_button(section: _Section) -> str:
+    count = "" if section.count is None else str(section.count)
+    return (
+        f'<button data-v="{e(section.id)}">{e(section.label)}'
+        f'<span class="cnt">{e(count)}</span></button>'
+    )
+
+
+def _section_html(section: _Section) -> str:
+    search = (
+        f'<input class="search" placeholder="filter {e(section.label.lower())}…">'
+        if section.searchable
+        else ""
+    )
+    return f'<section class="section" id="sec-{e(section.id)}">{search}{section.body}</section>'
+
+
+def _page(sections: list[_Section], generated: datetime, cwd: Path) -> str:
+    nav = "".join(_nav_button(s) for s in sections)
+    main = "".join(_section_html(s) for s in sections)
+    return (
+        '<!doctype html><html lang="en"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        "<title>capdisc · discovery report</title>"
+        f"<style>{STYLE}</style></head><body>"
+        "<header><h1>capdisc · discovery report</h1>"
+        '<div class="meta">what the engine harvests from this machine · generated '
+        f"<b>{e(generated.isoformat(timespec='seconds'))}</b> · "
+        f"<b>{e(redact_home(cwd))}</b></div></header>"
+        f'<div class="layout"><nav>{nav}</nav><main>{main}</main></div>'
+        '<div id="backdrop"></div>'
+        '<div id="drawer"><div class="dhead"><span class="dtitle"></span>'
+        '<button class="dclose" aria-label="close">&times;</button></div>'
+        '<div class="dbody"></div></div>'
+        f"<script>{SCRIPT}</script></body></html>"
+    )
+
+
+def render_environment_html(report: EnvironmentReport) -> str:
+    """Render an `EnvironmentReport` as one self-contained HTML document.
+
+    Pure over the snapshot: every dynamic value comes from `report` and is escaped. Existence of
+    each scan root is read from disk as it is rendered.
+
+    Args:
+        report: The gathered harvest, as produced by `build_report`.
+
+    Returns:
+        A complete `<!doctype html>` page with inline styles and script and no external resources.
+    """
+    sections = [
+        _Section(
+            id="overview",
+            label="Overview",
+            body=render_overview_section(report),
+            searchable=False,
+        ),
+        _Section(
+            id="roots",
+            label="Scan roots",
+            body=render_roots_section(report.scan_roots, report.plugin_dirs),
+            count=report.scan_root_count,
+        ),
+        _Section(
+            id="inventory",
+            label="Disk inventory",
+            body=render_inventory_section(report.inventory),
+            count=report.capture_count,
+        ),
+        _Section(
+            id="skills",
+            label="Skills",
+            body=render_skills_section(report.skills),
+            count=report.skill_count,
+        ),
+        _Section(
+            id="tools",
+            label="Builtin tools",
+            body=render_tools_section(report.builtin_tools),
+            count=report.tool_count,
+        ),
+        _Section(
+            id="plugins",
+            label="Plugins",
+            body=render_plugins_section(report.plugins, report.inventory, report.mcp_servers),
+            count=report.plugin_count,
+        ),
+        _Section(
+            id="mcp",
+            label="MCP servers",
+            body=render_mcp_section(report.mcp_servers),
+            count=report.mcp_server_count,
+        ),
+    ]
+    return _page(sections, report.generated_at, report.cwd)