patdown 0.1.0__py3-none-any.whl

patdown/__init__.py

@@ -0,0 +1,8 @@
+"""patdown: frisk everything your AI agent reads.
+
+Scans skills, rules files, hook configs and MCP servers for prompt injection,
+hidden Unicode, exfiltration channels, leaked secrets and poisoned tool
+descriptions. Zero dependencies.
+"""
+
+__version__ = "0.1.0"

patdown/__main__.py

@@ -0,0 +1,4 @@
+from patdown.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

patdown/baseline.py

@@ -0,0 +1,45 @@
+"""Baseline files: accept the findings you have reviewed, fail only on new ones."""
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+
+from patdown import __version__
+from patdown.findings import Finding
+
+BASELINE_FILENAME = ".patdown-baseline.json"
+
+
+def load_baseline(path: str) -> set[str]:
+    if not os.path.isfile(path):
+        return set()
+    with open(path, "r", encoding="utf-8") as fh:
+        try:
+            data = json.load(fh)
+        except json.JSONDecodeError:
+            return set()
+    items = data.get("findings", []) if isinstance(data, dict) else []
+    return {str(i.get("fingerprint")) for i in items if isinstance(i, dict) and i.get("fingerprint")}
+
+
+def write_baseline(path: str, findings: list[Finding]) -> None:
+    payload = {
+        "tool": "patdown",
+        "version": __version__,
+        "generated": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "findings": [
+            {"fingerprint": f.fingerprint, "rule": f.rule, "path": f.path, "line": f.line, "message": f.message}
+            for f in findings
+        ],
+    }
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(payload, fh, indent=2, ensure_ascii=False)
+        fh.write("\n")
+
+
+def apply_baseline(findings: list[Finding], baseline: set[str]) -> tuple[list[Finding], int]:
+    if not baseline:
+        return findings, 0
+    kept = [f for f in findings if f.fingerprint not in baseline]
+    return kept, len(findings) - len(kept)

patdown/cli.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+
+from patdown import __version__
+from patdown.baseline import BASELINE_FILENAME, apply_baseline, load_baseline, write_baseline
+from patdown.discover import ScanOptions, home_targets, iter_documents
+from patdown.engine import Scanner, dedupe
+from patdown.findings import Finding, Severity
+from patdown.report import render_json, render_sarif, render_terminal
+from patdown.report.terminal import want_color
+from patdown.rules import ALL_RULES, rule_by_id
+from patdown.rules.base import KIND_MCP_CONFIG
+from patdown.textutil import is_stealth_char
+
+SUBCOMMANDS = ("scan", "mcp", "rules", "explain", "baseline", "strip")
+EXIT_CLEAN, EXIT_FINDINGS, EXIT_ERROR = 0, 1, 2
+
+
+def _add_output_args(p: argparse.ArgumentParser) -> None:
+    g = p.add_argument_group("output")
+    g.add_argument("--json", action="store_true", help="emit JSON instead of the terminal report")
+    g.add_argument("--sarif", action="store_true", help="emit SARIF 2.1.0 (GitHub code scanning)")
+    g.add_argument("-o", "--output", metavar="FILE", help="write the report to FILE instead of stdout")
+    g.add_argument("--fail-on", default="high", metavar="LEVEL", help="exit 1 if any finding is at or above LEVEL (critical/high/medium/low/info/never). Default: high")
+    g.add_argument("--min-severity", default="low", metavar="LEVEL", help="hide findings below LEVEL. Default: low")
+    g.add_argument("--ignore", action="append", default=[], metavar="RULE", help="disable a rule id (repeatable, comma-separated ok)")
+    g.add_argument("--only", action="append", default=[], metavar="RULE", help="run only these rule ids")
+    g.add_argument("--baseline", metavar="FILE", help=f"suppress findings listed in FILE (default: {BASELINE_FILENAME} if present)")
+    g.add_argument("--no-color", action="store_true", help="disable ANSI colours")
+    g.add_argument("--color", action="store_true", help="force ANSI colours")
+    g.add_argument("-q", "--quiet", action="store_true", help="print nothing but the summary line")
+    g.add_argument("-v", "--verbose", action="store_true", help="print progress to stderr")
+
+
+def _add_scan_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("paths", nargs="*", help="files or directories to scan (default: current directory)")
+    p.add_argument("--home", action="store_true", help="also scan your user-level agent config (~/.claude, ~/.cursor, ~/.codex, Claude Desktop, ...)")
+    p.add_argument("--exclude", action="append", default=[], metavar="GLOB", help="skip paths matching GLOB (repeatable)")
+    p.add_argument("--no-default-excludes", action="store_true", help="also scan node_modules, .git, build dirs, ...")
+    p.add_argument("--max-file-size", type=int, default=2 * 1024 * 1024, metavar="BYTES", help="skip files larger than this (default 2 MiB)")
+    p.add_argument("--follow-symlinks", action="store_true", help="follow symbolic links while walking")
+    p.add_argument("--mcp", action="store_true", help="also connect to every MCP server found in scanned config files and inspect its tools")
+    p.add_argument("--timeout", type=float, default=20.0, help="seconds to wait for an MCP server (with --mcp)")
+    p.add_argument("--lockfile", metavar="FILE", help="MCP lockfile to compare against (default: patdown.lock in the current directory if present)")
+    p.add_argument("--lock", action="store_true", help="write/update the MCP lockfile after scanning (with --mcp)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="patdown",
+        description="Frisk everything your AI agent reads: skills, rules files, hooks and MCP servers.",
+        epilog="Run `patdown` with no arguments to scan the current directory. Exit code 1 means findings at or above --fail-on.",
+    )
+    parser.add_argument("--version", action="version", version=f"patdown {__version__}")
+    sub = parser.add_subparsers(dest="cmd")
+
+    scan = sub.add_parser("scan", help="scan files and directories (default command)")
+    _add_scan_args(scan)
+    _add_output_args(scan)
+
+    mcp = sub.add_parser("mcp", help="connect to MCP servers and inspect their tools live")
+    mcp.add_argument("configs", nargs="*", help="MCP config files (default: project configs in the current directory)")
+    mcp.add_argument("--home", action="store_true", help="also use user-level MCP configs (Claude Desktop, Cursor, Codex, ...)")
+    mcp.add_argument("--server", action="append", default=[], metavar="CMD", help="ad-hoc stdio server command line, e.g. --server \"npx -y some-mcp\" (repeatable)")
+    mcp.add_argument("--url", action="append", default=[], metavar="URL", help="ad-hoc streamable-HTTP server URL (repeatable)")
+    mcp.add_argument("--timeout", type=float, default=20.0, help="seconds to wait for each server (default 20)")
+    mcp.add_argument("--lockfile", metavar="FILE", default=None, help="lockfile path (default: patdown.lock)")
+    mcp.add_argument("--lock", action="store_true", help="write/update the lockfile with the current tool set")
+    mcp.add_argument("--no-lock", action="store_true", help="do not read any lockfile")
+    _add_output_args(mcp)
+
+    sub.add_parser("rules", help="list all rules")
+
+    explain = sub.add_parser("explain", help="describe a rule")
+    explain.add_argument("rule")
+
+    base = sub.add_parser("baseline", help=f"write {BASELINE_FILENAME} accepting all current findings")
+    _add_scan_args(base)
+    base.add_argument("--baseline-out", default=BASELINE_FILENAME, metavar="FILE", help="where to write the baseline")
+    base.add_argument("--ignore", action="append", default=[], metavar="RULE")
+    base.add_argument("--only", action="append", default=[], metavar="RULE")
+    base.add_argument("-v", "--verbose", action="store_true")
+
+    strip = sub.add_parser("strip", help="remove invisible / bidi / tag characters from files")
+    strip.add_argument("files", nargs="+")
+    strip.add_argument("--write", action="store_true", help="modify files in place (default: report only)")
+    return parser
+
+
+def _split_ids(values: list[str]) -> list[str]:
+    out: list[str] = []
+    for v in values:
+        out.extend(x.strip() for x in v.split(",") if x.strip())
+    return out
+
+
+def _severity(value: str) -> Severity | None:
+    if value.lower() in ("never", "none", "off"):
+        return None
+    return Severity.parse(value)
+
+
+def _emit(text: str, output: str | None) -> None:
+    if output:
+        with open(output, "w", encoding="utf-8") as fh:
+            fh.write(text + "\n")
+    else:
+        try:
+            sys.stdout.write(text + "\n")
+        except UnicodeEncodeError:
+            sys.stdout.buffer.write((text + "\n").encode("utf-8", "replace"))
+
+
+def _finish(args: argparse.Namespace, findings: list[Finding], stats: dict[str, object]) -> int:
+    min_sev = Severity.parse(args.min_severity)
+    shown = [f for f in findings if f.severity >= min_sev]
+    fail_on = _severity(args.fail_on)
+    if args.sarif:
+        _emit(render_sarif(shown, stats), args.output)
+    elif args.json:
+        _emit(render_json(shown, stats), args.output)
+    else:
+        color = want_color(True if args.color else (False if args.no_color or args.output else None))
+        text = render_terminal([] if args.quiet else shown, stats, color, args.verbose)
+        if args.quiet:
+            text = text.splitlines()[-2] if shown else text
+        _emit(text, args.output)
+    if fail_on is not None and any(f.severity >= fail_on for f in shown):
+        return EXIT_FINDINGS
+    return EXIT_CLEAN
+
+
+def _scan_paths(args: argparse.Namespace, scanner: Scanner) -> tuple[list[Finding], int, list[str]]:
+    roots = list(args.paths) or ["."]
+    if args.home:
+        roots.extend(home_targets())
+    opts = ScanOptions(
+        excludes=list(args.exclude), default_excludes=not args.no_default_excludes,
+        max_bytes=args.max_file_size, follow_symlinks=args.follow_symlinks,
+    )
+    findings: list[Finding] = []
+    files = 0
+    mcp_configs: list[str] = []
+    for doc in iter_documents(roots, opts):
+        files += 1
+        if args.verbose:
+            print(f"  scanning {doc.path} [{doc.kind}]", file=sys.stderr)
+        if doc.kind == KIND_MCP_CONFIG and doc.abspath:
+            mcp_configs.append(doc.abspath)
+        findings.extend(scanner.scan_document(doc))
+    return findings, files, mcp_configs
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    t0 = time.perf_counter()
+    scanner = Scanner(ignore_rules=_split_ids(args.ignore), only_rules=_split_ids(args.only) or None)
+    findings, files, mcp_configs = _scan_paths(args, scanner)
+    stats: dict[str, object] = {"files": files}
+    if args.mcp:
+        from patdown.mcp.scan import run_mcp_scan, specs_from_file
+        specs = [s for p in mcp_configs for s in specs_from_file(p)]
+        lock_path = args.lockfile or ("patdown.lock" if os.path.isfile("patdown.lock") or args.lock else None)
+        mcp_findings, inventories = run_mcp_scan(specs, scanner, args.timeout, lock_path, args.lock)
+        findings.extend(mcp_findings)
+        stats["servers"] = len(inventories)
+    baseline_path = args.baseline or (BASELINE_FILENAME if os.path.isfile(BASELINE_FILENAME) else None)
+    if baseline_path:
+        findings, suppressed = apply_baseline(findings, load_baseline(baseline_path))
+        stats["baselined"] = suppressed
+    stats["seconds"] = round(time.perf_counter() - t0, 3)
+    return _finish(args, dedupe(findings), stats)
+
+
+def cmd_mcp(args: argparse.Namespace) -> int:
+    from patdown.mcp.scan import discover_config_files, run_mcp_scan, spec_from_command, specs_from_file
+    from patdown.mcp.client import ServerSpec
+
+    t0 = time.perf_counter()
+    scanner = Scanner(ignore_rules=_split_ids(args.ignore), only_rules=_split_ids(args.only) or None)
+    configs = list(args.configs) or discover_config_files(args.home)
+    specs = [s for p in configs for s in specs_from_file(p)]
+    for i, cmd in enumerate(args.server, 1):
+        specs.append(spec_from_command(cmd, i))
+    for i, url in enumerate(args.url, 1):
+        specs.append(ServerSpec(name=f"url{i}", url=url, source="--url"))
+    if not specs:
+        print("patdown: no MCP servers found. Pass a config file, --server \"cmd args\", --url, or --home.", file=sys.stderr)
+        return EXIT_ERROR
+    if args.verbose:
+        for s in specs:
+            print(f"  connecting to {s.name}: {s.describe()}", file=sys.stderr)
+    lock_path = None if args.no_lock else (args.lockfile or "patdown.lock")
+    if lock_path and not args.lock and not os.path.isfile(lock_path):
+        lock_path = None
+    findings, inventories = run_mcp_scan(specs, scanner, args.timeout, args.lockfile or "patdown.lock" if args.lock else lock_path, args.lock)
+    stats: dict[str, object] = {
+        "servers": len(inventories),
+        "tools": sum(len(i.tools) for i in inventories),
+        "seconds": round(time.perf_counter() - t0, 3),
+    }
+    if args.lock:
+        print(f"patdown: lockfile written to {args.lockfile or 'patdown.lock'}", file=sys.stderr)
+    baseline_path = args.baseline or (BASELINE_FILENAME if os.path.isfile(BASELINE_FILENAME) else None)
+    if baseline_path:
+        findings, suppressed = apply_baseline(findings, load_baseline(baseline_path))
+        stats["baselined"] = suppressed
+    return _finish(args, findings, stats)
+
+
+def cmd_rules(args: argparse.Namespace) -> int:
+    width = max(len(r.name) for r in ALL_RULES) + 2
+    for r in ALL_RULES:
+        print(f"{r.id}  {r.name.ljust(width)}{r.severity.name.ljust(9)} {r.description}")
+    print("\nPD090-PD096  mcp-*  live MCP checks: lockfile drift, cross-server references, name collisions")
+    return EXIT_CLEAN
+
+
+def cmd_explain(args: argparse.Namespace) -> int:
+    r = rule_by_id(args.rule)
+    if r is None:
+        print(f"patdown: unknown rule {args.rule!r}; run `patdown rules`", file=sys.stderr)
+        return EXIT_ERROR
+    kinds = "all file kinds" if r.kinds is None else ", ".join(sorted(r.kinds))
+    print(f"{r.id} {r.name}\n  default severity: {r.severity.name}\n  applies to: {kinds}\n\n  {r.description}")
+    if r.kind_severity:
+        print("\n  severity by kind:")
+        for k, s in sorted(r.kind_severity.items()):
+            print(f"    {k.ljust(14)} {s.name}")
+    print(f"\n  suppress on one line with a `patdown:ignore {r.id}` comment, or a whole file with `patdown:ignore-file`.")
+    return EXIT_CLEAN
+
+
+def cmd_baseline(args: argparse.Namespace) -> int:
+    scanner = Scanner(ignore_rules=_split_ids(args.ignore), only_rules=_split_ids(args.only) or None)
+    findings, files, _ = _scan_paths(args, scanner)
+    write_baseline(args.baseline_out, findings)
+    print(f"patdown: baseline with {len(findings)} finding(s) from {files} file(s) written to {args.baseline_out}")
+    return EXIT_CLEAN
+
+
+def cmd_strip(args: argparse.Namespace) -> int:
+    total = 0
+    for path in args.files:
+        try:
+            with open(path, "rb") as fh:
+                raw = fh.read()
+            text = raw.decode("utf-8")
+        except (OSError, UnicodeDecodeError) as exc:
+            print(f"patdown: skipping {path}: {exc}", file=sys.stderr)
+            continue
+        cleaned = (text[0] if text and ord(text[0]) == 0xFEFF else "") + "".join(
+            ch for i, ch in enumerate(text) if not (is_stealth_char(ord(ch)) and not (i == 0 and ord(ch) == 0xFEFF))
+        )
+        removed = len(text) - len(cleaned)
+        total += removed
+        if removed and args.write:
+            with open(path, "wb") as fh:
+                fh.write(cleaned.encode("utf-8"))
+        print(f"{path}: {removed} stealth character(s) {'removed' if args.write else 'found'}")
+    if total and not args.write:
+        print("re-run with --write to remove them", file=sys.stderr)
+    return EXIT_CLEAN
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or (argv[0] not in SUBCOMMANDS and argv[0] not in ("-h", "--help", "--version")):
+        argv.insert(0, "scan")
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.cmd == "scan":
+            return cmd_scan(args)
+        if args.cmd == "mcp":
+            return cmd_mcp(args)
+        if args.cmd == "rules":
+            return cmd_rules(args)
+        if args.cmd == "explain":
+            return cmd_explain(args)
+        if args.cmd == "baseline":
+            return cmd_baseline(args)
+        if args.cmd == "strip":
+            return cmd_strip(args)
+    except ValueError as exc:
+        print(f"patdown: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    except KeyboardInterrupt:
+        print("patdown: interrupted", file=sys.stderr)
+        return EXIT_ERROR
+    parser.print_help()
+    return EXIT_ERROR
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

patdown/discover.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from typing import Any, Iterator
+
+from patdown.rules.base import (
+    KIND_CONFIG, KIND_MARKDOWN, KIND_MCP_CONFIG, KIND_PLUGIN, KIND_RULES,
+    KIND_SCRIPT, KIND_SETTINGS, KIND_SKILL, KIND_SKILL_SCRIPT, KIND_TEXT, Document,
+)
+
+DEFAULT_EXCLUDE_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", ".venv", "venv", "__pycache__", ".tox",
+    ".nox", ".mypy_cache", ".pytest_cache", ".ruff_cache", "dist", "build", "target",
+    ".next", ".nuxt", ".turbo", "coverage", ".gradle", ".terraform", "site-packages",
+    ".eggs", ".cache", ".parcel-cache",
+}
+SKIP_FILENAMES = {
+    "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "poetry.lock", "Cargo.lock",
+    "uv.lock", "Gemfile.lock", "composer.lock", "go.sum", "bun.lockb", "flake.lock",
+    ".patdown-baseline.json", "patdown.lock",
+}
+BINARY_EXT = {
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".bmp", ".tiff", ".psd", ".pdf",
+    ".woff", ".woff2", ".ttf", ".otf", ".eot", ".zip", ".gz", ".tgz", ".bz2", ".xz",
+    ".7z", ".rar", ".tar", ".jar", ".war", ".exe", ".dll", ".so", ".dylib", ".bin",
+    ".pyc", ".pyo", ".class", ".o", ".a", ".wasm", ".mp3", ".mp4", ".mov", ".avi",
+    ".wav", ".ogg", ".flac", ".sqlite", ".db", ".parquet", ".npy", ".npz", ".pkl",
+    ".min.js", ".map", ".lockb",
+}
+SCRIPT_EXT = {
+    ".sh", ".bash", ".zsh", ".fish", ".ps1", ".psm1", ".bat", ".cmd", ".py", ".js",
+    ".mjs", ".cjs", ".ts", ".rb", ".pl", ".php", ".lua", ".go", ".rs", ".java",
+    ".kt", ".swift", ".c", ".cc", ".cpp", ".cs", ".scala", ".exs", ".ex", ".r",
+    ".applescript", ".vbs",
+}
+MARKDOWN_EXT = {".md", ".mdx", ".mdc", ".markdown", ".txt", ".rst", ".adoc"}
+CONFIG_EXT = {".json", ".jsonc", ".json5", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".env"}
+
+RULES_FILENAMES = {
+    "claude.md", "claude.local.md", "agents.md", "agent.md", "gemini.md", "codex.md",
+    ".cursorrules", ".windsurfrules", ".clinerules", ".roomodes", ".goosehints",
+    "copilot-instructions.md", "conventions.md", "llms.txt", "llms-full.txt",
+    "instructions.md", "system.md", "prompt.md", "prompts.md",
+}
+RULES_DIR_PARTS = (
+    "/.cursor/rules/", "/.clinerules/", "/.roo/rules", "/.github/instructions/",
+    "/.windsurf/rules/", "/.claude/commands/", "/.claude/agents/", "/.codex/prompts/",
+    "/.gemini/commands/", "/.continue/rules/", "/.kiro/steering/", "/.amazonq/rules/",
+    "/.trae/rules/", "/commands/", "/agents/",
+)
+MCP_CONFIG_FILENAMES = {
+    ".mcp.json", "mcp.json", "claude_desktop_config.json", "mcp_config.json",
+    "mcp-config.json", "mcp_servers.json", "mcp-servers.json", "opencode.json",
+    "opencode.jsonc", ".claude.json",
+}
+SETTINGS_FILENAMES = {"settings.json", "settings.local.json", "hooks.json"}
+SETTINGS_DIR_PARTS = ("/.claude/", "/.cursor/", "/.gemini/", "/hooks/", "/.claude-plugin/", "/.codex/", "/.kiro/", "/.windsurf/", "/.copilot/")
+PLUGIN_FILENAMES = {"plugin.json", "marketplace.json"}
+
+
+@dataclass
+class ScanOptions:
+    excludes: list[str] = field(default_factory=list)
+    default_excludes: bool = True
+    max_bytes: int = 2 * 1024 * 1024
+    follow_symlinks: bool = False
+
+
+def norm(path: str) -> str:
+    return path.replace("\\", "/")
+
+
+def classify(path: str, skill_dirs: set[str] | None = None) -> str:
+    p = norm(path)
+    name = os.path.basename(p)
+    low = name.lower()
+    ext = os.path.splitext(low)[1]
+    parts = "/" + p.strip("/") + "/"
+
+    in_skill = False
+    if skill_dirs:
+        d = os.path.dirname(p)
+        while d:
+            if d in skill_dirs:
+                in_skill = True
+                break
+            nd = os.path.dirname(d)
+            if nd == d:
+                break
+            d = nd
+    if low == "skill.md":
+        return KIND_SKILL
+    if in_skill:
+        if ext in MARKDOWN_EXT:
+            return KIND_SKILL
+        if ext in SCRIPT_EXT or ext == "":
+            return KIND_SKILL_SCRIPT
+        return KIND_SKILL
+    if low in MCP_CONFIG_FILENAMES:
+        return KIND_MCP_CONFIG
+    if low == "config.toml" and "/.codex/" in parts:
+        return KIND_MCP_CONFIG
+    if low == "hooks.json":
+        return KIND_SETTINGS
+    if low in SETTINGS_FILENAMES and any(seg in parts for seg in SETTINGS_DIR_PARTS):
+        return KIND_SETTINGS
+    if low in PLUGIN_FILENAMES and "/.claude-plugin/" in parts:
+        return KIND_PLUGIN
+    if low in RULES_FILENAMES:
+        return KIND_RULES
+    if low.endswith((".instructions.md", ".prompt.md", ".agent.md", ".chatmode.md")):
+        return KIND_RULES
+    if ext in MARKDOWN_EXT and any(seg in parts for seg in RULES_DIR_PARTS):
+        return KIND_RULES
+    if ext in MARKDOWN_EXT:
+        return KIND_MARKDOWN
+    if ext in SCRIPT_EXT:
+        return KIND_SCRIPT
+    if ext in CONFIG_EXT or low.startswith(".env"):
+        return KIND_CONFIG
+    return KIND_TEXT
+
+
+_JSONC_COMMENT = re.compile(r"//[^\n]*|/\*.*?\*/", re.S)
+_TRAILING_COMMA = re.compile(r",(\s*[}\]])")
+
+
+def parse_structured(text: str, path: str) -> Any:
+    """Best-effort parse for JSON / JSONC / TOML config files."""
+    low = path.lower()
+    body = text.lstrip("\ufeff")
+    if low.endswith(".toml"):
+        try:
+            import tomllib  # py3.11+
+            return tomllib.loads(body)
+        except Exception:
+            return None
+    if low.endswith((".json", ".jsonc", ".json5")):
+        try:
+            return json.loads(body)
+        except Exception:
+            pass
+        try:
+            stripped = _TRAILING_COMMA.sub(r"\1", _JSONC_COMMENT.sub("", body))
+            return json.loads(stripped)
+        except Exception:
+            return None
+    return None
+
+
+STRUCTURED_KINDS = {KIND_MCP_CONFIG, KIND_SETTINGS, KIND_PLUGIN, KIND_CONFIG}
+
+
+def read_document(abspath: str, display: str, kind: str, max_bytes: int) -> Document | None:
+    try:
+        size = os.path.getsize(abspath)
+        if size > max_bytes or size == 0:
+            return None
+        with open(abspath, "rb") as fh:
+            raw = fh.read()
+    except OSError:
+        return None
+    if b"\x00" in raw[:8192]:
+        return None
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        if raw[:2] in (b"\xff\xfe", b"\xfe\xff"):
+            try:
+                text = raw.decode("utf-16")
+            except UnicodeDecodeError:
+                return None
+        else:
+            return None
+    data = parse_structured(text, abspath) if kind in STRUCTURED_KINDS else None
+    return Document(path=display, text=text, kind=kind, data=data, abspath=abspath)
+
+
+def _excluded(rel: str, name: str, opts: ScanOptions) -> bool:
+    for pat in opts.excludes:
+        if fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(name, pat):
+            return True
+    return False
+
+
+def display_path(abspath: str) -> str:
+    try:
+        cwd = os.path.abspath(os.getcwd())
+        if os.path.commonpath([cwd, abspath]) == cwd:
+            return norm(os.path.relpath(abspath, cwd))
+    except ValueError:
+        pass
+    return norm(abspath)
+
+
+def iter_documents(roots: list[str], opts: ScanOptions) -> Iterator[Document]:
+    for root in roots:
+        root = os.path.abspath(root)
+        if os.path.isfile(root):
+            doc = read_document(root, display_path(root), classify(root, _skill_dirs_for_file(root)), opts.max_bytes)
+            if doc:
+                yield doc
+            continue
+        if not os.path.isdir(root):
+            print(f"patdown: warning: {root} is not a file or directory", file=sys.stderr)
+            continue
+        skill_dirs = _find_skill_dirs(root, opts)
+        for dirpath, dirnames, filenames in os.walk(root, followlinks=opts.follow_symlinks):
+            rel_dir = norm(os.path.relpath(dirpath, root))
+            if rel_dir == ".":
+                rel_dir = ""
+            dirnames[:] = sorted(
+                d for d in dirnames
+                if not (opts.default_excludes and _default_excluded_dir(d))
+                and not _excluded(norm(os.path.join(rel_dir, d)), d, opts)
+            )
+            for fn in sorted(filenames):
+                if fn in SKIP_FILENAMES:
+                    continue
+                low = fn.lower()
+                if any(low.endswith(e) for e in BINARY_EXT):
+                    continue
+                abspath = os.path.join(dirpath, fn)
+                rel = norm(os.path.join(rel_dir, fn))
+                if _excluded(rel, fn, opts):
+                    continue
+                if not opts.follow_symlinks and os.path.islink(abspath):
+                    continue
+                kind = classify(norm(abspath), skill_dirs)
+                doc = read_document(abspath, display_path(abspath), kind, opts.max_bytes)
+                if doc:
+                    yield doc
+
+
+def _default_excluded_dir(name: str) -> bool:
+    """Dependency, VCS and build-artifact directories skipped unless --no-default-excludes."""
+    return name in DEFAULT_EXCLUDE_DIRS or name.endswith((".egg-info", ".dist-info"))
+
+
+def _find_skill_dirs(root: str, opts: ScanOptions) -> set[str]:
+    out: set[str] = set()
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=opts.follow_symlinks):
+        dirnames[:] = [d for d in dirnames if not (opts.default_excludes and _default_excluded_dir(d))]
+        if any(f.lower() == "skill.md" for f in filenames):
+            out.add(norm(dirpath))
+    return out
+
+
+def _skill_dirs_for_file(abspath: str) -> set[str]:
+    d = os.path.dirname(abspath)
+    try:
+        if any(f.lower() == "skill.md" for f in os.listdir(d)):
+            return {norm(d)}
+    except OSError:
+        pass
+    return set()
+
+
+def home_targets() -> list[str]:
+    """User-level locations where agents keep instructions, hooks and MCP configs."""
+    home = os.path.expanduser("~")
+    cands = [
+        "~/.claude", "~/.claude.json", "~/.cursor", "~/.codex", "~/.gemini",
+        "~/.windsurf", "~/.continue", "~/.kiro", "~/.config/opencode",
+        "~/.config/Claude/claude_desktop_config.json",
+        "~/Library/Application Support/Claude/claude_desktop_config.json",
+        "~/.config/github-copilot", "~/.copilot", "~/.aider.conf.yml", "~/.goosehints",
+        "~/.config/goose",
+    ]
+    appdata = os.environ.get("APPDATA")
+    if appdata:
+        cands.append(os.path.join(appdata, "Claude", "claude_desktop_config.json"))
+        cands.append(os.path.join(appdata, "Code", "User", "mcp.json"))
+    cands.append(os.path.join(home, ".config", "Code", "User", "mcp.json"))
+    cands.append(os.path.join(home, "Library", "Application Support", "Code", "User", "mcp.json"))
+    out = []
+    for c in cands:
+        p = os.path.expanduser(c)
+        if os.path.exists(p):
+            out.append(p)
+    return out