@i-scope/iscope-bridge-client

Part of the @i-scope/debugger SDK — one of seven leaf packages aggregated by the @i-scope/debugger meta-umbrella. Most users should install the meta (npm install @i-scope/debugger), which transitively pulls this package in together with the DAP adapter and MCP server. Install @i-scope/iscope-bridge-client directly only when you talk to the native helper at the raw JSON-RPC level without DAP / MCP on top — e.g. one-shot CLI tools that just need OpenFile / GetStatus, or custom non-debug automation.

Node.js JSON-RPC client for iScopeBridge.exe — the native helper that bridges JSON-RPC stdio to COM/OLE Automation calls on Oscilloscope.exe.

This is the client side of the bridge. The server side (iScopeBridge.exe binary) ships in @i-scope/iscope-bridge, which this package pulls in as a dependency — so a single npm install @i-scope/iscope-bridge-client gives you both.

Install

npm install @i-scope/iscope-bridge-client

Windows only (the helper is a Win32 native binary).

Quick start

import {
    IScopeBridge,
    resolveHelperPath,
} from '@i-scope/iscope-bridge-client';

const bridge = new IScopeBridge({
    helperPath: resolveHelperPath(),       // finds the bundled .exe
    onStderr:   (chunk) => console.error(chunk),
});

await bridge.start();
const info = await bridge.initialize({ autoLaunch: true });
console.log(`connected to Oscilloscope.exe (pid=${info.pid})`);

bridge.on('trace', (e) => console.log(`[${e.level}] ${e.text}`));

await bridge.openFile({ path: 'C:/Oscillograms/test.mwf' });
await bridge.executeFile({ file: 'C:/scripts/probe.ajs' });

// ... later
await bridge.shutdown({ closePolicy: 'ifWeLaunched' });
await bridge.stop();

API surface

IScopeBridge

JSON-RPC peer that owns one iScopeBridge.exe child process. Promise API for requests, EventEmitter for unsolicited notifications:

| Request | Returns | |--------------------------------------|--------------------------| | ping(echo?) | echoed object | | initialize({ autoLaunch?, oscPath? }) | InitializeResult | | shutdown({ closePolicy? }) | ShutdownResult | | getStatus() | StatusResult | | openFile({ path }) | OpenFileResult | | executeFile({ file, breakpoints? }) | ExecuteFileResult | | setBreakpoint({ line, set }) | null | | resumeExec({ action }) | null | | getStackContent({ req, list }) | StackContentResult |

| Event | Payload | |--------------------|--------------------------| | trace | TraceEvent | | stop | (no payload) | | breakHit | BreakHitEvent | | error | ScriptErrorEvent | | breakpointErrors | BreakpointErrorsEvent | | rpc-error | Error | | exit | child exit code |

resolveHelperPath(opts?)

Three-tier resolver for the helper binary path:

1. userOverride (explicit setting / launch.json field) — wins.
2. bundledRoot/bin/iScopeBridge.exe — when the caller bundles its own copy (e.g. a VS Code extension passing ctx.extensionPath).
3. The installed @i-scope/iscope-bridge package — found via Node's module resolver.

launchMsgNeedsOscPrompt(msg)

Pure detector — returns true when the helper's error message contains OSC_NOT_FOUND. UI (Browse / Open Settings prompt) is left to the caller; this is the protocol layer only.

VLST helpers

parseVlst, decodeVlstBase64, packEvalReqData, dumpVlst — re- exported from @i-scope/vlst-parser for ergonomic single-import usage.

Related packages

This package is one of seven leaves of the @i-scope/debugger SDK meta-umbrella. The full family:

| Package | Role | |---------|------| | @i-scope/debugger | meta — one-install entry point for the whole SDK | | @i-scope/mcp-server | MCP server for AI agents (22 tools) | | @i-scope/dap-adapter | DAP server (AjsDebugSession) — embeddable + stdio | | @i-scope/iscope-bridge-client (you are here) | Node JSON-RPC client to the native helper | | @i-scope/iscope-bridge | Win32 native helper binary (iScopeBridge.exe) | | @i-scope/source-map-bridge | TS ↔ AJS source-map manager | | @i-scope/vlst-parser | Parser for VLST locals/Watch blobs | | @i-scope/com-protocol-types | TS-mirror of COM DISPID / event constants |

License

MIT — see LICENSE.

Repository

Part of the iScope Debugger monorepo: https://gitlab.com/i-scope/Debugger