@saptools/cf-inspector 0.4.8 → 0.4.11

package/README.md

@@ -94,6 +94,7 @@ cf-inspector snapshot --port 9229 \
 | `--condition <expr>` | Only pause when this JS expression evaluates truthy in the paused frame. Errors in the condition are silently treated as `false` by V8 |
 | `--hit-count <n>` | Skip the first N − 1 hits and only pause on the Nth (combines with `--condition` via logical AND) |
 | `--capture <expr,…>` | Top-level comma-separated expressions to evaluate in the paused frame; nested commas inside objects, arrays, calls, or strings are preserved. Object results are materialized to JSON strings when serializable, with fallback to CDP descriptions for non-serializable values |
+| `--setup-eval <expr>` | Repeatable, order-preserving global expression evaluated inside the inspected process before breakpoint setup. It can mutate runtime state, so use it only in controlled debug sessions |
 | `--stack-depth <n>` | Walk this many call frames per hit (default: `1`, top frame only). When `> 1`, the result includes a `stack` array |
 | `--stack-captures <expr,…>` | Expressions to evaluate on each call frame in the captured stack |
 | `--timeout <seconds>` | How long to wait for the breakpoint to hit (default: `30`) |
@@ -129,9 +130,10 @@ strict immediate error is preferred.
 
 For Cloud Foundry targets, replace `--port` with
 `--region/--org/--space/--app`. Cloud Foundry commands and tunnel readiness
-allow up to 180 seconds by default. `--cf-timeout <seconds>` overrides only the
-tunnel-readiness phase; snapshot `--timeout` separately controls how long to
-wait for a breakpoint hit.
+allow up to 180 seconds by default. For commands without their own wait
+semantics, `--timeout <seconds>` controls CF tunnel readiness. For breakpoint
+and exception commands, `--timeout` is reserved for the command wait and tunnel
+readiness keeps the 180-second default.
 
 ### 📡 `cf-inspector log`
 
@@ -202,6 +204,7 @@ Each event is a `WatchEvent`:
 | `--port <number>` | Local port the inspector or tunnel listens on |
 | `--bp <file:line>` | **Required.** Source location to capture on (repeatable) |
 | `--capture <expr,…>` | Top-level comma-separated expressions to evaluate per hit |
+| `--setup-eval <expr>` | Repeatable, order-preserving global expression evaluated inside the inspected process before breakpoint setup. It can mutate runtime state, so use it only in controlled debug sessions |
 | `--condition <expr>` | Only emit hits where this expression evaluates truthy |
 | `--hit-count <n>` | Start emitting once the line has been hit N or more times |
 | `--remote-root <value>` | Path-mapping anchor (same DSL as `snapshot`) |
@@ -266,10 +269,19 @@ cf-inspector eval --port 9229 --expr 'process.uptime()'
 
 ### 📜 `cf-inspector list-scripts`
 
-Print every script the V8 instance knows about (useful for debugging path-mapping issues).
+Print every script the V8 instance knows about (useful for debugging path-mapping issues). Add `--filter <pattern>` to narrow noisy script lists with a literal/wildcard pattern; `|` separates alternatives and `.*` / `.+` match variable text.
 
 ```bash
-cf-inspector list-scripts --port 9229
+cf-inspector list-scripts --port 9229 --filter 'dist/.+\.js'
+```
+
+### 🎯 `cf-inspector list-targets`
+
+Print `/json/list` inspector targets with stable indexes. Use the index with `--target <index>` when a long-running worker thread appears as a separate target.
+
+```bash
+cf-inspector list-targets --port 9229
+cf-inspector snapshot --port 9229 --target 1 --bp dist/worker.js:42
 ```
 
 ### 🔗 `cf-inspector attach`

package/dist/cli.js

@@ -409,15 +409,54 @@ async function openCfTunnel(target) {
     ...target.signal === void 0 ? {} : { signal: target.signal },
     ...target.onStatus === void 0 ? {} : { onStatus: target.onStatus }
   };
-  const handle = await startDebugger(opts);
+  try {
+    const handle = await startDebugger(opts);
+    return {
+      localPort: handle.session.localPort,
+      handle,
+      dispose: async () => {
+        await handle.dispose();
+      }
+    };
+  } catch (err) {
+    return reuseExistingTunnelOrThrow(err, target.onStatus);
+  }
+}
+function reuseExistingTunnelOrThrow(err, onStatus) {
+  if (!isSessionAlreadyRunningError(err)) {
+    throw err;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  const port = extractExistingTunnelPort(message);
+  if (port === void 0) {
+    throw err;
+  }
+  const warning = `Reusing existing tunnel on port ${port.toString()}`;
+  onStatus?.("ready", warning);
   return {
-    localPort: handle.session.localPort,
-    handle,
-    dispose: async () => {
-      await handle.dispose();
-    }
+    localPort: port,
+    dispose: () => Promise.resolve()
   };
 }
+function isSessionAlreadyRunningError(err) {
+  if (typeof err !== "object" || err === null) {
+    return false;
+  }
+  const code = err.code;
+  return code === "SESSION_ALREADY_RUNNING";
+}
+function extractExistingTunnelPort(message) {
+  const match = /on port (\d+)/i.exec(message);
+  if (match === null) {
+    return void 0;
+  }
+  const rawPort = match[1];
+  if (rawPort === void 0) {
+    return void 0;
+  }
+  const port = Number.parseInt(rawPort, 10);
+  return Number.isNaN(port) ? void 0 : port;
+}
 
 // src/inspector/session.ts
 import { performance } from "perf_hooks";
@@ -782,11 +821,12 @@ async function connectInspector(options) {
   const host = options.host ?? DEFAULT_HOST;
   const connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
   const targets = await discoverInspectorTargets(host, options.port, connectTimeoutMs);
-  const target = targets[0];
+  const targetIndex = options.targetIndex ?? 0;
+  const target = targets[targetIndex];
   if (!target) {
     throw new CfInspectorError(
       "INSPECTOR_DISCOVERY_FAILED",
-      `No inspector targets available on ${host}:${options.port.toString()}`
+      `No inspector target at index ${targetIndex.toString()} on ${host}:${options.port.toString()} (available: ${targets.length.toString()})`
     );
   }
   const client = await CdpClient.connect({
@@ -882,22 +922,23 @@ function parsePositiveInt(raw, label) {
   }
   return value;
 }
-async function resolveTargetWithCurrentCfTarget(opts) {
+async function resolveTargetWithCurrentCfTarget(opts, options = {}) {
   const port = parsePositiveInt(opts.port, "--port");
+  const targetIndex = parseTargetIndex(opts.target);
   if (port !== void 0) {
-    return { kind: "port", port, host: opts.host ?? "127.0.0.1" };
+    return { kind: "port", port, host: opts.host ?? "127.0.0.1", ...targetIndexOption(targetIndex) };
   }
   const app = optionalText(opts.app);
   if (app === void 0) {
     throw missingTargetError();
   }
-  const cfTimeoutSec = parsePositiveInt(opts.cfTimeout, "--cf-timeout") ?? DEFAULT_CF_TIMEOUT_SEC;
+  const tunnelTimeoutSec = parseTunnelTimeout(opts, options);
   const region = optionalText(opts.region);
   const apiEndpoint = optionalText(opts.apiEndpoint);
   const org = optionalText(opts.org);
   const space = optionalText(opts.space);
   if (region !== void 0 && org !== void 0 && space !== void 0) {
-    return buildCfTarget(region, apiEndpoint, org, space, app, cfTimeoutSec);
+    return buildCfTarget(region, apiEndpoint, org, space, app, tunnelTimeoutSec, targetIndex);
   }
   const current = await readCurrentTarget();
   if (current === void 0) {
@@ -912,10 +953,30 @@ async function resolveTargetWithCurrentCfTarget(opts) {
     org ?? current.org,
     space ?? current.space,
     app,
-    cfTimeoutSec
+    tunnelTimeoutSec,
+    targetIndex
   );
 }
-function buildCfTarget(region, apiEndpoint, org, space, app, cfTimeoutSec) {
+function parseTunnelTimeout(opts, options) {
+  if (options.useTimeoutForTunnel === false) {
+    return DEFAULT_CF_TIMEOUT_SEC;
+  }
+  return parsePositiveInt(opts.timeout, "--timeout") ?? DEFAULT_CF_TIMEOUT_SEC;
+}
+function parseTargetIndex(raw) {
+  if (raw === void 0) {
+    return void 0;
+  }
+  const value = Number.parseInt(raw, 10);
+  if (Number.isNaN(value) || value < 0 || value.toString() !== raw.trim()) {
+    throw new CfInspectorError("INVALID_ARGUMENT", `Invalid --target: "${raw}" \u2014 expected a non-negative integer`);
+  }
+  return value;
+}
+function targetIndexOption(targetIndex) {
+  return targetIndex === void 0 ? {} : { targetIndex };
+}
+function buildCfTarget(region, apiEndpoint, org, space, app, tunnelTimeoutSec, targetIndex) {
   return {
     kind: "cf",
     region,
@@ -923,7 +984,8 @@ function buildCfTarget(region, apiEndpoint, org, space, app, cfTimeoutSec) {
     org,
     space,
     app,
-    cfTimeoutMs: cfTimeoutSec * 1e3
+    tunnelTimeoutMs: tunnelTimeoutSec * 1e3,
+    ...targetIndexOption(targetIndex)
   };
 }
 function optionalText(value) {
@@ -966,7 +1028,11 @@ async function withSession(target, fn, reportProgress) {
     reportProgress?.(
       `Connecting to the Node.js inspector at ${tunnel.host}:${tunnel.port.toString()}...`
     );
-    session = await connectInspector({ port: tunnel.port, host: tunnel.host });
+    session = await connectInspector({
+      port: tunnel.port,
+      host: tunnel.host,
+      ...targetIndexOption(target.targetIndex)
+    });
     reportProgress?.("Inspector session is ready.");
     return await fn(session, tunnel.port);
   } finally {
@@ -993,10 +1059,10 @@ async function openTarget(target, reportProgress) {
     org: target.org,
     space: target.space,
     app: target.app,
-    tunnelReadyTimeoutMs: target.cfTimeoutMs,
+    tunnelReadyTimeoutMs: target.tunnelTimeoutMs,
     ...reportProgress === void 0 ? {} : {
-      onStatus: (status) => {
-        reportProgress(formatCfTunnelStatus(status));
+      onStatus: (status, message) => {
+        reportProgress(message ?? formatCfTunnelStatus(status));
       }
     }
   });
@@ -1058,6 +1124,20 @@ async function evaluateGlobal(session, expression) {
     silent: true
   });
 }
+async function runSetupEvals(session, expressions) {
+  for (const expression of expressions) {
+    const result = await evaluateGlobal(session, expression);
+    if (result.exceptionDetails !== void 0) {
+      throw new CfInspectorError(
+        "SETUP_EVAL_FAILED",
+        exceptionDetailsMessage(result, "setup evaluation failed")
+      );
+    }
+  }
+}
+function exceptionDetailsMessage(result, fallback) {
+  return typeof result.exceptionDetails?.exception?.description === "string" ? result.exceptionDetails.exception.description : typeof result.exceptionDetails?.text === "string" ? result.exceptionDetails.text : fallback;
+}
 function listScripts(session) {
   return [...session.scripts.values()];
 }
@@ -2081,8 +2161,9 @@ import process5 from "process";
 function warnOnUnboundBreakpoints(handles) {
   for (const handle of handles) {
     if (handle.resolvedLocations.length === 0) {
+      const tsHint = handle.file.endsWith(".ts") ? " Hint: Source TS breakpoints may not bind. Try inspecting loaded scripts with list-scripts and target the compiled .js file instead." : "";
       process5.stderr.write(
-        `[cf-inspector] warning: breakpoint ${handle.file}:${handle.line.toString()} did not bind to any loaded script. Check the path or pass --remote-root. Use 'list-scripts' to inspect what V8 currently has loaded.
+        `[cf-inspector] warning: breakpoint ${handle.file}:${handle.line.toString()} did not bind to any loaded script. Check the path or pass --remote-root. Use 'list-scripts' to inspect what V8 currently has loaded.${tsHint}
 `
       );
     }
@@ -2122,7 +2203,7 @@ function formatPauseLocation(pause) {
 // src/cli/commands/exception.ts
 var VALID_PAUSE_TYPES = ["uncaught", "caught", "all"];
 async function handleException(opts) {
-  const target = await resolveTargetWithCurrentCfTarget(opts);
+  const target = await resolveTargetWithCurrentCfTarget(opts, { useTimeoutForTunnel: false });
   const prepared = prepareExceptionCommand(opts, target);
   const result = await runExceptionCommand(prepared, opts);
   if (opts.json) {
@@ -2201,7 +2282,8 @@ async function disablePauseOnExceptionsBestEffort(session) {
 import process7 from "process";
 async function handleListScripts(opts) {
   const target = await resolveTargetWithCurrentCfTarget(opts);
-  const scripts = await withSession(target, (session) => Promise.resolve(listScripts(session)));
+  const filter = compileScriptUrlFilter(opts.filter);
+  const scripts = (await withSession(target, (session) => Promise.resolve(listScripts(session)))).filter((script) => filter === void 0 || filter(script.url));
   if (opts.json) {
     writeJson(scripts);
     return;
@@ -2211,6 +2293,92 @@ async function handleListScripts(opts) {
 `);
   }
 }
+async function handleListTargets(opts) {
+  const target = await resolveTargetWithCurrentCfTarget(opts);
+  const tunnel = await openTarget(target);
+  try {
+    const targets = await discoverInspectorTargets(tunnel.host, tunnel.port, 5e3);
+    const indexedTargets = targets.map((entry, index) => ({ index, ...entry }));
+    if (opts.json) {
+      writeJson(indexedTargets);
+      return;
+    }
+    for (const entry of indexedTargets) {
+      process7.stdout.write(`${entry.index.toString()}	${entry.type}	${entry.title}	${entry.url}
+`);
+    }
+  } finally {
+    await tunnel.dispose();
+  }
+}
+function compileScriptUrlFilter(pattern) {
+  if (pattern === void 0 || pattern.length === 0) {
+    return void 0;
+  }
+  const alternatives = splitPatternAlternatives(pattern).map((alternative) => parseFilterTokens(alternative)).filter((tokens) => tokens.length > 0);
+  return (url) => alternatives.some((tokens) => matchesFilterTokens(url, tokens));
+}
+function splitPatternAlternatives(pattern) {
+  const alternatives = [];
+  let current = "";
+  for (let index = 0; index < pattern.length; index++) {
+    const char = pattern[index] ?? "";
+    if (char === "\\" && index + 1 < pattern.length) {
+      current += `${char}${pattern[index + 1] ?? ""}`;
+      index++;
+    } else if (char === "|") {
+      alternatives.push(current);
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  alternatives.push(current);
+  return alternatives;
+}
+function parseFilterTokens(pattern) {
+  const tokens = [];
+  let literal = "";
+  for (let index = 0; index < pattern.length; index++) {
+    const char = pattern[index] ?? "";
+    const nextChar = pattern[index + 1];
+    if (char === "\\" && nextChar !== void 0) {
+      literal += nextChar;
+      index++;
+    } else if (char === "." && (nextChar === "*" || nextChar === "+")) {
+      if (literal.length > 0) {
+        tokens.push(literal);
+      }
+      literal = "";
+      tokens.push({ kind: "wildcard", minChars: nextChar === "+" ? 1 : 0 });
+      index++;
+    } else {
+      literal += char;
+    }
+  }
+  if (literal.length > 0) {
+    tokens.push(literal);
+  }
+  return tokens;
+}
+function matchesFilterTokens(value, tokens) {
+  let position = 0;
+  for (const token of tokens) {
+    if (typeof token === "string") {
+      const nextPosition = value.indexOf(token, position);
+      if (nextPosition === -1) {
+        return false;
+      }
+      position = nextPosition + token.length;
+    } else {
+      if (token.minChars === 1 && position >= value.length) {
+        return false;
+      }
+      position += token.minChars;
+    }
+  }
+  return true;
+}
 
 // src/cli/commands/log.ts
 import process9 from "process";
@@ -2534,7 +2702,7 @@ import { performance as performance4 } from "perf_hooks";
 import process10 from "process";
 init_types();
 async function handleSnapshot(opts) {
-  const target = await resolveTargetWithCurrentCfTarget(opts);
+  const target = await resolveTargetWithCurrentCfTarget(opts, { useTimeoutForTunnel: false });
   const prepared = prepareSnapshotCommand(opts, target);
   const reportProgress = opts.quiet === true ? void 0 : writeProgress;
   const result = await runSnapshotCommand(prepared, opts, reportProgress);
@@ -2557,8 +2725,10 @@ function prepareSnapshotCommand(opts, target) {
   const condition = opts.condition !== void 0 && opts.condition.trim().length > 0 ? opts.condition.trim() : void 0;
   const hitCount = parsePositiveInt(opts.hitCount, "--hit-count");
   const stackDepth = parsePositiveInt(opts.stackDepth, "--stack-depth");
+  const setupEvals = parseSetupEvals(opts.setupEval);
   return {
     target,
+    setupEvals,
     breakpoints: opts.bp.map((spec) => parseBreakpointSpec(spec)),
     captures: parseCaptureList(opts.capture),
     remoteRoot: parseRemoteRoot(opts.remoteRoot),
@@ -2572,6 +2742,12 @@ function prepareSnapshotCommand(opts, target) {
 }
 async function runSnapshotCommand(command, opts, reportProgress) {
   return await withSession(command.target, async (session) => {
+    if (command.setupEvals.length > 0) {
+      const setupCount = command.setupEvals.length;
+      reportProgress?.(`Running ${setupCount.toString()} setup ${setupCount === 1 ? "evaluation" : "evaluations"}...`);
+      await runSetupEvals(session, command.setupEvals);
+      reportProgress?.("Setup evaluation complete.");
+    }
     if (command.condition !== void 0) {
       reportProgress?.("Validating the breakpoint condition...");
       await validateExpression(session, command.condition);
@@ -2654,13 +2830,17 @@ async function resumeAfterSnapshot(session, snapshot, pausedStartedAt, reportPro
     return withPausedDuration(snapshot, null);
   }
 }
+function parseSetupEvals(raw) {
+  const values = Array.isArray(raw) ? raw : [];
+  return values.filter((expr) => typeof expr === "string" && expr.trim().length > 0).map((expr) => expr.trim());
+}
 
 // src/cli/commands/watch.ts
 import { performance as performance5 } from "perf_hooks";
 import process11 from "process";
 init_types();
 async function handleWatch(opts) {
-  const target = await resolveTargetWithCurrentCfTarget(opts);
+  const target = await resolveTargetWithCurrentCfTarget(opts, { useTimeoutForTunnel: false });
   const prepared = prepareWatchCommand(opts, target);
   let stoppedReason = "signal";
   let emitted = 0;
@@ -2687,8 +2867,10 @@ function prepareWatchCommand(opts, target) {
   const hitCount = parsePositiveInt(opts.hitCount, "--hit-count");
   const stackDepth = parsePositiveInt(opts.stackDepth, "--stack-depth");
   const condition = opts.condition !== void 0 && opts.condition.trim().length > 0 ? opts.condition.trim() : void 0;
+  const setupEvals = parseSetupEvals2(opts.setupEval);
   return {
     target,
+    setupEvals,
     breakpoints: opts.bp.map((spec) => parseBreakpointSpec(spec)),
     captures: parseCaptureList(opts.capture),
     remoteRoot: parseRemoteRoot(opts.remoteRoot),
@@ -2703,6 +2885,9 @@ function prepareWatchCommand(opts, target) {
   };
 }
 async function runWatchLoop(session, command, opts, signal) {
+  if (command.setupEvals.length > 0) {
+    await runSetupEvals(session, command.setupEvals);
+  }
   if (command.condition !== void 0) {
     await validateExpression(session, command.condition);
   }
@@ -2876,10 +3061,15 @@ function writeWatchSummary(reason, emitted, json) {
 `
   );
 }
+function parseSetupEvals2(raw) {
+  const values = Array.isArray(raw) ? raw : [];
+  return values.filter((expr) => typeof expr === "string" && expr.trim().length > 0).map((expr) => expr.trim());
+}
 
 // src/cli/program.ts
-function applyTargetOptions(cmd) {
-  return cmd.option("--port <number>", "Local port the inspector or tunnel listens on").option("--host <host>", "Hostname (default: 127.0.0.1)", "127.0.0.1").option("--region <key>", "CF region key (default: current cf target)").option("--api-endpoint <url>", "CF API endpoint override for --region").option("--org <name>", "CF org name (default: current cf target)").option("--space <name>", "CF space name (default: current cf target)").option("--app <name>", "CF app name when not using --port").option("--cf-timeout <seconds>", "Timeout for CF tunnel readiness in seconds (default: 180)");
+function applyTargetOptions(cmd, options = {}) {
+  const withBaseOptions = cmd.option("--port <number>", "Local port the inspector or tunnel listens on").option("--host <host>", "Hostname (default: 127.0.0.1)", "127.0.0.1").option("--region <key>", "CF region key (default: current cf target)").option("--api-endpoint <url>", "CF API endpoint override for --region").option("--org <name>", "CF org name (default: current cf target)").option("--space <name>", "CF space name (default: current cf target)").option("--app <name>", "CF app name when not using --port").option("--target <index>", "Inspector target index from /json/list (default: 0)");
+  return options.includeTimeout === false ? withBaseOptions : withBaseOptions.option("--timeout <seconds>", "Timeout for CF tunnel readiness in seconds (default: 180)");
 }
 var collectStrings = (value, prev = []) => [
   ...prev,
@@ -2894,13 +3084,15 @@ async function main(argv) {
   registerException(program);
   registerEval(program);
   registerListScripts(program);
+  registerListTargets(program);
   registerAttach(program);
   await program.parseAsync([...argv]);
 }
 function registerSnapshot(program) {
   applyTargetOptions(
-    program.command("snapshot").description("Set a breakpoint, wait for it to hit, capture expressions, and resume")
-  ).option("--bp <file:line>", "Breakpoint location (repeatable; first hit wins), e.g. src/handler.ts:42", collectStrings, []).option("--capture <expr,\u2026>", "Top-level comma-separated expressions to evaluate in the paused frame").option("--timeout <seconds>", "How long to wait for the breakpoint to hit (default: 30)").option("--max-value-length <chars>", "Maximum characters per captured value before truncation (default: 4096)").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--condition <expr>", "Only pause when this JS expression evaluates truthy in the paused frame").option("--hit-count <n>", "Only pause after the breakpoint has been hit N or more times").option("--stack-depth <n>", "Walk this many call frames when capturing (default: 1, only top frame)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame in the stack").option("--include-scopes", "Include expanded paused-frame scopes in the snapshot").option("--no-json", "Print a human-readable summary instead of JSON").option("--quiet", "Suppress progress messages on stderr").option("--keep-paused", "Skip Debugger.resume after capture; Node may resume when this CLI disconnects").option("--fail-on-unmatched-pause", "Fail immediately if the target pauses somewhere else").action(async (opts) => {
+    program.command("snapshot").description("Set a breakpoint, wait for it to hit, capture expressions, and resume"),
+    { includeTimeout: false }
+  ).option("--bp <file:line>", "Breakpoint location (repeatable; first hit wins), e.g. src/handler.ts:42", collectStrings, []).option("--capture <expr,\u2026>", "Top-level comma-separated expressions to evaluate in the paused frame").option("--setup-eval <expr>", "Evaluate a global setup expression before breakpoint setup (repeatable)", collectStrings, []).option("--timeout <seconds>", "How long to wait for the breakpoint to hit (default: 30)").option("--max-value-length <chars>", "Maximum characters per captured value before truncation (default: 4096)").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--condition <expr>", "Only pause when this JS expression evaluates truthy in the paused frame").option("--hit-count <n>", "Only pause after the breakpoint has been hit N or more times").option("--stack-depth <n>", "Walk this many call frames when capturing (default: 1, only top frame)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame in the stack").option("--include-scopes", "Include expanded paused-frame scopes in the snapshot").option("--no-json", "Print a human-readable summary instead of JSON").option("--quiet", "Suppress progress messages on stderr").option("--keep-paused", "Skip Debugger.resume after capture; Node may resume when this CLI disconnects").option("--fail-on-unmatched-pause", "Fail immediately if the target pauses somewhere else").action(async (opts) => {
     await handleSnapshot(opts);
   });
 }
@@ -2913,14 +3105,16 @@ function registerLog(program) {
 }
 function registerWatch(program) {
   applyTargetOptions(
-    program.command("watch").description("Stream a snapshot per breakpoint hit (multi-shot watch); resume between hits")
-  ).option("--bp <file:line>", "Breakpoint location (repeatable), e.g. src/handler.ts:42", collectStrings, []).option("--capture <expr,\u2026>", "Top-level comma-separated expressions to evaluate per hit").option("--condition <expr>", "Only emit hits where this JS expression evaluates truthy").option("--hit-count <n>", "Start emitting after the line has been hit N or more times").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--duration <seconds>", "Stop streaming after N seconds (default: run until SIGINT)").option("--max-events <n>", "Stop streaming after emitting N watch events").option("--timeout <seconds>", "How long to wait for the next hit before giving up (default: 30)").option("--max-value-length <chars>", "Maximum characters per captured value before truncation (default: 4096)").option("--stack-depth <n>", "Walk this many call frames per hit (default: 1)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame").option("--include-scopes", "Include expanded paused-frame scopes per hit").option("--no-json", "Print human-readable lines instead of JSON Lines").action(async (opts) => {
+    program.command("watch").description("Stream a snapshot per breakpoint hit (multi-shot watch); resume between hits"),
+    { includeTimeout: false }
+  ).option("--bp <file:line>", "Breakpoint location (repeatable), e.g. src/handler.ts:42", collectStrings, []).option("--capture <expr,\u2026>", "Top-level comma-separated expressions to evaluate per hit").option("--setup-eval <expr>", "Evaluate a global setup expression before breakpoint setup (repeatable)", collectStrings, []).option("--condition <expr>", "Only emit hits where this JS expression evaluates truthy").option("--hit-count <n>", "Start emitting after the line has been hit N or more times").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--duration <seconds>", "Stop streaming after N seconds (default: run until SIGINT)").option("--max-events <n>", "Stop streaming after emitting N watch events").option("--timeout <seconds>", "How long to wait for the next hit before giving up (default: 30)").option("--max-value-length <chars>", "Maximum characters per captured value before truncation (default: 4096)").option("--stack-depth <n>", "Walk this many call frames per hit (default: 1)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame").option("--include-scopes", "Include expanded paused-frame scopes per hit").option("--no-json", "Print human-readable lines instead of JSON Lines").action(async (opts) => {
     await handleWatch(opts);
   });
 }
 function registerException(program) {
   applyTargetOptions(
-    program.command("exception").description("Pause on a thrown exception, capture the value and frame, then resume")
+    program.command("exception").description("Pause on a thrown exception, capture the value and frame, then resume"),
+    { includeTimeout: false }
   ).option("--type <state>", "Pause type: uncaught (default), caught, or all").option("--capture <expr,\u2026>", "Top-level comma-separated expressions to evaluate in the paused frame").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--timeout <seconds>", "How long to wait for an exception (default: 30)").option("--max-value-length <chars>", "Maximum characters per captured value before truncation (default: 4096)").option("--stack-depth <n>", "Walk this many call frames when capturing (default: 1)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame in the stack").option("--include-scopes", "Include expanded paused-frame scopes in the snapshot").option("--keep-paused", "Skip Debugger.resume after capture; Node may resume when this CLI disconnects").option("--no-json", "Print a human-readable summary instead of JSON").action(async (opts) => {
     await handleException(opts);
   });
@@ -2935,10 +3129,17 @@ function registerEval(program) {
 function registerListScripts(program) {
   applyTargetOptions(
     program.command("list-scripts").description("Print the scripts the V8 instance currently knows about")
-  ).option("--no-json", "Print scriptId<TAB>url instead of JSON").action(async (opts) => {
+  ).option("--filter <pattern>", "Only include script URLs matching this pattern").option("--no-json", "Print scriptId<TAB>url instead of JSON").action(async (opts) => {
     await handleListScripts(opts);
   });
 }
+function registerListTargets(program) {
+  applyTargetOptions(
+    program.command("list-targets").description("Print inspector targets from /json/list for selecting workers with --target")
+  ).option("--no-json", "Print index<TAB>type<TAB>title<TAB>url instead of JSON").action(async (opts) => {
+    await handleListTargets(opts);
+  });
+}
 function registerAttach(program) {
   applyTargetOptions(
     program.command("attach").description("Connect, fetch the inspector version, and disconnect (smoke-test)")