ghosttrap-cli 0.3.16__tar.gz → 0.3.18__tar.gz

{ghosttrap_cli-0.3.16 → ghosttrap_cli-0.3.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ghosttrap-cli
-Version: 0.3.16
+Version: 0.3.18
 Summary: Watch for errors streaming from ghosttrap.io
 Project-URL: Homepage, https://github.com/alex-rowley/ghosttrap-cli
 Requires-Python: >=3.10
@@ -41,6 +41,8 @@ After fixing, Claude restarts peek and waits for the next one. Errors become a r
 
 Your app needs [ghosttrap-sdk](https://github.com/alex-rowley/ghosttrap-sdk) to report errors. The Claude Code skill handles the integration automatically — it installs the SDK, wires it into your app, and adds Django/Celery hooks if applicable. You shouldn't need to touch the SDK manually.
 
+If you want to manually flag a caught exception or a non-exception condition, call `ghosttrap.trap(exc_or_message)` from your app code — see the [SDK README](https://github.com/alex-rowley/ghosttrap-sdk#manually-trap-an-event).
+
 ## Commands
 
 | Command | What it does |
@@ -51,6 +53,8 @@ Your app needs [ghosttrap-sdk](https://github.com/alex-rowley/ghosttrap-sdk) to
 | `ghosttrap last` | Fetch the most recent error and exit (no waiting) |
 | `ghosttrap last --clear` | Fetch the most recent error and skip everything older |
 | `ghosttrap watch` | Stream all errors continuously |
+| `ghosttrap list [n]` | Print a numbered summary of the most recent `n` errors (default 10, max 50). Doesn't move the cursor. |
+| `ghosttrap show <i>` | Full details for row `i` from the last `list` (1-based). Doesn't move the cursor. |
 | `ghosttrap clear` | Skip all outstanding errors |
 | `ghosttrap nuke` | Permanently delete every server-side row for the current repo (errors + token). Requires typed confirmation. |
 

{ghosttrap_cli-0.3.16 → ghosttrap_cli-0.3.18}/README.md

@@ -32,6 +32,8 @@ After fixing, Claude restarts peek and waits for the next one. Errors become a r
 
 Your app needs [ghosttrap-sdk](https://github.com/alex-rowley/ghosttrap-sdk) to report errors. The Claude Code skill handles the integration automatically — it installs the SDK, wires it into your app, and adds Django/Celery hooks if applicable. You shouldn't need to touch the SDK manually.
 
+If you want to manually flag a caught exception or a non-exception condition, call `ghosttrap.trap(exc_or_message)` from your app code — see the [SDK README](https://github.com/alex-rowley/ghosttrap-sdk#manually-trap-an-event).
+
 ## Commands
 
 | Command | What it does |
@@ -42,6 +44,8 @@ Your app needs [ghosttrap-sdk](https://github.com/alex-rowley/ghosttrap-sdk) to
 | `ghosttrap last` | Fetch the most recent error and exit (no waiting) |
 | `ghosttrap last --clear` | Fetch the most recent error and skip everything older |
 | `ghosttrap watch` | Stream all errors continuously |
+| `ghosttrap list [n]` | Print a numbered summary of the most recent `n` errors (default 10, max 50). Doesn't move the cursor. |
+| `ghosttrap show <i>` | Full details for row `i` from the last `list` (1-based). Doesn't move the cursor. |
 | `ghosttrap clear` | Skip all outstanding errors |
 | `ghosttrap nuke` | Permanently delete every server-side row for the current repo (errors + token). Requires typed confirmation. |
 

{ghosttrap_cli-0.3.16 → ghosttrap_cli-0.3.18}/ghosttrap_cli/cli.py

@@ -2,29 +2,18 @@
 
 import argparse
 import asyncio
-import hashlib
 import json
 import os
 import subprocess
 import sys
+import tempfile
 import time
+import urllib.error
 import urllib.request
 
 import websockets
 
-KNOWN_SKILL_HASHES = {
-    "aeda67bc5971bd8af4d7ebe819ebcce5acead562fa618227a1798b4b5ae7143e",  # v0.2.0
-    "0f2d2f4105e393fc69084d404d5a8154ba5d97fd23f92810c51345e3dc68e9a0",  # v0.3.0
-    "8564b65b8ab5c63283cda1706e30ca62bc4e111d33ba8918220f4b556ad01da1",  # v0.3.1..v0.3.3
-    "5759b2e0dc8ca47c3801915fd688cc8da878a7ab8d405f5183ffd7e8c8df4c55",  # v0.3.4..v0.3.7
-    "0651bb4247cf5c68960ff5b63d6a5d0c85ff1ce08e7966ab4823601ff02cf1f4",  # v0.3.9
-    "38810f43867a2a91420cc3dacbc71d2acabd7125596fd5b43f222b49725c9696",  # v0.3.10
-    "19b67d913dc5214ee4db3610bd8749da67324c174b904b5da71ee6de13e23e63",  # v0.3.11
-    "bf7768c3de266b7018d5c722c6c9991b487e7897786b3a406c460842cdcde8b5",  # v0.3.12
-    "d3f594c4c3601a4594c18ebc5e16dfd4abad4ab97d56285ecc20634b919b6731",  # v0.3.14
-}
-
-__version__ = "0.3.16"
+__version__ = "0.3.18"
 
 GHOSTTRAP_SERVER = "wss://ghosttrap.io/stream/"
 CONFIG_DIR = os.path.expanduser("~/.ghosttrap")
@@ -74,6 +63,10 @@ Read `~/.ghosttrap/config.json` for state. It contains:
 3. If `sdk_installed` is false or missing: install the SDK (`pip install ghosttrap-sdk`), wire `ghosttrap.init("<token>")` into the app startup. For Django projects, also add `"ghosttrap.django.GhostTrapApp"` to INSTALLED_APPS (re-attaches logging handler after Django's dictConfig) and `"ghosttrap.django.GhostTrapMiddleware"` to MIDDLEWARE (catches unhandled view exceptions). The SDK auto-hooks into Celery task_failure if Celery is installed, and attaches a logging handler for logger.exception() calls. Use whatever pattern the project already uses for configuration (env vars, settings files, hardcoded — match the existing style). Then update the config: set `sdk_installed: true`, `sdk_version`, `init_file` to record what you did. Only pass `send_user=True` to `init()` if the user explicitly asks for user context in reports — it's PII and stays off by default.
 4. Run `ghosttrap peek --clear` with `run_in_background: true`. The `--clear` flag skips any stale backlog from prior sessions so you only get fresh errors.
 
+## Manual capture
+
+For caught exceptions or non-exception conditions the user explicitly wants reported, use `ghosttrap.trap(exc_or_message)` from app code — pass an exception instance or a string. Synthetic string events arrive as type `TrappedEvent` with the caller's stack. Only wire this in when the user asks for it; don't add `trap()` calls speculatively.
+
 ## When peek returns
 
 1. **Immediately restart peek** in the background before doing anything else — this ensures you're listening for the next error while you work on the current one. Use plain `ghosttrap peek` here (no `--clear`) — you only want to skip backlog at session start.
@@ -83,6 +76,8 @@ Read `~/.ghosttrap/config.json` for state. It contains:
 ## Other commands
 
 - `ghosttrap last` — fetch the single most recent error and exit immediately, no waiting. Useful when the user wants to look at the latest error without starting a watch. Add `--clear` to also skip everything older in one shot.
+- `ghosttrap list [n]` — print a numbered summary of the most recent `n` errors (default 10, max 50). Does not move the cursor. Caches the ordered ids in config so a follow-up `ghosttrap show <i>` returns full details for that row.
+- `ghosttrap show <i>` — full details for the i-th row from the most recent `ghosttrap list`. Does not move the cursor.
 - `ghosttrap clear` — manually skip outstanding errors without waiting. Useful if the user explicitly wants to drop the queue.
 - `ghosttrap nuke` — permanently delete every server-side row for the current repo (errors + the Repo row + its token). Requires the user to type the repo name `owner/name` to confirm. Only run if the user explicitly asks to wipe server data — never proactively. After it succeeds the token is dead; the user would need to `ghosttrap setup` again to use this repo.
 
@@ -201,26 +196,33 @@ def get_gh_token():
         sys.exit(1)
 
 
-def _get_repo_token(config, requested=None):
-    """Get the repo token. If `requested` is 'owner/name', match strictly. Else cwd, else first."""
+def _get_repo_entry(config, requested=None):
+    """Return (key, entry) for the chosen repo. Same resolution rules as _get_repo_token."""
     repos = config.get("repos", {})
     if not repos:
         print("error: no repos configured. run 'ghosttrap setup' first.", file=sys.stderr)
         sys.exit(1)
     if requested:
-        for entry in repos.values():
+        for k, entry in repos.items():
             if f"{entry.get('owner')}/{entry.get('name')}" == requested:
-                return entry["token"]
+                return k, entry
         available = sorted(f"{e['owner']}/{e['name']}" for e in repos.values())
         print(f"error: '{requested}' is not in your config.", file=sys.stderr)
         print(f"available: {', '.join(available)}", file=sys.stderr)
         sys.exit(1)
     cwd_repo = _detect_repo_from_cwd()
     if cwd_repo:
-        for entry in repos.values():
+        for k, entry in repos.items():
             if f"{entry.get('owner')}/{entry.get('name')}" == cwd_repo:
-                return entry["token"]
-    return next(iter(repos.values()))["token"]
+                return k, entry
+    k = next(iter(repos))
+    return k, repos[k]
+
+
+def _get_repo_token(config, requested=None):
+    """Get the repo token. If `requested` is 'owner/name', match strictly. Else cwd, else first."""
+    _, entry = _get_repo_entry(config, requested)
+    return entry["token"]
 
 
 async def _connect_and_handle(server_url, token, config, once=False):
@@ -295,22 +297,69 @@ def _require_setup():
         sys.exit(1)
 
 
-def _write_skill():
+def _write_skill(config=None):
     os.makedirs(SKILL_DIR, exist_ok=True)
     with open(SKILL_FILE, "w") as f:
         f.write(SKILL_CONTENT)
+    if config is None:
+        config = _load_config()
+    config["skill_baseline"] = SKILL_CONTENT
+    _save_config(config)
+
+
+def _merge_skill(base, local, remote):
+    """3-way merge via `git merge-file -p`. Returns (merged_text, clean)."""
+    with tempfile.TemporaryDirectory() as d:
+        bp = os.path.join(d, "base")
+        lp = os.path.join(d, "local")
+        rp = os.path.join(d, "remote")
+        for path, text in [(bp, base), (lp, local), (rp, remote)]:
+            with open(path, "w") as f:
+                f.write(text)
+        result = subprocess.run(
+            ["git", "merge-file", "-p",
+             "-L", "your edits", "-L", "previous release", "-L", "new release",
+             lp, bp, rp],
+            capture_output=True, text=True,
+        )
+        return result.stdout, result.returncode == 0
 
 
 def _refresh_skill_if_stale():
     if not os.path.exists(SKILL_FILE):
         return
     with open(SKILL_FILE) as f:
-        content = f.read()
-    if content == SKILL_CONTENT:
+        on_disk = f.read()
+    if on_disk == SKILL_CONTENT:
+        return
+    config = _load_config()
+    baseline = config.get("skill_baseline")
+    if baseline is None:
+        # Pre-baseline install: adopt current on-disk content as the baseline
+        # so future releases can 3-way-merge instead of clobbering local edits.
+        config["skill_baseline"] = on_disk
+        _save_config(config)
         return
-    if hashlib.sha256(content.encode()).hexdigest() in KNOWN_SKILL_HASHES:
-        _write_skill()
+    if baseline == on_disk:
+        _write_skill(config)
         print("ghosttrap skill file updated", file=sys.stderr)
+        return
+    merged, clean = _merge_skill(baseline, on_disk, SKILL_CONTENT)
+    if clean:
+        with open(SKILL_FILE, "w") as f:
+            f.write(merged)
+        config["skill_baseline"] = SKILL_CONTENT
+        _save_config(config)
+        print("ghosttrap skill file updated (merged with your local edits)", file=sys.stderr)
+        return
+    new_path = SKILL_FILE + ".new"
+    with open(new_path, "w") as f:
+        f.write(merged)
+    print(
+        f"ghosttrap skill update has conflicts with your local edits; "
+        f"merged candidate at {new_path} — resolve, copy to {SKILL_FILE}, and rerun.",
+        file=sys.stderr,
+    )
 
 
 async def setup(server_url, token):
@@ -339,7 +388,7 @@ async def setup(server_url, token):
 
             repos = event.get("repos", [])
             _save_repos(config, repos)
-            _write_skill()
+            _write_skill(config)
 
             target = repos[0] if repos else None
 
@@ -464,6 +513,126 @@ def nuke():
     _save_config(config)
 
 
+def _rel_time(iso):
+    if not iso:
+        return "?"
+    try:
+        from datetime import datetime, timezone
+        dt = datetime.fromisoformat(iso)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        delta = datetime.now(timezone.utc) - dt
+        s = int(delta.total_seconds())
+        if s < 60:
+            return f"{s}s ago"
+        if s < 3600:
+            return f"{s // 60}m ago"
+        if s < 86400:
+            return f"{s // 3600}h ago"
+        if s < 86400 * 30:
+            return f"{s // 86400}d ago"
+        return dt.strftime("%Y-%m-%d")
+    except Exception:
+        return iso
+
+
+def _print_error_details(error):
+    print(json.dumps({"type": "error", "error": error}))
+    sys.stdout.flush()
+    print(f"\n{'='*60}", file=sys.stderr)
+    print(f"  {error.get('repo', '?')}", file=sys.stderr)
+    print(f"  {error.get('type', '?')}: {error.get('message', '')}", file=sys.stderr)
+    frames = error.get("frames", [])
+    if frames:
+        f = frames[-1]
+        print(f"  at {f.get('file', '?')}:{f.get('line', '?')} in {f.get('function', '?')}", file=sys.stderr)
+    print(f"{'='*60}", file=sys.stderr)
+
+
+def list_recent(n=10, requested=None):
+    _require_setup()
+    config = _load_config()
+    _check_cli_version(config)
+    n = max(1, min(int(n), 50))
+    key, entry = _get_repo_entry(config, requested)
+    token = entry["token"]
+    server = GHOSTTRAP_SERVER.replace("wss://", "https://").replace("/stream/", "")
+    url = f"{server}/list/{token}/?n={n}"
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "ghosttrap-cli"})
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read())
+    except Exception as e:
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    errors = data.get("errors", [])
+    if not errors:
+        print("no errors yet", file=sys.stderr)
+        entry["recent"] = []
+        _save_config(config)
+        return
+
+    entry["recent"] = [e["id"] for e in errors]
+    _save_config(config)
+
+    width = len(str(len(errors)))
+    for i, e in enumerate(errors, 1):
+        when = _rel_time(e.get("created_at"))
+        etype = e.get("type") or "?"
+        msg = (e.get("message") or "").splitlines()[0] if e.get("message") else ""
+        if len(msg) > 60:
+            msg = msg[:57] + "..."
+        loc = ""
+        if e.get("file"):
+            loc = f"{e['file']}:{e.get('line', '?')}"
+            if e.get("function"):
+                loc += f" ({e['function']})"
+        print(f"  {i:>{width}}  {when:<12}  {etype:<20}  {msg:<60}  {loc}")
+    print(f"\nrun 'ghosttrap show <n>' to see full details. cursor unchanged.", file=sys.stderr)
+
+
+def show(index, requested=None):
+    _require_setup()
+    config = _load_config()
+    _check_cli_version(config)
+    key, entry = _get_repo_entry(config, requested)
+    recent = entry.get("recent") or []
+    if not recent:
+        print("error: no recent list cached. run 'ghosttrap list' first.", file=sys.stderr)
+        sys.exit(1)
+    try:
+        i = int(index)
+    except (TypeError, ValueError):
+        print(f"error: '{index}' is not a number.", file=sys.stderr)
+        sys.exit(1)
+    if i < 1 or i > len(recent):
+        print(f"error: index out of range. last list had {len(recent)} entries.", file=sys.stderr)
+        sys.exit(1)
+    db_id = recent[i - 1]
+    token = entry["token"]
+    server = GHOSTTRAP_SERVER.replace("wss://", "https://").replace("/stream/", "")
+    url = f"{server}/error/{token}/{db_id}/"
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "ghosttrap-cli"})
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            print(f"error: this error no longer exists on the server (id #{db_id}).", file=sys.stderr)
+        else:
+            print(f"error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(1)
+    error = data.get("error")
+    if not error:
+        print(f"error: empty response", file=sys.stderr)
+        sys.exit(1)
+    _print_error_details(error)
+
+
 def last(do_clear=False, requested=None):
     _require_setup()
     config = _load_config()
@@ -484,17 +653,7 @@ def last(do_clear=False, requested=None):
         print("no errors yet", file=sys.stderr)
         return
 
-    print(json.dumps({"type": "error", "error": error}))
-    sys.stdout.flush()
-
-    print(f"\n{'='*60}", file=sys.stderr)
-    print(f"  {error.get('repo', '?')}", file=sys.stderr)
-    print(f"  {error.get('type', '?')}: {error.get('message', '')}", file=sys.stderr)
-    frames = error.get("frames", [])
-    if frames:
-        f = frames[-1]
-        print(f"  at {f.get('file', '?')}:{f.get('line', '?')} in {f.get('function', '?')}", file=sys.stderr)
-    print(f"{'='*60}", file=sys.stderr)
+    _print_error_details(error)
 
     if do_clear:
         try:
@@ -526,6 +685,14 @@ def main():
     last_parser.add_argument("--clear", action="store_true", help="Also skip remaining outstanding errors")
     last_parser.add_argument("--repo", help="Target repo as owner/name (overrides cwd detection)")
 
+    list_parser = sub.add_parser("list", help="List the most recent N errors (summary only, cursor unchanged)")
+    list_parser.add_argument("n", nargs="?", type=int, default=10, help="How many to list (default 10, max 50)")
+    list_parser.add_argument("--repo", help="Target repo as owner/name (overrides cwd detection)")
+
+    show_parser = sub.add_parser("show", help="Show full details for an index from the last 'list' (cursor unchanged)")
+    show_parser.add_argument("index", type=int, help="1-based index from the last 'ghosttrap list'")
+    show_parser.add_argument("--repo", help="Target repo as owner/name (overrides cwd detection)")
+
     sub.add_parser("nuke", help="Permanently delete all server data for the current repo")
 
     args = parser.parse_args()
@@ -556,6 +723,12 @@ def main():
     elif args.command == "last":
         _refresh_skill_if_stale()
         last(do_clear=args.clear, requested=args.repo)
+    elif args.command == "list":
+        _refresh_skill_if_stale()
+        list_recent(n=args.n, requested=args.repo)
+    elif args.command == "show":
+        _refresh_skill_if_stale()
+        show(args.index, requested=args.repo)
     elif args.command == "nuke":
         nuke()
     else:

{ghosttrap_cli-0.3.16 → ghosttrap_cli-0.3.18}/ghosttrap_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ghosttrap-cli
-Version: 0.3.16
+Version: 0.3.18
 Summary: Watch for errors streaming from ghosttrap.io
 Project-URL: Homepage, https://github.com/alex-rowley/ghosttrap-cli
 Requires-Python: >=3.10
@@ -41,6 +41,8 @@ After fixing, Claude restarts peek and waits for the next one. Errors become a r
 
 Your app needs [ghosttrap-sdk](https://github.com/alex-rowley/ghosttrap-sdk) to report errors. The Claude Code skill handles the integration automatically — it installs the SDK, wires it into your app, and adds Django/Celery hooks if applicable. You shouldn't need to touch the SDK manually.
 
+If you want to manually flag a caught exception or a non-exception condition, call `ghosttrap.trap(exc_or_message)` from your app code — see the [SDK README](https://github.com/alex-rowley/ghosttrap-sdk#manually-trap-an-event).
+
 ## Commands
 
 | Command | What it does |
@@ -51,6 +53,8 @@ Your app needs [ghosttrap-sdk](https://github.com/alex-rowley/ghosttrap-sdk) to
 | `ghosttrap last` | Fetch the most recent error and exit (no waiting) |
 | `ghosttrap last --clear` | Fetch the most recent error and skip everything older |
 | `ghosttrap watch` | Stream all errors continuously |
+| `ghosttrap list [n]` | Print a numbered summary of the most recent `n` errors (default 10, max 50). Doesn't move the cursor. |
+| `ghosttrap show <i>` | Full details for row `i` from the last `list` (1-based). Doesn't move the cursor. |
 | `ghosttrap clear` | Skip all outstanding errors |
 | `ghosttrap nuke` | Permanently delete every server-side row for the current repo (errors + token). Requires typed confirmation. |
 

{ghosttrap_cli-0.3.16 → ghosttrap_cli-0.3.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ghosttrap-cli"
-version = "0.3.16"
+version = "0.3.18"
 description = "Watch for errors streaming from ghosttrap.io"
 readme = "README.md"
 requires-python = ">=3.10"