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

capdisc/hooks/types.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated
+
+from pydantic import Field
+
+HookTimeout = Annotated[
+    int,
+    Field(
+        ge=1,
+        le=86_400,
+        title="Hook timeout",
+        description="Seconds the hook may run before it is killed. Defaults vary by type "
+        "(command/http/mcp_tool 600, prompt 30, agent 60) and the docs set no maximum, so the "
+        "cap is only an absurd-value guard, not a product limit.",
+        examples=[30, 120, 600],
+    ),
+]
+ShellCommand = Annotated[
+    str,
+    Field(
+        min_length=1,
+        max_length=4000,
+        title="Shell command",
+        description="Command a command hook runs, or the executable to spawn when `args` is set.",
+        examples=["./run-tests.sh"],
+    ),
+]
+ShellArg = Annotated[
+    str,
+    Field(
+        max_length=2000,
+        title="Shell argument",
+        description="One argument in a command hook's argument vector.",
+    ),
+]
+HookUrl = Annotated[
+    str,
+    Field(
+        pattern=r"^https?://",
+        max_length=2000,
+        title="Hook URL",
+        description="Endpoint an http hook POSTs the event JSON to.",
+        examples=["http://localhost:8080/hooks/tool-use"],
+    ),
+]
+HeaderName = Annotated[
+    str,
+    Field(
+        pattern=r"^[A-Za-z0-9-]+$",
+        max_length=128,
+        title="Header name",
+        description="Name of an http hook request header.",
+        examples=["Authorization"],
+    ),
+]
+HeaderValue = Annotated[
+    str,
+    Field(
+        max_length=2000,
+        title="Header value",
+        description="Value of an http hook request header; supports `$VAR` interpolation.",
+        examples=["Bearer $MY_TOKEN"],
+    ),
+]
+EnvVarName = Annotated[
+    str,
+    Field(
+        pattern=r"^[A-Za-z_][A-Za-z0-9_]*$",
+        title="Env var",
+        description="Name of an environment variable.",
+        examples=["MY_TOKEN"],
+    ),
+]
+HookModel = Annotated[
+    str,
+    Field(
+        min_length=1,
+        max_length=64,
+        title="Hook model",
+        description="Model a prompt or agent hook evaluates with; omit for a fast default.",
+        examples=["haiku"],
+    ),
+]
+HookPrompt = Annotated[
+    str,
+    Field(
+        min_length=1,
+        max_length=8000,
+        title="Hook prompt",
+        description="Prompt a prompt or agent hook evaluates; `$ARGUMENTS` injects the input JSON.",
+        examples=["Verify all unit tests pass. $ARGUMENTS"],
+    ),
+]
+StatusMessage = Annotated[
+    str,
+    Field(
+        min_length=1,
+        max_length=200,
+        title="Status message",
+        description="Text shown while the hook runs.",
+    ),
+]
+HookCondition = Annotated[
+    str,
+    Field(
+        pattern=r"^[A-Za-z][A-Za-z0-9_]*(\(.*\))?$",
+        max_length=400,
+        title="Hook condition",
+        description=(
+            "A single permission rule narrowing when the handler runs on tool events, e.g. "
+            "'Bash(git *)' or 'Edit(*.ts)'; ignored on non-tool events."
+        ),
+        examples=["Bash(rm *)", "Edit(*.ts)"],
+    ),
+]
+HookMatcherPattern = Annotated[
+    str,
+    Field(
+        max_length=200,
+        title="Hook matcher",
+        description="Pattern selecting which subjects an event's handlers run for, e.g. "
+        "'Write|Edit', 'Bash', or '*' for all; empty also means all.",
+        examples=["Write|Edit", "Bash", "*", ""],
+    ),
+]
+RunOnce = Annotated[
+    bool,
+    Field(
+        description="If true, the hook runs once per session, then is removed. Only honored for "
+        "hooks declared in skill frontmatter — ignored in settings files and agent frontmatter.",
+    ),
+]
+RunAsync = Annotated[
+    bool,
+    Field(
+        description="If true, a command hook runs in the background without blocking Claude; its "
+        "output is delivered on the next conversation turn. Command hooks only.",
+    ),
+]
+AsyncRewake = Annotated[
+    bool,
+    Field(
+        description="If true, a command hook runs in the background and wakes Claude on exit "
+        "code 2 (implies async). The hook's stderr — or stdout if stderr is empty — is shown to "
+        "Claude as a system reminder, so it can react to a long-running background failure.",
+    ),
+]
+
+
+class HookShell(StrEnum):
+    """Interpreter a command hook runs under."""
+
+    bash = "bash"
+    powershell = "powershell"

capdisc/html.py

@@ -0,0 +1,75 @@
+"""Tiny HTML-escaping and markup primitives shared by the report and scope-inventory renderers.
+
+Lives at the package root (not inside `report/` or `scope/`) because both packages need it and
+`report/` already depends on `scope/` — putting it in `scope/` would make the reverse import
+circular.
+"""
+
+from __future__ import annotations
+
+import re
+from html import escape
+from pathlib import Path
+
+_FULL_MATCH_SECRET_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"(?i)\b(?:Bearer|Basic)\s+[A-Za-z0-9\-_.+/=]{8,}"),
+    re.compile(r"\bsk-(?:ant-)?[A-Za-z0-9_-]{10,}"),
+    re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}"),
+    re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,}"),
+    re.compile(r"\bAKIA[0-9A-Z]{16}"),
+    re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}"),
+)
+_KEY_VALUE_SECRET_PATTERN = re.compile(
+    r"(?i)\b((?:api[-_]?key|secret|token|password|passwd|auth)\w*)"
+    r"([\"'=:\s]{1,3})([A-Za-z0-9\-_./+=]{6,})"
+)
+_REDACTED = "[redacted]"
+
+
+def e(value: object) -> str:
+    """Escape any value for safe HTML text/attribute interpolation."""
+    return escape("" if value is None else str(value))
+
+
+def redact_home(value: object) -> str:
+    """Render `value` with the user's home directory prefix collapsed to `~`.
+
+    Applied to every path rendered into the discovery report so a shared report doesn't
+    disclose the OS username via each scanned/captured path."""
+    text = "" if value is None else str(value)
+    home = str(Path.home())
+    if home not in ("", "/") and text.startswith(home):
+        return "~" + text[len(home) :]
+    return text
+
+
+def redact_secrets(text: str) -> str:
+    """Best-effort scrub of secret-shaped substrings from arbitrary preview text: bearer/basic
+    auth headers, common provider API key prefixes, and `token=`/`secret=`-style key-value pairs.
+
+    Pattern-based, not a guarantee — a secret in an unusual shape can still slip through. Applied
+    to raw file-content previews (e.g. a hook's command string) that this tool didn't author,
+    before they're rendered into a report meant to be shared."""
+    redacted = text
+    for pattern in _FULL_MATCH_SECRET_PATTERNS:
+        redacted = pattern.sub(_REDACTED, redacted)
+    return _KEY_VALUE_SECRET_PATTERN.sub(lambda m: f"{m.group(1)}{m.group(2)}{_REDACTED}", redacted)
+
+
+def pill(label: str, css: str = "sc") -> str:
+    """A small uppercase badge; `css` picks its colour class."""
+    return f'<span class="pill {css}">{e(label)}</span>'
+
+
+def preview(text: str) -> str:
+    """A collapsible content preview; the toggle button only flips a CSS class.
+
+    Runs `redact_secrets` before escaping — a content preview of a file this tool didn't author
+    (a hook's command, a settings JSON slice) may carry a literal credential."""
+    if not text:
+        return ""
+    return (
+        '<button class="toggle" onclick="this.parentElement.classList.toggle(\'open\')">'
+        "&#9656; preview</button>"
+        f'<div class="preview">{e(redact_secrets(text))}</div>'
+    )

capdisc/mcp_catalog.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import subprocess
+from typing import Any
+
+from pydantic import TypeAdapter, ValidationError, model_validator
+
+from .base import InputModel
+from .catalog import CatalogMcpServer, McpServerRef, catalog_id
+
+_MCP_LIST = ("claude", "mcp", "list")
+SERVER_REF: TypeAdapter[McpServerRef] = TypeAdapter(
+    McpServerRef
+)  # the one place a server name becomes a ref
+
+
+class _ConnectedServerLine(InputModel):
+    """One `claude mcp list` line, kept only when it names a `Connected` server. The
+    command/URL after the name (which can carry credentials) is split off and never modeled."""
+
+    name: str
+
+    @model_validator(mode="before")
+    @classmethod
+    def _parse_line(cls, data: Any) -> Any:
+        if not isinstance(data, str):
+            return data
+        if ": " not in data or " - " not in data:
+            raise ValueError("not a 'name: command - status' line")
+        if "Connected" not in data.rsplit(" - ", 1)[-1]:
+            raise ValueError("server is not Connected")
+        return {"name": data.split(": ", 1)[0].strip()}
+
+
+def parse_mcp_servers(list_output: str) -> list[CatalogMcpServer]:
+    """Parse `claude mcp list` output into cards for the connected servers.
+
+    Only the server name is kept; the command/URL after it (which can carry credentials) is
+    split off and never indexed. The MCP config file is never read.
+
+    Args:
+        list_output: The stdout of `claude mcp list`.
+
+    Returns:
+        One card per distinct connected server (de-duplicated by id), skipping disconnected
+        lines and names that don't validate.
+    """
+    servers: list[CatalogMcpServer] = []
+    seen: set[str] = set()
+    for line in list_output.splitlines():
+        try:
+            name = _ConnectedServerLine.model_validate(line).name
+        except ValidationError:
+            continue
+        try:
+            ref = SERVER_REF.validate_python(name)
+        except ValidationError:
+            continue
+        try:
+            card = CatalogMcpServer(
+                id=catalog_id("mcp", ref), ref=ref, description=f"MCP server: {name}"
+            )
+        except ValidationError:
+            continue
+        # dedupe by id, not ref: two distinct refs can still truncate to the same catalog_id
+        if card.id in seen:
+            continue
+        seen.add(card.id)
+        servers.append(card)
+    return servers
+
+
+def enumerate_mcp_servers() -> list[CatalogMcpServer]:
+    """Enumerate connected MCP servers by running `claude mcp list`.
+
+    Spawned as an argv array (no shell); the config file is never touched.
+
+    Returns:
+        The connected server cards, or `[]` if the CLI is missing, times out, or errors.
+    """
+    try:
+        result = subprocess.run(  # noqa: S603 — fixed argv tuple, no shell, no untrusted input
+            _MCP_LIST, capture_output=True, text=True, timeout=30, check=False
+        )
+    except (OSError, subprocess.SubprocessError):
+        return []
+    return parse_mcp_servers(result.stdout)

capdisc/mcp_harvest/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from .cache import (
+    cache_is_stale,
+    read_mcp_cache,
+    refresh_in_background,
+    refresh_mcp_cache,
+    write_mcp_cache,
+)
+
+__all__ = [
+    "cache_is_stale",
+    "read_mcp_cache",
+    "refresh_in_background",
+    "refresh_mcp_cache",
+    "write_mcp_cache",
+]

capdisc/mcp_harvest/auth.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from fastmcp.client.auth import OAuth
+from key_value.aio.stores.filetree import FileTreeStore
+
+from ..settings import get_settings
+from .config import scalar_str
+from .types import ServerConfig
+
+logger = logging.getLogger(__name__)
+
+_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+def bare_name(ref: str) -> str:
+    """The bare server name from a full ref: `plugin:github:github` → `github`."""
+    return ref.rsplit(":", 1)[-1]
+
+
+def _host_of(url: str) -> str | None:
+    """The lowercased hostname of a url, or None when it has none."""
+    hostname = urlsplit(url).hostname
+    return hostname.lower() if hostname else None
+
+
+def _safe_for_auth(url: str) -> bool:
+    """Whether credentials may be attached to `url` at all: https, or plaintext http only to
+    a loopback host (local dev servers) — never a bearer token or OAuth client secret over an
+    unencrypted connection to a real host."""
+    scheme = urlsplit(url).scheme
+    if scheme == "https":
+        return True
+    return scheme == "http" and _host_of(url) in _LOCAL_HOSTS
+
+
+def _host_matches(url: str, expected_host: str) -> bool:
+    """Whether `url` resolves to exactly `expected_host` (case-insensitive)."""
+    return _host_of(url) == expected_host.lower()
+
+
+def ensure_private_dir(path: Path) -> None:
+    """Create `path` (with parents) and force it to mode 0700, whether newly created or
+    pre-existing — `Path.mkdir(mode=...)` only applies to a directory it creates, so a
+    pre-existing world-readable directory would otherwise silently hold plaintext OAuth
+    tokens."""
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    path.chmod(0o700)
+
+
+def server_auth(ref: str, config: ServerConfig, oauth: bool) -> str | OAuth | None:
+    """Resolve auth for one HTTP server, or None to connect anonymously.
+
+    A bearer token named in the settings' `mcp_bearer_env` always wins (non-interactive).
+    Otherwise, when `oauth` is set and the settings pre-register a client for the server,
+    the full browser flow runs, with tokens cached under `oauth_token_dir`. Stdio servers
+    (no `url`) never get auth — their config already carries what they need.
+
+    The bare server name is only a lookup key, never a trust boundary: a credential is
+    attached only when the server's own `url` also matches the configured `host`, so a
+    different (or malicious) server declared under the same bare name — e.g. by an
+    installed plugin — cannot receive a credential meant for another server. Credentials
+    are also refused entirely over a non-loopback plaintext connection.
+
+    Args:
+        ref: The server's full ref (`plugin:<plugin>:<server>` or a bare name).
+        config: The server's spawn config.
+        oauth: Whether the interactive OAuth flow is allowed for this run.
+
+    Returns:
+        A bearer token string, an `OAuth` flow handler, or None.
+    """
+    url = scalar_str(config.get("url"))
+    if url is None:
+        return None
+    if not _safe_for_auth(url):
+        logger.warning("refusing to attach credentials to non-HTTPS server %s", ref)
+        return None
+    name = bare_name(ref)
+    settings = get_settings()
+    bearer = settings.mcp_bearer_env.get(name)
+    if bearer is not None:
+        if not _host_matches(url, bearer.host):
+            logger.warning(
+                "refusing bearer token for %s: url host does not match configured %s",
+                ref,
+                bearer.host,
+            )
+        elif token := os.environ.get(bearer.env):
+            return token
+        else:
+            logger.warning(
+                "bearer env var %s is configured for %s but unset in this environment",
+                bearer.env,
+                ref,
+            )
+    client_conf = settings.mcp_oauth_clients.get(name) if oauth else None
+    if client_conf is None:
+        return None
+    if not _host_matches(url, client_conf.host):
+        logger.warning(
+            "refusing OAuth client for %s: url host does not match configured %s",
+            ref,
+            client_conf.host,
+        )
+        return None
+    token_dir = settings.oauth_token_dir
+    ensure_private_dir(token_dir)
+    return OAuth(
+        mcp_url=url,
+        scopes=client_conf.scopes,
+        client_id=client_conf.client_id,
+        client_secret=(os.environ.get(client_conf.secret_env) if client_conf.secret_env else None),
+        token_storage=FileTreeStore(data_directory=token_dir),
+        callback_port=client_conf.callback_port,
+    )

capdisc/mcp_harvest/cache.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import threading
+import time
+from pathlib import Path
+
+from pydantic import TypeAdapter, ValidationError
+
+from ..catalog import CatalogMcpServer
+from ..settings import get_settings
+from .config import all_server_configs
+from .connect import harvest_servers
+
+logger = logging.getLogger(__name__)
+
+_CACHE_TTL = 12 * 3600  # seconds; MCP tool inventories shift rarely, so a soft half-day is plenty
+_refresh_lock = threading.Lock()  # one background refresh per process at a time
+
+_CACHE: TypeAdapter[list[CatalogMcpServer]] = TypeAdapter(list[CatalogMcpServer])
+
+
+def read_mcp_cache(path: Path | None = None) -> list[CatalogMcpServer]:
+    """Read the cached, tool-enriched MCP server cards.
+
+    Args:
+        path: Cache file to read; the settings' `mcp_cache` when None.
+
+    Returns:
+        The cached cards, or `[]` when there is no valid cache yet.
+    """
+    path = path if path is not None else get_settings().mcp_cache
+    try:
+        return _CACHE.validate_json(path.read_text(encoding="utf-8"))
+    except (OSError, ValidationError):
+        return []
+
+
+def write_mcp_cache(servers: list[CatalogMcpServer], path: Path | None = None) -> None:
+    """Persist harvested server cards as the cache that recall reads.
+
+    Written atomically (write a sibling temp file, then rename it over the destination) so a
+    concurrent `read_mcp_cache` — e.g. `build_report` while a background refresh is writing —
+    never observes a truncated file; it sees either the old cache or the new one, never neither.
+
+    Args:
+        servers: The cards to write.
+        path: Destination cache file; parent dirs are created. The settings' `mcp_cache`
+            when None.
+    """
+    path = path if path is not None else get_settings().mcp_cache
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(f"{path.suffix}.tmp-{os.getpid()}-{threading.get_ident()}")
+    tmp.write_text(_CACHE.dump_json(servers, indent=2).decode(), encoding="utf-8")
+    tmp.replace(path)
+
+
+def refresh_mcp_cache(
+    plugins_root: Path | None = None,
+    path: Path | None = None,
+    project_dir: Path | None = None,
+    claude_json: Path | None = None,
+    oauth: bool = False,
+) -> list[CatalogMcpServer]:
+    """Harvest every MCP server across scopes and write the cache.
+
+    The impure refresh step: network and process spawning live here, never on the recall path.
+    A server's config (including any secrets in `env`) is used only to spawn it; only tool names,
+    descriptions, and parameters are cached.
+
+    Args:
+        plugins_root: Root of installed plugins; the settings' `plugins_root` when None.
+        path: Cache file to write; the settings' `mcp_cache` when None.
+        project_dir: Project root for project/local scope; the cwd when None.
+        claude_json: Path to `~/.claude.json`; the settings' `claude_json` when None.
+        oauth: Allow the interactive OAuth flow for HTTP servers with a pre-registered client.
+            Leave False on any background or hook path — it may open a browser.
+
+    Returns:
+        The freshly harvested cards (also written to `path`).
+    """
+    plugins_root = plugins_root if plugins_root is not None else get_settings().plugins_root
+    claude_json = claude_json if claude_json is not None else get_settings().claude_json
+    configs = all_server_configs(plugins_root, project_dir or Path.cwd(), claude_json)
+    cards = asyncio.run(harvest_servers(configs, oauth))
+    write_mcp_cache(cards, path)
+    return cards
+
+
+def cache_is_stale(path: Path | None = None, ttl_seconds: float = _CACHE_TTL) -> bool:
+    """Report whether the cache is due for a refresh.
+
+    Args:
+        path: Cache file to check; the settings' `mcp_cache` when None.
+        ttl_seconds: Maximum age before the cache is considered stale. Defaults to `_CACHE_TTL`.
+
+    Returns:
+        True if the cache is missing or older than `ttl_seconds`.
+    """
+    path = path if path is not None else get_settings().mcp_cache
+    try:
+        age = time.time() - path.stat().st_mtime
+    except OSError:
+        return True
+    return age > ttl_seconds
+
+
+def refresh_in_background(
+    plugins_root: Path | None = None,
+    path: Path | None = None,
+    project_dir: Path | None = None,
+    claude_json: Path | None = None,
+) -> threading.Thread | None:
+    """Run a one-shot cache refresh in a daemon thread and return immediately.
+
+    The harvest spawns MCP servers and does network I/O, so it must never run on the recall path;
+    this is how callers trigger it off that path. Best-effort: any failure is logged and swallowed,
+    never surfaced to the recall caller.
+
+    Args:
+        plugins_root: Root of installed plugins; the settings' `plugins_root` when None.
+        path: Cache file to write; the settings' `mcp_cache` when None.
+        project_dir: Project root for project/local scope; the cwd when None.
+        claude_json: Path to `~/.claude.json`; the settings' `claude_json` when None.
+
+    Returns:
+        The started daemon thread, or None if a refresh is already running in this process.
+    """
+    if not _refresh_lock.acquire(blocking=False):
+        return None
+
+    def _run() -> None:
+        try:
+            refresh_mcp_cache(plugins_root, path, project_dir, claude_json)
+        except Exception:
+            logger.exception("background MCP cache refresh failed")
+        finally:
+            _refresh_lock.release()
+
+    thread = threading.Thread(target=_run, name="mcp-cache-refresh", daemon=True)
+    thread.start()
+    return thread