if (typeof value !== 'string' || RegExpPrototypeExec(kDigitsRegex, value) === null) {

throw new ERR_DEBUGGER_STARTUP_ERROR(`Invalid ${name}: ${value}`);

}

const parsed = NumberParseInt(value, 10);

if (NumberIsNaN(parsed) || (!allowZero && parsed < 1)) {

throw new ERR_DEBUGGER_STARTUP_ERROR(`Invalid ${name}: ${value}`);

}

return parsed;

// Accepts file:line or file:line:column formats.

// Non-greedy (.+?) allows Windows drive-letter paths like C:\foo.js:10.

const match = RegExpPrototypeExec(/^(.+?):(\d+)(?::(\d+))?$/, text);

if (match === null) {

throw new ERR_DEBUGGER_STARTUP_ERROR(`Invalid probe location: ${text}`);

}

const suffix = match[1];

const line = parseUnsignedInteger(match[2], 'probe location');

// Column is left as undefined if the user does not supply one.

const column = match[3] !== undefined ? parseUnsignedInteger(match[3], 'probe location') : undefined;

return { suffix, line, column };

const seen = new SafeSet();

for (const probeIndex of pending) {

seen.add(formatTargetText(probes[probeIndex].target));

}

return ArrayPrototypeJoin(ArrayFrom(seen), ', ');

const lines = RegExpPrototypeSymbolSplit(/\r\n|\r|\n/g, stderr);

const kept = [];

for (let i = 0; i < lines.length; i++) {

const line = lines[i];

if (line === '' && i === lines.length - 1) { continue; }

if (line === kProbeDisconnectSentinel) { continue; }

if (line === kProbeAttachedSentinel) { continue; }

if (line === kProbeHelpLine) { continue; }

if (StringPrototypeStartsWith(line, kProbeListeningPrefix)) { continue; }

if (StringPrototypeStartsWith(line, kProbeEndingPrefix)) { continue; }

ArrayPrototypePush(kept, line);

}

return ArrayPrototypeJoin(kept, '\n');

if (property.type === 'string') {

return JSONStringify(property.value ?? '');

}

return property.value ?? property.type;

if (result === undefined || result === null || typeof result !== 'object') {

return result;

}

if (ArrayIsArray(result)) {

return ArrayPrototypeMap(result, trimRemoteObject);

}

const trimmed = { __proto__: null };

for (const { 0: key, 1: value } of ObjectEntries(result)) {

if (key === 'objectId' || key === 'className') {

continue;

}

trimmed[key] = trimRemoteObject(value);

}

return trimmed;

if (value === undefined || value === null || typeof value !== 'object') {

return value;

}

if (ArrayIsArray(value)) {

return ArrayPrototypeMap(value, stripProbePreviews);

}

const stripped = { __proto__: null };

for (const { 0: key, 1: entry } of ObjectEntries(value)) {

if (key === 'preview') {

continue;

}

stripped[key] = stripProbePreviews(entry);

}

return stripped;

if (result === undefined) { return 'undefined'; }

switch (result.type) {

case 'undefined':

return 'undefined';

case 'string':

return JSONStringify(result.value);

case 'number':

if (result.unserializableValue !== undefined) {

return result.unserializableValue;

}

return `${result.value}`;

case 'boolean':

return `${result.value}`;

case 'symbol':

return result.description || 'Symbol()';

case 'bigint':

return result.unserializableValue ?? result.description ?? '0n';

case 'function':

return result.description || 'function()';

case 'object':

if (result.subtype === 'null') {

return 'null';

}

if (result.subtype === 'error') {

return result.description || 'Error';

}

if (result.preview !== undefined) {

const properties = ArrayPrototypeJoin(ArrayPrototypeMap(

result.preview.properties,

result.preview.subtype === 'array' ?

(property) => formatPreviewPropertyValue(property) :

(property) => `${property.name}: ${formatPreviewPropertyValue(property)}`,

), ', ');

const suffix = result.preview.overflow ? ', ...' : '';

if (result.preview.subtype === 'array') {

return `[${properties}${suffix}]`;

}

return `{${properties}${suffix}}`;

}

return result.description || result.className || 'Object';

default:

return `${result.value ?? result.description ?? ''}`;

}

const lines = [];

for (const result of report.results) {

if (result.event === 'hit') {

const probe = report.probes[result.probe];

// If Debugger.scriptParsed was missed and the URL is unknown, fall back to the user's

// probe target text for readability. This is unlikely unless there's a bug in V8.

const locText = (result.location.url !== undefined) ?

formatHitLocation(result.location) : formatTargetText(probe.target);

ArrayPrototypePush(lines, `Hit ${result.hit} at ${locText}`);

if (result.error !== undefined) {

ArrayPrototypePush(lines, ` [error] ${probe.expr} = ${result.error.message}`);

} else {

ArrayPrototypePush(lines,

` ${probe.expr} = ` +

`${formatRemoteObject(result.result)}`);

}

continue;

}

if (result.event === 'completed') {

ArrayPrototypePush(lines, 'Completed');

continue;

}

if (result.event === 'miss') {

ArrayPrototypePush(lines,

`Missed probes: ` +

`${formatPendingProbeLocations(report.probes, result.pending)}`);

continue;

}

if (result.event === 'timeout') {

ArrayPrototypePush(lines, result.error.message);

continue;

}

if (result.event === 'error') {

ArrayPrototypePush(lines, result.error.message);

if (result.error.stderr !== undefined) {

ArrayPrototypePush(lines, ' [stderr]');

const stderrLines = RegExpPrototypeSymbolSplit(

/\r\n|\r|\n/g,

result.error.stderr,

);

for (let i = 0; i < stderrLines.length; i++) {

if (stderrLines[i] === '' && i === stderrLines.length - 1) {

continue;

}

ArrayPrototypePush(lines, ` ${stderrLines[i]}`);

}

}

}

}

return ensureTrailingNewline(ArrayPrototypeJoin(lines, '\n'));

let port = 0;

let preview = false;

let timeout = kProbeDefaultTimeout;

let json = false;

let sawSeparator = false;

let childStartIndex = args.length;

let pendingTarget;

let expectedExprIndex = -1;

const probes = [];

for (const token of tokens) {

if (token.kind === 'option-terminator') {

sawSeparator = true;

childStartIndex = token.index + 1;

break;

}

if (pendingTarget !== undefined) {

if (token.kind === 'option' &&

token.name === 'expr' &&

token.index === expectedExprIndex &&

token.value !== undefined) {

ArrayPrototypePush(probes, {

expr: token.value,

target: pendingTarget,

});

pendingTarget = undefined;

continue;

}

throw new ERR_DEBUGGER_STARTUP_ERROR(

'Each --probe must be followed immediately by --expr <expr>');

}

if (token.kind === 'positional') {

childStartIndex = token.index;

break;

}

switch (token.name) {

case 'json':

json = true;

break;

case 'timeout':

if (token.value === undefined) {

throw new ERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);

}

timeout = parseUnsignedInteger(token.value, 'timeout', true);

break;

case 'port':

if (token.value === undefined) {

throw new ERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);

}

port = parseUnsignedInteger(token.value, 'inspector port', true);

break;

case 'preview':

preview = true;

break;

case 'probe':

pendingTarget = parseProbeTarget(token.value);

expectedExprIndex = token.index + (token.inlineValue ? 1 : 2);

break;

case 'expr':

throw new ERR_DEBUGGER_STARTUP_ERROR('Unexpected --expr before --probe');

default:

if (probes.length > 0) {

throw new ERR_DEBUGGER_STARTUP_ERROR(

'Use -- before child Node.js flags in probe mode');

}

throw new ERR_DEBUGGER_STARTUP_ERROR(`Unknown probe option: ${token.rawName}`);

}

}

if (pendingTarget !== undefined) {

throw new ERR_DEBUGGER_STARTUP_ERROR(

'Each --probe must be followed immediately by --expr <expr>');

}

if (probes.length === 0) {

throw new ERR_DEBUGGER_STARTUP_ERROR(

'Probe mode requires at least one --probe <loc> --expr <expr> group');

}

const childArgv = ArrayPrototypeSlice(args, childStartIndex);

if (childArgv.length === 0) {

throw new ERR_DEBUGGER_STARTUP_ERROR('Probe mode requires a child script');

}

if (!sawSeparator && StringPrototypeStartsWith(childArgv[0], '-')) {

throw new ERR_DEBUGGER_STARTUP_ERROR('Use -- before child Node.js flags in probe mode');

}

let skipPortPreflight = port === 0;

for (const arg of childArgv) {

const inspectPortMatch = RegExpPrototypeExec(kInspectPortRegex, arg);

if (inspectPortMatch === null) {

continue;

}

if (inspectPortMatch[1] === '0') {

skipPortPreflight = true;

continue;

}

throw new ERR_DEBUGGER_STARTUP_ERROR(

'Only child --inspect-port=0 is supported in probe mode');

}

return {

host: '127.0.0.1',

port,

preview,

timeout,

json,

probes,

childArgv,

skipPortPreflight,

};

constructor(options) {

this.options = options;

this.client = new InspectClient();

this.child = null;

this.cleanupStarted = false;

this.childStderr = '';

this.disconnectRequested = false;

this.finished = false;

// True once the inspector WebSocket connects. Event handlers ignore

// pre-connect exits/closes so launch/connect failures report through run().

this.connected = false;

// True once breakpoints are bound and the target is released from --inspect-brk

// via `Runtime.runIfWaitingForDebugger`.

// Distinguishes "exited before user code ran" from "exited during the live session".

this.started = false;

// A sliding buffer of at most kProbeDisconnectSentinel.length to detect disconnect.

this.disconnectSentinelBuffer = '';

/** @type {Map<string, BreakpointDefinition>} keyed by V8 breakpointId. */

this.breakpointDefinitions = new SafeMap();

/** @type {Map<string, string>} scriptId -> URL. */

this.scriptIdToUrl = new SafeMap();

this.results = [];

this.timeout = null;

// The currently-awaited CDP request, or null when no request is in flight.

/** @type {{ method: string, probe: { index: number, location: Location } | null } | null} */

this.inFlight = null;

// Most recently completed probe, used for `error.probe` when a non-evaluate CDP call rejects.

this.lastProbeIndex = null;

const { promise, resolve } = PromiseWithResolvers();

this.completionPromise = promise;

this.resolveCompletion = resolve;

/** @type {Probe[]} */

this.probes = ArrayPrototypeMap(options.probes, ({ expr, target }) => ({ expr, target, hits: 0 }));

this.onChildOutput = FunctionPrototypeBind(this.onChildOutput, this);

this.onChildExit = FunctionPrototypeBind(this.onChildExit, this);

this.onClientClose = FunctionPrototypeBind(this.onClientClose, this);

this.onPaused = FunctionPrototypeBind(this.onPaused, this);

this.onScriptParsed = FunctionPrototypeBind(this.onScriptParsed, this);

}

// Marking the probing process to exit with 0, recorded hits are trustworthy.

finishWithTrustedResult(terminal) {

this.finish(kNoFailure, terminal);

}

// Marking the probing process to exit with 1, recorded hits are best-effort.

finishWithUnreliableResult(terminal) {

this.finish(kGenericUserError, terminal);

}

finish(exitCode, terminal) {

if (this.finished) { return; }

debug('finish: exitCode=%d, terminal=%s', exitCode, terminal?.event);

this.finished = true;

if (this.timeout !== null) {

clearTimeout(this.timeout);

this.timeout = null;

}

this.resolveCompletion({ exitCode, terminal });

}

getProbeTargetExitEvent(exitCode, signal) {

const pending = this.getPendingProbeIndices();

const how = signal !== null ? `with signal ${signal}` : `with code ${exitCode}`;

const status = pending.length === 0 ?

'target completion' : `probes: ${formatPendingProbeLocations(this.probes, pending)}`;

const error = {

__proto__: null,

code: 'probe_target_exit',

message: `Target exited ${how} before ${status}`,

};

if (exitCode !== null) { error.exitCode = exitCode; }

if (signal !== null) { error.signal = signal; }

error.stderr = trimProbeChildStderr(this.childStderr);

return { event: 'error', pending, error };

}

onChildOutput(text, which) {

if (which !== 'stderr') { return; }

this.childStderr += text;

const combined = this.disconnectSentinelBuffer + text;

// Detect the disconnect sentinel.

if (this.connected &&

StringPrototypeIncludes(combined, kProbeDisconnectSentinel)) {

this.disconnectRequested = true;

this.client.reset();

}

if (combined.length > kProbeDisconnectSentinel.length) { // Slide the buffer.

this.disconnectSentinelBuffer = StringPrototypeSlice(combined,

combined.length - kProbeDisconnectSentinel.length);

} else {

this.disconnectSentinelBuffer = combined;

}

}

onChildExit(code, signal) {

debug('child exit: code=%s signal=%s connected=%s started=%s finished=%s inFlight=%j',

code, signal, this.connected, this.started, this.finished, this.inFlight);

// Pre-connect exits are deliberately silent: the target never reached

// a state where probes could be set, so any report would be empty.

if (!this.connected) { return; }

if (this.finished) { return; }

if (this.inFlight !== null && this.inFlight.probe !== null) {

this.recordInspectorFailure({

reason: 'Target process exited during probe evaluation',

advice: kReviewProbeExprAdvice,

});

return;

}

if (this.started && code === 0 && signal === null) {

const pending = this.getPendingProbeIndices();

this.finishWithTrustedResult(pending.length === 0 ? { event: 'completed' } : { event: 'miss', pending });

return;

}

this.finishWithTrustedResult(this.getProbeTargetExitEvent(code, signal));

}

onClientClose() {

debug('client close: disconnectRequested=%s finished=%s inFlight=%j',

this.disconnectRequested, this.finished, this.inFlight);

if (!this.connected) { return; }

if (this.disconnectRequested) { return; }

if (this.finished) { return; }

if (this.child.exitCode !== null || this.child.signalCode !== null) {

this.onChildExit(this.child.exitCode, this.child.signalCode);

return;

}

if (!this.started) {

this.recordInspectorFailure({

reason: 'Inspector connection lost before probes started',

advice: kStartupTeardownAdvice,

});

return;

}

if (this.inFlight !== null) {

if (this.inFlight.probe !== null || this.lastProbeIndex !== null) {

this.recordInspectorFailure({

reason: 'Inspector connection lost during probe activity',

advice: 'A probe expression may have caused the disconnection. ' +

'If the failure repeats, review the probe expressions.',

});

} else {

this.recordInspectorFailure({

reason: 'Inspector connection lost during inspector activity',

advice: 'This is likely a Node.js bug. Please file an issue.',

});

}

return;

}

this.recordInspectorFailure({

reason: 'Inspector connection lost',

advice: 'The target was likely terminated externally. If the failure ' +

'persists, check the target\'s process environment.',

});

}

onPaused(params) {

this.handlePaused(params).catch((error) => {

if (error === kInspectorFailedSentinel) { return; }

this.recordInspectorFailure({

reason: 'Probe mode encountered an unexpected internal failure',

advice: 'This is likely a Node.js bug. Please file an issue.',

internalError: error,

});

});

}

async handlePaused(params) {

if (this.finished) { return; }

const hitBreakpoints = params.hitBreakpoints;

if (hitBreakpoints === undefined || hitBreakpoints.length === 0) {

await this.resume();

return;

}

const topFrame = params.callFrames?.[0];

const callFrameId = topFrame?.callFrameId;

if (callFrameId === undefined) {

await this.resume();

return;

}

const { scriptId, lineNumber, columnNumber } = topFrame.location;

// `Debugger.scriptParsed` should always precede a pause for the same script.

// It should only be undefined if there's a bug (even in that case, just omit it).

const location = {

url: this.scriptIdToUrl.get(scriptId),

// CDP locations are 0-based, locations in public report are 1-based.

line: lineNumber + 1,

column: columnNumber + 1,

};

for (const breakpointId of hitBreakpoints) {

// The breakpoint ID is stable even for scripts parsed after the initial resolution

// so we can count on it here.

const definition = this.breakpointDefinitions.get(breakpointId);

if (definition === undefined) { continue; }

// Evaluate the expressions in the order they appear on the command line.

for (const probeIndex of definition.probeIndices) {

await this.evaluateProbe(callFrameId, probeIndex, location);

if (this.finished) { break; }

}

}

await this.resume();

}

async evaluateProbe(callFrameId, probeIndex, location) {

if (this.finished) { return; }

const probe = this.probes[probeIndex];

const evaluation = await this.callCdp(

'Debugger.evaluateOnCallFrame',

{ callFrameId, expression: probe.expr, generatePreview: true },

{ __proto__: null, index: probeIndex, location },

);

this.lastProbeIndex = probeIndex;

probe.hits++;

const result = { probe: probeIndex, event: 'hit', hit: probe.hits, location };

if (evaluation.exceptionDetails !== undefined) {

result.error = {

__proto__: null,

message: evaluation.result?.description ?? 'Probe expression failed',

details: { __proto__: null, exception: trimRemoteObject(evaluation.exceptionDetails) },

};

} else {

result.result = trimRemoteObject(evaluation.result);

}

ArrayPrototypePush(this.results, result);

}

async resume() {

if (this.finished) { return; }

await this.callCdp('Debugger.resume');

}

async callCdp(method, params, probe = null) {

if (this.finished) { throw kInspectorFailedSentinel; }

this.inFlight = { __proto__: null, method, probe };

debug('CDP -> %s%s', method, probe !== null ? `, probe=${probe.index}` : '');

try {

const result = await this.client.callMethod(method, params);

// A timeout or process exit can finish the report while the CDP request

// is still outstanding. Ignore the late reply in that case.

if (this.finished) {

debug('CDP <- %s discarded (already finished)', method);

throw kInspectorFailedSentinel;

}

debug('CDP <- %s (success)', method);

return result;

} catch (err) {

if (err !== kInspectorFailedSentinel) { // Already handled.

debug('CDP <- %s error: %s', method, err?.code);

}

if (this.disconnectRequested) {

// Only the in-flight evaluation gets attribution. Other rejections

// under disconnect are downstream noise.

if (probe !== null) {

this.recordInspectorFailure({

reason: 'Target process exited during probe evaluation',

advice: kReviewProbeExprAdvice,

});

}

throw kInspectorFailedSentinel;

}

// Another event handler already recorded the terminal event.

if (this.finished) { throw kInspectorFailedSentinel; }

if (!this.started) {

this.recordInspectorFailure({

reason: 'Probe mode failed before user code ran',

advice: kStartupTeardownAdvice,

cdpError: err,

});

} else if (method === 'Debugger.evaluateOnCallFrame') {

this.recordInspectorFailure({

reason: 'The inspector could not evaluate a probe expression',

advice: `The rejection details are recorded on the probe hit. ${kReviewProbeExprAdvice}`,

cdpError: err,

});

} else if (this.lastProbeIndex !== null) {

this.recordInspectorFailure({

reason: 'Probe session failed after a probe evaluation',

advice: 'If the failure repeats, review the most-recently-evaluated probe expression.',

cdpError: err,

});

} else {

this.recordInspectorFailure({

reason: 'Probe session failed during inspector activity',

advice: 'This is likely a Node.js bug. Please file an issue.',

cdpError: err,

});

}

throw kInspectorFailedSentinel;

} finally {

this.inFlight = null;

}

}

// Records the first inspector-side terminal for the session, later callers are ignored.

recordInspectorFailure({ reason, advice, cdpError, internalError }) {

if (this.finished) { return; }

debug('recordInspectorFailure "%s": inFlight=%j, lastProbeIndex=%s, cdpError=%j',

reason, this.inFlight, this.lastProbeIndex, cdpError);

const child = this.child;

const exitedAbnormally = child !== null &&

(child.signalCode !== null || (child.exitCode !== null && child.exitCode !== 0));

const inFlightProbe = this.inFlight === null ? null : this.inFlight.probe;

// This normally emits `probe_failure`, but yields to `probe_target_exit` when the child

// has already exited abnormally and there is no in-flight probe to attribute to.

if (exitedAbnormally && inFlightProbe === null) {

this.finishWithTrustedResult(this.getProbeTargetExitEvent(child.exitCode, child.signalCode));

return;

}

const failedCdpMethod = this.inFlight === null ? null : this.inFlight.method;

let protocolError = null;

// // `ERR_DEBUGGER_ERROR` is a Node-internal code, not a CDP-level protocol code

if (cdpError !== undefined && cdpError.code !== 'ERR_DEBUGGER_ERROR') {

protocolError = { __proto__: null, message: cdpError.message, code: cdpError.code };

}

const protocolErrorGoesOnHit = (protocolError !== null) && (failedCdpMethod === 'Debugger.evaluateOnCallFrame');

let attribution = null;

if (inFlightProbe !== null) {

const { index, location } = inFlightProbe;

const error = { __proto__: null };

if (protocolErrorGoesOnHit) {

error.message = 'Probe evaluation failed at the protocol layer';

error.details = { __proto__: null, protocolError };

} else {

error.message = 'Probe evaluation did not complete';

}

this.probes[index].hits++;

ArrayPrototypePush(this.results, {

probe: index, event: 'hit', hit: this.probes[index].hits, location, error,

});

attribution = index;

} else if (failedCdpMethod !== null && this.lastProbeIndex !== null) {

attribution = this.lastProbeIndex;

}

// When there is no in-flight CDP call (e.g. `onClientClose` after all probes hit), ignore

// `lastProbeIndex` since it can't be attributed to a specific probe.

const pending = this.getPendingProbeIndices();

const suffix = pending.length === 0 ?

'' : ` before probes: ${formatPendingProbeLocations(this.probes, pending)}`;

const error = {

__proto__: null,

code: 'probe_failure',

message: `${reason}${suffix}. ${advice}`,

};

if (attribution !== null) { error.probe = attribution; }

error.stderr = trimProbeChildStderr(this.childStderr);

let details;

if (failedCdpMethod !== null) {

details = { __proto__: null, lastCdpMethod: failedCdpMethod };

if (protocolError !== null && !protocolErrorGoesOnHit) { details.protocolError = protocolError; }

}

if (internalError !== undefined) {

details ??= { __proto__: null };

details.internalError = { __proto__: null, message: internalError?.message, stack: internalError?.stack };

}

if (details !== undefined) { error.details = details; }

this.finishWithUnreliableResult({ event: 'error', pending, error });

}

startTimeout() {

this.timeout = setTimeout(() => {