@saptools/cf-inspector 0.4.10 → 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`) |
@@ -203,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`) |

package/dist/cli.js

@@ -1124,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()];
 }
@@ -2711,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),
@@ -2726,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);
@@ -2808,6 +2830,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 +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),
@@ -2857,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);
   }
@@ -3030,6 +3061,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 = {}) {
@@ -3057,7 +3092,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 +3107,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);
   });
 }