feat: add DAP debugger for argsh scripts (#98)

## Summary

Adds a Debug Adapter Protocol (DAP) server (`argsh-dap`) that enables
step-through debugging of argsh/bash scripts in VSCode. Uses bash's
built-in `DEBUG` trap — no bashdb or external dependencies required.

## Features

### Core DAP
- Breakpoints (file:line) with runtime updates
- Stepping: step in (F11), step over (F10), step out (Shift+F11),
continue (F5)
- Stack trace via `FUNCNAME`/`BASH_LINENO`/`BASH_SOURCE`
- Named pipe (FIFO) communication between debugger and bash process

### argsh-specific enhancements (#92-#97)
| Feature | Issue | Description |
|---------|-------|-------------|
| Smart breakpoints | #92 | Set breakpoints by subcommand name —
resolves through `:usage` namespace chain |
| Args inspector | #93 | "argsh Args" scope shows structured `:args`
definitions with field types |
| Auto-launch configs | #94 | Generate launch configs for all subcommand
paths from `:usage` tree |
| Import-aware resolution | #95 | Smart breakpoints search imported
files via the shared resolver |
| Variable tooltips | #96 | Hover shows argsh type annotations (`:~int`,
`:+`, etc.) |
| Command tree breakpoints | #97 | Function breakpoints use `:usage`
resolution |

### VSCode extension
- `argsh` debug type registered with launch config schema
- Auto-detect `argsh-dap` binary (bundled or PATH)
- Default "Debug Current File" config with `stopOnEntry`
- Configuration snippet for `launch.json`

### Architecture

```
VSCode ←── DAP (stdin/stdout) ──→ argsh-dap
                                      │
                                      ├── analyzes script via argsh_syntax
                                      ├── spawns bash with DEBUG trap prelude
                                      └── communicates via named pipes (FIFOs)
```

No `dap` crate — hand-rolled DAP types with `serde_json` (both available
crates are stale/alpha).

## Files changed

| File | Description |
|------|-------------|
| `crates/argsh-lsp/Cargo.toml` | Add `libc` dep, `[[bin]] argsh-dap` |
| `crates/argsh-lsp/src/bin/argsh-dap.rs` | DAP server binary (~600
lines) |
| `crates/argsh-lsp/tests/dap_integration.rs` | 8 integration tests |
| `vscode-argsh/src/debugProvider.ts` | Debug adapter factory + config
provider |
| `vscode-argsh/src/extension.ts` | Register debug provider |
| `vscode-argsh/package.json` | Debugger contributions, breakpoints,
settings |
| `docs/development/tools/debugger.mdx` | User documentation |
| `docs/sidebars.js` | Sidebar entry under Tools |

## Tests
- 8 DAP integration tests: version/help, initialize capabilities,
threads, breakpoints, configurationDone, scopes with argsh Args
- All 135 existing tests pass (55 LSP + 27 lint + 26 syntax + 19 unit +
8 DAP)
- Extension compiles clean

## Test plan
- [x] `cargo test --release` — all 135 tests pass
- [x] `npm run compile` — extension compiles
- [x] `argsh-dap --version` / `--help` works
- [ ] Manual testing: F5 in VSCode with a script, breakpoints, stepping

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: fentas

README.md

@@ -185,7 +185,7 @@ Runtime
 | Command | What it does | Backed by |
 |---|---|---|
 | [`argsh test`](https://arg.sh/development/fundamentals/test) | Run `.bats` tests; auto-discovers tests via `PATH_TESTS` | [bats-core](https://github.com/bats-core/bats-core) |
-| [`argsh lint`](https://arg.sh/development/fundamentals/lint) | Lint all shell files in your project | [shellcheck](https://www.shellcheck.net/) |
+| [`argsh lint`](https://arg.sh/development/fundamentals/lint) | Lint all shell files (shellcheck + argsh-lint) | [shellcheck](https://www.shellcheck.net/) + [argsh-lint](https://arg.sh/development/fundamentals/lint) |
 | [`argsh coverage`](https://arg.sh/development/fundamentals/coverage) | Generate a coverage report with a minimum threshold | [kcov](https://github.com/SimonKagstrom/kcov) |
 | [`argsh docs`](https://arg.sh/development/fundamentals/docs) | Generate Markdown docs from `@description` comments | [shdoc](https://github.com/reconquest/shdoc) |
 | [`argsh minify`](https://arg.sh/development/fundamentals/minify) | Bundle + minify + obfuscate a multi-file project into a single script | native Rust minifier |
@@ -286,9 +286,9 @@ Run `bash bench/usage-depth.sh` to reproduce.
 
 ### 🧩 IDE Support
 
-argsh includes a **Language Server** and **VSCode/Windsurf extension** for rich IDE support:
+argsh includes a **Language Server**, **CLI linter**, **debugger**, and **VSCode/Windsurf extension** for a complete development experience:
 
-- **Diagnostics** — 10 checks (AG001–AG010) with shellcheck-style suppression (`# argsh disable=AG004`)
+- **Diagnostics** — 12 checks (AG001–AG013) with shellcheck-style suppression (`# argsh disable=AG004`)
 - **Completions** — modifiers, types (built-in + custom), annotations, library functions (`is::`, `to::`, `string::`, ...)
 - **Help preview** — hover over functions to see generated `--help` output
 - **Go to definition** — Ctrl+Click on usage entries, `:-` mappings, `:~custom` types, imports
@@ -301,25 +301,35 @@ argsh includes a **Language Server** and **VSCode/Windsurf extension** for rich
 
 Works alongside shellcheck — argsh handles framework-specific validation, shellcheck handles general bash.
 
+**CLI Linter** (`argsh-lint`) — standalone binary with shellcheck-compatible flags for CI pipelines:
+
 ```bash
-# Build from source
-cd crates/argsh-lsp && cargo build --release
-cd vscode-argsh && npm install && npm run compile
+argsh-lint script.sh                        # gcc-style output
+argsh-lint --format=json --severity=warning  # JSON for CI
+argsh lint                                   # runs both shellcheck + argsh-lint
+argsh lint --only-argsh                      # argsh-lint only
 ```
 
-See the [LSP docs](https://arg.sh/development/tools/lsp) for configuration and full feature reference.
-
- 
+See the [Lint docs](https://arg.sh/development/fundamentals/lint) for the full flag reference.
 
-### 🚧 State of this Project
+**Debugger** (`argsh-dap`) — step-through debugging via VSCode with no external dependencies:
 
-> This project is in a very early stage.
+- **Breakpoints** — file:line, conditional (`(( i == 3 ))`), and by subcommand name
+- **Stepping** — step in (F11), step over (F10), step out (Shift+F11)
+- **Call stack** — full `FUNCNAME`/`BASH_SOURCE` trace with argsh namespace resolution
+- **Variable inspection** — argsh Args inspector shows `:args` field definitions with types
+- **Watch expressions** and **set variable at runtime**
+- **Subshell support** — `$()`, pipes, `{ ...; } &` don't deadlock
 
-That being said, most of it is quite rough. But it's a start. The best time that you join the conversation and try to refine the concept.
+Uses bash's built-in `DEBUG` trap — no `bashdb` required. See the [Debugger docs](https://arg.sh/development/tools/debugger).
 
-#### Short term goals
+```bash
+# Build from source
+cd crates/argsh-lsp && cargo build --release  # builds argsh-lsp, argsh-lint, argsh-dap
+cd vscode-argsh && npm install && npm run compile
+```
 
-- [ ] Bash debugger integration (e.g. with `bashdb`)
+See the [LSP docs](https://arg.sh/development/tools/lsp) for configuration and full feature reference.
 
  
 

crates/argsh-lsp/Cargo.toml

@@ -19,6 +19,13 @@ path = "src/main.rs"
 name = "argsh-lint"
 path = "src/bin/argsh-lint.rs"
 
+# Debug Adapter Protocol (DAP) server for step-through debugging of argsh
+# scripts. Uses bash's DEBUG trap for breakpoints and stepping — no bashdb
+# dependency required.
+[[bin]]
+name = "argsh-dap"
+path = "src/bin/argsh-dap.rs"
+
 [dependencies]
 argsh-syntax = { path = "../argsh-syntax" }
 tower-lsp = "0.20"
@@ -27,7 +34,10 @@ serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 dashmap = "6"
 regex = "1"
+tempfile = "3"
+
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
 
 [dev-dependencies]
-tempfile = "3"
 serde_json = "1"

crates/argsh-lsp/coverage.json

@@ -21,6 +21,20 @@
       "total_lines": "401",
       "excluded_lines": "0"
     },
+    {
+      "file": "crates/argsh-lsp/tests/dap_integration.rs",
+      "percent_covered": "99.31",
+      "covered_lines": "286",
+      "total_lines": "288",
+      "excluded_lines": "0"
+    },
+    {
+      "file": "crates/argsh-lsp/tests/dap_e2e.rs",
+      "percent_covered": "99.30",
+      "covered_lines": "426",
+      "total_lines": "429",
+      "excluded_lines": "0"
+    },
     {
       "file": "crates/argsh-lsp/src/format.rs",
       "percent_covered": "97.30",
@@ -84,6 +98,13 @@
       "total_lines": "408",
       "excluded_lines": "0"
     },
+    {
+      "file": "crates/argsh-lsp/src/bin/argsh-dap.rs",
+      "percent_covered": "78.38",
+      "covered_lines": "667",
+      "total_lines": "851",
+      "excluded_lines": "0"
+    },
     {
       "file": "crates/argsh-syntax/src/usage.rs",
       "percent_covered": "77.78",
@@ -141,12 +162,12 @@
       "excluded_lines": "0"
     }
   ],
-  "percent_covered": "79.45",
-  "covered_lines": 4915,
-  "total_lines": 6186,
+  "percent_covered": "81.17",
+  "covered_lines": 6294,
+  "total_lines": 7754,
   "excluded_lines": 0,
   "percent_low": 25,
   "percent_high": 75,
   "command": "cargo-test+llvm-cov",
-  "date": "2026-04-16 21:47:52"
+  "date": "2026-04-18 18:03:55"
 }