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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.2.0
+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"
@@ -194,6 +194,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
 
@@ -239,14 +243,15 @@ languages are supported out of the box:
 |----------|------------|------------------------|---------------|
 | 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.
+1. File extension: `.py` → Python; `.pl` / `.pm` / `.t` → Perl.
 2. Native executables (ELF, Mach-O, PE magic bytes) → C/C++.
-3. A `#!...python` shebang → Python.
+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.
@@ -282,9 +287,11 @@ 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,
-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++. `--terminal` is
 currently ignored for non-Python targets.
 
 ### C/C++ tips
@@ -303,6 +310,72 @@ currently ignored for non-Python targets.
   `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
 
 ```
@@ -893,6 +966,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 — 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
@@ -1002,11 +1109,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 +1143,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:

{textual_debugger-0.2.0/src/tdb → textual_debugger-0.2.2}/README.md

@@ -128,6 +128,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
 
@@ -173,14 +177,15 @@ languages are supported out of the box:
 |----------|------------|------------------------|---------------|
 | 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.
+1. File extension: `.py` → Python; `.pl` / `.pm` / `.t` → Perl.
 2. Native executables (ELF, Mach-O, PE magic bytes) → C/C++.
-3. A `#!...python` shebang → Python.
+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.
@@ -216,9 +221,11 @@ 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,
-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++. `--terminal` is
 currently ignored for non-Python targets.
 
 ### C/C++ tips
@@ -237,6 +244,72 @@ currently ignored for non-Python targets.
   `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
 
 ```
@@ -827,6 +900,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 — 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
@@ -936,11 +1043,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
@@ -969,8 +1077,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:

{textual_debugger-0.2.0 → textual_debugger-0.2.2}/pyproject.toml

@@ -25,7 +25,7 @@
       "pygments>=2.17.0",
       "fastapi>=0.115.0",
       "uvicorn>=0.30.0",
-      "mcp>=1.28.0",
+      "mcp>=1.28.0,<2.0.0",
 ]
 
   # extras needed to run the examples and tests
@@ -57,7 +57,7 @@
   where = ["src"]
 
   [tool.setuptools.package-data]
-  tdb = ["README.md"]
+  tdb = ["README.md", "adapters/perl/helpers.pl", "adapters/perl/Devel/TdbRemote.pm"]
 
   [tool.pytest.ini_options]
   testpaths = ["tests"]

{textual_debugger-0.2.0 → textual_debugger-0.2.2/src/tdb}/README.md

@@ -128,6 +128,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
 
@@ -173,14 +177,15 @@ languages are supported out of the box:
 |----------|------------|------------------------|---------------|
 | 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.
+1. File extension: `.py` → Python; `.pl` / `.pm` / `.t` → Perl.
 2. Native executables (ELF, Mach-O, PE magic bytes) → C/C++.
-3. A `#!...python` shebang → Python.
+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.
@@ -216,9 +221,11 @@ 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,
-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++. `--terminal` is
 currently ignored for non-Python targets.
 
 ### C/C++ tips
@@ -237,6 +244,72 @@ currently ignored for non-Python targets.
   `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
 
 ```
@@ -827,6 +900,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 — 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
@@ -936,11 +1043,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
@@ -969,8 +1077,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:

{textual_debugger-0.2.0 → textual_debugger-0.2.2}/src/tdb/__init__.py

@@ -1,6 +1,6 @@
 from tdb.breakpoint_hook import breakpoint
 from tdb.post_mortem import exception_hook
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"  # trailing digit odd == dev version
 
 __all__ = ["breakpoint", "exception_hook"]