@saptools/cf-inspector 0.2.2 → 0.3.1

package/README.md

@@ -115,6 +115,10 @@ cf-inspector snapshot --port 9229 \
 | `--no-json` | Print a human-readable summary instead of JSON |
 | `--keep-paused` | Skip the auto-resume after capture (useful for diagnostics) |
 
+JSON output includes `captureDurationMs`, the time spent collecting scopes and
+`--capture` expressions after the breakpoint has paused the process. It does
+not include the time spent waiting for the breakpoint to hit.
+
 For Cloud Foundry targets, replace `--port` with `--region/--org/--space/--app` (and optionally `--cf-timeout <seconds>` for the tunnel).
 
 ### 📡 `cf-inspector log`
@@ -233,14 +237,18 @@ console.log({ bp, snapshot, customValue });
 
 | Code | When |
 | --- | --- |
-| `INVALID_BREAKPOINT` | `--bp` is not in `file:line` form, or line is not a positive integer |
+| `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 |
+| `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 |
-| `CDP_REQUEST_FAILED` | A CDP method returned an error result |
+| `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 |
-| `EVALUATION_FAILED` | `Runtime.evaluate` / `Debugger.evaluateOnCallFrame` returned a remote exception |
-| `MISSING_TARGET` | Neither `--port` nor a CF target was provided |
+| `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>
 

package/dist/cli.js

@@ -606,7 +606,11 @@ async function connectInspector(options) {
   });
   const PAUSE_BUFFER_LIMIT = 32;
   const pauseBuffer = [];
+  const pauseWaitGate = { active: false };
   client.on("Debugger.paused", (raw) => {
+    if (pauseWaitGate.active) {
+      return;
+    }
     const params = raw;
     const event = {
       reason: asString(params.reason),
@@ -625,6 +629,7 @@ async function connectInspector(options) {
     target,
     scripts,
     pauseBuffer,
+    pauseWaitGate,
     dispose: async () => {
       try {
         await client.send("Debugger.disable");
@@ -750,17 +755,23 @@ async function waitForPause(session, options) {
       return head;
     }
   }
-  const params = await session.client.waitFor("Debugger.paused", {
-    timeoutMs: options.timeoutMs,
-    predicate: (raw) => {
-      const event = {
-        reason: asString(raw.reason),
-        hitBreakpoints: Array.isArray(raw.hitBreakpoints) ? raw.hitBreakpoints.filter((id) => typeof id === "string") : [],
-        callFrames: []
-      };
-      return pauseMatches(event, options.breakpointIds);
-    }
-  });
+  session.pauseWaitGate.active = true;
+  let params;
+  try {
+    const expected = options.breakpointIds;
+    params = await session.client.waitFor("Debugger.paused", {
+      timeoutMs: options.timeoutMs,
+      predicate: (raw) => {
+        if (expected === void 0 || expected.length === 0) {
+          return true;
+        }
+        const ids = Array.isArray(raw.hitBreakpoints) ? raw.hitBreakpoints.filter((id) => typeof id === "string") : [];
+        return ids.some((id) => expected.includes(id));
+      }
+    });
+  } finally {
+    session.pauseWaitGate.active = false;
+  }
   return {
     reason: asString(params.reason),
     hitBreakpoints: Array.isArray(params.hitBreakpoints) ? params.hitBreakpoints.filter((id) => typeof id === "string") : [],
@@ -790,6 +801,18 @@ async function evaluateGlobal(session, expression) {
 function listScripts(session) {
   return [...session.scripts.values()];
 }
+async function validateExpression(session, expression) {
+  const result = await session.client.send("Runtime.compileScript", {
+    expression,
+    sourceURL: "<cf-inspector-validate>",
+    persistScript: false
+  });
+  if (result.exceptionDetails === void 0) {
+    return;
+  }
+  const description = typeof result.exceptionDetails.exception?.description === "string" ? result.exceptionDetails.exception.description : typeof result.exceptionDetails.text === "string" ? result.exceptionDetails.text : "expression failed to compile";
+  throw new CfInspectorError("INVALID_EXPRESSION", description);
+}
 async function getProperties(session, objectId) {
   const result = await session.client.send("Runtime.getProperties", {
     objectId,
@@ -870,12 +893,6 @@ function generateSentinel() {
 async function streamLogpoint(session, options) {
   const sentinel = generateSentinel();
   const condition = buildLogpointCondition(sentinel, options.expression);
-  const handle = await setBreakpoint(session, {
-    file: options.location.file,
-    line: options.location.line,
-    ...options.remoteRoot === void 0 ? {} : { remoteRoot: options.remoteRoot },
-    condition
-  });
   let emitted = 0;
   const offEvent = session.client.on("Runtime.consoleAPICalled", (raw) => {
     const params = raw;
@@ -890,6 +907,19 @@ async function streamLogpoint(session, options) {
     emitted += 1;
     options.onEvent(event);
   });
+  let handle;
+  try {
+    handle = await setBreakpoint(session, {
+      file: options.location.file,
+      line: options.location.line,
+      ...options.remoteRoot === void 0 ? {} : { remoteRoot: options.remoteRoot },
+      condition
+    });
+  } catch (err) {
+    offEvent();
+    throw err;
+  }
+  options.onBreakpointSet?.(handle);
   const cleanup = async () => {
     offEvent();
     try {
@@ -939,6 +969,7 @@ async function waitForStop(session, options) {
 }
 
 // src/snapshot.ts
+import { performance } from "perf_hooks";
 var MAX_SCOPES = 3;
 var MAX_SCOPE_VARIABLES = 20;
 var MAX_CHILD_VARIABLES = 8;
@@ -1097,6 +1128,7 @@ function evalResultToCaptured(expression, result) {
   return buildCaptured("undefined");
 }
 async function captureSnapshot(session, pause, options = {}) {
+  const startedAt = performance.now();
   const top = pause.callFrames[0];
   let topFrame;
   let captures = [];
@@ -1123,10 +1155,12 @@ async function captureSnapshot(session, pause, options = {}) {
       );
     }
   }
+  const captureDurationMs = Math.round((performance.now() - startedAt) * 1e3) / 1e3;
   return {
     reason: pause.reason,
     hitBreakpoints: pause.hitBreakpoints,
     capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    captureDurationMs,
     ...topFrame === void 0 ? {} : { topFrame },
     captures
   };
@@ -1164,8 +1198,8 @@ function parsePositiveInt(raw, label) {
     return void 0;
   }
   const value = Number.parseInt(raw, 10);
-  if (Number.isNaN(value) || value <= 0) {
-    throw new CfInspectorError("MISSING_TARGET", `Invalid ${label}: "${raw}"`);
+  if (Number.isNaN(value) || value <= 0 || value.toString() !== raw.trim()) {
+    throw new CfInspectorError("INVALID_ARGUMENT", `Invalid ${label}: "${raw}" \u2014 expected a positive integer`);
   }
   return value;
 }
@@ -1236,9 +1270,23 @@ function writeJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}
 `);
 }
+function warnOnUnboundBreakpoints(handles) {
+  for (const handle of handles) {
+    if (handle.resolvedLocations.length === 0) {
+      process.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.
+`
+      );
+    }
+  }
+}
 function writeHumanSnapshot(snapshot) {
   const lines = [];
-  lines.push(`Snapshot @ ${snapshot.capturedAt}`, `  reason:  ${snapshot.reason}`);
+  lines.push(
+    `Snapshot @ ${snapshot.capturedAt}`,
+    `  reason:  ${snapshot.reason}`,
+    `  capture: ${snapshot.captureDurationMs.toFixed(1)}ms`
+  );
   if (snapshot.topFrame) {
     const frame = snapshot.topFrame;
     const fnName = frame.functionName.length === 0 ? "(anonymous)" : frame.functionName;
@@ -1278,6 +1326,9 @@ async function handleSnapshot(opts) {
   const timeoutMs = timeoutSec * 1e3;
   const condition = opts.condition !== void 0 && opts.condition.trim().length > 0 ? opts.condition.trim() : void 0;
   const result = await withSession(target, async (session) => {
+    if (condition !== void 0) {
+      await validateExpression(session, condition);
+    }
     const handles = await Promise.all(
       breakpoints.map(
         (bp) => setBreakpoint(session, {
@@ -1288,6 +1339,7 @@ async function handleSnapshot(opts) {
         })
       )
     );
+    warnOnUnboundBreakpoints(handles);
     const breakpointIds = handles.map((h) => h.breakpointId);
     const pause = await waitForPause(session, { timeoutMs, breakpointIds });
     const snapshot = await captureSnapshot(session, pause, { captures });
@@ -1370,6 +1422,7 @@ async function handleLog(opts) {
   process.once("SIGTERM", onSig);
   try {
     await withSession(target, async (session) => {
+      await validateExpression(session, expression);
       const result = await streamLogpoint(session, {
         location,
         expression,
@@ -1378,6 +1431,9 @@ async function handleLog(opts) {
         signal: abort.signal,
         onEvent: (event) => {
           writeLogEvent(event, opts.json);
+        },
+        onBreakpointSet: (handle) => {
+          warnOnUnboundBreakpoints([handle]);
         }
       });
       if (opts.json) {