@saptools/cf-inspector 0.3.6 → 0.3.8

package/README.md

@@ -18,11 +18,11 @@ Built so an AI agent (or a CI job) can drive a debugger from a single shell comm
 
 ## ✨ Features
 
-- 🎯 **One-shot snapshot** — `cf-inspector snapshot --bp src/handler.ts:42` sets the breakpoint, waits for it to hit, captures the scope, auto-resumes, prints JSON, exits
+- 🎯 **One-shot snapshot** — `cf-inspector snapshot --bp src/handler.ts:42` sets the breakpoint, waits for it to hit, captures requested expressions, auto-resumes, prints JSON, exits
 - ✅ **Conditional breakpoints** — `--condition 'req.userId === "abc"'` only pauses when the predicate is truthy
 - 🎭 **Multi-breakpoint** — repeat `--bp` to race several locations; first hit wins
 - 📡 **Non-pausing logpoints** — `cf-inspector log --at file:line --expr 'JSON.stringify({…})'` streams JSON Lines as the line executes, **without ever pausing the inspectee** (safe for production traffic)
-- 🧠 **Agent-friendly** — JSON-by-default I/O, deterministic shape, sensitive-name redaction (`password`, `credentials`, `token`, `secret`, `cookie`, …) baked in
+- 🧠 **Agent-friendly** — JSON-by-default I/O, deterministic shape, bounded value previews for large debugger payloads
 - 🧭 **Path mapping** — local `src/handler.ts:42` is matched against the remote URL via a `urlRegex`, with optional `--remote-root` literal or regex (same DSL as `cds-debug`)
 - 🔁 **Composes with `cf-debugger`** — pass `--app/--region/--org/--space` and the tunnel is opened automatically; pass `--port` to attach to anything CDP-speaking
 - 🪶 **Tiny dependency footprint** — `commander` + `ws` only, no heavy CDP framework
@@ -80,7 +80,7 @@ The first form connects directly to `localhost:9229`. The second internally call
 
 ### 📸 `cf-inspector snapshot`
 
-Set one or more breakpoints, wait for any of them to hit, capture the scope, auto-resume, exit.
+Set one or more breakpoints, wait for any of them to hit, capture frame metadata and requested expressions, auto-resume, exit.
 
 ```bash
 # Simple snapshot
@@ -112,11 +112,17 @@ cf-inspector snapshot --port 9229 \
 | `--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 |
 | `--timeout <seconds>` | How long to wait for the breakpoint to hit (default: `30`) |
 | `--remote-root <value>` | Optional path-mapping anchor: literal path or `regex:<pattern>` / `/pattern/flags` |
+| `--include-scopes` | Include expanded paused-frame scopes under `topFrame.scopes`. Omitted by default to keep targeted captures concise |
 | `--no-json` | Print a human-readable summary instead of JSON |
 | `--keep-paused` | Skip `Debugger.resume` after capture; Node may resume when the CLI disconnects |
 | `--fail-on-unmatched-pause` | Fail immediately if the target pauses somewhere else instead of waiting cooperatively |
 
-JSON output includes `pausedDurationMs`, the client-observed time from receiving
+JSON output includes frame metadata and `captures` by default. `topFrame.scopes`
+is only present with `--include-scopes`, because Cloud Foundry Node apps often
+carry large local/closure/module objects that drown out targeted captures. The
+output contains raw debugger values; use it only against trusted targets and be
+careful when sharing logs. The output also includes `pausedDurationMs`, the
+client-observed time from receiving
 the matching pause event until `Debugger.resume` completes. It does not include
 the time spent waiting for the breakpoint to hit. When `--keep-paused` is used,
 `pausedDurationMs` is `null` because `cf-inspector` intentionally skips
@@ -213,7 +219,9 @@ const bp = await setBreakpoint(session, {
   line: 42,
 });
 const pause = await waitForPause(session, { timeoutMs: 30_000 });
-const snapshot = await captureSnapshot(session, pause);
+const snapshot = await captureSnapshot(session, pause, {
+  captures: ["this.user"],
+});
 const topFrame = pause.callFrames[0];
 if (topFrame === undefined) {
   throw new Error("Breakpoint paused without a call frame");
@@ -234,7 +242,7 @@ console.log({ bp, snapshot, customValue });
 | `setBreakpoint(session, location)` | Set a breakpoint by file/line + optional remote root |
 | `removeBreakpoint(session, id)` | Remove a breakpoint by id |
 | `waitForPause(session, options)` | Resolve when the next `Debugger.paused` event fires |
-| `captureSnapshot(session, pause)` | Build a structured snapshot of the paused scope |
+| `captureSnapshot(session, pause, options)` | Build a structured snapshot of the paused frame. Pass `includeScopes: true` to expand scopes |
 | `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 |
@@ -280,7 +288,7 @@ console.log({ bp, snapshot, customValue });
 └──────────────────────┘   4. Debugger.setBreakpointByUrl({ urlRegex, lineNumber: Y - 1 })
             │              5. Wait for `Debugger.paused`
             ▼              6. Debugger.evaluateOnCallFrame(...)  for each --capture expression
-   JSON snapshot           7. Runtime.getProperties(scopeChain[i].object.objectId)
+   JSON snapshot           7. Runtime.getProperties(scopeChain[i].object.objectId) when --include-scopes is set
                            8. Debugger.resume   (unless --keep-paused)
 ```
 

package/dist/cli.js

@@ -1072,7 +1072,6 @@ var MAX_SCOPE_VARIABLES = 20;
 var MAX_CHILD_VARIABLES = 8;
 var MAX_VARIABLE_DEPTH = 2;
 var MAX_VALUE_LENGTH = 240;
-var SENSITIVE_NAME_REGEX = /(pass(?:word)?|credentials?|creds?|token|secret|api[_-]?key|authorization|cookie|session|private[_-]?key)/i;
 var PRIORITY_BY_TYPE = {
   local: 0,
   arguments: 1,
@@ -1133,13 +1132,7 @@ function formatPrimitive(value) {
   }
   return String(value);
 }
-function isSensitiveName(name) {
-  return SENSITIVE_NAME_REGEX.test(name);
-}
-function sanitizeValue(name, raw) {
-  if (isSensitiveName(name)) {
-    return "[REDACTED]";
-  }
+function limitValueLength(raw) {
   if (raw.length <= MAX_VALUE_LENGTH) {
     return raw;
   }
@@ -1155,9 +1148,8 @@ async function captureProperties(session, objectId, limit, depth) {
     limited.map(async (prop) => {
       const name = typeof prop.name === "string" ? prop.name : "?";
       const described = describeProperty(prop);
-      const sensitive = isSensitiveName(name);
       let children;
-      if (!sensitive && depth > 0 && described.objectId !== void 0 && isExpandable(described.type)) {
+      if (depth > 0 && described.objectId !== void 0 && isExpandable(described.type)) {
         try {
           const nested = await captureProperties(
             session,
@@ -1171,7 +1163,7 @@ async function captureProperties(session, objectId, limit, depth) {
         } catch {
         }
       }
-      const sanitizedValue = sensitive ? "[REDACTED]" : sanitizeValue(name, described.value);
+      const sanitizedValue = limitValueLength(described.value);
       const base = { name, value: sanitizedValue };
       const withType = described.type === void 0 ? base : { ...base, type: described.type };
       return children === void 0 ? withType : { ...withType, children };
@@ -1206,7 +1198,7 @@ async function captureScopes(session, frame) {
 function evalResultToCaptured(expression, result) {
   if (result.exceptionDetails !== void 0) {
     const text = typeof result.exceptionDetails.exception?.description === "string" ? result.exceptionDetails.exception.description : typeof result.exceptionDetails.text === "string" ? result.exceptionDetails.text : "evaluation failed";
-    return { expression, error: sanitizeValue(expression, text) };
+    return { expression, error: limitValueLength(text) };
   }
   const inner = result.result;
   if (!inner) {
@@ -1214,7 +1206,7 @@ function evalResultToCaptured(expression, result) {
   }
   const type = typeof inner.type === "string" ? inner.type : void 0;
   const buildCaptured = (rendered) => {
-    const sanitized = sanitizeValue(expression, rendered);
+    const sanitized = limitValueLength(rendered);
     const base = { expression, value: sanitized };
     return type === void 0 ? base : { ...base, type };
   };
@@ -1346,7 +1338,7 @@ async function withSerializedObjectCapture(session, expression, evalResult, capt
   if (normalized === void 0) {
     return captured;
   }
-  const value = sanitizeValue(expression, normalized);
+  const value = limitValueLength(normalized);
   return captured.type === void 0 ? { expression, value } : { expression, value, type: captured.type };
 }
 async function captureSnapshot(session, pause, options = {}) {
@@ -1354,14 +1346,16 @@ async function captureSnapshot(session, pause, options = {}) {
   let topFrame;
   let captures = [];
   if (top) {
-    const scopes = await captureScopes(session, top);
     topFrame = {
       functionName: top.functionName,
       ...top.url === void 0 ? {} : { url: top.url },
       line: top.lineNumber + 1,
-      column: top.columnNumber + 1,
-      scopes
+      column: top.columnNumber + 1
     };
+    if (options.includeScopes === true) {
+      const scopes = await captureScopes(session, top);
+      topFrame = { ...topFrame, scopes };
+    }
     if (options.captures !== void 0 && options.captures.length > 0) {
       captures = await Promise.all(
         options.captures.map(async (expression) => {
@@ -1371,7 +1365,7 @@ async function captureSnapshot(session, pause, options = {}) {
             return await withSerializedObjectCapture(session, expression, result, captured);
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            return { expression, error: message };
+            return { expression, error: limitValueLength(message) };
           }
         })
       );
@@ -1618,10 +1612,12 @@ function writeHumanSnapshot(snapshot) {
     lines.push(
       `  frame:   ${fnName} ${sourceUrl}:${frame.line.toString()}:${frame.column.toString()}`
     );
-    for (const scope of frame.scopes) {
-      lines.push(`  scope ${scope.type} (${scope.variables.length.toString()} vars):`);
-      for (const variable of scope.variables) {
-        lines.push(`    ${variable.name} = ${variable.value}`);
+    if (frame.scopes !== void 0) {
+      for (const scope of frame.scopes) {
+        lines.push(`  scope ${scope.type} (${scope.variables.length.toString()} vars):`);
+        for (const variable of scope.variables) {
+          lines.push(`    ${variable.name} = ${variable.value}`);
+        }
       }
     }
   }
@@ -1679,7 +1675,10 @@ async function handleSnapshot(opts) {
       }
     });
     const pausedStartedAt = pause.receivedAtMs ?? performance2.now();
-    const snapshot = await captureSnapshot(session, pause, { captures });
+    const snapshot = await captureSnapshot(session, pause, {
+      captures,
+      includeScopes: opts.includeScopes === true
+    });
     if (opts.keepPaused === true) {
       return withPausedDuration(snapshot, null);
     }
@@ -1843,7 +1842,7 @@ async function main(argv) {
     value
   ];
   applyTargetOptions(
-    program.command("snapshot").description("Set a breakpoint, wait for it to hit, capture the scope, and resume")
+    program.command("snapshot").description("Set a breakpoint, wait for it to hit, capture expressions, and resume")
   ).option(
     "--bp <file:line>",
     "Breakpoint location (repeatable; first hit wins), e.g. src/handler.ts:42",
@@ -1852,7 +1851,7 @@ async function main(argv) {
   ).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("--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("--no-json", "Print a human-readable summary instead of JSON").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("--include-scopes", "Include expanded paused-frame scopes in the snapshot").option("--no-json", "Print a human-readable summary instead of JSON").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);
   });
   applyTargetOptions(