@roblourens/dap-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Lourens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# dap-cli
+
+Give your agent debugging skills!
+
+A command-line debugger built for AI agents. Drive any [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) target — Node.js, Python, Chrome, custom adapters — from shell commands, with stable JSON output and `.vscode/launch.json` support.
+
+```bash
+npm install -g dap-cli
+```
+
+## Why
+
+Agents already know how to run shell commands. They don't know how to drive an IDE debugger. `dap-cli` closes that gap so an agent can:
+
+- **Set breakpoints, step, and inspect variables** in any runtime with a DAP adapter — no ad-hoc `console.log` campaigns or re-building the program for every new question.
+- **Reuse your `.vscode/launch.json` configs** — `dap-cli launch --config "Launch App"` runs the same configuration you'd pick from the Run and Debug picker in VS Code.
+- **Coordinate with other tools like [`playwright-cli`](https://www.npmjs.com/package/@playwright/cli)** — Playwright drives the page, dap-cli polls the debugger, both attached to the same Chromium instance.
+
+## Install the CLI
+
+```bash
+npm install -g dap-cli
+dap-cli --version
+```
+
+The first time the agent uses an adapter, dap-cli provisions it (js-debug binary; a Python venv with debugpy). See [docs/adapter-setup.md](docs/adapter-setup.md) for custom adapters and troubleshooting.
+
+## Install the agent skill
+
+The repo includes an [Open Plugins](https://open-plugins.com/) plugin. The [SKILL.md](dap-cli/skills/dap-cli/SKILL.md) at the root teaches your agent how to use the CLI — common commands, the polling loop, breakpoint verification, and language-specific gotchas for `js-debug` and `debugpy`.
+
+**VS Code (Copilot Chat agent mode):**
+
+1. Run **Chat: Install Plugin from Source**.
+2. Enter `roblourens/dap-cli`.
+
+**Claude Code / Copilot CLI / other Open Plugins hosts:**
+
+```text
+/plugin install roblourens/dap-cli
+```
+
+## Quick taste
+
+The philosophy: drive the target with explicit commands, poll `status` for state changes, every reply is a JSON envelope. Pass `--human` for human-readable output.
+
+```bash
+# launch a Node script paused at entry
+dap-cli launch --program app.js --stop-on-entry
+
+# set a breakpoint, continue, poll until paused
+dap-cli breakpoints set --source app.js --line 12
+dap-cli continue
+dap-cli status
+
+# inspect — IDs come from these calls, never guess
+dap-cli stack
+dap-cli scopes --frame-id 1000
+dap-cli variables --variables-reference 1001
+dap-cli evaluate --expression "user.email"
+```
+
+## Use your existing `launch.json`
+
+If the project has `.vscode/launch.json`, run a config by name:
+
+```bash
+# discover available configs (bare list, not envelope)
+dap-cli launch --list-configs
+
+# run a named config
+dap-cli attach --config "Attach to App"
+
+# layer extra fields onto a named config without abandoning it
+dap-cli launch --config "Attach to App" \
+  --json-overrides '{"sourceMaps":true,"resolveSourceMapLocations":["**","!**/node_modules/**"]}'
+```
+
+`--workspace` defaults to the current directory; pass it explicitly to point at a different repo. Compounds and most VS Code launch variables (`${workspaceFolder}`, `${env:NAME}`, etc.) are supported. See [docs/adapter-setup.md](docs/adapter-setup.md) for the full list.
+
+## Multiple sessions
+
+dap-cli is able to be running several debug sessions at once. Pass `--name <session>` to target one explicitly; when omitted, commands act on the active session (the most recent one, or whatever was set with `dap-cli use <name>`).
+
+```bash
+dap-cli launch --program api.js --name api
+dap-cli launch --program worker.js --name worker
+dap-cli status --name api
+dap-cli close api
+```
+
+## Going deeper
+
+Most of what an agent needs lives in [the SKILL.md](dap-cli/skills/dap-cli/SKILL.md). For longer-form material:
+
+| Doc | What it covers |
+|---|---|
+| [docs/adapter-setup.md](docs/adapter-setup.md) | Built-in adapter readiness; configuring custom stdio / socket adapters; supported launch variables |
+| [docs/playwright-interop.md](docs/playwright-interop.md) | Driving Chromium UI with `playwright-cli` while dap-cli polls — setup order, fixed CDP port, conditional breakpoints |
+
+## Building from source
+
+```bash
+git clone https://github.com/roblourens/dap-cli
+cd dap-cli
+npm install
+npm run build
+node dist/index.js --version
+```
+
+`npm run check` runs typecheck, lint, tests, and build.
+
+## License
+
+MIT