textual-debugger 0.2.0__tar.gz → 0.2.4__tar.gz

{textual_debugger-0.2.0 → textual_debugger-0.2.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.2.0
-Summary: A TUI Python debugger based on textual and debugpy
+Version: 0.2.4
+Summary: A TUI debugger for Python, Perl, and other languages.  Based on textual.
 Author-email: Al Danial <al.danial@gmail.com>
 License: textual-debugger is licensed to you under the MIT/X Consortium license:
         
@@ -39,11 +39,13 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Software Development :: Debuggers
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: textual>=8.0.0
@@ -51,7 +53,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"
@@ -68,8 +70,12 @@ Dynamic: license-file
 
 `textual-debugger` (the package) provides `tdb` (the command-line tool and module),
 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.
+with a Debug Adapter Protocol (DAP) implementation.  In addition to Python,
+`tdb` comes with built-in support for
+- C and C++ (via `gdb` or `lldb-dap`)
+- Perl (via `perl -d`)
+- Bash (via bash's own `DEBUG` trap; bash ≥ 4.4)
+- Tcsh (via source instrumentation of a stock `tcsh`)
 
 `tdb` is built with [textual](https://github.com/Textualize/textual) and speaks
 DAP to a pluggable debug adapter: [debugpy](https://github.com/microsoft/debugpy)
@@ -90,7 +96,9 @@ 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
+the richest feature set), C/C++ (via `gdb -i dap` or `lldb-dap`), Perl (via `perl -d`),
+Bash (via bash's own `DEBUG` trap), and Tcsh (via source instrumentation of a
+stock `tcsh`), 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.
@@ -194,6 +202,10 @@ tdb --lang python ./mytool
 # 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
 
@@ -232,21 +244,26 @@ python -m tdb my_program.py
 
 ## Multi-Language Debugging
 
-`tdb` debugs any language that has a Debug Adapter Protocol backend. Two
+`tdb` debugs any language that has a Debug Adapter Protocol backend. Five
 languages are supported out of the box:
 
-| Language | Adapter(s) | How to get the adapter | Feature level |
+| Language | Adapter(s) | Dependencies           | Feature level |
 |----------|------------|------------------------|---------------|
-| Python | `debugpy` (default) | installed with `textual-debugger` | everything in this README |
+| Python | `debugpy` (default) | Python ≥ 3.11 | 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) | perl ≥ 5.18 on PATH  | core debugging + remote attach |
+| Bash | bash-tdb (bundled) | bash ≥ 4.4 on PATH  | core debugging (no remote attach) |
+| Tcsh | tcsh-tdb (bundled) | tcsh on PATH | core debugging (no remote attach, no conditional breakpoints, no pause) |
 
 ### Language detection and selection
 
 The language is auto-detected from the debug target:
 
-1. File extension: `.py` → Python.
+1. File extension: `.py` → Python; `.pl` / `.pm` / `.t` → Perl; `.sh` / `.bash`
+   → Bash; `.csh` / `.tcsh` → Tcsh.
 2. Native executables (ELF, Mach-O, PE magic bytes) → C/C++.
-3. A `#!...python` shebang → Python.
+3. A `#!...python`, `#!...perl`, `#!...bash`, or `#!...csh`/`#!...tcsh`
+   shebang → Python / Perl / Bash / Tcsh 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.
@@ -278,15 +295,62 @@ 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
+Python-specific features are hidden or return "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,
-remote attach (`-r`), `--python`/`--pv`, `--no-subprocess`,
-automatic child-process attachment, and the post-mortem / `tdb.breakpoint()`
-hooks (those hooks live inside Python programs by nature). `--terminal` is
+`--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++, Bash, or Tcsh. `--terminal` is
 currently ignored for non-Python targets.
 
+**Bash limitations (v1):** the bash adapter uses bash's own `DEBUG` trap and
+has a smaller feature envelope than Python/Perl:
+
+- Debuggee code that installs its own `DEBUG` trap clobbers the harness;
+  debugging silently degrades to free-running.
+- No stopping inside subshells `(...)`, `$(...)`, or pipeline segments; they
+  execute normally.
+- Child bash processes run uninstrumented.
+- Outer-frame locals not inspectable (innermost frame only).
+- Pause is deferred while blocked in an external command.
+- `.sh` files that aren't bash are only diagnosed at launch, by bash itself
+  or the harness version check.
+- The `DEBUG` trap never fires on a function-definition line, so a
+  breakpoint on a `func() {` line never hits; entry and step-in stops land
+  on the first executable line of the function body instead.
+- The debug control channel occupies two inherited file descriptors
+  (typically high-numbered). A script that execs redirections onto those
+  exact fds (e.g. `exec 63>&-` or reusing them for its own I/O) will
+  silently break debugging.
+
+See [Bash](#bash) below for launch details.
+
+**Tcsh limitations (v1):** tcsh has no debug hooks at all, so the tcsh
+adapter debugs an instrumented temporary *copy* of the script (original
+paths and line numbers are preserved in everything tdb displays):
+
+- Conditional breakpoints are not supported; a condition set in the
+  Breakpoint View is ignored for tcsh (the breakpoint always stops).
+- No asynchronous pause: a free-running script stops only at the next
+  breakpoint (or when it exits).
+- A breakpoint binds to the nearest safe statement at or after the
+  requested line; unplaceable breakpoints are reported unverified.
+- Stack frames represent `source`d files, not native call frames, and only
+  literal `source` targets resolvable at launch are instrumented (computed
+  or `cd`-dependent sources run normally but are atomic to the debugger).
+- All frames show the same live shell state (Shell Variables, Environment,
+  Aliases, Arguments).  Stock tcsh keeps no per-frame history.
+- Multiple commands on one physical line (`a ; b`), command substitutions,
+  and external commands are atomic stepping units.
+- `$0` inside dynamically generated or evaluated text can expose the
+  generated copy's path (ordinary lexical `$0` is rewritten correctly).
+- Requires Python ≥ 3.11.
+
+See [Tcsh](#tcsh) below for launch details.
+
 ### C/C++ tips
 
 - Compile with `-g` (ideally `-g -O0`). If no breakpoint in a file can be
@@ -297,12 +361,183 @@ currently ignored for non-Python targets.
   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.
+  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`) so only need
+`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
+```
+
+**Compile-time code (`BEGIN` blocks):** Perl runs `BEGIN` blocks and the
+`use` statements that are themselves `BEGIN` blocks while it is still
+*compiling* your program, before stock `perl5db` ever stops. `tdb` arms the
+debugger ahead of compilation so that code is debuggable too, which means the
+first stop is the first **compile-time** statement of your file (typically
+`use strict;` near the top) rather than the first runtime statement. Step from
+there and you land inside your `BEGIN` blocks, with the stack and evaluate
+views working normally (local variable listing is limited at a compile-time
+stop); the `Stack` view shows the frame as `main::BEGIN`. Stepping through a
+`use` line takes a few steps (the pragma's
+own compile-time work happens in between) but you are never dragged into
+another module's internals.
+
+Two consequences worth knowing:
+
+- **Breakpoints are deferred while your program compiles.** During the compile
+  phase Perl has only parsed part of your file, so its line table is
+  incomplete and a breakpoint can't be verified yet. `tdb` holds such requests
+  and, while it single-steps through the rest of compilation, checks each
+  compile-time statement it lands on against them. A breakpoint placed
+  *inside* a `BEGIN` block fires there directly, on the first run, without
+  needing to be stepped into by hand. Conditional breakpoints work the same
+  way at compile time; a condition that itself errors behaves exactly like a
+  bad condition at runtime in that it does not fire. Two residual caveats: a
+  breakpoint on a non-statement line (the `BEGIN {` line itself, or a blank
+  line) never fires during the compile phase, since it's never actually
+  trapped as a statement; and `hitCondition` (break on the Nth hit) isn't
+  honored for a compile-time stop, only a plain `condition`.
+- **Startup is slower for large dependency graphs**, because the debugger is
+  active throughout compilation. A script with a big `use` tree takes
+  noticeably longer to reach its first stop under `tdb`.
+
+**`END` blocks** are entered with **step-in** (`s`). `next` and `continue` run
+straight past them to program termination, which is standard `perl5db`
+behavior, not a `tdb` limitation.
+
+**When your program dies:** an uncaught Perl error (`die`, or a fatal runtime
+error such as division by zero) opens the same error modal Python tracebacks
+get: the message, the call stack parsed from Perl's `at FILE line N.` /
+`... called at FILE line N` output, and Code View navigated to the failing
+line. This works for compile-time failures too, including a `die` inside a
+`BEGIN` block that aborts compilation. Press `e` in Code View to re-summon the
+last error. `tdb` also reports the debuggee's real exit status rather than
+assuming success.
+
+**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
+print "Waiting for tdb to attach on port 5678\n";
+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, for example:
+
+```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. Asynchronous pause (as Python gets via `debugpy`) needs a control channel
+`Devel::TdbRemote` doesn't implement yet; `pause` in attach mode returns a
+"not available" error instead of hanging.
+
+### Bash
+
+`tdb` bundles its own bash adapter (`bash-tdb`) so no separate adapter install
+needed, just a `bash` ≥ 4.4 on `PATH`. It drives stock bash's own `DEBUG`
+trap (with `extdebug` for return-value control) under the hood via a small
+harness script sourced through `BASH_ENV`, so it works with any bash already
+on the system.
+
+**Launching a script:**
+
+```bash
+tdb script.sh
+```
+
+Core debugging works as described above (breakpoints, stepping,
+continue/pause, stack, variables, evaluate console), with the v1 caveats
+listed in [What works for non-Python languages](#what-works-for-non-python-languages).
+Most notably, a breakpoint can't be set on a `func() {` line itself (the
+`DEBUG` trap never fires there), stops never land inside subshells or
+pipeline segments, child bash processes run uninstrumented, and only the
+innermost frame's locals are inspectable. There is no remote-attach mode for
+Bash.
+
+The Variables view shows three scopes for bash: Locals (innermost frame
+only), Globals (unexported shell variables), and Environment (exported
+variables, both inherited and script-`export`ed).
+
+### Tcsh
+
+`tdb` bundles its own tcsh adapter (`tcsh-tdb`) so no separate adapter
+is needed, just a stock `tcsh` on `PATH` (or
+`{"adapters": {"tcsh": "/path/to/tcsh"}}` in `config.json`). Stock tcsh has
+no debugger hooks, so the adapter instruments a temporary copy of the script
+(and of any literal `source`d files), runs it with `tcsh -f`, and
+coordinates stops through private FIFOs. tdb always shows the original
+source paths and line numbers; the generated copies are private adapter
+details and are cleaned up when the session ends.
+
+**Launching a script:**
+
+```bash
+tdb script.csh
+```
+
+Core debugging works as described above: line breakpoints, stepping
+(`next` steps over `source`d files, `stepIn` steps into instrumented ones),
+stack navigation across `source` nesting, variable inspection, and the
+evaluate console with the v1 caveats listed in
+[What works for non-Python languages](#what-works-for-non-python-languages),
+most notably: no conditional breakpoints, no pause of a free-running
+script, and stepping is per logical source line.
+
+The Variables view shows four scopes for tcsh: Shell Variables (`set`),
+Environment (`setenv`), Aliases, and Arguments (`argv`). All of them show
+the live state of the single tcsh process. The evaluate console executes
+text directly in the paused shell. It can inspect *and mutate* state
+(`set name = value` takes effect immediately), and a syntax error in
+evaluated text can terminate the debuggee; there is no isolation.
+
 ## Layout
 
 ```
@@ -446,8 +681,10 @@ Breakpoints persist across session restarts.
 
 ### Variable Inspection
 
-The Variable View shows a tree of scopes (Locals, Globals) with all variables in the current
-frame. Expand nodes to drill into complex objects.  Children are loaded lazily on demand.
+The Variable View shows a tree of scopes with all variables in the current frame. The scopes
+themselves are language-dependent: Locals, Globals, plus Environment for bash; Lexicals,
+Globals, Specials for Perl (see the [Bash](#bash) and [Perl](#perl) sections above for
+details). 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
@@ -893,6 +1130,40 @@ 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 including breakpoints (including `-k`/`-t` and persisted
+ones), stepping, continue/pause, Evaluate-console entries, stack-frame
+navigation, variable expansion, restart, quit. The session is
+written 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` 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 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
@@ -932,7 +1203,7 @@ client expects to launch servers.
 | 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}` |
+| Control | `control(action, timeout_s=30)` where `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()` |
@@ -1002,11 +1273,12 @@ 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 targets only) |
 | `--pv` | Shorthand for --python .venv/bin/python |
-| `--lang LANGUAGE` | Debuggee language (`python`, `cpp`); default: auto-detect from the target |
+| `--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
@@ -1035,8 +1307,17 @@ 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: