Node Inspect Debugger

Node Inspect Debugger

Overview

console.log is a guess with a print statement attached — you have to already suspect where to look and what to print. A breakpoint inverts that: you stop the world at a line and read every local and closure variable in the frame, walk the call stack, and evaluate expressions in the paused context. When the bug lives in state a log can't cheaply reach — a closure captured three calls ago, a paused async frame, the Electron main process, the internals of a long-lived WebSocket server — the inspector is the tool.

This skill is the TOOL half of a pair; the METHOD is systematic-debugging (its Phase 1 "gather evidence" and Phase 3 "test one variable" are exactly when you reach for a breakpoint).

When to Use

Reach for the inspector when the state you need is expensive or impossible to log:

• The dashboard server (packages/server, TypeScript run directly via the native loader, or jiti on the PI_DASHBOARD_TS_LOADER=jiti opt-in) — request handlers whose failure depends on accumulated in-memory state.
• The restart orchestrator / PTY workers (restart-helper.ts) — a detached process whose closure state you can't console.log from the parent.
• Dual WebSocket server closure state — connection maps and buffers held in closures across the bridge and browser servers.
• The Electron main process — lifecycle/bootstrap state that never reaches a browser console.
• The bridge extension — code running inside every pi session, where adding logs means reloading every session.

If a single well-placed console.log would answer the question, use the log. The inspector earns its setup cost when the state is deep, closure-bound, or in a process you can't easily instrument.

Two tiers

Tier 1 — the node inspect REPL cheat-sheet

node inspect opens a REPL against the inspector. Core commands:

In repl mode you can read any in-scope variable by name — this is the fastest way to answer "what is x right now?".

Tier 2 — pi-dashboard native-loader launch (the default)

The dashboard server runs TypeScript directly (no dist/*.js build) through the Node-native loader @blackbelt-technology/pi-dashboard-shared/platform/native-ts-register.mjs (module.stripTypeScriptTypes, transform mode). Launch the target with the inspector and that register module:

node --inspect-brk=<port> --enable-source-maps --import <native-ts-register-url> cli.ts

Resolve the URL by package specifier, never by path arithmetic:

import { createRequire } from "node:module";
import { pathToFileURL } from "node:url";
const req = createRequire(process.argv[1] ?? import.meta.url);
const hook = pathToFileURL(req.resolve("@blackbelt-technology/pi-dashboard-shared/platform/native-ts-register.mjs")).href;

• Type erasure replaces types with whitespace, so .ts lines stay aligned for ordinary code; TS-only constructs that transform mode rewrites (enum, namespace, parameter properties) may shift columns. Keep --enable-source-maps on.
• The log header names the running loader: grep "launch (parent pid" ~/.pi/dashboard/server.log | tail -1.

Tier 2b — jiti launch (PI_DASHBOARD_TS_LOADER=jiti opt-in, spike-verified)

Under the jiti fallback (PI_DASHBOARD_TS_LOADER=jiti) the server runs TypeScript through jiti. Launch the target with the inspector and jiti's register hook:

node --inspect-brk=<port> --enable-source-maps --import <jiti-register-hook-url> cli.ts

• --inspect-brk=<port> halts at the very first line so you can set breakpoints before anything runs.
• --enable-source-maps is not required for line-level breakpoints (jiti is line-preserving, see pitfall below) but keep it: it gives exact column precision and correct Error.stack line numbers.