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

capdisc/plugin_catalog.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import Field, TypeAdapter, ValidationError
+
+from .base import InputModel
+from .catalog import CatalogPlugin, McpServerRef, PluginRef, SkillRef, Tag, catalog_id
+from .discovery import skill_ref
+from .mcp_catalog import SERVER_REF
+
+# one place a plugin name becomes a ref
+_PLUGIN_REF: TypeAdapter[PluginRef] = TypeAdapter(PluginRef)
+_TAG: TypeAdapter[Tag] = TypeAdapter(Tag)  # one place a keyword becomes a tag
+_INSTALLED = "installed_plugins.json"
+_MANIFEST = ".claude-plugin/plugin.json"
+_MCP_CONFIG = ".mcp.json"
+_MCP_WRAPPER_KEY = "mcpServers"
+
+
+class _PluginManifest(InputModel):
+    """The `.claude-plugin/plugin.json` of one installed plugin — name, description, keywords."""
+
+    name: str | None = None
+    description: str | None = None
+    keywords: list[str] = []
+
+
+class _InstalledEntry(InputModel):
+    install_path: Path | None = Field(default=None, alias="installPath")
+
+
+class _InstalledPlugins(InputModel):
+    """The `installed_plugins.json` registry: each `name@marketplace` key maps to its installs."""
+
+    plugins: dict[str, list[_InstalledEntry]] = {}
+
+
+class _OpaqueServer(InputModel):
+    """One `.mcp.json` server entry, modeled empty: `InputModel` is `extra="ignore"`, so validation
+    parses and drops the command/url/headers/credentials. Only the name (map key) survives."""
+
+
+class _McpConfig(InputModel):
+    """The `mcpServers`-wrapped `.mcp.json` shape; the flat shape is that same map at top level."""
+
+    mcpServers: dict[str, _OpaqueServer] = {}
+
+
+_INSTALLED_ADAPTER = TypeAdapter(_InstalledPlugins)
+_MANIFEST_ADAPTER = TypeAdapter(_PluginManifest)
+_MCP_WRAPPED_ADAPTER = TypeAdapter(_McpConfig)
+_MCP_FLAT_ADAPTER = TypeAdapter(dict[str, _OpaqueServer])
+
+
+def _first_install_path(installs: list[_InstalledEntry]) -> Path | None:
+    """Pick a plugin's install directory from its registry records.
+
+    Args:
+        installs: A plugin's install records; a registry can list several and some carry no path.
+
+    Returns:
+        The first record's install directory, or None if none carries one.
+    """
+    return next((entry.install_path for entry in installs if entry.install_path), None)
+
+
+def _skill_refs(install_path: Path) -> list[SkillRef]:
+    """Derive the skill refs a plugin bundles from its `skills/*/SKILL.md` files.
+
+    Derived the same way the skill index derives them, so these refs join to the plugin's
+    `CatalogSkill` entries.
+
+    Args:
+        install_path: The plugin's install directory; its `skills/` tree is walked.
+
+    Returns:
+        The bundled skill refs, de-duplicated in first-seen order.
+    """
+    refs: list[SkillRef] = []
+    for skill_md in sorted((install_path / "skills").rglob("SKILL.md")):
+        ref = skill_ref(skill_md)
+        if ref and ref not in refs:
+            refs.append(ref)
+    return refs
+
+
+def _mcp_refs(install_path: Path) -> list[McpServerRef]:
+    """Derive the MCP server refs a plugin declares in its `.mcp.json`.
+
+    Only the server names (keys) are kept; `_OpaqueServer` drops the values, so a
+    command/URL/credential never lands on a card. The file comes in two shapes — a `mcpServers`
+    wrapper or the servers map at the top level — so the wrapper is tried first, falling back to
+    the flat map.
+
+    Args:
+        install_path: The plugin's install directory holding `.mcp.json`.
+
+    Returns:
+        The declared server refs, de-duplicated in first-seen order; `[]` if the file is absent,
+        unparseable, or holds no valid names.
+    """
+    try:
+        raw = (install_path / _MCP_CONFIG).read_text(encoding="utf-8")
+    except OSError:
+        return []
+    try:
+        servers = _MCP_WRAPPED_ADAPTER.validate_json(
+            raw
+        ).mcpServers or _MCP_FLAT_ADAPTER.validate_json(raw)
+    except ValidationError:
+        return []
+    refs: list[McpServerRef] = []
+    for name in servers:
+        if name == _MCP_WRAPPER_KEY:
+            continue
+        try:
+            ref = SERVER_REF.validate_python(name)
+        except ValidationError:
+            continue
+        if ref not in refs:
+            refs.append(ref)
+    return refs
+
+
+def _tags(keywords: list[str]) -> list[Tag]:
+    """Fold a plugin's keywords into valid `Tag`s for lexical recall.
+
+    Each keyword goes through the `Tag` normalizer, the one slug owner.
+
+    Args:
+        keywords: The plugin's declared keywords.
+
+    Returns:
+        The normalized tags, de-duplicated in first-seen order, dropping any that don't survive
+        slugging.
+    """
+    out: list[Tag] = []
+    for kw in keywords:
+        try:
+            tag = _TAG.validate_python(kw)
+        except ValidationError:
+            continue
+        if tag not in out:
+            out.append(tag)
+    return out
+
+
+def _plugin_card(
+    plugin_key: str, manifest: _PluginManifest, install_path: Path
+) -> CatalogPlugin | None:
+    """Build one plugin card, including the skills and MCP servers it bundles.
+
+    Args:
+        plugin_key: The registry key `name@marketplace`; the marketplace suffix is dropped (and
+            the `name` field preferred over it) so the ref is the bare plugin name.
+        manifest: The plugin's parsed manifest; a plugin with no description is skipped.
+        install_path: The plugin's install directory, scanned for bundled skills and servers.
+
+    Returns:
+        The card, or None when the manifest has no description or the fields don't validate.
+    """
+    if not manifest.description:
+        return None
+    try:
+        ref = _PLUGIN_REF.validate_python(manifest.name or plugin_key.split("@", 1)[0])
+        return CatalogPlugin(
+            id=catalog_id("plugin", ref),
+            ref=ref,
+            description=manifest.description,
+            tags=_tags(manifest.keywords),
+            skills=_skill_refs(install_path),
+            mcp_servers=_mcp_refs(install_path),
+        )
+    except ValidationError:
+        return None
+
+
+def _read_manifest(install_path: Path) -> _PluginManifest | None:
+    """Read one plugin's `.claude-plugin/plugin.json` manifest.
+
+    Args:
+        install_path: The plugin's install directory.
+
+    Returns:
+        The parsed manifest, or None when the file is missing or unparseable.
+    """
+    try:
+        raw = (install_path / _MANIFEST).read_text(encoding="utf-8")
+    except OSError:
+        return None
+    try:
+        return _MANIFEST_ADAPTER.validate_json(raw)
+    except ValidationError:
+        return None
+
+
+def _read_registry(plugins_root: Path) -> _InstalledPlugins | None:
+    """Read the installed-plugins registry.
+
+    Args:
+        plugins_root: Root holding `installed_plugins.json`.
+
+    Returns:
+        The parsed registry, or None when the file is missing or unparseable.
+    """
+    try:
+        raw = (plugins_root / _INSTALLED).read_text(encoding="utf-8")
+    except OSError:
+        return None
+    try:
+        return _INSTALLED_ADAPTER.validate_json(raw)
+    except ValidationError:
+        return None
+
+
+def installed_plugins(plugins_root: Path) -> dict[str, Path]:
+    """Map each installed plugin to its install directory.
+
+    The source for reading a plugin's bundled config (e.g. its `.mcp.json`).
+
+    Args:
+        plugins_root: Root holding `installed_plugins.json`.
+
+    Returns:
+        `{name@marketplace: install_dir}`, omitting plugins whose records carry no path; `{}`
+        when the registry is missing.
+    """
+    registry = _read_registry(plugins_root)
+    if registry is None:
+        return {}
+    found: dict[str, Path] = {}
+    for key, installs in registry.plugins.items():
+        install_path = _first_install_path(installs)
+        if install_path is not None:
+            found[key] = install_path
+    return found
+
+
+def installed_plugin_dirs(plugins_root: Path) -> list[Path]:
+    """List every plugin install directory, for `ScopeRoots.discover(plugin_dirs=…)`.
+
+    Feeds the scan so plugin-bundled skills are indexed. These are scan roots only — never
+    indexed into a card, since an install path is a local absolute path.
+
+    Args:
+        plugins_root: Root holding `installed_plugins.json`.
+
+    Returns:
+        The install directories, de-duplicated in first-seen order.
+    """
+    seen: list[Path] = []
+    for path in installed_plugins(plugins_root).values():
+        if path not in seen:
+            seen.append(path)
+    return seen
+
+
+def enumerate_plugins_with_paths(plugins_root: Path) -> list[tuple[CatalogPlugin, Path]]:
+    """Enumerate installed plugins as catalog cards, paired with the install directory each was
+    built from.
+
+    The install path a card actually came from — not re-derived later by matching the card's
+    ref back against the registry keys, which can mismatch (and silently drop the plugin) when a
+    plugin's manifest `name` differs from its registry key.
+
+    Args:
+        plugins_root: Root holding `installed_plugins.json`.
+
+    Returns:
+        One `(card, install_path)` per plugin with a usable manifest, de-duplicated by id; `[]`
+        if the registry is missing or unreadable.
+    """
+    registry = _read_registry(plugins_root)
+    if registry is None:
+        return []
+
+    cards: list[tuple[CatalogPlugin, Path]] = []
+    seen: set[str] = set()
+    for plugin_key, installs in registry.plugins.items():
+        install_path = _first_install_path(installs)
+        if install_path is None:
+            continue
+        manifest = _read_manifest(install_path)
+        if manifest is None:
+            continue
+        card = _plugin_card(plugin_key, manifest, install_path)
+        # dedupe by id, not ref: two distinct refs can still truncate to the same catalog_id
+        if card is None or card.id in seen:
+            continue
+        seen.add(card.id)
+        cards.append((card, install_path))
+    return cards
+
+
+def enumerate_plugins(plugins_root: Path) -> list[CatalogPlugin]:
+    """Enumerate installed plugins as catalog cards.
+
+    Reads each plugin's manifest for its description and keywords. Never executes plugin code.
+
+    Args:
+        plugins_root: Root holding `installed_plugins.json`.
+
+    Returns:
+        One card per plugin with a usable manifest, de-duplicated by ref; `[]` if the registry
+        is missing or unreadable.
+    """
+    return [card for card, _ in enumerate_plugins_with_paths(plugins_root)]

capdisc/report/__init__.py

@@ -0,0 +1,36 @@
+"""Render the full discovery harvest of this machine as one self-contained HTML document.
+
+A developer tool for eyeballing what the discovery layer aggregates — scan roots, the on-disk
+scope inventory, indexed skills, built-in tools, installed plugins, and connected MCP servers —
+not a product feature. `build_report` scans the machine into an `EnvironmentReport` (the
+machine-readable snapshot, which round-trips through Pydantic JSON); `render_environment_html`
+renders that snapshot to HTML. `write_report` persists both; `python -m
+capdisc.report` writes them to the default paths.
+
+All markup is built here in Python and every dynamic value is escaped; the inline JS only toggles
+classes and `style.display` and reads input values, so the page renders untrusted paths and file
+contents safely.
+"""
+
+from __future__ import annotations
+
+from .cli import main
+from .components import ComponentGroup, PluginComponents, plugin_components
+from .harvest import build_report, write_report, write_report_on_start
+from .models import EnvironmentReport, IndexedPlugin, IndexedSkill, McpSource
+from .page import render_environment_html
+
+__all__ = [
+    "ComponentGroup",
+    "EnvironmentReport",
+    "IndexedPlugin",
+    "IndexedSkill",
+    "McpSource",
+    "PluginComponents",
+    "build_report",
+    "main",
+    "plugin_components",
+    "render_environment_html",
+    "write_report",
+    "write_report_on_start",
+]

capdisc/report/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

capdisc/report/assets.py

@@ -0,0 +1,138 @@
+"""Inline CSS and JS for the self-contained HTML report — no external resources."""
+
+from __future__ import annotations
+
+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}
+code,.mono{font-family:ui-monospace,"SF Mono",Menlo,Consolas,monospace}
+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)}
+.layout{display:flex;min-height:calc(100vh - 80px)}
+nav{width:220px;flex:none;border-right:1px solid var(--bd);background:var(--panel);padding:12px;
+position:sticky;top:0;align-self:flex-start;height:calc(100vh - 80px);overflow:auto}
+nav button{display:flex;justify-content:space-between;width:100%;text-align:left;background:none;
+border:none;color:var(--fg);padding:9px 11px;border-radius:7px;cursor:pointer;font-size:13px;
+margin-bottom:2px}
+nav button:hover{background:var(--panel2)}
+nav button.active{background:var(--ac);color:#04111f;font-weight:600}
+nav .cnt{color:var(--mut);font-size:11px}nav button.active .cnt{color:#04111f}
+main{flex:1;padding:20px 24px;overflow:auto}
+.section{display:none}.section.active{display:block}
+.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}
+.desc{color:#c9d1d9;margin:7px 0 0;font-size:13px}
+.path{color:var(--mut);font-size:11.5px;margin-top:6px;word-break:break-all}
+.tags{margin-top:8px;display:flex;gap:5px;flex-wrap:wrap}
+.tag{background:var(--panel2);border:1px solid var(--bd);border-radius:20px;padding:1px 9px;
+font-size:11px;color:var(--cy)}
+.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)}
+.k-tool{background:#3d1f2a;color:#ff7b9c}.k-mcp_server{background:#1f3a3d;color:var(--cy)}
+.sc{background:var(--panel2);border:1px solid var(--bd);color:var(--mut)}
+.eff-b{background:#16341f;color:var(--gn)}
+.toolrow{font-size:12px;padding:6px 0;border-top:1px solid var(--bd)}
+.toolrow:first-child{border-top:none}
+.toolname{color:var(--cy);font-weight:600}.params{color:var(--mut)}
+.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}
+.bigstat{display:flex;gap:14px;flex-wrap:wrap;margin-bottom:18px}
+.stat{background:var(--panel);border:1px solid var(--bd);border-radius:10px;padding:12px 16px;
+min-width:110px}
+.stat .n{font-size:24px;font-weight:700}.stat .l{color:var(--mut);font-size:12px}
+.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}
+.tblwrap{overflow-x:auto;margin-top:8px;-webkit-overflow-scrolling:touch}
+table.tbl{width:100%;border-collapse:collapse;font-size:12px}
+table.tbl th,table.tbl td{text-align:left;padding:5px 9px;border-bottom:1px solid var(--bd);
+vertical-align:top}
+table.tbl th{color:var(--mut);font-weight:600;font-size:10.5px;text-transform:uppercase;
+letter-spacing:.4px;white-space:nowrap}
+table.tbl td.num,table.tbl th.num{text-align:right;font-variant-numeric:tabular-nums;
+white-space:nowrap}
+table.tbl tr:last-child td{border-bottom:none}
+table.tbl tr.total td{border-top:1px solid var(--bd);font-weight:700;color:var(--fg)}
+table.tbl td.toolname{color:var(--cy);font-weight:600;white-space:nowrap}
+.more{cursor:pointer;color:var(--ac);font-size:11.5px;background:none;border:1px solid var(--bd);
+border-radius:6px;padding:3px 11px;margin-top:9px}
+.more:hover{border-color:var(--ac)}
+.popup-src{display:none}
+#backdrop{position:fixed;inset:0;background:rgba(0,0,0,.55);display:none;z-index:40}
+#backdrop.open{display:block}
+#drawer{position:fixed;left:0;right:0;bottom:0;max-height:72vh;background:var(--panel);
+border-top:1px solid var(--bd);border-radius:14px 14px 0 0;box-shadow:0 -10px 34px rgba(0,0,0,.5);
+transform:translateY(101%);transition:transform .22s ease;z-index:50;display:flex;
+flex-direction:column}
+#drawer.open{transform:translateY(0)}
+#drawer .dhead{display:flex;justify-content:space-between;align-items:center;padding:13px 18px;
+border-bottom:1px solid var(--bd)}
+#drawer .dtitle{font-weight:600;font-size:14px}
+#drawer .dclose{cursor:pointer;background:none;border:none;color:var(--mut);font-size:24px;
+line-height:1;padding:0 4px}
+#drawer .dclose:hover{color:var(--fg)}
+#drawer .dbody{overflow:auto;padding:6px 18px 20px}
+@media(max-width:820px){
+  .layout{flex-direction:column;min-height:0}
+  nav{width:auto;height:auto;position:static;border-right:none;
+      border-bottom:1px solid var(--bd);display:flex;flex-wrap:wrap;gap:4px;overflow:visible}
+  nav button{width:auto;margin:0}
+  main{padding:16px}
+  .stat{min-width:88px;flex:1 1 88px}
+  .bigstat{gap:8px}
+}
+"""
+
+SCRIPT = """
+const sections=document.querySelectorAll('.section');
+const navs=document.querySelectorAll('nav button');
+function show(v){
+  sections.forEach(s=>s.classList.toggle('active',s.id==='sec-'+v));
+  navs.forEach(b=>b.classList.toggle('active',b.dataset.v===v));
+}
+navs.forEach(b=>b.addEventListener('click',()=>show(b.dataset.v)));
+document.querySelectorAll('.search').forEach(inp=>{
+  inp.addEventListener('input',()=>{
+    const q=inp.value.toLowerCase().trim();
+    inp.closest('.section').querySelectorAll('.card[data-s]').forEach(c=>{
+      c.style.display=(!q||c.dataset.s.includes(q))?'':'none';
+    });
+  });
+});
+const backdrop=document.getElementById('backdrop');
+const drawer=document.getElementById('drawer');
+const dtitle=drawer.querySelector('.dtitle');
+const dbody=drawer.querySelector('.dbody');
+function closeDrawer(){
+  drawer.classList.remove('open');backdrop.classList.remove('open');dbody.replaceChildren();
+}
+document.querySelectorAll('.more').forEach(btn=>{
+  btn.addEventListener('click',()=>{
+    const src=btn.parentElement.querySelector('.popup-src');
+    dtitle.textContent=btn.dataset.title||'Details';
+    dbody.replaceChildren();
+    if(src){for(const node of src.children)dbody.appendChild(node.cloneNode(true));}
+    drawer.classList.add('open');backdrop.classList.add('open');
+  });
+});
+backdrop.addEventListener('click',closeDrawer);
+drawer.querySelector('.dclose').addEventListener('click',closeDrawer);
+document.addEventListener('keydown',ev=>{if(ev.key==='Escape')closeDrawer();});
+show('overview');
+"""

capdisc/report/cards.py

@@ -0,0 +1,109 @@
+"""Catalog-entry cards, dispatched on the discriminated union."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import assert_never
+
+from ..catalog import (
+    CatalogEntry,
+    CatalogMcpServer,
+    CatalogPlugin,
+    CatalogSkill,
+    CatalogTool,
+    McpTool,
+)
+from ..html import e, pill
+from .components import PluginComponents, components_block
+from .html import (
+    CLASS_MCP,
+    CLASS_SKILL,
+    CLASS_TOOL,
+    card_block,
+    desc_block,
+    id_span,
+    path_block,
+    ref_span,
+    row_block,
+    search_key,
+    tag_chips,
+)
+
+# A tool list longer than this moves out of the card into a bottom drawer, so a server with a
+# large surface (playwright, dq) doesn't blow the card open.
+_TOOLS_INLINE_MAX = 6
+
+
+def _skill_card(skill: CatalogSkill, path: Path | None) -> str:
+    head = pill("skill", CLASS_SKILL) + ref_span(skill.ref) + id_span(skill.id)
+    inner = row_block(head) + desc_block(skill.description) + tag_chips(list(skill.tags))
+    if path is not None:
+        inner += path_block(path)
+    return card_block(search_key(skill.ref, skill.search_text), inner)
+
+
+def _tool_card(tool: CatalogTool) -> str:
+    facets = [pill("read-only" if tool.read_only else "writes")]
+    if tool.needs_network:
+        facets.append(pill("network"))
+    head = pill("tool", CLASS_TOOL) + ref_span(tool.ref) + "".join(facets) + id_span(tool.id)
+    inner = row_block(head) + desc_block(tool.description) + tag_chips(list(tool.tags))
+    return card_block(search_key(tool.ref, tool.search_text), inner)
+
+
+def _tools_table(tools: list[McpTool]) -> str:
+    rows = "".join(
+        f"<tr><td class='toolname'>{e(t.name)}</td>"
+        f"<td class='mono params'>{e(', '.join(t.params))}</td>"
+        f"<td>{e(t.description)}</td></tr>"
+        for t in tools
+    )
+    return (
+        "<div class='tblwrap'><table class='tbl'><thead><tr>"
+        "<th>tool</th><th>params</th><th>description</th>"
+        f"</tr></thead><tbody>{rows}</tbody></table></div>"
+    )
+
+
+def _mcp_card(server: CatalogMcpServer) -> str:
+    head = pill("mcp", CLASS_MCP) + ref_span(server.ref) + id_span(f"{len(server.tools)} tools")
+    inner = row_block(head) + desc_block(server.description) + tag_chips(list(server.tags))
+    if server.tools:
+        table = _tools_table(server.tools)
+        if len(server.tools) > _TOOLS_INLINE_MAX:
+            inner += (
+                f"<button class='more' data-title='{e(server.ref)} · {len(server.tools)} tools'>"
+                f"{len(server.tools)} tools &#9656;</button>"
+                f"<div class='popup-src'>{table}</div>"
+            )
+        else:
+            inner += table
+    return card_block(search_key(server.ref, server.search_text), inner)
+
+
+def plugin_card(plugin: CatalogPlugin, components: PluginComponents | None = None) -> str:
+    head = pill("plugin") + ref_span(plugin.ref) + id_span(plugin.id)
+    inner = row_block(head) + desc_block(plugin.description) + tag_chips(list(plugin.tags))
+    if plugin.skills:
+        inner += f'<div class="path"><b>skills:</b> {e(", ".join(plugin.skills))}</div>'
+    if plugin.mcp_servers:
+        inner += f'<div class="path"><b>mcp:</b> {e(", ".join(plugin.mcp_servers))}</div>'
+    if components is not None:
+        inner += components_block(components)
+    return card_block(search_key(plugin.ref, plugin.search_text), inner)
+
+
+def entry_card(entry: CatalogEntry, location: Path | None) -> str:
+    """Render one catalog entry as a card, dispatched by its variant. `location` is a skill's
+    SKILL.md path and is ignored for the other variants."""
+    match entry:
+        case CatalogSkill():
+            return _skill_card(entry, location)
+        case CatalogTool():
+            return _tool_card(entry)
+        case CatalogMcpServer():
+            return _mcp_card(entry)
+        case CatalogPlugin():
+            return plugin_card(entry)
+        case _ as unreachable:
+            assert_never(unreachable)

capdisc/report/cli.py

@@ -0,0 +1,35 @@
+"""`capdisc` / `python -m capdisc.report` entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from ..settings import get_settings
+from .harvest import REPORT_HTML_NAME, REPORT_JSON_NAME, build_report, write_report
+
+_DESCRIPTION = (
+    "Scan this machine's Claude Code capabilities — skills, built-in tools, plugins, and "
+    "connected MCP servers — and write a JSON snapshot and an HTML report to the default paths."
+)
+
+
+def main() -> None:
+    """Build the report against this machine and write both files to the default paths."""
+    parser = argparse.ArgumentParser(prog="capdisc", description=_DESCRIPTION)
+    parser.add_argument(
+        "--oauth",
+        action="store_true",
+        help="allow the interactive OAuth flow (browser) for HTTP MCP servers with a "
+        "pre-registered client in settings; forces a fresh MCP harvest",
+    )
+    args = parser.parse_args()
+    write_report(build_report(oauth=args.oauth))
+    report_dir = get_settings().report_dir
+    sys.stdout.write(
+        f"wrote {report_dir / REPORT_JSON_NAME}\nwrote {report_dir / REPORT_HTML_NAME}\n"
+    )
+
+
+if __name__ == "__main__":
+    main()