@saptools/cf-inspector 0.4.7 → 0.4.10

package/README.md

@@ -10,7 +10,7 @@ Built so an AI agent (or a CI job) can drive a debugger from a single shell comm
 [![license](https://img.shields.io/npm/l/@saptools/cf-inspector.svg?style=flat&color=blue)](./LICENSE)
 [![node](https://img.shields.io/node/v/@saptools/cf-inspector.svg?style=flat&color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
 
-[Install](#-install) • [Quick Start](#-quick-start) • [CLI](#-cli) • [API](#-programmatic-usage) • [How it works](#-how-it-works)
+[Install](#-install) • [Quick Start](#-quick-start) • [CLI](#-cli) • [How it works](#-how-it-works)
 
 </div>
 
@@ -129,9 +129,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`
 
@@ -266,105 +267,29 @@ 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 attach`
+### 🎯 `cf-inspector list-targets`
 
-Connect, fetch the runtime version, print it, disconnect. Useful as a smoke-test that the tunnel is healthy.
+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 attach --port 9229
+cf-inspector list-targets --port 9229
+cf-inspector snapshot --port 9229 --target 1 --bp dist/worker.js:42
 ```
 
----
+### 🔗 `cf-inspector attach`
 
-## 🧑‍💻 Programmatic Usage
-
-```ts
-import {
-  connectInspector,
-  setBreakpoint,
-  waitForPause,
-  captureSnapshot,
-  evaluateOnFrame,
-  resume,
-} from "@saptools/cf-inspector";
-
-const session = await connectInspector({ port: 9229 });
-const bp = await setBreakpoint(session, {
-  file: "src/handler.ts",
-  line: 42,
-});
-const pause = await waitForPause(session, { timeoutMs: 30_000 });
-const snapshot = await captureSnapshot(session, pause, {
-  captures: ["this.user"],
-  maxValueLength: 4096,
-});
-const topFrame = pause.callFrames[0];
-if (topFrame === undefined) {
-  throw new Error("Breakpoint paused without a call frame");
-}
-const customValue = await evaluateOnFrame(session, topFrame.callFrameId, "this.user");
-await resume(session);
-await session.dispose();
+Connect, fetch the runtime version, print it, disconnect. Useful as a smoke-test that the tunnel is healthy.
 
-console.log({ bp, snapshot, customValue });
+```bash
+cf-inspector attach --port 9229
 ```
 
-<details>
-<summary><b>📚 Full export list</b></summary>
-
-| Export | Description |
-| --- | --- |
-| `connectInspector(options)` | Open a CDP WebSocket session against a port |
-| `setBreakpoint(session, location)` | Set a breakpoint by file/line + optional remote root and `hitCount` |
-| `removeBreakpoint(session, id)` | Remove a breakpoint by id |
-| `setPauseOnExceptions(session, state)` | Configure exception pause state: `none / uncaught / caught / all` |
-| `waitForPause(session, options)` | Resolve when the next `Debugger.paused` event fires; supports `pauseReasons` allow-list |
-| `captureSnapshot(session, pause, options)` | Build a structured snapshot of the paused frame. Pass `includeScopes: true` to expand scopes, `stackDepth` + `stackCaptures` for multi-frame walks, or `maxValueLength` to override the default captured value limit |
-| `captureException(session, pause, maxValueLength)` | Materialize the exception attached to a `Debugger.paused` event |
-| `walkStack(session, frames, options)` | Walk a call stack and evaluate per-frame expressions |
-| `evaluateOnFrame(session, frameId, expression)` | Evaluate in a paused frame |
-| `evaluateGlobal(session, expression)` | Evaluate against the global Runtime |
-| `listScripts(session)` | Return the scripts the V8 instance knows about |
-| `resume(session)` | Resume execution |
-| `streamLogpoint(session, options)` | Stream a non-pausing logpoint until duration / signal / max-events / transport-close |
-| `buildLogpointCondition(sentinel, expression, options?)` | Build the CDP `condition` string for a logpoint with optional predicate / hit-count gates |
-| `buildHitCountedCondition(hitCount, key, userCondition?)` | Build the hit-count gate used by `setBreakpoint({ hitCount })` |
-| `parseRemoteRoot(value)` | Parse a literal/regex remote-root setting |
-| `buildBreakpointUrlRegex(input)` | Build a CDP `urlRegex` for a file path |
-| `CfInspectorError` | Rich error class with typed `code` |
-
-</details>
-
-<details>
-<summary><b>🧪 Error codes</b></summary>
-
-| Code | When |
-| --- | --- |
-| `INVALID_ARGUMENT` | A numeric flag (`--port`, `--timeout`, `--duration`, …) is not a positive integer |
-| `INVALID_BREAKPOINT` | `--bp` / `--at` is not in `file:line` form, or line is not a positive integer |
-| `INVALID_REMOTE_ROOT` | `--remote-root` regex did not compile |
-| `INVALID_EXPRESSION` | `--condition` or `--expr` failed to parse on V8 (`Runtime.compileScript` reported a SyntaxError) — fast-fail before the breakpoint is set |
-| `INVALID_HIT_COUNT` | `--hit-count` is not a positive integer |
-| `INVALID_PAUSE_TYPE` | `cf-inspector exception --type` is not one of `uncaught / caught / all` |
-| `BREAKPOINT_DID_NOT_BIND` | Reserved: a breakpoint resolved to no scripts. Currently surfaced as a stderr warning only — see `BreakpointHandle.resolvedLocations` for programmatic detection |
-| `INSPECTOR_DISCOVERY_FAILED` | `/json/list` did not return a usable WebSocket URL |
-| `INSPECTOR_CONNECTION_FAILED` | WebSocket handshake failed, or the connection closed mid-request |
-| `CDP_REQUEST_FAILED` | A CDP method returned an error result, timed out, or failed to send |
-| `BREAKPOINT_NOT_HIT` | The breakpoint did not hit before the timeout elapsed |
-| `UNRELATED_PAUSE` | The target paused somewhere else and `--fail-on-unmatched-pause` was enabled |
-| `UNRELATED_PAUSE_TIMEOUT` | The target stayed paused somewhere else until the snapshot timeout elapsed |
-| `EVALUATION_FAILED` | Reserved for future use — current evaluation paths surface remote exceptions inline via `CapturedExpression.error` instead of throwing |
-| `MISSING_TARGET` | Neither `--port` nor a complete CF target (`--region/--org/--space/--app`) was provided |
-| `ABORTED` | Reserved for future use by long-running streams when an `AbortSignal` fires |
-
-</details>
-
 ---
 
 ## 🔭 How it works

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));
       }
     }
   });
@@ -2081,8 +2147,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 +2189,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 +2268,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 +2279,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 +2688,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);
@@ -2660,7 +2814,7 @@ 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;
@@ -2878,8 +3032,9 @@ function writeWatchSummary(reason, emitted, json) {
 }
 
 // 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,12 +3049,14 @@ 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")
+    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("--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 +3070,16 @@ function registerLog(program) {
 }
 function registerWatch(program) {
   applyTargetOptions(
-    program.command("watch").description("Stream a snapshot per breakpoint hit (multi-shot watch); resume between hits")
+    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("--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 +3094,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)")