abapgit-agent 1.9.0 → 1.10.0

package/README.md

@@ -150,6 +150,27 @@ abapgit-agent dump --date TODAY
 abapgit-agent dump --user DEVELOPER --date TODAY --detail 1
 ```
 
+### Debug Commands
+
+```bash
+# Set a breakpoint
+abapgit-agent debug set --files abap/zcl_my_class.clas.abap:42
+
+# Attach and debug interactively (human REPL)
+abapgit-agent debug attach
+
+# Attach in scripted AI mode — emits JSON on hit, starts background daemon
+abapgit-agent debug attach --json
+
+# Step, inspect variables, call stack (no --session needed)
+abapgit-agent debug step --type over --json
+abapgit-agent debug vars --json
+abapgit-agent debug stack --json
+
+# Always release the frozen work process when done
+abapgit-agent debug step --type continue --json
+```
+
 ### Utility Commands
 
 ```bash
@@ -193,6 +214,7 @@ npm run pull -- --url <git-url> --branch main
 | preview Command | [docs/preview-command.md](docs/preview-command.md) |
 | where Command | [docs/where-command.md](docs/where-command.md) |
 | dump Command | [docs/dump-command.md](docs/dump-command.md) |
+| debug Command | [docs/debug-command.md](docs/debug-command.md) |
 | ref Command | [docs/ref-command.md](docs/ref-command.md) |
 | REST API Reference | [API.md](API.md) |
 | Error Handling | [ERROR_HANDLING.md](ERROR_HANDLING.md) |

package/abap/CLAUDE.md

@@ -256,106 +256,138 @@ abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.cla
 
 ---
 
-### 9. Use `dump` Command to Investigate Runtime Errors (ST22)
+### 9. Troubleshooting ABAP Issues
 
-**When a user reports an ABAP runtime error, OR when any command returns HTTP 500 / an unexpected ABAP error, proactively check for short dumps.**
+Two commands are available for investigating bugs at runtime:
 
-```
-❌ WRONG: Ask user to open ST22 transaction manually
-❌ WRONG: Give up after an HTTP 500 without checking what caused it
-✅ CORRECT: Use abapgit-agent dump to query short dumps and find the root cause
-```
+| Command | Use when | What it gives you |
+|---------|----------|-------------------|
+| `dump`  | Error already occurred (ST22 crash) | Error type, call stack, exact source line |
+| `debug` | Need to trace logic step-by-step | Live variable values, step into/over, expand structures |
 
-#### When to Use `dump`
+#### When Something Goes Wrong — Start with `dump`
 
-| Scenario | Action |
-|----------|--------|
-| User reports "there was a dump in production" | `dump --user <user> --date TODAY` |
-| Any command returns HTTP 500 or unexpected error | `dump --date TODAY` (check for recent dumps) |
-| `pull` or `inspect` fails with internal ABAP error | `dump --date TODAY` |
-| Test run fails with runtime error | `dump --program <program> --date TODAY` |
-| Investigating TIME_OUT or other specific error | `dump --error TIME_OUT` |
-| Finding all errors from a specific user | `dump --user DEVELOPER` |
-| Full error analysis with source location | `dump --detail 1` (after listing) |
-
-#### Typical Investigation Workflow
+**First reflex** for any HTTP 500, runtime error, or user-reported crash:
 
 ```bash
-# Step 1: List recent dumps (last 7 days by default)
-abapgit-agent dump
+abapgit-agent dump --date TODAY           # list today's dumps
+abapgit-agent dump --date TODAY --detail 1  # full detail: call stack + source
+```
 
-# Step 2: Narrow by program or user if known
-abapgit-agent dump --program ZMY_PROGRAM --date TODAY
+The `--detail` output shows the exact failing line (`>>>>>` marker), call stack,
+and SAP's error analysis. Use it before asking the user to open ST22.
 
-# Step 3: View full details of the first result
-abapgit-agent dump --program ZMY_PROGRAM --date TODAY --detail 1
+Common filters:
+```bash
+abapgit-agent dump --user DEVELOPER --date TODAY        # specific user
+abapgit-agent dump --error TIME_OUT                     # specific error type
+abapgit-agent dump --program ZMY_PROGRAM --detail 1     # specific program, full detail
 ```
 
-The `--detail` output includes:
-- **What happened** — high-level error description
-- **Error analysis** — detailed SAP explanation
-- **Call stack** — method-by-method trace with line numbers
-- **Source with `>>>>>` marker** — exact line where the dump occurred
+After identifying the failing class/method, use `view` for broader context:
+```bash
+abapgit-agent view --objects ZCL_MY_CLASS
+```
+
+#### When There Is No Dump — Use `debug`
 
-#### Reading Detail Output
+Use `debug` when:
+- The bug is a logic error (wrong output, no crash)
+- You need to inspect variable values mid-execution
+- You want to verify which branch of code runs
 
+**Step 1 — set a breakpoint** on the first executable statement you want to inspect:
+```bash
+abapgit-agent debug set --files src/zcl_my_class.clas.abap:42   # from local file
+abapgit-agent debug set --objects ZCL_MY_CLASS:42                # by name (no local file needed)
+abapgit-agent debug list    # confirm it was registered
 ```
-  Short Dump Detail
 
-  Error       MESSAGE_TYPE_X
-  Date        2024-01-15 (Europe/Berlin)
-  Time        09:26:53
-  User        DEVELOPER
-  Program     ZMY_PROGRAM
+> **Line number must point to an executable statement** — not a comment, blank line,
+> `DATA` declaration, or `METHOD`/`ENDMETHOD`. Use `view --objects` to find valid lines.
 
-  What happened:
-  -------------------------------------------------------
-  A RAISE statement raised the exception "MESSAGE_TYPE_X".
+**Step 2 — attach and trigger**
 
-  Call stack:
-  -------------------------------------------------------
-    1  ZCL_MY_CLASS->DO_SOMETHING (line 42)
-    2  ZMY_PROGRAM START-OF-SELECTION (line 5)
+Two modes depending on context:
 
-  Source (ZCL_MY_CLASS=============CM003, line 42):
-  -------------------------------------------------------
-        METHOD do_something.
-          DATA lv_val TYPE i.
->>>>>     RAISE EXCEPTION TYPE cx_my_error.    ← error here
-          lv_val = lv_val + 1.
-        ENDMETHOD.
+*Interactive (human in a terminal):*
+```bash
+# Terminal 1 — attach (blocks waiting for breakpoint, opens REPL on hit)
+abapgit-agent debug attach
+
+# Terminal 2 — trigger (any command that calls the backend)
+abapgit-agent unit --files src/zcl_my_class.clas.testclasses.abap
+abapgit-agent inspect --files src/zcl_my_class.clas.abap
 ```
 
-**After identifying the error location**, use `view` to understand the class context:
+*Scripted (AI / automation) — best practice: individual sequential calls:*
+
+Once the daemon is running and the session is saved to the state file, each
+`vars/stack/step` command is a plain standalone call — no bash script needed.
 
 ```bash
-# View the class/method where the dump occurred
-abapgit-agent view --objects ZCL_MY_CLASS
-```
+# Step 1: start attach listener in background (spawns a daemon, saves session to state file)
+abapgit-agent debug attach --json > /tmp/attach.json 2>&1 &
+sleep 2
 
-#### Filters Reference
+# Step 2: trigger in background — MUST stay alive for the whole session
+abapgit-agent unit --files src/zcl_my_class.clas.testclasses.abap > /tmp/trigger.json 2>&1 &
 
-```bash
-# Filter by user
-abapgit-agent dump --user DEVELOPER
+# Step 3: poll until breakpoint fires and session JSON appears in attach output
+SESSION=""
+for i in $(seq 1 30); do
+  sleep 0.5
+  SESSION=$(grep -o '"session":"[^"]*"' /tmp/attach.json 2>/dev/null | head -1 | cut -d'"' -f4)
+  [ -n "$SESSION" ] && break
+done
 
-# Filter by date (system timezone)
-abapgit-agent dump --date TODAY
-abapgit-agent dump --date YESTERDAY
-abapgit-agent dump --date 2024-01-01..2024-01-31
+# Step 4: inspect and step — each is an individual call, no --session needed
+abapgit-agent debug stack --json
+abapgit-agent debug vars  --json
+abapgit-agent debug vars  --expand LS_OBJECT --json
+abapgit-agent debug step  --type over --json
+abapgit-agent debug vars  --json
 
-# Filter by program
-abapgit-agent dump --program ZMY_PROGRAM
+# Step 5: ALWAYS release the ABAP work process before finishing
+abapgit-agent debug step --type continue --json
 
-# Filter by error type
-abapgit-agent dump --error TIME_OUT
-abapgit-agent dump --error MESSAGE_TYPE_X
+# Step 6: check trigger result
+cat /tmp/trigger.json
+rm -f /tmp/attach.json /tmp/trigger.json
+```
+
+> **Four rules for scripted mode:**
+> 1. `sleep 2` after starting attach — the listener must register on the server before the trigger fires
+> 2. Keep the trigger process alive in the background for the entire session — if it exits, the ABAP work process is released and the session ends
+> 3. Always finish with `step --type continue` — this releases the frozen work process so the trigger can complete normally
+> 4. **Never pass `--session` to `step/vars/stack`** — it bypasses the daemon IPC and causes `noSessionAttached`. Omit it and let commands auto-load from the saved state file.
 
-# Show full detail for result #N (combine with same filters)
-abapgit-agent dump --user DEVELOPER --date TODAY --detail 1
+**Step 3 — step through and inspect**
 
-# Use explicit timezone (e.g., for distributed teams)
-abapgit-agent dump --date TODAY --timezone Europe/Berlin
+*Interactive REPL commands (after `attach` without `--json`):*
+```
+  debug> v          — show all variables
+  debug> x LT_DATA  — expand a table or structure
+  debug> n          — step over
+  debug> s          — step into
+  debug> bt         — call stack
+  debug> q          — detach (program continues); kill — hard abort
+```
+
+*Scripted commands (after `attach --json`) — omit `--session`, commands auto-load from state file:*
+```bash
+abapgit-agent debug vars   --json                        # all variables
+abapgit-agent debug vars   --name LV_RESULT --json       # one variable
+abapgit-agent debug vars   --expand LT_DATA --json       # drill into table/structure
+abapgit-agent debug step   --type over --json            # step over
+abapgit-agent debug step   --type into --json            # step into
+abapgit-agent debug step   --type continue --json        # continue to next breakpoint / finish
+abapgit-agent debug stack  --json                        # call stack (shows which test method is active)
+```
+
+**Clean up** when done:
+```bash
+abapgit-agent debug delete --all
 ```
 
 ---

package/bin/abapgit-agent

@@ -51,6 +51,7 @@ async function main() {
     preview: require('../src/commands/preview'),
     where: require('../src/commands/where'),
     dump: require('../src/commands/dump'),
+    debug: require('../src/commands/debug'),
     ref: require('../src/commands/ref'),
     init: require('../src/commands/init'),
     pull: require('../src/commands/pull'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "main": "src/index.js",
   "files": [
@@ -34,6 +34,11 @@
     "test:cmd:preview": "node tests/run-all.js --cmd --command=preview",
     "test:cmd:tree": "node tests/run-all.js --cmd --command=tree",
     "test:cmd:dump": "node tests/run-all.js --cmd --command=dump",
+    "test:cmd:debug": "node tests/run-all.js --cmd --command=debug",
+    "test:debug:scenarios": "bash tests/integration/debug-scenarios.sh",
+    "test:debug:scenarios:1": "bash tests/integration/debug-scenarios.sh 1",
+    "test:debug:scenarios:2": "bash tests/integration/debug-scenarios.sh 2",
+    "test:debug:scenarios:3": "bash tests/integration/debug-scenarios.sh 3",
     "test:cmd:upgrade": "node tests/run-all.js --cmd --command=upgrade",
     "test:lifecycle": "node tests/run-all.js --lifecycle",
     "test:pull": "node tests/run-all.js --pull",