ephem-debugger-py 0.3.2__tar.gz

ephem_debugger_py-0.3.2/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.3
+Name: ephem-debugger-py
+Version: 0.3.2
+Summary: Dev-only observability for AI agent debugging
+Author: ephem-sh
+Requires-Dist: django>=4.2 ; extra == 'django'
+Requires-Dist: fastapi>=0.100.0 ; extra == 'fastapi'
+Requires-Dist: starlette>=0.27.0 ; extra == 'fastapi'
+Requires-Dist: flask>=2.3 ; extra == 'flask'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://debugger.ephem.sh/
+Project-URL: Repository, https://github.com/ephem-sh/debugger
+Provides-Extra: django
+Provides-Extra: fastapi
+Provides-Extra: flask
+Description-Content-Type: text/markdown
+
+# ephem-debugger-py
+
+Dev-only observability middleware for Python web frameworks. Part of the [debugger](https://github.com/ephem-sh/debugger) project.
+
+Captures HTTP requests, console output, and browser-side data from your dev server. AI agents query this data through the `dbg` CLI.
+
+> **Preview** — under active development.
+
+## Install
+
+```bash
+pip install ephem-debugger-py
+```
+
+## FastAPI
+
+```python
+from fastapi import FastAPI
+from ephem_debugger_py.middleware.fastapi import instrument
+
+app = FastAPI()
+instrument(app, port=8000)
+```
+
+## Flask
+
+```python
+from flask import Flask
+from ephem_debugger_py.middleware.flask import init_debugger
+
+app = Flask(__name__)
+init_debugger(app, port=5000)
+```
+
+## Django
+
+Add to `settings.py`:
+
+```python
+MIDDLEWARE = [
+    'ephem_debugger_py.middleware.django.DebuggerMiddleware',
+    # ... other middleware
+]
+
+DEBUGGER_PORT = 8000
+```
+
+## Query with CLI
+
+```bash
+npx dbg status
+npx dbg server console
+npx dbg browser console
+npx dbg browser network
+```
+
+## How it works
+
+1. Middleware captures HTTP request/response metadata and logging output
+2. IPC bridge exposes data via Unix socket (or TCP on Windows)
+3. Browser client script is auto-injected into HTML responses
+4. `dbg` CLI queries the session — works the same across all languages
+
+## Other languages
+
+- **Node.js** — [`@ephem-sh/debugger`](https://www.npmjs.com/package/@ephem-sh/debugger)
+- **Go** — [`ephem-debugger-go`](https://github.com/ephem-sh/debugger/tree/main/packages/debugger-go)
+- **Rust** — [`ephem-debugger-rs`](https://crates.io/crates/ephem-debugger-rs)
+
+## License
+
+MIT

ephem_debugger_py-0.3.2/README.md

@@ -0,0 +1,72 @@
+# ephem-debugger-py
+
+Dev-only observability middleware for Python web frameworks. Part of the [debugger](https://github.com/ephem-sh/debugger) project.
+
+Captures HTTP requests, console output, and browser-side data from your dev server. AI agents query this data through the `dbg` CLI.
+
+> **Preview** — under active development.
+
+## Install
+
+```bash
+pip install ephem-debugger-py
+```
+
+## FastAPI
+
+```python
+from fastapi import FastAPI
+from ephem_debugger_py.middleware.fastapi import instrument
+
+app = FastAPI()
+instrument(app, port=8000)
+```
+
+## Flask
+
+```python
+from flask import Flask
+from ephem_debugger_py.middleware.flask import init_debugger
+
+app = Flask(__name__)
+init_debugger(app, port=5000)
+```
+
+## Django
+
+Add to `settings.py`:
+
+```python
+MIDDLEWARE = [
+    'ephem_debugger_py.middleware.django.DebuggerMiddleware',
+    # ... other middleware
+]
+
+DEBUGGER_PORT = 8000
+```
+
+## Query with CLI
+
+```bash
+npx dbg status
+npx dbg server console
+npx dbg browser console
+npx dbg browser network
+```
+
+## How it works
+
+1. Middleware captures HTTP request/response metadata and logging output
+2. IPC bridge exposes data via Unix socket (or TCP on Windows)
+3. Browser client script is auto-injected into HTML responses
+4. `dbg` CLI queries the session — works the same across all languages
+
+## Other languages
+
+- **Node.js** — [`@ephem-sh/debugger`](https://www.npmjs.com/package/@ephem-sh/debugger)
+- **Go** — [`ephem-debugger-go`](https://github.com/ephem-sh/debugger/tree/main/packages/debugger-go)
+- **Rust** — [`ephem-debugger-rs`](https://crates.io/crates/ephem-debugger-rs)
+
+## License
+
+MIT

ephem_debugger_py-0.3.2/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "ephem-debugger-py"
+version = "0.3.2"
+description = "Dev-only observability for AI agent debugging"
+readme = "README.md"
+authors = [
+    { name = "ephem-sh" }
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://debugger.ephem.sh/"
+Repository = "https://github.com/ephem-sh/debugger"
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100.0", "starlette>=0.27.0"]
+django = ["django>=4.2"]
+flask = ["flask>=2.3"]
+
+[build-system]
+requires = ["uv_build>=0.10.10,<0.11.0"]
+build-backend = "uv_build"

ephem_debugger_py-0.3.2/src/ephem_debugger_py/__init__.py

@@ -0,0 +1,48 @@
+"""Dev-only observability for AI agent debugging.
+
+Usage with FastAPI::
+
+    from ephem_debugger_py.middleware.fastapi import Middleware, logger, close
+    app.add_middleware(Middleware, port=8000)
+
+Usage with Django (settings.py)::
+
+    MIDDLEWARE = ["ephem_debugger_py.middleware.django.DebuggerMiddleware", ...]
+
+Usage with Flask::
+
+    from ephem_debugger_py.middleware.flask import init_debugger
+    init_debugger(app, port=5000)
+"""
+from __future__ import annotations
+
+from .bridge import Bridge
+from .capture import DebuggerHandler
+from .protocol import SessionInfo, compute_socket_path, create_session
+from .store import LogStore
+
+
+class Debugger:
+    """Main debugger instance. Creates store, bridge, and logging handler."""
+
+    def __init__(self, framework: str, port: int) -> None:
+        self.session = create_session(framework, port)
+        self.store = LogStore(self.session)
+        self.bridge = Bridge(self.store, self.session.socket_path)
+        self.handler = DebuggerHandler(self.store)
+        self.bridge.start()
+
+    def close(self) -> None:
+        """Stop the bridge and clean up resources."""
+        self.bridge.stop()
+
+
+__all__ = [
+    "Debugger",
+    "LogStore",
+    "Bridge",
+    "DebuggerHandler",
+    "SessionInfo",
+    "create_session",
+    "compute_socket_path",
+]

ephem_debugger_py-0.3.2/src/ephem_debugger_py/bridge.py

@@ -0,0 +1,175 @@
+"""IPC bridge -- NDJSON server for the dbg CLI."""
+from __future__ import annotations
+
+import json
+import os
+import socket
+import threading
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .store import LogStore
+
+
+class Bridge:
+    """NDJSON IPC server that the dbg CLI connects to.
+
+    On Windows, uses TCP on localhost with a .debugger/bridge.addr discovery
+    file. On Unix, uses a Unix domain socket.
+    """
+
+    def __init__(self, store: LogStore, socket_path: str) -> None:
+        self._store = store
+        self._socket_path = socket_path
+        self._server: socket.socket | None = None
+        self._thread: threading.Thread | None = None
+        self._running = False
+
+    def start(self) -> None:
+        """Start listening for CLI connections."""
+        if os.name == "nt":
+            self._start_tcp()
+        else:
+            self._start_unix()
+
+    def _start_unix(self) -> None:
+        sock_dir = os.path.dirname(self._socket_path)
+        os.makedirs(sock_dir, exist_ok=True)
+        try:
+            os.unlink(self._socket_path)
+        except OSError:
+            pass
+
+        self._server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self._server.bind(self._socket_path)
+        self._server.listen(5)
+        self._server.settimeout(1.0)
+        self._running = True
+        self._thread = threading.Thread(target=self._accept_loop, daemon=True)
+        self._thread.start()
+        self._write_session_file()
+
+    def _start_tcp(self) -> None:
+        self._server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._server.bind(("127.0.0.1", 0))
+        self._server.listen(5)
+        self._server.settimeout(1.0)
+
+        addr = self._server.getsockname()
+        addr_str = f"{addr[0]}:{addr[1]}"
+
+        # Write addr file so CLI can discover us
+        addr_dir = os.path.join(os.getcwd(), ".debugger")
+        os.makedirs(addr_dir, exist_ok=True)
+        addr_file = os.path.join(addr_dir, "bridge.addr")
+        with open(addr_file, "w") as f:
+            f.write(addr_str)
+
+        # Update session socket_path to actual TCP address for discovery
+        self._store.session.socket_path = addr_str
+
+        self._running = True
+        self._thread = threading.Thread(target=self._accept_loop, daemon=True)
+        self._thread.start()
+        self._write_session_file()
+
+    def _write_session_file(self) -> None:
+        """Write session.json for multi-session discovery."""
+        session_dir = os.path.join(os.getcwd(), ".debugger")
+        os.makedirs(session_dir, exist_ok=True)
+        session_file = os.path.join(session_dir, "session.json")
+        with open(session_file, "w") as f:
+            json.dump(self._store.session.to_dict(), f)
+            f.write("\n")
+
+    def _accept_loop(self) -> None:
+        while self._running:
+            try:
+                if self._server is None:
+                    break
+                conn, _ = self._server.accept()
+                threading.Thread(
+                    target=self._handle_conn, args=(conn,), daemon=True
+                ).start()
+            except socket.timeout:
+                continue
+            except OSError:
+                break
+
+    def _handle_conn(self, conn: socket.socket) -> None:
+        try:
+            data = b""
+            while True:
+                chunk = conn.recv(4096)
+                if not chunk:
+                    break
+                data += chunk
+                while b"\n" in data:
+                    line, data = data.split(b"\n", 1)
+                    if not line.strip():
+                        continue
+                    self._handle_request(conn, line)
+        except OSError:
+            pass
+        finally:
+            conn.close()
+
+    def _handle_request(self, conn: socket.socket, line: bytes) -> None:
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError:
+            return
+
+        req_id = req.get("id", "")
+        command = req.get("command", "")
+
+        if command == "push":
+            # Push entries from external sources
+            entries = req.get("entries", [])
+            if isinstance(entries, list):
+                for entry in entries:
+                    self._store.push(entry)
+            resp = {"id": req_id, "ok": True, "data": []}
+        elif command == "status":
+            resp = {
+                "id": req_id,
+                "ok": True,
+                "data": [],
+                "session": self._store.session.to_dict(),
+            }
+        else:
+            filters = req.get("filters")
+            data = self._store.query(command, filters)
+            resp = {"id": req_id, "ok": True, "data": data}
+
+        try:
+            conn.sendall(json.dumps(resp).encode() + b"\n")
+        except OSError:
+            pass
+
+    def stop(self) -> None:
+        """Stop the bridge and clean up socket/addr files."""
+        self._running = False
+        if self._server:
+            self._server.close()
+        if self._thread:
+            self._thread.join(timeout=2)
+
+        # Remove session file
+        try:
+            os.unlink(os.path.join(os.getcwd(), ".debugger", "session.json"))
+        except OSError:
+            pass
+
+        # Cleanup
+        if os.name != "nt":
+            try:
+                os.unlink(self._socket_path)
+            except OSError:
+                pass
+        else:
+            try:
+                addr_file = os.path.join(os.getcwd(), ".debugger", "bridge.addr")
+                os.unlink(addr_file)
+            except OSError:
+                pass