@saptools/cf-inspector 0.3.8 → 0.3.11

package/README.md

@@ -46,20 +46,6 @@ pnpm add @saptools/cf-inspector
 
 ## 🚀 Quick Start
 
-### Local Node process
-
-```bash
-# Terminal 1 — run any Node app with the inspector enabled
-node --inspect=9229 my-app.js
-
-# Terminal 2 — capture a snapshot when handler.ts:42 hits
-cf-inspector snapshot \
-  --port 9229 \
-  --bp src/handler.ts:42 \
-  --capture 'this.user, req.body' \
-  --timeout 30
-```
-
 ### Cloud Foundry app (auto-tunnel)
 
 ```bash
@@ -72,7 +58,7 @@ cf-inspector snapshot \
   --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.
+This command internally calls `@saptools/cf-debugger` to open the SSH tunnel, runs the snapshot through it, and tears the tunnel down on exit.
 
 ---
 
@@ -111,24 +97,21 @@ 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 |
 | `--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`) |
+| `--max-value-length <chars>` | Maximum characters per captured value before truncation (default: `4096`) |
 | `--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 |
+| `--keep-paused` | Skip `Debugger.resume` after capture |
 | `--fail-on-unmatched-pause` | Fail immediately if the target pauses somewhere else instead of waiting cooperatively |
 
-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
-`Debugger.resume`. Node may resume execution when this one-shot CLI disconnects,
-so treat `--keep-paused` as a low-level diagnostic escape hatch, not a durable
-paused-session mode.
+Snapshot JSON includes frame metadata and `captures` by default. `topFrame.scopes`
+is only present with `--include-scopes` because scope objects can be large and
+drown out targeted captures. Values are raw debugger values, so be careful when
+sharing logs.
+
+`pausedDurationMs` measures the client-observed time from receiving the matching
+pause event until `Debugger.resume` completes. With `--keep-paused`, it is `null`
+because resume is intentionally skipped.
 
 If the target pauses somewhere else first, for example another debugger's
 breakpoint or a `debugger;` statement, `snapshot` does not resume it by default.
@@ -221,6 +204,7 @@ const bp = await setBreakpoint(session, {
 const pause = await waitForPause(session, { timeoutMs: 30_000 });
 const snapshot = await captureSnapshot(session, pause, {
   captures: ["this.user"],
+  maxValueLength: 4096,
 });
 const topFrame = pause.callFrames[0];
 if (topFrame === undefined) {
@@ -242,7 +226,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, options)` | Build a structured snapshot of the paused frame. Pass `includeScopes: true` to expand scopes |
+| `captureSnapshot(session, pause, options)` | Build a structured snapshot of the paused frame. Pass `includeScopes: true` to expand scopes or `maxValueLength` to override the default captured value limit |
 | `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 |

package/dist/cli.js

@@ -1067,11 +1067,12 @@ async function waitForStop(session, options) {
 }
 
 // src/snapshot.ts
+init_types();
 var MAX_SCOPES = 3;
 var MAX_SCOPE_VARIABLES = 20;
 var MAX_CHILD_VARIABLES = 8;
 var MAX_VARIABLE_DEPTH = 2;
-var MAX_VALUE_LENGTH = 240;
+var DEFAULT_MAX_VALUE_LENGTH = 4096;
 var PRIORITY_BY_TYPE = {
   local: 0,
   arguments: 1,
@@ -1132,16 +1133,28 @@ function formatPrimitive(value) {
   }
   return String(value);
 }
-function limitValueLength(raw) {
-  if (raw.length <= MAX_VALUE_LENGTH) {
+function resolveMaxValueLength(value) {
+  if (value === void 0) {
+    return DEFAULT_MAX_VALUE_LENGTH;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new CfInspectorError(
+      "INVALID_ARGUMENT",
+      `Invalid maxValueLength: ${value.toString()} \u2014 expected a positive integer`
+    );
+  }
+  return value;
+}
+function limitValueLength(raw, maxValueLength = DEFAULT_MAX_VALUE_LENGTH) {
+  if (raw.length <= maxValueLength) {
     return raw;
   }
-  return `${raw.slice(0, MAX_VALUE_LENGTH)}...`;
+  return `${raw.slice(0, maxValueLength)}...`;
 }
 function isExpandable(type) {
   return type === "object" || type === "function";
 }
-async function captureProperties(session, objectId, limit, depth) {
+async function captureProperties(session, objectId, limit, depth, maxValueLength) {
   const properties = await getProperties(session, objectId);
   const limited = properties.slice(0, limit);
   const variables = await Promise.all(
@@ -1155,7 +1168,8 @@ async function captureProperties(session, objectId, limit, depth) {
             session,
             described.objectId,
             MAX_CHILD_VARIABLES,
-            depth - 1
+            depth - 1,
+            maxValueLength
           );
           if (nested.length > 0) {
             children = nested;
@@ -1163,7 +1177,7 @@ async function captureProperties(session, objectId, limit, depth) {
         } catch {
         }
       }
-      const sanitizedValue = limitValueLength(described.value);
+      const sanitizedValue = limitValueLength(described.value, maxValueLength);
       const base = { name, value: sanitizedValue };
       const withType = described.type === void 0 ? base : { ...base, type: described.type };
       return children === void 0 ? withType : { ...withType, children };
@@ -1178,7 +1192,7 @@ function selectScopes(scopeChain) {
 function priorityOf(type) {
   return PRIORITY_BY_TYPE[type] ?? Number.MAX_SAFE_INTEGER;
 }
-async function captureScopes(session, frame) {
+async function captureScopes(session, frame, maxValueLength) {
   const scopes = selectScopes(frame.scopeChain);
   return await Promise.all(
     scopes.map(async (scope) => {
@@ -1187,7 +1201,13 @@ async function captureScopes(session, frame) {
         return { type: scope.type, variables: [] };
       }
       try {
-        const variables = await captureProperties(session, objectId, MAX_SCOPE_VARIABLES, MAX_VARIABLE_DEPTH);
+        const variables = await captureProperties(
+          session,
+          objectId,
+          MAX_SCOPE_VARIABLES,
+          MAX_VARIABLE_DEPTH,
+          maxValueLength
+        );
         return { type: scope.type, variables };
       } catch {
         return { type: scope.type, variables: [] };
@@ -1195,10 +1215,10 @@ async function captureScopes(session, frame) {
     })
   );
 }
-function evalResultToCaptured(expression, result) {
+function evalResultToCaptured(expression, result, maxValueLength = DEFAULT_MAX_VALUE_LENGTH) {
   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: limitValueLength(text) };
+    return { expression, error: limitValueLength(text, maxValueLength) };
   }
   const inner = result.result;
   if (!inner) {
@@ -1206,7 +1226,7 @@ function evalResultToCaptured(expression, result) {
   }
   const type = typeof inner.type === "string" ? inner.type : void 0;
   const buildCaptured = (rendered) => {
-    const sanitized = limitValueLength(rendered);
+    const sanitized = limitValueLength(rendered, maxValueLength);
     const base = { expression, value: sanitized };
     return type === void 0 ? base : { ...base, type };
   };
@@ -1301,9 +1321,15 @@ function toStructuredValue(variable) {
   }
   return out;
 }
-async function renderObjectCapture(session, objectId) {
+async function renderObjectCapture(session, objectId, maxValueLength) {
   try {
-    const properties = await captureProperties(session, objectId, MAX_SCOPE_VARIABLES, MAX_VARIABLE_DEPTH);
+    const properties = await captureProperties(
+      session,
+      objectId,
+      MAX_SCOPE_VARIABLES,
+      MAX_VARIABLE_DEPTH,
+      maxValueLength
+    );
     const structured = {};
     for (const variable of properties) {
       structured[variable.name] = toStructuredValue(variable);
@@ -1322,7 +1348,7 @@ function normalizeRenderedObjectCapture(rendered, original) {
   }
   return rendered;
 }
-async function withSerializedObjectCapture(session, expression, evalResult, captured) {
+async function withSerializedObjectCapture(session, expression, evalResult, captured, maxValueLength) {
   if (captured.error !== void 0 || captured.value === void 0) {
     return captured;
   }
@@ -1330,7 +1356,7 @@ async function withSerializedObjectCapture(session, expression, evalResult, capt
   if (objectId === void 0) {
     return captured;
   }
-  const rendered = await renderObjectCapture(session, objectId);
+  const rendered = await renderObjectCapture(session, objectId, maxValueLength);
   if (rendered === void 0) {
     return captured;
   }
@@ -1338,10 +1364,11 @@ async function withSerializedObjectCapture(session, expression, evalResult, capt
   if (normalized === void 0) {
     return captured;
   }
-  const value = limitValueLength(normalized);
+  const value = limitValueLength(normalized, maxValueLength);
   return captured.type === void 0 ? { expression, value } : { expression, value, type: captured.type };
 }
 async function captureSnapshot(session, pause, options = {}) {
+  const maxValueLength = resolveMaxValueLength(options.maxValueLength);
   const top = pause.callFrames[0];
   let topFrame;
   let captures = [];
@@ -1353,7 +1380,7 @@ async function captureSnapshot(session, pause, options = {}) {
       column: top.columnNumber + 1
     };
     if (options.includeScopes === true) {
-      const scopes = await captureScopes(session, top);
+      const scopes = await captureScopes(session, top, maxValueLength);
       topFrame = { ...topFrame, scopes };
     }
     if (options.captures !== void 0 && options.captures.length > 0) {
@@ -1361,11 +1388,17 @@ async function captureSnapshot(session, pause, options = {}) {
         options.captures.map(async (expression) => {
           try {
             const result = await evaluateOnFrame(session, top.callFrameId, expression);
-            const captured = evalResultToCaptured(expression, result);
-            return await withSerializedObjectCapture(session, expression, result, captured);
+            const captured = evalResultToCaptured(expression, result, maxValueLength);
+            return await withSerializedObjectCapture(
+              session,
+              expression,
+              result,
+              captured,
+              maxValueLength
+            );
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            return { expression, error: limitValueLength(message) };
+            return { expression, error: limitValueLength(message, maxValueLength) };
           }
         })
       );
@@ -1643,6 +1676,7 @@ async function handleSnapshot(opts) {
   const remoteRoot = parseRemoteRoot(opts.remoteRoot);
   const captures = parseCaptureList(opts.capture);
   const timeoutSec = parsePositiveInt(opts.timeout, "--timeout") ?? DEFAULT_BREAKPOINT_TIMEOUT_SEC;
+  const maxValueLength = parsePositiveInt(opts.maxValueLength, "--max-value-length");
   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) => {
@@ -1677,7 +1711,8 @@ async function handleSnapshot(opts) {
     const pausedStartedAt = pause.receivedAtMs ?? performance2.now();
     const snapshot = await captureSnapshot(session, pause, {
       captures,
-      includeScopes: opts.includeScopes === true
+      includeScopes: opts.includeScopes === true,
+      ...maxValueLength === void 0 ? {} : { maxValueLength }
     });
     if (opts.keepPaused === true) {
       return withPausedDuration(snapshot, null);
@@ -1848,7 +1883,7 @@ async function main(argv) {
     "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("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option(
+  ).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("--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) => {