/prismer-node-inspect-debugger

name: prismer-node-inspect-debugger
scope: coding
description: "Debug Node.js via --inspect + Chrome DevTools Protocol CLI."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [ linux, macos, windows ]
metadata:
  nativeReplaces: [ node-inspect-debugger ]
  hermes:
    tags: [ debugging, nodejs, node-inspect, cdp, breakpoints, ui-tui ]
    related_skills: [ systematic-debugging, python-debugpy ]
  requiresExplicitGrant: true

Prismer execution contract

This is the uniquely named `prismer-node-inspect-debugger` skill, adapted from Hermes. Use the actual tools exposed by the executing host; examples using terminal, process, delegate_task, vision_analyze or browser_* are not tool registrations. Missing dependencies do not hide this skill. Report command startup, version, account/permissions and task-specific live verification separately. Use task-owned artifact paths and existing user authorization; do not change shared accounts, Runtime/provider configuration, global security settings or unrelated work. See NOTICE.md and LICENSE for resource provenance. Runtime availability and upstream-entry suppression are owned by the integration layer.

Node.js Inspect Debugger

Overview

When `console.log` isn't enough, drive Node's built-in V8 inspector programmatically from the terminal. You get real breakpoints, step in/over/out, call-stack walking, local/closure scope dumps, and arbitrary expression evaluation in the paused frame.

Two tools, pick one:

• **`node inspect`** — built-in, zero install, CLI REPL. Best for quick poking.
• **`ndb` / CDP via `chrome-remote-interface`** — scriptable from Node/Python; best when you want to automate many breakpoints, collect state across runs, or debug non-interactively from an agent loop.

**Prefer `node inspect` first.** It's always available and the REPL is fast.

When to Use

• A Node test fails and you need to see intermediate state
• ui-tui crashes or behaves wrong and you want to inspect React/Ink state pre-render
• tui_gateway child processes (`_SlashWorker`, PTY bridge workers) misbehave
• You need to inspect a value in a closure that `console.log` can't reach without patching
• Perf: attach to a running process to capture a CPU profile or heap snapshot

**Don't use for:** things `console.log` solves in under a minute. Breakpoint-driven debugging is heavier; use it when the payoff is real.

Quick Reference: `node inspect` REPL

Launch paused on first line:

node inspect path/to/script.js
# or with tsx
node --inspect-brk $(which tsx) path/to/script.ts

The `debug>` prompt accepts:

| Command | Action | |---|---| | `c` or `cont` | continue | | `n` or `next` | step over | | `s` or `step` | step into | | `o` or `out` | step out | | `pause` | pause running code | | `sb('file.js', 42)` | set breakpoint at file.js line 42 | | `sb(42)` | set breakpoint at line 42 of current file | | `sb('functionName')` | break when function is called | | `cb('file.js', 42)` | clear breakpoint | | `breakpoints` | list all breakpoints | | `bt` | backtrace (call stack) | | `list(5)` | show 5 lines of source around current position | | `watch('expr')` | evaluate expr on every pause | | `watchers` | show watched expressions | | `repl` | drop into REPL in current scope (Ctrl+C to exit REPL) | | `exec expr` | evaluate expression once | | `restart` | restart script | | `kill` | kill the script | | `.exit` | quit debugger |

**In the `repl` sub-mode:** type any JS expression, including access to locals/closure variables. `Ctrl+C` exits back to `debug>`.

Attaching to a Running Process

When the process is already running (e.g. a long-lived dev server or the TUI gateway):

# 1. Send SIGUSR1 to enable the inspector on an existing process
kill -SIGUSR1 <pid>
# Node prints: Debugger listening on ws://127.0.0.1:9229/<uuid>

# 2. Attach the debugger CLI
node inspect -p <pid>
# or by URL
node inspect ws://127.0.0.1:9229/<uuid>

To start a process with the inspector from the beginning:

node --inspect script.js           # listen on 127.0.0.1:9229, keep running
node --inspect-brk script.js       # listen AND pause on first line
node --inspect=0.0.0.0:9230 script.js   # custom host:port

For TypeScript via tsx:

node --inspect-brk --import tsx script.ts
# or older tsx
node --inspect-brk -r tsx/cjs script.ts

Programmatic CDP (scripting from terminal)

When you want to automate — set many breakpoints, capture scope state, script a repro — use `chrome-remote-interface`:

npm i -g chrome-remote-interface        # or project-local
# Start your target:
node --inspect-brk=9229 target.js &

Driver script (save as `~/.hermes/cache/scratch/cdp-debug.js`):

const CDP = require('chrome-remote-interface');

(async () => {
  const client = await CDP({ port: 9229 });
  const { Debugger, Runtime } = client;

  Debugger.paused(async ({ callFrames, reason }) => {
    const top = callFrames[0];
    console.log(`PAUSED: ${reason} @ ${top.url}:${top.location.lineNumber + 1}`);

    // Walk scopes for locals
    for (const scope of top.scopeChain) {
      if (scope.type === 'local' || scope.type === 'closure') {
        const { result } = await Runtime.getProperties({
          objectId: scope.object.objectId,
          ownProperties: true,
        });
        for (const p of result) {
          // Only inspect pre-approved non-sensitive fields, never every local.
          if (['status', 'phase'].includes(p.name)) {
            console.log(`  ${scope.type}.${p.name} =`, p.value?.value);
          }
        }
      }
    }

    // Evaluate an expression in the paused frame
    const { result } = await Debugger.evaluateOnCallFrame({
      callFrameId: top.callFrameId,
      expression: 'typeof state',
    });
    console.log('state =', result.value ?? result.description);

    await Debugger.resume();
  });

  await Runtime.enable();
  await Debugger.enable();

  // Set a breakpoint by URL regex + li