abapgit-agent 1.8.9 → 1.10.0

package/README.md

@@ -144,6 +144,31 @@ abapgit-agent preview --objects SFLIGHT --compact
 abapgit-agent where --objects ZCL_MY_CLASS
 abapgit-agent where --objects ZIF_MY_INTERFACE
 abapgit-agent where --objects ZCL_MY_CLASS --type CLAS
+
+# Query short dumps (ST22)
+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
@@ -188,6 +213,8 @@ npm run pull -- --url <git-url> --branch main
 | view Command | [docs/view-command.md](docs/view-command.md) |
 | 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,6 +256,142 @@ abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.cla
 
 ---
 
+### 9. Troubleshooting ABAP Issues
+
+Two commands are available for investigating bugs at runtime:
+
+| 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 Something Goes Wrong — Start with `dump`
+
+**First reflex** for any HTTP 500, runtime error, or user-reported crash:
+
+```bash
+abapgit-agent dump --date TODAY           # list today's dumps
+abapgit-agent dump --date TODAY --detail 1  # full detail: call stack + source
+```
+
+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.
+
+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
+```
+
+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`
+
+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
+```
+
+> **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.
+
+**Step 2 — attach and trigger**
+
+Two modes depending on context:
+
+*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
+```
+
+*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
+# 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
+
+# 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 &
+
+# 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
+
+# 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
+
+# Step 5: ALWAYS release the ABAP work process before finishing
+abapgit-agent debug step --type continue --json
+
+# 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.
+
+**Step 3 — step through and inspect**
+
+*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
+```
+
+---
+
 ## Development Workflow
 
 This project's workflow mode is configured in `.abapGitAgent` under `workflow.mode`.
@@ -672,6 +808,13 @@ abapgit-agent view --objects ZTABLE --type TABL
 
 # Display package tree
 abapgit-agent tree --package \$MY_PACKAGE
+
+# Investigate runtime errors (ST22 short dumps)
+abapgit-agent dump                                          # Last 7 days
+abapgit-agent dump --user DEVELOPER --date TODAY           # Today's dumps for a user
+abapgit-agent dump --program ZMY_PROGRAM                   # Dumps from a specific program
+abapgit-agent dump --error TIME_OUT                        # Dumps by error type
+abapgit-agent dump --user DEVELOPER --detail 1             # Full detail of first result
 ```
 
 ---

package/bin/abapgit-agent

@@ -50,6 +50,8 @@ async function main() {
     view: require('../src/commands/view'),
     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.8.9",
+  "version": "1.10.0",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "main": "src/index.js",
   "files": [
@@ -33,6 +33,12 @@
     "test:cmd:view": "node tests/run-all.js --cmd --command=view",
     "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",