@saptools/cf-inspector 0.4.10 → 0.4.12

package/README.md

@@ -40,6 +40,8 @@ Built so an AI agent (or a CI job) can drive a debugger from a single shell comm
 npm install -g @saptools/cf-inspector
 # or
 pnpm add @saptools/cf-inspector
+
+cf-inspector --version
 ```
 
 > [!NOTE]
@@ -94,6 +96,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`) |
@@ -203,6 +206,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`) |
@@ -282,6 +286,8 @@ cf-inspector list-targets --port 9229
 cf-inspector snapshot --port 9229 --target 1 --bp dist/worker.js:42
 ```
 
+If `list-targets`, `attach`, or another command reports `ECONNREFUSED`, the local inspector or tunnel on that port is usually stale/closed. Restart the local Node inspector or tunnel and retry; for Cloud Foundry targets, prefer `--app/--region/--org/--space` so `cf-inspector` can open a fresh tunnel.
+
 ### 🔗 `cf-inspector attach`
 
 Connect, fetch the runtime version, print it, disconnect. Useful as a smoke-test that the tunnel is healthy.

package/dist/cli.js

@@ -155,6 +155,9 @@ var init_wsTransport = __esm({
 import process12 from "process";
 
 // src/cli/program.ts
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
 import { Command } from "commander";
 
 // src/cli/commands/attach.ts
@@ -190,16 +193,39 @@ async function fetchJson(url, timeoutMs) {
       );
     });
     req.on("error", (err) => {
-      reject(
-        err instanceof CfInspectorError ? err : new CfInspectorError(
-          "INSPECTOR_DISCOVERY_FAILED",
-          `Inspector discovery at ${url} failed: ${err.message}`
-        )
-      );
+      reject(err instanceof CfInspectorError ? err : formatDiscoveryRequestError(url, err));
     });
     req.end();
   });
 }
+function isNodeSystemError(err) {
+  return err instanceof Error;
+}
+function isConnectionRefusedOrUnreachable(code) {
+  return code === "ECONNREFUSED" || code === "ECONNRESET" || code === "ETIMEDOUT" || code === "EHOSTUNREACH" || code === "ENETUNREACH";
+}
+function formatEndpoint(url, err) {
+  if (typeof err.address === "string" && typeof err.port === "number") {
+    return `${err.address}:${err.port.toString()}`;
+  }
+  const parsed = new URL(url);
+  return parsed.host;
+}
+function formatDiscoveryRequestError(url, err) {
+  const detail = err instanceof Error ? err.message : String(err);
+  if (!isNodeSystemError(err) || !isConnectionRefusedOrUnreachable(err.code)) {
+    return new CfInspectorError(
+      "INSPECTOR_DISCOVERY_FAILED",
+      `Inspector discovery at ${url} failed: ${detail}`
+    );
+  }
+  const endpoint = formatEndpoint(url, err);
+  return new CfInspectorError(
+    "INSPECTOR_DISCOVERY_FAILED",
+    `Cannot reach Node inspector discovery at ${url}. Nothing is listening on ${endpoint}, or the inspector tunnel is stale/closed. Restart the local inspector or tunnel and retry. If this port came from cf-debugger, stop the stale session and start a fresh tunnel, or run cf-inspector with --app/--region/--org/--space so it can open a tunnel.`,
+    detail
+  );
+}
 function parseJsonResponse(chunks) {
   const text = Buffer.concat(chunks).toString("utf8");
   return JSON.parse(text);
@@ -1124,6 +1150,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()];
 }
@@ -2711,8 +2751,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),
@@ -2726,48 +2768,57 @@ function prepareSnapshotCommand(opts, target) {
 }
 async function runSnapshotCommand(command, opts, reportProgress) {
   return await withSession(command.target, async (session) => {
-    if (command.condition !== void 0) {
-      reportProgress?.("Validating the breakpoint condition...");
-      await validateExpression(session, command.condition);
-      reportProgress?.("Breakpoint condition is valid.");
-    }
-    const breakpointCount = command.breakpoints.length;
-    reportProgress?.(
-      `Setting ${breakpointCount.toString()} ${breakpointCount === 1 ? "breakpoint" : "breakpoints"}...`
-    );
-    const handles = await setCommandBreakpoints(session, command);
-    const resolvedCount = handles.reduce(
-      (total, handle) => total + handle.resolvedLocations.length,
-      0
-    );
-    reportProgress?.(
-      `Breakpoint setup complete: ${resolvedCount.toString()} resolved ${resolvedCount === 1 ? "location" : "locations"}.`
-    );
-    warnOnUnboundBreakpoints(handles);
-    reportProgress?.(
-      `Waiting up to ${(command.timeoutMs / 1e3).toString()}s for a breakpoint hit...`
-    );
-    const pause = await waitForCommandPause(session, opts, handles, command.timeoutMs);
-    const captureCount = command.captures.length;
-    reportProgress?.(
-      `Breakpoint hit; capturing ${captureCount.toString()} ${captureCount === 1 ? "expression" : "expressions"}...`
-    );
-    const pausedStartedAt = pause.receivedAtMs ?? performance4.now();
-    const snapshot = await captureSnapshot(session, pause, {
-      captures: command.captures,
-      includeScopes: opts.includeScopes === true,
-      ...command.maxValueLength === void 0 ? {} : { maxValueLength: command.maxValueLength },
-      ...command.stackDepth === void 0 ? {} : { stackDepth: command.stackDepth },
-      stackCaptures: command.stackCaptures
-    });
-    if (opts.keepPaused === true) {
-      reportProgress?.("Snapshot captured; leaving the target paused as requested.");
-      return withPausedDuration(snapshot, null);
-    }
-    reportProgress?.("Snapshot captured; resuming the target...");
-    return await resumeAfterSnapshot(session, snapshot, pausedStartedAt, reportProgress);
+    return await runSnapshotOnSession(session, command, opts, reportProgress);
   }, reportProgress);
 }
+async function runSnapshotOnSession(session, command, opts, reportProgress) {
+  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);
+    reportProgress?.("Breakpoint condition is valid.");
+  }
+  const breakpointCount = command.breakpoints.length;
+  reportProgress?.(
+    `Setting ${breakpointCount.toString()} ${breakpointCount === 1 ? "breakpoint" : "breakpoints"}...`
+  );
+  const handles = await setCommandBreakpoints(session, command);
+  const resolvedCount = handles.reduce(
+    (total, handle) => total + handle.resolvedLocations.length,
+    0
+  );
+  reportProgress?.(
+    `Breakpoint setup complete: ${resolvedCount.toString()} resolved ${resolvedCount === 1 ? "location" : "locations"}.`
+  );
+  warnOnUnboundBreakpoints(handles);
+  reportProgress?.(
+    `Waiting up to ${(command.timeoutMs / 1e3).toString()}s for a breakpoint hit...`
+  );
+  const pause = await waitForCommandPause(session, opts, handles, command.timeoutMs);
+  const captureCount = command.captures.length;
+  reportProgress?.(
+    `Breakpoint hit; capturing ${captureCount.toString()} ${captureCount === 1 ? "expression" : "expressions"}...`
+  );
+  const pausedStartedAt = pause.receivedAtMs ?? performance4.now();
+  const snapshot = await captureSnapshot(session, pause, {
+    captures: command.captures,
+    includeScopes: opts.includeScopes === true,
+    ...command.maxValueLength === void 0 ? {} : { maxValueLength: command.maxValueLength },
+    ...command.stackDepth === void 0 ? {} : { stackDepth: command.stackDepth },
+    stackCaptures: command.stackCaptures
+  });
+  if (opts.keepPaused === true) {
+    reportProgress?.("Snapshot captured; leaving the target paused as requested.");
+    return withPausedDuration(snapshot, null);
+  }
+  reportProgress?.("Snapshot captured; resuming the target...");
+  return await resumeAfterSnapshot(session, snapshot, pausedStartedAt, reportProgress);
+}
 async function setCommandBreakpoints(session, command) {
   return await Promise.all(
     command.breakpoints.map(
@@ -2808,6 +2859,10 @@ 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";
@@ -2841,8 +2896,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),
@@ -2857,6 +2914,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);
   }
@@ -3030,6 +3090,10 @@ 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, options = {}) {
@@ -3040,9 +3104,27 @@ var collectStrings = (value, prev = []) => [
   ...prev,
   value
 ];
+function readPackageVersion() {
+  let current = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 4; depth += 1) {
+    const candidate = join(current, "package.json");
+    try {
+      const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+      if (typeof parsed === "object" && parsed !== null) {
+        const record = parsed;
+        if (record["name"] === "@saptools/cf-inspector" && typeof record["version"] === "string") {
+          return record["version"];
+        }
+      }
+    } catch {
+    }
+    current = dirname(current);
+  }
+  throw new Error("Unable to read @saptools/cf-inspector package version");
+}
 async function main(argv) {
   const program = new Command();
-  program.name("cf-inspector").description("Drive a Node.js inspector from the command line \u2014 set breakpoints, capture snapshots, evaluate expressions");
+  program.name("cf-inspector").version(readPackageVersion()).description("Drive a Node.js inspector from the command line \u2014 set breakpoints, capture snapshots, evaluate expressions");
   registerSnapshot(program);
   registerLog(program);
   registerWatch(program);
@@ -3057,7 +3139,7 @@ function registerSnapshot(program) {
   applyTargetOptions(
     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) => {
+  ).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);
   });
 }
@@ -3072,7 +3154,7 @@ function registerWatch(program) {
   applyTargetOptions(
     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) => {
+  ).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);
   });
 }