textual-debugger 0.1.2__tar.gz → 0.1.4__tar.gz

{textual_debugger-0.1.2 → textual_debugger-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.1.2
+Version: 0.1.4
 Summary: A TUI Python debugger based on textual and debugpy
 Author-email: Al Danial <al.danial@gmail.com>
 License: textual-debugger is licensed to you under the MIT/X Consortium license:
@@ -51,6 +51,7 @@ Requires-Dist: debugpy>=1.8.0
 Requires-Dist: pygments>=2.17.0
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: mcp>=1.28.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -88,9 +89,9 @@ It specifically supports modules
     - `threading` (with a thread inspector)
     - `multiprocessing` / `concurrent.futures` (with automatic child process attachment and a process inspector)
 
-- supports remote attachment to any debugpy-enabled Python program
+- supports remote attachment to debugpy-enabled Python programs
 
-- includes a JSON-RPC server mode for programmatic debug control, making it suitable for
+- includes a JSON-RPC server mode that enables programmatic debug control, making it suitable for
 automated, headless debugging workflows and AI-assisted debugging
 
 - can spawn the debuggee in an external terminal to enable debugging TUI applications
@@ -182,10 +183,20 @@ tdb --no-stop-on-entry my_program.py
 tdb --terminal xterm my_program.py
 
 # attach to a remote Python program that has a debugpy server on port 5678
-tdb -r remotehost:5678 my_program.py
+# (source code is automatically downloaded from the remote host)
+tdb -r remotehost:5678
 
-# prevent `argparse` confusion by separating `tdb` switches from
-# the debuggee switches by prefixing the debuggee with `--`
+# attach to a remote Python program that has a debugpy server on port 5678
+# and set a breakpoint where tdb and the remote program have the same
+# source code layout
+tdb -r remotehost:5678  -k my_program.py:42
+
+# attach to a remote Python program that has a debugpy server on port 5678
+# and set a breakpoint where code on the local host is at a different location
+# than code on the remote host
+tdb -r remotehost:5678 --local-root /my/code/dir --remote-root /app -k my_program.py:42
+
+# separate tdb arguments from debuggee arguments with `--` 
 tdb --python /path/to/venv/bin/python -- my_program.py -k 17 --max 23.3
 ```
 
@@ -199,7 +210,7 @@ python -m tdb my_program.py
 
 ```
 ┌─ Header ──────────────────────────────────────────────┐
-├─ Menu Bar (File | Configure | Help) ──────────────────┤
+├─ Menu Bar (File / Configure / Help)───────────────────┤
 │                           │                           │
 │   Code View               │  Console View (stdout)    │
 │   (source + breakpoints)  ├───────────────────────────┤
@@ -270,7 +281,7 @@ Switch from Navigate back to Debug mode with `Escape`.
 
 > **Note:** Many terminals send the byte sequence `ESC+f` for `Alt+F`, which Textual's
 ANSI parser rewrites to `Ctrl+Right` (the readline "forward-word" convention).
-`tdb` binds both so `Alt+F` works as expected regardless.
+`tdb` binds both so `Alt+F` works as expected.
 
 ### Debugging Controls
 
@@ -288,8 +299,10 @@ those for gdb/pdb, with some aliases and extras thrown in for convenience.
 | `u` / `d` | Navigate stack up (caller) / down (callee) |
 | `j` / `k` | Move cursor down / up (with count: `5j`, `10k`) |
 | `G` | Go to last line (with count: `42G` jumps to line 42) |
+| `e` | Re-display the last error (traceback) |
 | `R` | Restart the debug session |
-| `Ctrl+Q` | Quit |
+| `q q` | Quit |
+| `Ctrl+q` | Quit |
 
 > **Note:** `f` ("finish") and `r` ("return") are both aliases for step-out. DAP's only
 "exit-a-function" primitive is `stepOut`, which runs the rest of the current function
@@ -310,7 +323,7 @@ print(results)   # next stop lands here, not on each sub-line above
 
 lands on `print(results)`, not on each interior sub-line of the `gather` call. Switch to
 **Line** mode (Configure > Step Mode) to get debugpy's native per-line behavior, which
-stops on each physical line — useful for inspecting how a complex expression is built up.
+stops on each physical line--useful for inspecting how a complex expression is built up.
 The choice is saved to `~/.config/tdb/config.json`.
 
 ### Breakpoints
@@ -337,6 +350,11 @@ The Variable View shows a tree of scopes (Locals, Globals) with all variables in
 frame. Expand nodes to drill into complex objects.  Children are loaded lazily on demand.
 Variable values can be changed in the Evaluate Console.
 
+Double-click a variable, or highlight the variable with the text cursor in
+the Variables View and press `Enter`
+to display that variable in a modal.  This simplifies inspection of
+large or deeply nested data structures.
+
 ### Call Stack
 
 The Stack View shows the full call stack. Click a frame to navigate to its source
@@ -344,7 +362,8 @@ location and inspect its variables.
 
 ### Evaluate Console
 
-A REPL at the bottom-left evaluates expressions in the current scope:
+A read-evaluate-print loop (REPL) at the bottom left permits
+interactive evaluation of expressions in the current scope:
 
 ```
 >>> len(items)
@@ -370,8 +389,11 @@ The Console View captures stdout (normal text) and stderr (red text) from the de
 in real time.
 
 If your program prints a lot, or prompts for input, or uses colors or
-terminal control codes, consider running it in an external terminal
-with `--terminal` for the best experience.
+terminal control codes, run the program in an external terminal
+with `--terminal` for a better experience.
+The `--terminal` switch requires a graphical environment and a compatible
+terminal emulator.
+
 
 ### Crash Detection
 
@@ -381,6 +403,9 @@ When the debuggee raises an unhandled exception, `tdb`:
 3. Populates the Stack View with the exception's call stack
 4. Lets you press `R` to restart or `Escape` to dismiss
 
+> Note:  after dismissing the traceback modal, you
+> can display it again by hitting `e` when focus is in the Code View.
+
 ### Post-Mortem Exception Hook
 
 You can have `tdb` pop open automatically when *any* Python program crashes without the
@@ -389,7 +414,6 @@ need to launch through `tdb` up front. Install the hook once at the top of your
 ```python
 import sys
 import tdb
-
 sys.excepthook = tdb.exception_hook
 ```
 
@@ -407,11 +431,11 @@ In post-mortem mode you can:
 - Read the full traceback (including chained `cause`/`context` exceptions) in the Console View
 - Jump around the source with the full Code View (syntax highlighting, goto-line, etc.)
 
-Stepping, `continue`, breakpoints, restart, and Evaluate are disabled. The original
-interpreter is gone, the view is a frozen snapshot. Press `q` to exit.
+Stepping, continue, breakpoints, restart, and the Evaluate View are disabled. The original
+interpreter is gone since the view is a frozen snapshot. Press `q` to exit.
 
 The hook is a no-op when stdin/stdout aren't a tty (e.g. when your program is piped or
-run from cron), so it's safe to leave installed in production-style code. Snapshots are
+run from cron), so it is safe to leave installed in production code. Snapshots are
 written to a temp file that is deleted as soon as `tdb` exits.
 
 Snapshot depth / breadth is capped (5 levels, 50 children per container) to keep the
@@ -422,7 +446,6 @@ memoization.
 
 `tdb` has an improved implemenation of the standard `breakpoint()` function (or equivalently,
 `pdb.set_trace()`) used to pause at a specific line to inspect, then
-here=
 continuing--use `tdb.breakpoint()`:
 
 ```python
@@ -445,7 +468,7 @@ spawns `python -m tdb -r <port>` as a subprocess so the TUI takes over the termi
 and pauses the calling thread at the line that called `tdb.breakpoint()` (the hook
 auto-steps out of its own helper so you land in your own frame, not inside
 `breakpoint_hook.py`). Stepping (`n`/`s`/`o`), `continue`, and setting/removing breakpoints
-all work normally; quitting `tdb` (`Ctrl+Q`) detaches without killing the program, and
+all work normally; quitting `tdb` (`Ctrl+q`) detaches without killing the program, and
 debugpy auto-resumes any threads still paused.
 
 This differs from `tdb.exception_hook` in one way:
@@ -458,6 +481,12 @@ drive the user's program forward.
 As with `exception_hook`, the call is a no-op when stdin/stdout aren't a tty, so it's
 safe to leave in code paths that sometimes run headless.
 
+Quitting `tdb` while paused in a `tdb.breakpoint()` session detaches the debugger and
+lets the program continue running normally.
+This behavior matches hitting `c` while in a conventional (that is, the Python
+standard library's) `breakpoint()` session.
+If you want to kill the program instead, use `Ctrl+c` in the terminal running the debuggee.
+
 ### Async Task Inspector
 
 For programs using `asyncio`, the menu bar shows an **Async Tasks (N)** label with the count of
@@ -467,13 +496,17 @@ active tasks (updated each time the program stops). Click it to open a full-scre
   primitive (`Lock.acquire`, `Queue.get`, `asyncio.sleep`, …), and coroutine
 - **Right pane**: detail view with full stack trace and an expandable variable tree (same
 as the main Variables View) for the selected task
-- Press `g` to switch the right pane to the **wait graph** — a tree showing each blocked
+- Press `g` to switch the right pane to the **wait graph** which is a tree showing
+  each blocked
   task, the asyncio primitive it's parked on, and the task(s) holding that primitive.
   Cycles (deadlocks) are highlighted in red both in the task table and as a "Deadlock
   cycles" section at the top of the graph. Selecting a node in the tree highlights the
   corresponding task in the table.
 - Navigate with arrow keys; press `r` to refresh, `Escape` to close
 
+> Note:  Async task relationships may be directed acyclic graphs (DAGs) rather than trees
+> but I don't know of a way to visualize DAGs in textual.
+
 RPC equivalents:
 
 ```bash
@@ -585,6 +618,36 @@ All debugging features (breakpoints, stepping, variable inspection, threads, pro
 async tasks) work in remote attach mode. The Code View automatically navigates to the
 source file when the program stops.
 
+**Mapping remote paths to local copies (`--local-root` / `--remote-root`):** when the
+debuggee lives on another machine, or in a container, or simply in a different directory
+on the same machine, the source paths it reports (and the paths it expects breakpoints
+to refer to) won't match anything on the `tdb` host. To bridge that gap, give `tdb` one
+or more `--local-root` / `--remote-root` pairs. Each `--local-root` points at a local
+directory containing a copy of the code; each `--remote-root` is the corresponding path
+on the debuggee. The two flags must be supplied in equal numbers and are paired in CLI
+order via `zip()`, so the first `--local-root` matches the first `--remote-root`, the
+second matches the second, and so on. `debugpy` then translates paths bidirectionally:
+breakpoints set on a local file land on the matching remote file, and source paths
+returned in stopped-events / stack-traces are rewritten back to the local copy so the
+Code View loads directly from disk (no DAP `source` round-trip needed).
+
+These flags are required whenever you want to set a `-k` breakpoint against a remote
+debuggee whose code lives at a different path than your local copy. For example, if the
+remote runs `program.py` at `/path/to/code/program.py` and your local copy is at
+`/local/project/code/program.py`, set a breakpoint at line 321 with:
+
+```bash
+tdb -r RHOST:15678 \
+    --local-root /local/project/code \
+    --remote-root /path/to/code \
+    -k program.py:321
+```
+
+With `--local-root` set, a relative `-k FILE:LINE` is resolved by searching each
+`--local-root` directory in CLI order (first match wins); absolute paths still work as
+before. Multiple pairs can be supplied to mirror multiple source trees (e.g. an
+application directory and a shared library directory) in one invocation.
+
 ### External Terminal Support
 
 Some Python programs, notably text user interfaces, use terminal control
@@ -676,11 +739,12 @@ curl -s -X POST http://127.0.0.1:8150/rpc \
 | `set_breakpoint` | `["file:line"]` or `["file:line", "condition", "hit_condition"]` | Set a breakpoint |
 | `remove_breakpoint` | `["file:line"]` | Remove a breakpoint |
 | `list_breakpoints` | `[]` | Show all breakpoints |
-| `continue` | `[]` | Resume execution |
-| `next` | `[]` | Step over |
-| `step_in` | `[]` | Step into |
-| `step_out` | `[]` | Step out |
-| `pause` | `[]` | Pause execution |
+| `continue` | `[]` or `[timeout_s]` | Resume execution; on timeout returns `"still running — call pause or wait again"` (success) |
+| `next` | `[]` or `[timeout_s]` | Step over |
+| `step_in` | `[]` or `[timeout_s]` | Step into |
+| `step_out` | `[]` or `[timeout_s]` | Step out |
+| `pause` | `[]` | Pause execution; bypasses the dispatch lock so it can interrupt an in-flight blocking action |
+| `wait_for_stop` | `[]` or `[timeout_s]` | Wait for the next stop without issuing a step (use after `continue` returns `"still running"` to keep waiting) |
 | `inspect` | `["expr1", "expr2", ...]` | Evaluate multiple expressions |
 | `evaluate` | `["expression"]` | Evaluate a single expression |
 | `stack_up` | `[]` | Move up the call stack |
@@ -709,25 +773,111 @@ curl -N http://127.0.0.1:8150/events
 Events: `initialized`, `stopped`, `continued`, `terminated`, `exited`, `output`.
 Each is JSON with `event`, `data`, and `timestamp` fields.
 
+## MCP Integration
+
+tdb ships a Model Context Protocol (MCP) server (`tdb-mcp`) that exposes
+the debugger as a curated set of tools an AI agent can call. The MCP
+server is a third in-process consumer of the same dispatch handlers the
+TUI and the HTTP server use — so an agent gets the same lock semantics,
+including the pause-during-continue bypass, and the same DAP-backed
+inspection surface.
+
+For a worked end-to-end example (prompting an agent to find two
+runtime bugs in a sample program) see
+[docs/tutorial-mcp-debugging.md](docs/tutorial-mcp-debugging.md) and
+its companion `examples/sales_report_buggy.py`.
+
+### Running the MCP server
+
+Configure your MCP client (Claude Desktop, an IDE extension, etc.) to
+launch `tdb-mcp` over stdio. Example `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tdb": {
+      "command": "tdb-mcp"
+    }
+  }
+}
+```
+
+Three equivalent invocation forms: `tdb-mcp` (the dedicated entry
+point), `tdb --mcp` (the main CLI with the `--mcp` switch), and
+`python -m tdb.mcp` (module form). Pick whichever matches how your MCP
+client expects to launch servers.
+
+### Tool surface (16 tools, curated)
+
+| Cluster | Tools |
+|---------|-------|
+| Lifecycle | `debug_launch`, `debug_attach`, `quit` |
+| Control | `control(action, timeout_s=30)` — `action ∈ {continue, next, step_in, step_out, pause, wait_for_stop}` |
+| Inspection | `inspect(expressions)`, `read_source(file_path)`, `stack_trace()`, `status()`, `get_output()` |
+| Breakpoints | `set_breakpoint(spec, condition?, hit_condition?)`, `remove_breakpoint(spec)`, `list_breakpoints()` |
+| Differentiators | `threads(thread_id?)`, `tasks(task_name?)`, `processes(name_or_pid?)`, `wait_graph()` |
+
+`control` is intentionally one tool that takes an action enum — the six
+underlying RPC actions share a return shape, and agents perform
+measurably better with a small surface than with one tool per action.
+`threads` / `tasks` / `processes` overload list-vs-inspect via a
+single optional argument for the same reason.
+
+### Agent flow for a long-running step
+
+```
+agent → control(action="continue", timeout_s=30)
+mcp   → "still running — call pause or wait again"
+agent → control(action="pause")        # OR: control(action="wait_for_stop", timeout_s=30)
+mcp   → "<file>:<line>"
+agent → inspect(["x", "len(buf)"])
+mcp   → "x = 7\nlen(buf) = 1024"
+```
+
+`pause` bypasses the dispatch lock so it can interrupt a `continue`
+that's still mid-flight (HTTP and MCP share the same `NO_LOCK_ACTIONS`
+policy — see `tdb/server/app.py`).
+
+### Security caveat
+
+`inspect` calls debugpy's `evaluate`, which is **arbitrary Python
+execution in the debuggee process**. This is inherent to a debugger and
+not a tdb-specific concern, but MCP clients (and the humans running
+them) should apply appropriate permission models: don't auto-approve
+`inspect` against untrusted expressions, and don't expose `tdb-mcp` on
+a network — stdio transport only by design.
+
+### Deferred / out of scope (v1)
+
+- SSE-style event push — `control` and `wait_for_stop` make polling
+  efficient enough; events would also need uneven MCP-client support.
+- HTTP / streamable-HTTP transports — would require auth (which the
+  HTTP RPC server also currently lacks); stdio inherits the trust of
+  the process that spawned it.
+- Multi-session — one debug session per MCP process.
+
 ## CLI Reference
 
 ```
-usage: tdb [-h] [-v/--version] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
-           [--no-just-my-code] [--no-subprocess] [--python PYTHON]
-           [-d/--doc] [--doc-text] [--keybindings {default,vim,emacs}]
+usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
+           [--no-just-my-code] [--no-subprocess] [--python PYTHON] [--pv]
+           [--keybindings {default,vim,emacs}]
            [--terminal {xterm,konsole,gnome-terminal,ghostty,kitty,iterm2,warp,wezterm,terminator}]
-           [--server] [--headless] [-k FILE:LINE|LINE] [--server-port SERVER_PORT]
+           [--local-root PATH] [--remote-root PATH]
+           [--server] [--headless] [-k FILE:LINE|LINE] [--server-port SERVER_PORT] [-d] [--doc-text]
            [program] [args ...]
-
 ```
 
 | Flag | Description |
 |------|-------------|
 | `-r HOST:PORT` | Attach to a remote debugpy server |
+| `--local-root PATH` | Local directory containing a copy of remote code (repeat to mirror multiple trees). Pair with `--remote-root`; counts must match. Required when `-k` sets a breakpoint against a remote debuggee whose code lives at a different path. |
+| `--remote-root PATH` | Remote directory matched to `--local-root` (same CLI position via `zip()`). |
 | `-k`, `--breakpoint FILE:LINE|LINE` | Set a breakpoint (may be repeated). Passing `-k` implies `--no-stop-on-entry` so the program runs straight to the first breakpoint. |
 | `--no-stop-on-entry` | Do not pause at the first line (default: stop on entry; automatic when `-k` is given) |
 | `--cwd DIR` | Working directory for the debuggee |
 | `--python PATH` | Python interpreter for the debuggee |
+| `--pv` | Shorthand for --python .venv/bin/python |
 | `--no-just-my-code` | Step into stdlib/site-packages code instead of skipping it
   (default: skipped). On uncaught exceptions, the crash modal always shows the full traceback
   including library frames, regardless of this flag. |
@@ -759,7 +909,7 @@ into) handle multi-line source statements:
 | Value | Behavior |
 |-------|----------|
 | `"statement"` (default) | A multi-line statement (e.g. a `gather(...)` call spanning five lines) is one step. The debugger keeps issuing DAP steps until execution leaves the statement, then stops on the next logical line. |
-| `"line"` | debugpy's native per-line behavior — stops on every physical line, including each interior sub-line of a multi-line expression. |
+| `"line"` | debugpy's native per-line behavior (stops on every physical line, including each interior sub-line of a multi-line expression)|
 
 Change it from the menu (**Configure > Step Mode**); the choice is saved immediately and
 applies to all future sessions. Breakpoint hits, exceptions, and pauses always interrupt