debugger: add edit-free runtime expression probes to node inspect

doc/api/debugger.md

@@ -90,6 +90,157 @@ steps to the next line. Type `help` to see what other commands are available.
 Pressing `enter` without typing a command will repeat the previous debugger
 command.
 
+## Probe mode
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+`node inspect` supports a non-interactive probe mode for inspecting runtime values
+in an application via the flag `--probe`. Probe mode launches the application,
+sets one or more source breakpoints, evaluates one expression whenever a
+matching breakpoint is hit, and prints one final report when the session ends
+(either on normal completion or timeout). This allows developers to perform
+printf-style debugging without having to modify the application code and
+clean up afterwards, and it supports structured output for tool use.
+
+```console
+$ node inspect [--json] [--preview] [--timeout=<ms>] [--port=<port>] \
+    --probe app.js:10 --expr 'x' \
+    [--probe app.js:20 --expr 'y' ...] \
+    [--] [<node-option> ...] <script.js> [args...]
+```
+
+* `--probe <file>:<line>[:<col>]`: Source location to probe. Line and column number
+  are 1-based.
+* `--timeout=<ms>`: A global wall-clock deadline for the entire probe session.
+  The default is `30000`. This can be used to probe a long-running application
+  that can be terminated externally.
+* `--json`: If used, prints a structured JSON report instead of the default text report.
+* `--preview`: If used, non-primitive values will include CDP property previews for
+  object-like JSON probe values.
+* `--port=<port>`: Selects the local inspector port used for the `--inspect-brk`
+  launch path. Probe mode defaults to `0`, which requests a random port.
+* `--` is optional unless the child needs its own Node.js flags.
+
+Additional rules about the `--probe` and `--expr` arguments:
+
+* `--probe <file>:<line>[:<col>]` and `--expr <expr>` are strict pairs. Each
+  `--probe` must be followed immediately by exactly one `--expr`.
+* `--timeout`, `--json`, `--preview`, and `--port` are global probe options
+  for the whole probe session. They may appear before or between probe pairs,
+  but not between a `--probe` and its matching `--expr`.
+
+If a single probe needs to evaluate more than one value,
+evaluate a structured value in `--expr`, for example `--expr "{ foo, bar }"`
+or `--expr "[foo, bar]"`, and use `--preview` to include property previews for
+any object-like values in the output.
+
+Probe mode only prints the final probe report to stdout, and otherwise silences
+stdout/stderr from the child process. If the child exits with an error after the
+probe session starts, the final report records a terminal `error` event with the
+exit code and captured child stderr. Invalid arguments and fatal launch or
+connect failures may still print diagnostics to stderr without a final probe
+result.
+
+Consider this script:
+
+```js
+// cli.js
+let maxRSS = 0;
+for (let i = 0; i < 2; i++) {
+  const { rss } = process.memoryUsage();
+  maxRSS = Math.max(maxRSS, rss);
+}
+```
+
+If `--json` is not used, the output is printed in a human-readable text format:
+
+```console
+$ node inspect --probe cli.js:5 --expr 'rss' cli.js
+Hit 1 at cli.js:5
+  rss = 54935552
+Hit 2 at cli.js:5
+  rss = 55083008
+Completed
+```
+
+Primitive results are printed directly, while objects and arrays use Chrome
+DevTools Protocol preview data when available. Other non-primitive values
+fall back to the Chrome DevTools Protocol `description` string.
+Expression failures are recorded as `[error] ...` lines and do not fail
+the overall session. If richer text formatting is needed, wrap the expression
+in `JSON.stringify(...)` or `util.inspect(...)`.
+
+When `--json` is used, the output shape looks like this:
+
+```console
+$ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
+{"v":1,"probes":[{"expr":"rss","target":["cli.js",5]}],"results":[{"probe":0,"event":"hit","hit":1,"result":{"type":"number","value":55443456,"description":"55443456"}},{"probe":0,"event":"hit","hit":2,"result":{"type":"number","value":55574528,"description":"55574528"}},{"event":"completed"}]}
+```
+
+```json
+{
+  "v": 1, // Probe JSON schema version.
+  "probes": [
+    {
+      "expr": "rss", // The expression paired with --probe.
+      "target": ["cli.js", 5] // [file, line] or [file, line, col].
+    }
+  ],
+  "results": [
+    {
+      "probe": 0, // Index into probes[].
+      "event": "hit", // Hit events are recorded in observation order.
+      "hit": 1, // 1-based hit count for this probe.
+      "result": {
+        "type": "number",
+        "value": 55443456,
+        "description": "55443456"
+      }
+      // If the expression throws, "error" is present instead of "result".
+    },
+    {
+      "probe": 0,
+      "event": "hit",
+      "hit": 2,
+      "result": {
+        "type": "number",
+        "value": 55574528,
+        "description": "55574528"
+      }
+    },
+    {
+      "event": "completed"
+      // The final entry is always a terminal event, for example:
+      // 1. { "event": "completed" }
+      // 2. { "event": "miss", "pending": [0, 1] }
+      // 3. {
+      //      "event": "timeout",
+      //      "pending": [0],
+      //      "error": {
+      //       "code": "probe_timeout",
+      //       "message": "Timed out after 30000ms waiting for probes: app.js:10"
+      //      }
+      //    }
+      // 4. {
+      //      "event": "error",
+      //      "pending": [0],
+      //      "error": {
+      //       "code": "probe_target_exit",
+      //       "exitCode": 1,
+      //       "stderr": "[Error: boom]",
+      //       "message": "Target exited with code 1 before probes: app.js:10"
+      //      }
+      //    }
+    }
+  ]
+}
+```
+
 ## Watchers
 
 It is possible to watch expression and variable values while debugging. On

lib/internal/debugger/inspect.js

@@ -5,12 +5,10 @@ const {
   ArrayPrototypeJoin,
   ArrayPrototypeMap,
   ArrayPrototypePop,
-  ArrayPrototypePushApply,
   ArrayPrototypeShift,
   ArrayPrototypeSlice,
   FunctionPrototypeBind,
   Number,
-  Promise,
   PromisePrototypeThen,
   PromiseResolve,
   Proxy,
@@ -20,91 +18,31 @@ const {
   StringPrototypeSplit,
 } = primordials;
 
-const { spawn } = require('child_process');
 const { EventEmitter } = require('events');
-const net = require('net');
 const util = require('util');
 const {
-  setInterval: pSetInterval,
   setTimeout: pSetTimeout,
 } = require('timers/promises');
-const {
-  AbortController,
-} = require('internal/abort_controller');
 
 const InspectClient = require('internal/debugger/inspect_client');
+const {
+  launchChildProcess,
+  writeUsageAndExit,
+} = require('internal/debugger/inspect_helpers');
+const {
+  startProbeMode,
+} = require('internal/debugger/inspect_probe');
 const createRepl = require('internal/debugger/inspect_repl');
 
 const debuglog = util.debuglog('inspect');
 
-const { ERR_DEBUGGER_STARTUP_ERROR } = require('internal/errors').codes;
 const {
   exitCodes: {
     kGenericUserError,
     kNoFailure,
-    kInvalidCommandLineArgument,
   },
 } = internalBinding('errors');
 
-async function portIsFree(host, port, timeout = 3000) {
-  if (port === 0) return; // Binding to a random port.
-
-  const retryDelay = 150;
-  const ac = new AbortController();
-  const { signal } = ac;
-
-  pSetTimeout(timeout).then(() => ac.abort());
-
-  const asyncIterator = pSetInterval(retryDelay);
-  while (true) {
-    await asyncIterator.next();
-    if (signal.aborted) {
-      throw new ERR_DEBUGGER_STARTUP_ERROR(
-        `Timeout (${timeout}) waiting for ${host}:${port} to be free`);
-    }
-    const error = await new Promise((resolve) => {
-      const socket = net.connect(port, host);
-      socket.on('error', resolve);
-      socket.on('connect', () => {
-        socket.end();
-        resolve();
-      });
-    });
-    if (error?.code === 'ECONNREFUSED') {
-      return;
-    }
-  }
-}
-
-const debugRegex = /Debugger listening on ws:\/\/\[?(.+?)\]?:(\d+)\//;
-async function runScript(script, scriptArgs, inspectHost, inspectPort,
-                         childPrint) {
-  await portIsFree(inspectHost, inspectPort);
-  const args = [`--inspect-brk=${inspectPort}`, script];
-  ArrayPrototypePushApply(args, scriptArgs);
-  const child = spawn(process.execPath, args);
-  child.stdout.setEncoding('utf8');
-  child.stderr.setEncoding('utf8');
-  child.stdout.on('data', (chunk) => childPrint(chunk, 'stdout'));
-  child.stderr.on('data', (chunk) => childPrint(chunk, 'stderr'));
-
-  let output = '';
-  return new Promise((resolve) => {
-    function waitForListenHint(text) {
-      output += text;
-      const debug = RegExpPrototypeExec(debugRegex, output);
-      if (debug) {
-        const host = debug[1];
-        const port = Number(debug[2]);
-        child.stderr.removeListener('data', waitForListenHint);
-        resolve([child, port, host]);
-      }
-    }
-
-    child.stderr.on('data', waitForListenHint);
-  });
-}
-
 function createAgentProxy(domain, client) {
   const agent = new EventEmitter();
   agent.then = (then, _catch) => {
@@ -139,9 +77,8 @@ class NodeInspector {
 
     if (options.script) {
       this._runScript = FunctionPrototypeBind(
-        runScript, null,
-        options.script,
-        options.scriptArgs,
+        launchChildProcess, null,
+        [options.script, ...options.scriptArgs],
         options.host,
         options.port,
         FunctionPrototypeBind(this.childPrint, this));
@@ -330,14 +267,14 @@ function parseArgv(args) {
 function startInspect(argv = ArrayPrototypeSlice(process.argv, 2),
                       stdin = process.stdin,
                       stdout = process.stdout) {
+  const invokedAs = `${process.argv0} ${process.argv[1]}`;
+
   if (argv.length < 1) {
-    const invokedAs = `${process.argv0} ${process.argv[1]}`;
+    writeUsageAndExit(invokedAs);
+  }
 
-    process.stderr.write(`Usage: ${invokedAs} script.js\n` +
-                         `       ${invokedAs} <host>:<port>\n` +
-                         `       ${invokedAs} --port=<port> Use 0 for random port assignment\n` +
-                         `       ${invokedAs} -p <pid>\n`);
-    process.exit(kInvalidCommandLineArgument);
+  if (startProbeMode(invokedAs, argv, stdout)) {
+    return;
   }
 
   const options = parseArgv(argv);

lib/internal/debugger/inspect_client.js

@@ -1,12 +1,14 @@
 'use strict';
 
 const {
+  ArrayPrototypeForEach,
   ArrayPrototypePush,
   ErrorCaptureStackTrace,
   FunctionPrototypeBind,
   JSONParse,
   JSONStringify,
   ObjectKeys,
+  ObjectValues,
   Promise,
 } = primordials;
 
@@ -224,6 +226,15 @@ class Client extends EventEmitter {
   }
 
   reset() {
+    const pending = this._pending;
+    if (pending) {
+      ArrayPrototypeForEach(ObjectValues(pending), (handler) => {
+        handler({
+          code: 'ERR_DEBUGGER_ERROR',
+          message: 'Debugger session ended',
+        });
+      });
+    }
     if (this._http) {
       this._http.destroy();
     }