@i-scope/debugger 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog — @i-scope/debugger
+
+All notable changes to this package will be documented here. The format
+is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-05-19
+
+### Added
+
+- Initial public release. Meta-package umbrella for the iScope Debugger SDK.
+- Direct dependencies: `@i-scope/mcp-server@^0.4.0`, `@i-scope/dap-adapter@^0.2.0`.
+- Transitively brings in `iscope-bridge-client`, `iscope-bridge` (Win32 binary),
+  `source-map-bridge`, `vlst-parser`, `com-protocol-types`.
+- No runtime code of its own; install convenience only.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iScope
+
+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,111 @@
+# @i-scope/debugger
+
+[![npm version](https://img.shields.io/npm/v/%40i-scope%2Fdebugger.svg?label=npm)](https://www.npmjs.com/package/@i-scope/debugger)
+[![npm downloads](https://img.shields.io/npm/dm/%40i-scope%2Fdebugger.svg)](https://www.npmjs.com/package/@i-scope/debugger)
+[![License: MIT](https://img.shields.io/npm/l/%40i-scope%2Fdebugger.svg)](./LICENSE)
+[![Node](https://img.shields.io/node/v/%40i-scope%2Fdebugger.svg)](#)
+
+Official single-install entry point for the **iScope Debugger SDK** —
+the open-source toolkit for debugging Oscilloscope.exe `.ajs` (JScript
+ES3) scripts. This is a pure **meta-package**: it ships no runtime
+code, just a curated set of `dependencies` that transitively pull in
+every piece of the SDK (DAP adapter, MCP server, Win32 native helper,
+source-map / VLST / COM-protocol leaves).
+
+## Quick install
+
+```bash
+npm install @i-scope/debugger
+```
+
+That's it. After install you can import from any of the underlying
+packages — `@i-scope/mcp-server`, `@i-scope/dap-adapter`,
+`@i-scope/iscope-bridge-client`, etc. — without listing them
+individually in your own `package.json`.
+
+## Who should install this
+
+| Persona | Recommended install | Entry point |
+|---------|---------------------|-------------|
+| AI agent through MCP | `@i-scope/debugger` (full set) | `import ... from '@i-scope/mcp-server'`; or wire `.cursor/mcp.json` |
+| DAP host integration (WebStorm, Neovim DAP, custom IDE) | `@i-scope/debugger` (full set) | `import { AjsDebugSession } from '@i-scope/dap-adapter'` |
+| CLI / custom Node tooling | `@i-scope/debugger` (full set) OR point-pick `@i-scope/iscope-bridge-client` standalone | `import { IScopeBridge } from '@i-scope/iscope-bridge-client'` |
+| VS Code / Cursor end-user | **Do NOT install this.** Install the `.vsix` extension from Marketplace — it bundles everything. | F5 in `.ajs` / `.ts` files |
+
+Note that `@i-scope/debugger` (this package, published on **npmjs.com**)
+and the unscoped `iscope-debugger` (the VS Code / Cursor extension
+published on the **Visual Studio Marketplace** and OpenVSX) are two
+different artefacts living on two different registries with two
+different audiences — there is no name collision. End-users install
+the extension; SDK consumers install this meta-package.
+
+## What's inside
+
+Installing `@i-scope/debugger` transitively brings in the full SDK
+(2 direct deps + 5 transitive):
+
+- [`@i-scope/mcp-server`](https://www.npmjs.com/package/@i-scope/mcp-server) *(direct dep)* — MCP server exposing 21 debugger tools to AI agents (16 debug + 4 UI modal + 1 system preflight).
+- [`@i-scope/dap-adapter`](https://www.npmjs.com/package/@i-scope/dap-adapter) *(direct dep)* — DAP server (`AjsDebugSession`) for IDE integrations; ships both a stand-alone stdio server (`npx iscope-debug-server`) and an embeddable class.
+- [`@i-scope/iscope-bridge-client`](https://www.npmjs.com/package/@i-scope/iscope-bridge-client) *(transitive)* — Node JSON-RPC client to the native helper; exports `IScopeBridge`, `resolveHelperPath`, OSC_NOT_FOUND detector, VLST helpers.
+- [`@i-scope/iscope-bridge`](https://www.npmjs.com/package/@i-scope/iscope-bridge) *(transitive)* — Win32 native helper `iScopeBridge.exe` (JSON-RPC stdio → COM bridge to Oscilloscope.exe). Binary-only tarball.
+- [`@i-scope/source-map-bridge`](https://www.npmjs.com/package/@i-scope/source-map-bridge) *(transitive)* — bidirectional TS ↔ AJS source-map manager (inline / sidecar / implicit, webpack:// URLs).
+- [`@i-scope/vlst-parser`](https://www.npmjs.com/package/@i-scope/vlst-parser) *(transitive)* — pure-TypeScript parser for Oscilloscope VLST blobs (the wire format for locals / Watch).
+- [`@i-scope/com-protocol-types`](https://www.npmjs.com/package/@i-scope/com-protocol-types) *(transitive)* — COM constants mirror (DISPID, GSTID, RTID, STEPACT, BRKREASON) — TS dzeркало of `Constants.h`.
+
+`@i-scope/dap-adapter` is listed as a direct dep (in addition to being
+transitive through `@i-scope/mcp-server`) so the DAP-only persona gets
+a clean top-level `npm update @i-scope/dap-adapter`.
+
+## Prerequisites
+
+This SDK targets **Windows only** (the `iScopeBridge.exe` helper is
+Win32 native, and `Oscilloscope.exe` is a Windows COM server). Before
+the debugger can attach to a running Oscilloscope you need:
+
+- Windows 10 / 11.
+- [Oscilloscope.exe](https://gitlab.com/i-scope/Debugger) installed
+  and running with a `.mwf` waveform loaded.
+- Machine Debug Manager (MDM) registered — i.e. `pdm.dll` present
+  under `HKCR\CLSID\{0BB89CE8-...}`. Install via "Windows Script
+  Debugger" or via the legacy `script56.exe` package.
+- Node.js ≥ 20 in your host process.
+
+See the [root README](https://gitlab.com/i-scope/Debugger/-/blob/main/README.md)
+of the monorepo for the full Prerequisites section, including
+preflight diagnostics (`debug_preflight_check` / `system_preflight_check`
+MCP tools) that verify the above and return a structured verdict.
+
+## Quick start — MCP integration (most common path)
+
+After `npm install @i-scope/debugger`, point your MCP client (Cursor,
+Claude Code, …) at the bundled server. Example `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "iscope-debugger": {
+      "command": "npx",
+      "args": ["-y", "@i-scope/mcp-server"]
+    }
+  }
+}
+```
+
+The AI agent now has access to all 21 MCP tools — `debug_launch`,
+`debug_set_breakpoints`, `debug_step_into`, `debug_variables`,
+`debug_snapshot`, `debug_resolve_source`, `ui_modal_list`,
+`system_preflight_check`, … See
+[`@i-scope/mcp-server` README](https://www.npmjs.com/package/@i-scope/mcp-server)
+for the full tool reference.
+
+## Documentation
+
+- Monorepo: <https://gitlab.com/i-scope/Debugger>
+- [Root README](https://gitlab.com/i-scope/Debugger/-/blob/main/README.md) — Prerequisites + project layout.
+- [`AGENTS.md`](https://gitlab.com/i-scope/Debugger/-/blob/main/AGENTS.md) — AI session orientation guide.
+- [`info/Plan.md`](https://gitlab.com/i-scope/Debugger/-/blob/main/info/Plan.md) — overall architecture and project plan.
+- [`info/Naming-Taxonomy.md`](https://gitlab.com/i-scope/Debugger/-/blob/main/info/Naming-Taxonomy.md) — npm scope taxonomy across iScope products (why this package is named `@i-scope/debugger` rather than `iscope-sdk` or `@iscope/*`).
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@i-scope/debugger",
+  "version": "0.2.0",
+  "license": "MIT",
+  "description": "iScope Debugger — meta-package. Single-install entry point for the full debugger SDK: DAP adapter for IDE integrations, MCP server for AI agents, Win32 native helper bridge, source-map / VLST / COM-protocol building blocks. Pure dependency umbrella; no runtime code of its own.",
+  "keywords": [
+    "iscope-debugger",
+    "iscope",
+    "i-scope",
+    "debugger",
+    "ajs",
+    "jscript",
+    "oscilloscope",
+    "autoscope",
+    "dap",
+    "mcp",
+    "sdk",
+    "meta-package"
+  ],
+  "homepage": "https://gitlab.com/i-scope/Debugger",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/i-scope/Debugger.git",
+    "directory": "packages/debugger"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/i-scope/Debugger/-/issues"
+  },
+  "files": [
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "win32"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@i-scope/mcp-server": "^0.4.2",
+    "@i-scope/dap-adapter": "^0.2.2"
+  }
+}