@saptools/cf-inspector 0.2.1 → 0.3.0

package/README.md

@@ -69,7 +69,7 @@ export SAP_PASSWORD=...
 cf-inspector snapshot \
   --region eu10 --org my-org --space dev --app my-srv \
   --bp src/handler.ts:42 \
-  --remote-root 'regex:^/(home/vcap/app|srv-.*)$'
+  --remote-root 'regex:^/(home/vcap/app|example-root-.*)$'
 ```
 
 The first form connects directly to `localhost:9229`. The second internally calls `@saptools/cf-debugger` to open the SSH tunnel, runs the snapshot through it, and tears the tunnel down on exit.
@@ -233,14 +233,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>
 
@@ -265,8 +269,8 @@ Path mapping uses CDP's first-class `urlRegex`:
 | --- | --- |
 | _omitted_ | `(?:^|/)src/handler\.(?:ts\|js)$` |
 | `/home/vcap/app` (literal) | `^file:///home/vcap/app/src/handler\.(?:ts\|js)$` |
-| `regex:^/srv-.*$` | `^file:///srv-[^/]+/src/handler\.(?:ts\|js)$` |
-| `/^/srv-.*$/` | same as above |
+| `regex:^/example-root-.*$` | `^file:///example-root-[^/]+/src/handler\.(?:ts\|js)$` |
+| `/^/example-root-.*$/` | same as above |
 
 `.ts ↔ .js` is folded into the regex automatically because Node's V8 inspector normally serves both the source-mapped TypeScript URL and the runtime JavaScript URL — matching either is correct.
 

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 {
@@ -1164,8 +1194,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,6 +1266,16 @@ 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}`);
@@ -1278,6 +1318,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 +1331,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 +1414,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 +1423,9 @@ async function handleLog(opts) {
         signal: abort.signal,
         onEvent: (event) => {
           writeLogEvent(event, opts.json);
+        },
+        onBreakpointSet: (handle) => {
+          warnOnUnboundBreakpoints([handle]);
         }
       });
       if (opts.json) {