boost-skill-cli 1.0.4__tar.gz → 1.0.6__tar.gz

boost_skill_cli-1.0.6/CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md — working rules for the boost workspace
+
+boost is a "Homebrew for AI coding skills": a Python CLI (`boost_cli`) that finds,
+installs, and governs the skill/rule/workflow files that AI coding agents run on.
+Package name on PyPI is `boost-skill-cli`; the command is `boost`.
+
+## The one gate that matters
+
+Before calling any change done, run the full gate:
+
+```bash
+make check          # == lint test smoke mutation
+```
+
+It is four gates and **all must pass**:
+
+| Gate       | Command                                        | Threshold |
+|------------|------------------------------------------------|-----------|
+| `lint`     | `ruff check boost_cli tests` + `mypy`          | zero errors |
+| `test`     | `pytest tests/unit tests/functional --cov`     | **80%** coverage (`fail_under = 80`) |
+| `smoke`    | `bash tests/smoke.sh`                           | 0 failed |
+| `mutation` | `python3 scripts/mutation_gate.py --run --min 80` | **80%** of `boost_cli/core` mutants killed |
+
+New/changed core logic needs tests that both cover it *and* kill mutants —
+untested code counts as unkilled mutants, so the mutation gate fails even at 80%
+line coverage. Target `boost_cli/core` behavior with assertions, not just imports.
+
+## Non-obvious rules
+
+- **`boost_cli/data/registries.json` is GENERATED — never hand-edit it.** The
+  source of truth is `scripts/build_registries.py` (the `SKILLS` / `RULES` /
+  `WORKFLOWS` tuples). Edit those, then regenerate:
+  `python3 scripts/build_registries.py`. Each row is
+  `(owner/repo, category, focus, est_items, confidence)`. Add awesome-list repos
+  to `LIST_ONLY` so item-count math stays honest. Verify a repo is real
+  (`gh api repos/<owner/repo>`) before adding it.
+- **Sandbox tests via env, and export separately.** boost state lives under
+  `HOME`/`BOOST_HOME`; tests point them at a tempdir. In zsh, one-line chains
+  like `export A=$(...) B=$A/x` leave `B` broken — use separate `export`
+  statements.
+- **Versioning is setuptools-scm from git tags.** There is no `__version__`
+  constant and `boost_cli/_version.py` is generated + gitignored. Don't hardcode
+  or assert exact versions; version tests are shape-only (`^boost \S+$`). The
+  publish workflow filename must stay `publish.yml` (PyPI Trusted Publisher
+  matches on it).
+- **Target Python ≥ 3.9** (`requires-python = ">=3.9"`). Avoid 3.10+-only syntax
+  (structural pattern matching, `X | Y` runtime unions in non-annotation context).
+- **Three item kinds, one scanner.** `core/catalog.scan_dir` indexes `skill`
+  (SKILL.md), `rule` (.mdc/.cursorrules/.windsurfrules/.clinerules), and
+  `workflow` (commands/agents/workflows Markdown). **Only `skill` installs** —
+  `store.install` refuses non-skill kinds; rules/workflows are search/tap-only.
+
+## Layout
+
+- `boost_cli/commands/` — CLI command groups   · `boost_cli/core/` — engine (the mutation-gated code)
+- `boost_cli/data/` — shipped catalog data (generated)   · `scripts/` — build/gate tooling
+- `tests/unit`, `tests/functional`, `tests/smoke.sh` — the three test tiers
+- `docs/` — `overview.html` (visual guide), `DEBUGGING.md`

{boost_skill_cli-1.0.4 → boost_skill_cli-1.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.4
+Version: 1.0.6
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE
@@ -744,14 +744,17 @@ boost tap --defaults          # pull in the 5 starter registries
 ```
 
 Want the whole ecosystem instead of the starter set? boost ships a **curated
-registry catalog** — 90+ classified GitHub registries of skills, Cursor/Windsurf
+registry catalog** — 100+ classified GitHub registries of skills, Cursor/Windsurf
 **rules**, and Claude Code **workflows** (slash commands & subagents),
-collectively indexing thousands of items:
+collectively indexing thousands of items. Categories include a curated
+**`rag`** set — official Weaviate, Pinecone, and DSPy skill libraries plus
+Graph-RAG and agentic-RAG toolkits for building retrieval pipelines:
 
 ```bash
 boost tap --catalog --dry-run                 # browse the classified catalog
 boost tap --catalog --type skill --limit 20   # tap the 20 biggest skill packs
 boost tap --catalog --type rule               # every rules registry
+boost tap --catalog --category rag            # RAG / vector-search skill packs
 boost tap --catalog --category security       # filter by category
 ```
 
@@ -831,6 +834,13 @@ Standard-library Python only — no third-party runtime dependencies. Every
 path under `~/.boost` and `~/.agents/skills` is resolved from `$HOME` at
 call time, which is what makes the sandboxing above possible.
 
+When something misbehaves, boost keeps a rotating diagnostic log at
+`~/.boost/logs/boost.log` and writes a full crash report on any unexpected
+error. Turn up detail with `boost --verbose <cmd>` or `boost --debug <cmd>`,
+read the trail with `boost log --diagnostics`, and see
+[`docs/DEBUGGING.md`](docs/DEBUGGING.md) for log levels, env vars, crash
+reports, and the free services that monitor the project.
+
 ## Test suite
 
 Three layers, all enforced (`make check` runs the full set; CI runs the same thing):

{boost_skill_cli-1.0.4 → boost_skill_cli-1.0.6}/README.md

@@ -40,14 +40,17 @@ boost tap --defaults          # pull in the 5 starter registries
 ```
 
 Want the whole ecosystem instead of the starter set? boost ships a **curated
-registry catalog** — 90+ classified GitHub registries of skills, Cursor/Windsurf
+registry catalog** — 100+ classified GitHub registries of skills, Cursor/Windsurf
 **rules**, and Claude Code **workflows** (slash commands & subagents),
-collectively indexing thousands of items:
+collectively indexing thousands of items. Categories include a curated
+**`rag`** set — official Weaviate, Pinecone, and DSPy skill libraries plus
+Graph-RAG and agentic-RAG toolkits for building retrieval pipelines:
 
 ```bash
 boost tap --catalog --dry-run                 # browse the classified catalog
 boost tap --catalog --type skill --limit 20   # tap the 20 biggest skill packs
 boost tap --catalog --type rule               # every rules registry
+boost tap --catalog --category rag            # RAG / vector-search skill packs
 boost tap --catalog --category security       # filter by category
 ```
 
@@ -127,6 +130,13 @@ Standard-library Python only — no third-party runtime dependencies. Every
 path under `~/.boost` and `~/.agents/skills` is resolved from `$HOME` at
 call time, which is what makes the sandboxing above possible.
 
+When something misbehaves, boost keeps a rotating diagnostic log at
+`~/.boost/logs/boost.log` and writes a full crash report on any unexpected
+error. Turn up detail with `boost --verbose <cmd>` or `boost --debug <cmd>`,
+read the trail with `boost log --diagnostics`, and see
+[`docs/DEBUGGING.md`](docs/DEBUGGING.md) for log levels, env vars, crash
+reports, and the free services that monitor the project.
+
 ## Test suite
 
 Three layers, all enforced (`make check` runs the full set; CI runs the same thing):

{boost_skill_cli-1.0.4 → boost_skill_cli-1.0.6}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.4'
-__version_tuple__ = version_tuple = (1, 0, 4)
+__version__ = version = '1.0.6'
+__version_tuple__ = version_tuple = (1, 0, 6)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.4 → boost_skill_cli-1.0.6}/boost_cli/cli.py

@@ -9,12 +9,21 @@ from __future__ import annotations
 import difflib
 import importlib
 import sys
+import time
 from typing import List
 
 from . import PRODUCT, TAGLINE, __version__
+from .core import logs
 from .core import output as out
 from .errors import BoostError
 
+# Global flags handled before dispatch, stripped from the command's own argv.
+_GLOBAL_FLAGS = {
+    "--verbose": "verbose", "-v": "verbose",
+    "--debug": "debug",
+    "--quiet": "quiet", "-q": "quiet",
+}
+
 # group key -> (icon token, title, description)
 GROUPS = {
     "pkg":  ("pkg",  "Package Management",
@@ -160,6 +169,13 @@ def print_command_help(name: str) -> int:
     return _dispatch(name, ["--help"], soft=True)
 
 
+def _crash_hint(report) -> str:
+    where = ("a crash report was written to %s" % report if report
+             else "set BOOST_DEBUG=1 to see the full traceback")
+    return "%s — re-run with --debug for the traceback, or file it at %s" % (
+        where, "https://github.com/jonnyeclectic/boost/issues")
+
+
 def _unknown(name: str) -> int:
     close = difflib.get_close_matches(name, list(_BY_NAME), n=3)
     out.err("unknown command: %s" % name,
@@ -181,8 +197,25 @@ def _dispatch(name: str, argv: List[str], soft: bool = False) -> int:
     return int(rc or 0)
 
 
+def _extract_globals(argv: List[str]) -> tuple[dict, List[str]]:
+    """Peel leading global flags (`boost --debug install …`) off argv.
+
+    Only flags *before* the command name are treated as global, so a
+    subcommand keeps its own `--verbose`/`-q` (e.g. `boost lint --verbose`).
+    """
+    opts = {"verbose": False, "debug": False, "quiet": False}
+    i = 0
+    while i < len(argv) and argv[i] in _GLOBAL_FLAGS:
+        opts[_GLOBAL_FLAGS[argv[i]]] = True
+        i += 1
+    return opts, argv[i:]
+
+
 def main(argv: List[str] | None = None) -> int:
     argv = list(sys.argv[1:] if argv is None else argv)
+    opts, argv = _extract_globals(argv)
+    logs.configure(verbose=opts["verbose"], debug=opts["debug"],
+                   quiet=opts["quiet"])
     if not argv or argv[0] in ("-h", "--help"):
         print_help()
         return 0
@@ -197,17 +230,39 @@ def main(argv: List[str] | None = None) -> int:
     name, rest = argv[0], argv[1:]
     if name not in _BY_NAME:
         return _unknown(name)
+    logs.log_invocation([name, *rest])
+    start = time.perf_counter()
+    rc = 70  # assume the worst until a handler proves otherwise
     try:
-        return _dispatch(name, rest)
+        rc = _dispatch(name, rest)
+        return rc
     except BoostError as e:
+        logs.get_logger().info("BoostError: %s", e.message)
+        rc = 1
         out.err(e.message, hint=e.hint)
-        return 1
+        return rc
     except KeyboardInterrupt:
+        logs.get_logger().debug("interrupted by user")
+        rc = 130
         print()
-        return 130
+        return rc
     except BrokenPipeError:
         try:
             sys.stdout.close()
         except Exception:
             pass
-        return 0
+        rc = 0
+        return rc
+    except Exception as e:  # noqa: BLE001 — top-level safety net
+        report = logs.write_crash_report(e, [name, *rest])
+        if logs.is_debug():
+            raise
+        out.err("boost hit an unexpected error: %s: %s"
+                % (type(e).__name__, e),
+                hint=_crash_hint(report))
+        return 70  # EX_SOFTWARE
+    finally:
+        # Bookend every invocation with its exit code + duration, even when the
+        # --debug path re-raises the traceback above.
+        logs.log_completion([name, *rest], rc,
+                            (time.perf_counter() - start) * 1000)

{boost_skill_cli-1.0.4 → boost_skill_cli-1.0.6}/boost_cli/commands/info.py

@@ -16,7 +16,7 @@ import textwrap
 import webbrowser
 from pathlib import Path
 
-from ..core import ai, catalog, frontmatter, gitutil, journal, lockfile, paths, registry, store, util
+from ..core import ai, catalog, frontmatter, gitutil, journal, lockfile, logs, paths, registry, store, util
 from ..core import output as out
 from ..errors import BoostError
 
@@ -378,13 +378,52 @@ def cmd_explain(argv):
     return 0
 
 
+def _show_diagnostics(limit):
+    lp = logs.log_path()
+    if not lp.exists():
+        out.info("no diagnostic log yet at %s" % lp)
+        return 0
+    lines = lp.read_text(encoding="utf-8", errors="replace").splitlines()
+    out.heading("diagnostic log — %s" % lp)
+    for line in lines[-limit:]:
+        out.info(line)
+    return 0
+
+
+def _show_crashes(limit):
+    ldir = paths.logs_dir()
+    reports = sorted(ldir.glob("crash-*.log"), reverse=True) if ldir.is_dir() else []
+    if not reports:
+        out.info("no crash reports — nothing has blown up (that boost noticed)")
+        return 0
+    out.heading("crash reports in %s" % ldir)
+    for r in reports[:limit]:
+        try:
+            first = r.read_text(encoding="utf-8", errors="replace").splitlines()
+            summary = next((ln for ln in first if ln.startswith("command:")), "")
+        except OSError:
+            summary = ""
+        out.info("%s  %s" % (r.name, summary))
+    out.info("")
+    out.dim("  view one with:  cat %s/<name>" % ldir)
+    return 0
+
+
 def cmd_log(argv):
     ap = argparse.ArgumentParser(prog="boost log",
                                  description="Git log for a skill, or boost's activity log")
     ap.add_argument("name", nargs="?", help="skill to show upstream history for")
     ap.add_argument("-n", "--limit", type=int, default=20, metavar="N",
                     help="max entries (default 20)")
+    ap.add_argument("--diagnostics", action="store_true",
+                    help="show boost's diagnostic log trail (not skill history)")
+    ap.add_argument("--crashes", action="store_true",
+                    help="list recent crash reports")
     args = ap.parse_args(argv)
+    if args.crashes:
+        return _show_crashes(args.limit)
+    if args.diagnostics:
+        return _show_diagnostics(args.limit)
     if args.name:
         lock = lockfile.get_skill(args.name)
         if lock:

{boost_skill_cli-1.0.4 → boost_skill_cli-1.0.6}/boost_cli/commands/quality.py

@@ -17,8 +17,8 @@ from pathlib import Path
 from typing import List, Optional, Tuple
 
 from ..core import (agents, ai, catalog, frontmatter, gitutil, journal,
-                    lockfile, output as out, paths, policy, registry, store,
-                    util)
+                    lockfile, logs, output as out, paths, policy, registry,
+                    store, util)
 from ..errors import BoostError
 
 # --- audit: dangerous-content patterns ------------------------------------
@@ -323,6 +323,16 @@ def cmd_doctor(argv):
     if not rotation:
         bad("journal is overdue for rotation — run `boost heal`")
 
+    lp = logs.log_path()
+    if lp.exists():
+        out.ok("diagnostic log at %s" % _tilde(lp))
+    crashes = sorted(paths.logs_dir().glob("crash-*.log")) \
+        if paths.logs_dir().is_dir() else []
+    if crashes:
+        out.warn("%d crash report%s in %s (newest: %s) — see `boost log --crashes`"
+                 % (len(crashes), _s(len(crashes)), _tilde(paths.logs_dir()),
+                    crashes[-1].name))
+
     line1 = ("%d skill%s installed · %d tap%s synced · %d broken link%s"
              % (len(skills), _s(len(skills)), tap_ok, _s(tap_ok),
                 len(broken), _s(len(broken))))

{boost_skill_cli-1.0.4 → boost_skill_cli-1.0.6}/boost_cli/core/config.py

@@ -22,6 +22,15 @@ DEFAULTS = {
     "serve": {"port": 8787},
     "policy_enforce": True,
     "telemetry": False,
+    "logging": {
+        # Console verbosity for the diagnostic log on stderr. "OFF" keeps
+        # stderr clean (the default); set DEBUG/INFO/WARNING/ERROR to always
+        # surface the trail. The rotating file always records at DEBUG.
+        # Overridden by --verbose/--debug/--quiet and BOOST_LOG_LEVEL.
+        # See core/logs.py and docs/DEBUGGING.md.
+        "level": "OFF",
+        "file": True,  # set false (or BOOST_NO_LOG=1) to disable the log file
+    },
 }
 
 # Recommended public registries, added via `boost tap --defaults`.

boost_skill_cli-1.0.6/boost_cli/core/logs.py

@@ -0,0 +1,250 @@
+"""Diagnostic logging & crash reporting — boost's black box recorder.
+
+This is separate from two neighbouring concerns:
+
+  * ``core.output`` is the *human* channel — the pretty stdout a user reads.
+  * ``core.journal`` is the *activity* feed — semantic events (`install`,
+    `uninstall`) that power `boost pulse`/`trending`/`who`.
+
+``core.logs`` is the *diagnostic* channel: a rotating, machine-greppable trail
+of what boost did and why, written to ``~/.boost/logs/boost.log``, plus full
+crash reports when an unexpected exception escapes. Nothing here is meant for
+normal reading — it exists so that when something breaks, there is a trail.
+
+Verbosity is resolved once, in this order (first wins):
+
+  1. ``--debug`` flag / ``BOOST_DEBUG=1``      -> console shows DEBUG + tracebacks
+  2. ``--verbose`` / ``-v`` flag              -> console shows INFO
+  3. ``--quiet`` / ``-q`` flag                -> console stays silent
+  4. ``BOOST_LOG_LEVEL=DEBUG|INFO|WARNING|…`` -> explicit console level
+  5. config ``logging.level`` (default ``OFF`` -> console silent)
+
+The console diagnostic channel is *off by default* — user-facing messages
+already go through ``core.output``. The *file* handler always records at DEBUG
+regardless of console verbosity, so a plain run still leaves a complete trail to
+inspect after the fact. Set ``BOOST_NO_LOG=1`` (or config ``logging.file=false``)
+to disable the file.
+
+Each invocation bookends the trail with an ``invoke:`` line and a ``done:`` line
+that carries the exit code and wall-clock duration, so the log doubles as a
+lightweight timing record for spotting slow commands after the fact.
+"""
+from __future__ import annotations
+
+import logging
+import logging.handlers
+import os
+import platform
+import sys
+import traceback
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional
+
+from . import paths
+
+LOGGER_NAME = "boost"
+MAX_BYTES = 1_000_000  # ~1 MB per file …
+BACKUP_COUNT = 3       # … times (N+1) files kept = ~4 MB ceiling
+KEEP_CRASH_REPORTS = 20
+
+_LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL")
+
+# Set by configure(); read by main()'s exception handler to decide whether to
+# print a full traceback or a friendly one-liner.
+_debug_console = False
+_configured = False
+
+
+def _stamp() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _file_stamp() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+
+def log_path() -> Path:
+    return paths.logs_dir() / "boost.log"
+
+
+def is_debug() -> bool:
+    """True when the user asked for debug output (flag or env)."""
+    return _debug_console
+
+
+def _console_level(verbose: bool, debug: bool, quiet: bool) -> Optional[int]:
+    """Resolve the stderr diagnostic-handler level, or None to suppress it.
+
+    The console diagnostic channel is *off by default* — user-facing messages
+    already go through ``core.output``. It turns on only when explicitly asked
+    for, so a normal run leaves stderr clean while the file keeps the full
+    DEBUG trail.
+    """
+    if debug or os.environ.get("BOOST_DEBUG"):
+        return logging.DEBUG
+    if verbose:
+        return logging.INFO
+    if quiet:
+        return None
+    env = (os.environ.get("BOOST_LOG_LEVEL") or "").strip().upper()
+    if env in _LEVELS:
+        return getattr(logging, env)
+    from . import config
+    cfg = str(config.get("logging.level", "OFF") or "OFF").upper()
+    return getattr(logging, cfg) if cfg in _LEVELS else None
+
+
+def _file_enabled() -> bool:
+    if os.environ.get("BOOST_NO_LOG"):
+        return False
+    from . import config
+    return bool(config.get("logging.file", True))
+
+
+def get_logger() -> logging.Logger:
+    return logging.getLogger(LOGGER_NAME)
+
+
+def reset() -> None:
+    """Detach all handlers and forget configuration.
+
+    Real runs configure logging exactly once, but an in-process test suite
+    reconfigures against a fresh sandbox $HOME each test; without this the
+    first test's file handler would linger and write to a stale path.
+    """
+    global _configured, _debug_console
+    logger = logging.getLogger(LOGGER_NAME)
+    for h in list(logger.handlers):
+        try:
+            h.close()
+        except Exception:
+            pass
+        logger.removeHandler(h)
+    _configured = False
+    _debug_console = False
+
+
+def configure(verbose: bool = False, debug: bool = False,
+              quiet: bool = False) -> logging.Logger:
+    """Install handlers on the ``boost`` logger. Idempotent within a process."""
+    global _debug_console, _configured
+    logger = logging.getLogger(LOGGER_NAME)
+    logger.setLevel(logging.DEBUG)  # handlers do the real filtering
+    logger.propagate = False
+
+    _debug_console = bool(debug or os.environ.get("BOOST_DEBUG"))
+
+    if _configured:
+        return logger
+    _configured = True
+
+    fmt = logging.Formatter(
+        "%(asctime)s %(levelname)-7s %(name)s: %(message)s",
+        datefmt="%Y-%m-%dT%H:%M:%SZ",
+    )
+
+    # File handler — always DEBUG, best-effort (never break the CLI over a log).
+    if _file_enabled():
+        try:
+            paths.logs_dir().mkdir(parents=True, exist_ok=True)
+            fh = logging.handlers.RotatingFileHandler(
+                log_path(), maxBytes=MAX_BYTES, backupCount=BACKUP_COUNT,
+                encoding="utf-8", delay=True,
+            )
+            fh.setLevel(logging.DEBUG)
+            fh.setFormatter(fmt)
+            logger.addHandler(fh)
+        except OSError:
+            pass
+
+    # Console handler — only attached when something should surface on stderr.
+    level = _console_level(verbose, debug, quiet)
+    if level is not None:
+        ch = logging.StreamHandler(sys.stderr)
+        ch.setLevel(level)
+        ch.setFormatter(fmt)
+        logger.addHandler(ch)
+
+    return logger
+
+
+def log_invocation(argv: List[str]) -> None:
+    """Record a command invocation at the head of the trail."""
+    get_logger().info("invoke: boost %s", " ".join(argv))
+
+
+def log_completion(argv: List[str], rc: int, elapsed_ms: float) -> None:
+    """Close out an invocation with its exit code and wall-clock duration.
+
+    A clean exit logs at INFO; any non-zero code logs at WARNING so a failing
+    run stands out when scanning the trail (and surfaces with ``--verbose``).
+    """
+    level = logging.INFO if rc == 0 else logging.WARNING
+    get_logger().log(level, "done: boost %s -> rc=%d in %dms",
+                     " ".join(argv), rc, round(elapsed_ms))
+
+
+def _boost_version() -> str:
+    try:
+        from .. import __version__
+        return str(__version__)
+    except Exception:
+        return "unknown"
+
+
+def _env_snapshot() -> List[str]:
+    keys = sorted(k for k in os.environ
+                  if k.startswith("BOOST_") or k in ("NO_COLOR", "CLICOLOR_FORCE"))
+    return ["%s=%s" % (k, os.environ[k]) for k in keys]
+
+
+def write_crash_report(exc: BaseException, argv: List[str]) -> Optional[Path]:
+    """Dump a full crash report and return its path (or None if it can't).
+
+    Captures the traceback, invocation, versions and boost-relevant env so a
+    user can attach one file to a bug report instead of reproducing by hand.
+    """
+    tb = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+    body = "\n".join([
+        "boost crash report",
+        "==================",
+        "time:     %s" % _stamp(),
+        "version:  %s" % _boost_version(),
+        "python:   %s" % sys.version.split()[0],
+        "platform: %s" % platform.platform(),
+        "command:  boost %s" % " ".join(argv),
+        "",
+        "environment:",
+        *("  " + line for line in (_env_snapshot() or ["  (none)"])),
+        "",
+        "traceback:",
+        tb.rstrip(),
+        "",
+    ])
+    # Always try to get it into the rotating trail, even if the file write fails.
+    try:
+        get_logger().error("crash: %s: %s", type(exc).__name__, exc)
+    except Exception:
+        pass
+    try:
+        paths.logs_dir().mkdir(parents=True, exist_ok=True)
+        report = paths.logs_dir() / ("crash-%s.log" % _file_stamp())
+        report.write_text(body, encoding="utf-8")
+        _prune_crash_reports()
+        return report
+    except OSError:
+        return None
+
+
+def _prune_crash_reports() -> None:
+    """Keep only the most recent KEEP_CRASH_REPORTS crash files."""
+    try:
+        reports = sorted(paths.logs_dir().glob("crash-*.log"))
+    except OSError:
+        return
+    for stale in reports[:-KEEP_CRASH_REPORTS]:
+        try:
+            stale.unlink()
+        except OSError:
+            pass