textual-debugger 0.1.5__tar.gz → 0.2.2__tar.gz

{textual_debugger-0.1.5 → textual_debugger-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.1.5
+Version: 0.2.2
 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,7 +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
+Requires-Dist: mcp<2.0.0,>=1.28.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -67,12 +67,18 @@ Dynamic: license-file
 # `textual-debugger`
 
 `textual-debugger` (the package) provides `tdb` (the command-line tool and module),
-a full-featured terminal-based Python debugger.
-
-`tdb` is built with [textual](https://github.com/Textualize/textual)
-and [debugpy](https://github.com/microsoft/debugpy) (the Debug Adapter Protocol engine behind
-VS Code's Python debugger). It provides a rich interactive interface for stepping through code,
-inspecting variables, managing breakpoints, and evaluating expressions in complex Python programs.
+a full-featured terminal-based debugger for Python and other languages
+with a Debug Adapter Protocol (DAP) implementation. C and C++ support (via
+`gdb` or `lldb-dap`) is built in.
+
+`tdb` is built with [textual](https://github.com/Textualize/textual) and speaks
+DAP to a pluggable debug adapter: [debugpy](https://github.com/microsoft/debugpy)
+(the engine behind VS Code's Python debugger) for Python,
+[GDB's DAP mode](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Debugger-Adapter-Protocol.html) or
+[lldb-dap](https://lldb.llvm.org/resources/lldbdap.html)
+for compiled code. It provides a rich interactive interface for stepping through
+code, inspecting variables, managing breakpoints, and evaluating expressions in
+complex programs.
 
 - PyPI: https://pypi.org/project/textual-debugger/
 - GitHub: https://github.com/AlDanial/tdb
@@ -83,6 +89,10 @@ MIT License.  Copyright 2026 by Al Danial.
 
 `tdb`:
 
+- debugs multiple languages through the Debug Adapter Protocol: Python (via `debugpy`,
+the richest feature set) and C/C++ (via `gdb -i dap` or `lldb-dap`), with the language
+auto-detected from the target (ref. [Multi-Language Debugging](#multi-language-debugging)).
+
 - supports debugging of synchronous, asynchronous, multi-threaded, and multi-process Python code.
 It specifically supports modules
     - `asyncio` (with a built-in async task inspector and task wait graph)
@@ -169,11 +179,25 @@ tdb my_program.py
 # debug with arguments
 tdb my_program.py arg1 arg2
 
+# debug a C/C++ (or other native) executable built with -g.  The ELF/Mach-O/PE
+# binary is auto-detected and debugged through GDB's DAP mode (GDB >= 14)
+tdb ./myprog arg1 arg2
+
+# same, but using lldb-dap (LLVM >= 17) instead of gdb
+tdb --adapter lldb-dap ./myprog
+
+# force the language when auto-detection can't tell (e.g. an extensionless script)
+tdb --lang python ./mytool
+
 # add breakpoints at lines 20 and 35 of `my_program.py` and line 14
 # of `module.py` (when -k is given, --no-stop-on-entry is set and the
 # program runs to the first breakpoint)
 tdb -k 20 -k 35 -k module.py:14 my_program.py arg1 arg2
 
+# run straight to line 20 without saving the breakpoint for future
+# sessions (-t is -k minus the persistence)
+tdb -t 20 my_program.py
+
 # use a specific virtualenv
 tdb --python /path/to/venv/bin/python my_program.py
 
@@ -210,6 +234,148 @@ Alternatively, use the module entry point:
 python -m tdb my_program.py
 ```
 
+## Multi-Language Debugging
+
+`tdb` debugs any language that has a Debug Adapter Protocol backend. Two
+languages are supported out of the box:
+
+| Language | Adapter(s) | How to get the adapter | Feature level |
+|----------|------------|------------------------|---------------|
+| Python | `debugpy` (default) | installed with `textual-debugger` | everything in this README |
+| C / C++ (any native binary) | `gdb` (default), `lldb-dap` (alternate) | `gdb -i dap` requires GDB ≥ 14; `lldb-dap` ships with LLVM ≥ 17 (e.g. `apt install lldb`) | core debugging: breakpoints, stepping, stack, variables, evaluate console |
+| Perl | perl-tdb (bundled) | needs perl ≥ 5.18 on PATH (or `{"adapters": {"perl": ...}}`) | core debugging + remote attach |
+
+### Language detection and selection
+
+The language is auto-detected from the debug target:
+
+1. File extension: `.py` → Python; `.pl` / `.pm` / `.t` → Perl.
+2. Native executables (ELF, Mach-O, PE magic bytes) → C/C++.
+3. A `#!...python` or `#!...perl` shebang → Python / Perl respectively.
+4. C/C++/Rust *source* files (`.c`, `.cpp`, `.rs`, …) produce an error with a
+   hint: compile with debug info (`g++ -g -O0`) and debug the binary.
+5. Anything else produces an error naming the `--lang` override.
+
+`--lang` forces the language; `--adapter` picks a non-default adapter within
+it (`tdb --lang cpp --adapter lldb-dap ./myprog`).
+
+> **Migration note:** extensionless Python scripts without a `python` shebang
+> were previously assumed to be Python; they now require `--lang python`.
+
+### Adapters are found on `PATH`
+
+`tdb` does not download or bundle adapters. If the adapter executable isn't
+found, the error names the package to install. To use an adapter from a
+non-standard location, or change a language's default adapter, add to
+`config.json` (see [Configuration](#configuration)):
+
+```json
+{
+  "adapters": {"lldb-dap": "/opt/llvm/bin/lldb-dap"},
+  "default_adapters": {"cpp": "lldb-dap"}
+}
+```
+
+### What works for non-Python languages
+
+Core debugging works identically for every language: breakpoints (incl.
+conditions and persistence), stepping, continue/pause, run-to-cursor, stack
+navigation, variable inspection, the evaluate console, syntax highlighting,
+and the JSON-RPC / MCP programmatic modes.
+
+Python-specific features are hidden or return a clear "not supported for this
+language" message when debugging other languages: statement-granularity
+stepping (non-Python languages always step per line), the async task /
+process inspectors and wait graph, the evaluate console's trailing-`?` help,
+`--python`/`--pv`, `--no-subprocess`, automatic child-process attachment, and
+the post-mortem / `tdb.breakpoint()` hooks (those hooks live inside Python
+programs by nature). Remote attach (`-r`) also works for Perl (see
+[Perl](#perl) — `Devel::TdbRemote` in place of `debugpy.listen()`), but not
+for C/C++. `--terminal` is
+currently ignored for non-Python targets.
+
+### C/C++ tips
+
+- Compile with `-g` (ideally `-g -O0`). If no breakpoint in a file can be
+  bound, `tdb` prints a console warning suggesting the program may lack
+  debug info.
+- Stack frames pointing into system libraries often have no source on disk;
+  the Code View shows a `<Could not read …>` placeholder while the stack,
+  variables, and evaluate console remain fully usable.
+- GDB (the default adapter) has the most complete libstdc++
+  pretty-printing. `lldb-dap` (via `--adapter lldb-dap`) also debugs
+  GCC-built binaries fine — DWARF is compiler-neutral.
+- **GDB evaluate-console quirk:** GDB's DAP treats REPL input as CLI
+  commands, so evaluate expressions with an explicit `print`, e.g.
+  `print x` rather than bare `x` (bare `x` collides with GDB's
+  examine-memory command). `lldb-dap` evaluates bare expressions directly.
+
+### Perl
+
+`tdb` bundles its own Perl adapter (`perl-tdb`) — no separate adapter install
+needed, just a `perl` ≥ 5.18 on `PATH`. It drives stock `perl5db` under the
+hood, so it works with any Perl already on the system.
+
+**Launching a script:**
+
+```bash
+tdb script.pl
+```
+
+**Remote attach:** useful when the Perl process is already running (a long-
+lived service, a process started by something other than `tdb`) or lives on
+another host/container. Add three lines to the target program, with the
+`use` line first so the debugger is armed before any of your code compiles:
+
+```perl
+use Devel::TdbRemote;                 # FIRST line of your program
+...
+Devel::TdbRemote::listen(5678);       # non-blocking
+Devel::TdbRemote::wait_for_client();  # blocks until tdb connects
+```
+
+Then attach from `tdb`, forcing the language since there's no local `program`
+argument for `tdb` to detect it from:
+
+```bash
+tdb --lang perl -r host:5678
+```
+
+**Arming caveat:** only code *compiled after* the debugger is armed can be
+stepped into or breakpointed. That's why `use Devel::TdbRemote;` must be the
+first line of the program. If you can't edit the first line (e.g. a wrapper
+script controls startup), arm it before Perl even parses your file instead:
+`perl -d:TdbRemote prog.pl`, or set `PERL5OPT=-d:TdbRemote` in the
+environment that launches the debuggee.
+
+**Copying the adapter to a remote host:** `Devel::TdbRemote` and its helper
+script are plain files, not a CPAN install — copy both onto the remote
+machine and point `PERL5LIB` at the directory that contains them:
+
+```bash
+# From a checkout or an installed wheel's site-packages/tdb/adapters/perl:
+scp -r Devel/TdbRemote.pm helpers.pl remote-host:/opt/tdb-perl/
+# On the remote host:
+export PERL5LIB=/opt/tdb-perl:$PERL5LIB
+```
+
+(`Devel/TdbRemote.pm` locates `helpers.pl` next to itself at runtime, so keep
+the two files in the same relative layout shown above — `helpers.pl` is a
+sibling of the `Devel/` directory, not inside it.)
+
+**PadWalker (optional but recommended):** inspecting lexical (`my`)
+variables in the *current* frame always works. Lexicals in outer/caller
+frames need the `PadWalker` module installed on the debuggee's Perl; without
+it, tdb falls back to a read-only pad walk that can't reach fully into
+enclosing scopes, and outer-frame variable listings degrade accordingly.
+Install with `cpanm PadWalker` (or your distro's package) for full fidelity.
+
+**Pause is unavailable in attach mode.** Launch-mode sessions (`tdb
+script.pl`) support pausing a running program at any time. Remote-attach
+sessions don't — debugpy-style asynchronous pause needs a control channel
+`Devel::TdbRemote` doesn't implement yet; `pause` in attach mode returns a
+clear "not available" error instead of hanging.
+
 ## Layout
 
 ```
@@ -238,7 +404,7 @@ The footer shows the most relevant keybindings for the current mode.
 ### Navigation and Keybindings
 
 
-The Code View shows syntax-highlighted Python source with line numbers.
+The Code View shows syntax-highlighted source (lexer chosen per language) with line numbers.
 A cursor line (blue) tracks your position; the current execution line is highlighted in gold.
 
 **View focus shortcuts (global):**
@@ -330,6 +496,9 @@ lands on `print(results)`, not on each interior sub-line of the `gather` call. S
 stops on each physical line--useful for inspecting how a complex expression is built up.
 The choice is saved to `~/.config/tdb/config.json`.
 
+Statement mode requires a source-language model and is currently Python-only;
+other languages always step per line (the Step Mode menu says so if you try).
+
 ### Breakpoints
 
 Click the gutter in the Code View to toggle a breakpoint, or press `b` in Debug mode.
@@ -387,6 +556,15 @@ interactive evaluation of expressions in the current scope:
 
 Variable values set here are reflected in the running code.
 
+### Cut / Paste
+
+Expression for the Evaluate Console are often copied from the Code View.
+Doing this in `tdb` differs from traditional terminal behavior, because `textual` applications
+capture mouse events for their own use.
+
+Instead, hold the `Shift` key while performing your conventional cut/paste keystrokes or mouse
+operation to get the expected behavior.
+
 ### Console Output
 
 The Console View captures stdout (normal text) and stderr (red text) from the debuggee
@@ -754,7 +932,7 @@ 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` | `[]` or `[timeout_s]` | Resume execution; on timeout returns `"still running — call pause or wait again"` (success) |
+| `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 |
@@ -788,12 +966,46 @@ 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.
 
+## Recording and replaying sessions
+
+`tdb --record session.jsonl prog.py` runs a normal TUI session and captures
+your debugging actions — breakpoints (including `-k`/`-t` and persisted
+ones), stepping, continue/pause, Evaluate-console entries, stack-frame
+navigation, variable expansion, restart, quit — to `session.jsonl` as
+JSON-RPC commands. Works with launch mode (any language) and `-r`
+remote attach.
+
+Replay it two ways:
+
+- `tdb --replay session.jsonl` — one command: launches the recorded
+  program headless, feeds every recorded command through the same RPC
+  dispatch `tdb --server` uses, and prints a transcript (recorded time,
+  command, verbatim result, interleaved program output). Exit code 0 iff
+  every command succeeded. Add `--timing` to reproduce the original
+  pacing, `--replay-timeout S` to bound each stop-wait (default 30 s).
+- Against a live server: start `tdb --server prog.py`, then feed line 2
+  onward of the file to `POST /rpc` — each line is already a valid
+  request body:
+
+      tail -n +2 session.jsonl | while read line; do
+          curl -s -X POST -H 'Content-Type: application/json' \
+               -d "$line" http://127.0.0.1:8150/rpc
+      done
+
+  (On Windows, an equivalent loop in Python: read the file, skip the
+  first line, `requests.post` each remaining line.)
+
+Not captured: pure viewing (scrolling, search, modals, thread/task
+lists), breakpoint enable/disable toggles, variable expansions when the
+adapter reports no `evaluateName` (currently the Perl adapter), and
+File > Open program switches.
+
 ## 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,
+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.
 
@@ -832,17 +1044,24 @@ client expects to launch servers.
 | 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
+`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.
 
+`debug_launch` accepts optional `lang` and `adapter` parameters mirroring the
+CLI's `--lang`/`--adapter`; when omitted, the language is auto-detected from
+`program`, so an agent can hand it a compiled binary directly. The
+`tasks`/`processes`/`wait_graph` tools stay registered for every language but
+return a structured "not supported when debugging C/C++"-style error for
+non-Python debuggees.
+
 ### Agent flow for a long-running step
 
 ```
 agent → control(action="continue", timeout_s=30)
-mcp   → "still running — call pause or wait again"
+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)"])
@@ -851,7 +1070,7 @@ 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`).
+policy; see `tdb/server/app.py`).
 
 ### Security caveat
 
@@ -860,22 +1079,23 @@ 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.
+a network (stdio transport only by design).
 
 ### Deferred / out of scope (v1)
 
-- SSE-style event push — `control` and `wait_for_stop` make polling
+- 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 / 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.
+- Multi-session: one debug session per MCP process.
 
 ## CLI Reference
 
 ```
 usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
            [--no-just-my-code] [--no-subprocess] [--python PYTHON] [--pv]
+           [--lang LANGUAGE] [--adapter ADAPTER]
            [--keybindings {default,vim,emacs}]
            [--terminal {xterm,konsole,gnome-terminal,ghostty,kitty,iterm2,warp,wezterm,terminator}]
            [--local-root PATH] [--remote-root PATH]
@@ -889,10 +1109,13 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | `--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. |
+| `-t`, `--to-line FILE:LINE|LINE` | Like `-k`, but the breakpoint is not saved to the breakpoints file — it just takes you to that spot in the code for this session (may be repeated). |
 | `--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 |
+| `--python PATH` | Python interpreter for the debuggee (Python targets only) |
 | `--pv` | Shorthand for --python .venv/bin/python |
+| `--lang LANGUAGE` | Debuggee language (`python`, `cpp`, `perl`); default: auto-detect from the target |
+| `--adapter ADAPTER` | Debug adapter within the language (e.g. `--lang cpp --adapter lldb-dap`); default: the language's standard adapter |
 | `--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. |
@@ -912,11 +1135,25 @@ On Windows, it uses `%APPDATA%\tdb\`.
 
 | File | Contents |
 |------|----------|
-| `config.json` | User preferences (keybinding scheme, color theme, step mode) |
+| `config.json` | User preferences (keybinding scheme, color theme, step mode, adapter overrides) |
 | `breakpoints.json` | Breakpoints from previous sessions, keyed by project directory |
 
+Adapter-related keys in `config.json`: `adapters` maps an adapter id to an
+executable path (`{"adapters": {"lldb-dap": "/opt/llvm/bin/lldb-dap"}}`), and
+`default_adapters` picks a language's default adapter
+(`{"default_adapters": {"cpp": "lldb-dap"}}`).
+
+**Perl is a special case:** `perl-tdb` is tdb's own bundled adapter (always
+found — it's Python code, not an external executable), so
+`adapters.perl` doesn't select an adapter binary. Instead it names the
+*Perl interpreter* tdb should spawn to run the debuggee:
+`{"adapters": {"perl": "/path/to/perl"}}`. Use this when the `perl` on
+`PATH` is too old (< 5.18) or you need a specific `perlbrew`/`plenv` version.
+
 Breakpoints are saved on exit and restored when debugging a program in the same
-directory. Each project's breakpoints are independent.
+directory. Each project's breakpoints are independent. Breakpoints set with
+`-t`/`--to-line` are the exception: they behave like `-k` breakpoints during
+the session but are never saved.
 
 **Step mode** (`step_mode` in `config.json`) controls how `n` (step over) and `s` (step
 into) handle multi-line source statements:
@@ -934,7 +1171,8 @@ fires as expected.
 ## Tech Stack
 
 - [textual](https://github.com/Textualize/textual) : TUI framework
-- [debugpy](https://github.com/microsoft/debugpy) : Debug Adapter Protocol implementation
+- [debugpy](https://github.com/microsoft/debugpy) : Debug Adapter Protocol implementation for Python
+- [gdb](https://sourceware.org/gdb/) / [lldb-dap](https://lldb.llvm.org/resources/lldbdap.html) : optional, user-installed DAP adapters for C/C++
 - [pygments](https://pygments.org/) : Syntax highlighting
 - [FastAPI](https://fastapi.tiangolo.com/) + [uvicorn](https://www.uvicorn.org/) : JSON-RPC server