@saptools/cf-inspector 0.3.7 → 0.3.9

package/README.md

@@ -22,7 +22,7 @@ Built so an AI agent (or a CI job) can drive a debugger from a single shell comm
 - ✅ **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
@@ -111,6 +111,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 |
 | `--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 |
@@ -120,7 +121,9 @@ cf-inspector snapshot --port 9229 \
 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 also includes `pausedDurationMs`, the client-observed time from receiving
+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
@@ -219,6 +222,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) {
@@ -240,7 +244,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,12 +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 SENSITIVE_NAME_REGEX = /(pass(?:word)?|credentials?|creds?|token|secret|api[_-]?key|authorization|cookie|session|private[_-]?key)/i;
+var DEFAULT_MAX_VALUE_LENGTH = 4096;
 var PRIORITY_BY_TYPE = {
   local: 0,
   arguments: 1,
@@ -1133,37 +1133,43 @@ 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 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`
+    );
   }
-  if (raw.length <= MAX_VALUE_LENGTH) {
+  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(
     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,
             described.objectId,
             MAX_CHILD_VARIABLES,
-            depth - 1
+            depth - 1,
+            maxValueLength
           );
           if (nested.length > 0) {
             children = nested;
@@ -1171,7 +1177,7 @@ async function captureProperties(session, objectId, limit, depth) {
         } catch {
         }
       }
-      const sanitizedValue = sensitive ? "[REDACTED]" : sanitizeValue(name, 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 };
@@ -1186,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) => {
@@ -1195,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: [] };
@@ -1203,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: sanitizeValue(expression, text) };
+    return { expression, error: limitValueLength(text, maxValueLength) };
   }
   const inner = result.result;
   if (!inner) {
@@ -1214,7 +1226,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, maxValueLength);
     const base = { expression, value: sanitized };
     return type === void 0 ? base : { ...base, type };
   };
@@ -1309,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);
@@ -1330,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;
   }
@@ -1338,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;
   }
@@ -1346,10 +1364,11 @@ async function withSerializedObjectCapture(session, expression, evalResult, capt
   if (normalized === void 0) {
     return captured;
   }
-  const value = sanitizeValue(expression, 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 = [];
@@ -1361,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) {
@@ -1369,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: message };
+            return { expression, error: limitValueLength(message, maxValueLength) };
           }
         })
       );
@@ -1651,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) => {
@@ -1685,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);
@@ -1856,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) => {