@saptools/cf-inspector 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { DebuggerHandle } from '@saptools/cf-debugger';
 
-type CfInspectorErrorCode = "INVALID_ARGUMENT" | "INVALID_BREAKPOINT" | "INVALID_REMOTE_ROOT" | "INVALID_EXPRESSION" | "BREAKPOINT_DID_NOT_BIND" | "INSPECTOR_DISCOVERY_FAILED" | "INSPECTOR_CONNECTION_FAILED" | "CDP_REQUEST_FAILED" | "BREAKPOINT_NOT_HIT" | "EVALUATION_FAILED" | "MISSING_TARGET" | "ABORTED";
+type CfInspectorErrorCode = "INVALID_ARGUMENT" | "INVALID_BREAKPOINT" | "INVALID_REMOTE_ROOT" | "INVALID_EXPRESSION" | "BREAKPOINT_DID_NOT_BIND" | "INSPECTOR_DISCOVERY_FAILED" | "INSPECTOR_CONNECTION_FAILED" | "CDP_REQUEST_FAILED" | "BREAKPOINT_NOT_HIT" | "UNRELATED_PAUSE" | "UNRELATED_PAUSE_TIMEOUT" | "EVALUATION_FAILED" | "MISSING_TARGET" | "ABORTED";
 declare class CfInspectorError extends Error {
     readonly code: CfInspectorErrorCode;
     readonly detail?: string;
@@ -54,6 +54,7 @@ interface PauseEvent {
     readonly reason: string;
     readonly hitBreakpoints: readonly string[];
     readonly callFrames: readonly CallFrameInfo[];
+    readonly receivedAtMs?: number;
 }
 interface VariableSnapshot {
     readonly name: string;
@@ -78,14 +79,16 @@ interface CapturedExpression {
     readonly type?: string;
     readonly error?: string;
 }
-interface SnapshotResult {
+interface SnapshotCaptureResult {
     readonly reason: string;
     readonly hitBreakpoints: readonly string[];
     readonly capturedAt: string;
-    readonly captureDurationMs: number;
     readonly topFrame?: FrameSnapshot;
     readonly captures: readonly CapturedExpression[];
 }
+interface SnapshotResult extends SnapshotCaptureResult {
+    readonly pausedDurationMs: number | null;
+}
 interface ScriptInfo {
     readonly scriptId: string;
     readonly url: string;
@@ -170,12 +173,16 @@ interface InspectorVersion {
 interface PauseWaitGate {
     active: boolean;
 }
+interface DebuggerState {
+    lastResumedAtMs?: number;
+}
 interface InspectorSession {
     readonly client: CdpClient;
     readonly target: InspectorTarget;
     readonly scripts: ReadonlyMap<string, ScriptInfo>;
     readonly pauseBuffer: PauseEvent[];
     readonly pauseWaitGate: PauseWaitGate;
+    readonly debuggerState: DebuggerState;
     dispose(): Promise<void>;
 }
 interface CdpEvalResult {
@@ -204,6 +211,8 @@ declare function removeBreakpoint(session: InspectorSession, breakpointId: strin
 interface WaitForPauseOptions {
     readonly timeoutMs: number;
     readonly breakpointIds?: readonly string[];
+    readonly unmatchedPausePolicy?: "wait-for-resume" | "fail";
+    readonly onUnmatchedPause?: (pause: PauseEvent) => void;
 }
 declare function waitForPause(session: InspectorSession, options: WaitForPauseOptions): Promise<PauseEvent>;
 declare function resume(session: InspectorSession): Promise<void>;
@@ -236,7 +245,7 @@ declare function getProperties(session: InspectorSession, objectId: string): Pro
 interface CaptureSnapshotOptions {
     readonly captures?: readonly string[];
 }
-declare function captureSnapshot(session: InspectorSession, pause: PauseEvent, options?: CaptureSnapshotOptions): Promise<SnapshotResult>;
+declare function captureSnapshot(session: InspectorSession, pause: PauseEvent, options?: CaptureSnapshotOptions): Promise<SnapshotCaptureResult>;
 
 interface LogpointEvent {
     readonly ts: string;
@@ -296,4 +305,4 @@ interface OpenedTunnel {
 }
 declare function openCfTunnel(target: TunnelTarget): Promise<OpenedTunnel>;
 
-export { type BreakpointHandle, type BreakpointLocation, type CallFrameInfo, type CaptureSnapshotOptions, type CapturedExpression, CfInspectorError, type CfInspectorErrorCode, type FrameSnapshot, type InspectorConnectOptions, type InspectorSession, type InspectorTarget, type LogpointEvent, type LogpointStreamOptions, type LogpointStreamResult, type OpenedTunnel, type PauseEvent, type RemoteRootSetting, type ResolvedLocation, type ScopeInfo, type ScopeSnapshot, type ScriptInfo, type SetBreakpointInput, type SnapshotResult, type TunnelTarget, type VariableSnapshot, type WaitForPauseOptions, buildBreakpointUrlRegex, buildLogpointCondition, captureSnapshot, connectInspector, discoverInspectorTargets, evaluateGlobal, evaluateOnFrame, fetchInspectorVersion, getProperties, listScripts, openCfTunnel, parseBreakpointSpec, parseRemoteRoot, removeBreakpoint, resume, setBreakpoint, streamLogpoint, validateExpression, waitForPause };
+export { type BreakpointHandle, type BreakpointLocation, type CallFrameInfo, type CaptureSnapshotOptions, type CapturedExpression, CfInspectorError, type CfInspectorErrorCode, type DebuggerState, type FrameSnapshot, type InspectorConnectOptions, type InspectorSession, type InspectorTarget, type LogpointEvent, type LogpointStreamOptions, type LogpointStreamResult, type OpenedTunnel, type PauseEvent, type RemoteRootSetting, type ResolvedLocation, type ScopeInfo, type ScopeSnapshot, type ScriptInfo, type SetBreakpointInput, type SnapshotCaptureResult, type SnapshotResult, type TunnelTarget, type VariableSnapshot, type WaitForPauseOptions, buildBreakpointUrlRegex, buildLogpointCondition, captureSnapshot, connectInspector, discoverInspectorTargets, evaluateGlobal, evaluateOnFrame, fetchInspectorVersion, getProperties, listScripts, openCfTunnel, parseBreakpointSpec, parseRemoteRoot, removeBreakpoint, resume, setBreakpoint, streamLogpoint, validateExpression, waitForPause };

package/dist/index.js

@@ -215,6 +215,15 @@ function stripTrailingSlash(value) {
   }
   return value;
 }
+function normalizeRegexRootPattern(pattern) {
+  const withoutStartAnchor = pattern.startsWith("^") ? pattern.slice(1) : pattern;
+  const withoutEndAnchor = withoutStartAnchor.endsWith("$") && !isEscaped(withoutStartAnchor, withoutStartAnchor.length - 1) ? withoutStartAnchor.slice(0, -1) : withoutStartAnchor;
+  return stripTrailingSlash(withoutEndAnchor);
+}
+function buildFileUrlRegex(rootPattern, tail) {
+  const separator = rootPattern.endsWith("/") ? "" : "/";
+  return `^file://${rootPattern}${separator}${tail}$`;
+}
 function escapeRegExp(value) {
   return value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
 }
@@ -241,16 +250,18 @@ function buildBreakpointUrlRegex(input) {
     }
     case "literal": {
       const escapedRoot = escapeRegExp(input.remoteRoot.value);
-      return `^file://${escapedRoot}/${tail}$`;
+      return buildFileUrlRegex(escapedRoot, tail);
     }
     case "regex": {
-      return `^file://${input.remoteRoot.pattern}/${tail}$`;
+      const rootPattern = normalizeRegexRootPattern(input.remoteRoot.pattern);
+      return buildFileUrlRegex(rootPattern, tail);
     }
   }
 }
 
 // src/inspector.ts
 import { request } from "http";
+import { performance } from "perf_hooks";
 
 // src/cdp.ts
 init_types();
@@ -606,21 +617,21 @@ async function connectInspector(options) {
   const PAUSE_BUFFER_LIMIT = 32;
   const pauseBuffer = [];
   const pauseWaitGate = { active: false };
+  const debuggerState = {};
   client.on("Debugger.paused", (raw) => {
     if (pauseWaitGate.active) {
       return;
     }
     const params = raw;
-    const event = {
-      reason: asString(params.reason),
-      hitBreakpoints: Array.isArray(params.hitBreakpoints) ? params.hitBreakpoints.filter((id) => typeof id === "string") : [],
-      callFrames: toCallFrames(params.callFrames)
-    };
+    const event = toPauseEvent(params, performance.now());
     if (pauseBuffer.length >= PAUSE_BUFFER_LIMIT) {
       pauseBuffer.shift();
     }
     pauseBuffer.push(event);
   });
+  client.on("Debugger.resumed", () => {
+    debuggerState.lastResumedAtMs = performance.now();
+  });
   await client.send("Runtime.enable");
   await client.send("Debugger.enable");
   return {
@@ -629,6 +640,7 @@ async function connectInspector(options) {
     scripts,
     pauseBuffer,
     pauseWaitGate,
+    debuggerState,
     dispose: async () => {
       try {
         await client.send("Debugger.disable");
@@ -746,36 +758,121 @@ function pauseMatches(pause, breakpointIds) {
   }
   return pause.hitBreakpoints.some((id) => breakpointIds.includes(id));
 }
+function toPauseEvent(params, receivedAtMs) {
+  return {
+    reason: asString(params.reason),
+    hitBreakpoints: Array.isArray(params.hitBreakpoints) ? params.hitBreakpoints.filter((id) => typeof id === "string") : [],
+    callFrames: toCallFrames(params.callFrames),
+    receivedAtMs
+  };
+}
+function remainingUntil(deadlineMs) {
+  return Math.max(0, deadlineMs - performance.now());
+}
+function topFrameLocation(pause) {
+  const top = pause.callFrames[0];
+  if (top === void 0) {
+    return "(no call frame)";
+  }
+  const url = top.url !== void 0 && top.url.length > 0 ? top.url : "(unknown)";
+  return `${url}:${(top.lineNumber + 1).toString()}:${(top.columnNumber + 1).toString()}`;
+}
+function pauseDetail(pause) {
+  return JSON.stringify({
+    reason: pause.reason,
+    hitBreakpoints: pause.hitBreakpoints,
+    topFrame: topFrameLocation(pause)
+  });
+}
+function hasResumedSincePause(session, pause) {
+  const pauseAt = pause.receivedAtMs;
+  const resumedAt = session.debuggerState.lastResumedAtMs;
+  return pauseAt !== void 0 && resumedAt !== void 0 && resumedAt >= pauseAt;
+}
+function throwBreakpointTimeout(timeoutMs) {
+  throw new CfInspectorError(
+    "BREAKPOINT_NOT_HIT",
+    `Timed out waiting for matching Debugger.paused after ${timeoutMs.toString()}ms`
+  );
+}
+function throwUnrelatedPauseTimeout(pause, timeoutMs) {
+  throw new CfInspectorError(
+    "UNRELATED_PAUSE_TIMEOUT",
+    `Target stayed paused by another debugger event before this command's breakpoint could hit within ${timeoutMs.toString()}ms`,
+    pauseDetail(pause)
+  );
+}
+async function waitForUnmatchedPauseToResume(session, pause, deadlineMs, timeoutMs) {
+  if (hasResumedSincePause(session, pause)) {
+    return;
+  }
+  const remainingMs = remainingUntil(deadlineMs);
+  if (remainingMs <= 0) {
+    throwUnrelatedPauseTimeout(pause, timeoutMs);
+  }
+  try {
+    await session.client.waitFor("Debugger.resumed", { timeoutMs: remainingMs });
+    session.debuggerState.lastResumedAtMs = performance.now();
+  } catch (err) {
+    if (err instanceof CfInspectorError && err.code === "BREAKPOINT_NOT_HIT") {
+      throwUnrelatedPauseTimeout(pause, timeoutMs);
+    }
+    throw err;
+  }
+}
+async function handleUnmatchedPause(session, pause, options, deadlineMs) {
+  if (options.unmatchedPausePolicy === "fail") {
+    throw new CfInspectorError(
+      "UNRELATED_PAUSE",
+      "Target paused before this command's breakpoint was reached",
+      pauseDetail(pause)
+    );
+  }
+  if (hasResumedSincePause(session, pause)) {
+    return;
+  }
+  options.onUnmatchedPause?.(pause);
+  await waitForUnmatchedPauseToResume(session, pause, deadlineMs, options.timeoutMs);
+}
 async function waitForPause(session, options) {
+  const deadlineMs = performance.now() + options.timeoutMs;
   const buffer = session.pauseBuffer;
-  while (buffer.length > 0) {
-    const head = buffer.shift();
-    if (head !== void 0 && pauseMatches(head, options.breakpointIds)) {
-      return head;
+  while (buffer.length > 0 || remainingUntil(deadlineMs) > 0) {
+    while (buffer.length > 0) {
+      const buffered = buffer.shift();
+      if (buffered === void 0) {
+        continue;
+      }
+      if (pauseMatches(buffered, options.breakpointIds)) {
+        return buffered;
+      }
+      await handleUnmatchedPause(session, buffered, options, deadlineMs);
     }
-  }
-  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) {
+    const remainingMs = remainingUntil(deadlineMs);
+    if (remainingMs <= 0) {
+      throwBreakpointTimeout(options.timeoutMs);
+    }
+    session.pauseWaitGate.active = true;
+    let receivedAtMs;
+    let params;
+    try {
+      params = await session.client.waitFor("Debugger.paused", {
+        timeoutMs: remainingMs,
+        predicate: () => {
+          receivedAtMs = performance.now();
           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;
+      });
+    } finally {
+      session.pauseWaitGate.active = false;
+    }
+    const pause = toPauseEvent(params, receivedAtMs ?? performance.now());
+    if (pauseMatches(pause, options.breakpointIds)) {
+      return pause;
+    }
+    await handleUnmatchedPause(session, pause, options, deadlineMs);
   }
-  return {
-    reason: asString(params.reason),
-    hitBreakpoints: Array.isArray(params.hitBreakpoints) ? params.hitBreakpoints.filter((id) => typeof id === "string") : [],
-    callFrames: toCallFrames(params.callFrames)
-  };
+  throwBreakpointTimeout(options.timeoutMs);
 }
 async function resume(session) {
   await session.client.send("Debugger.resume");
@@ -826,13 +923,12 @@ async function getProperties(session, objectId) {
 }
 
 // src/snapshot.ts
-import { performance } from "perf_hooks";
 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)?|token|secret|api[_-]?key|authorization|cookie|session|private[_-]?key)/i;
+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,
@@ -893,8 +989,11 @@ function formatPrimitive(value) {
   }
   return String(value);
 }
+function isSensitiveName(name) {
+  return SENSITIVE_NAME_REGEX.test(name);
+}
 function sanitizeValue(name, raw) {
-  if (SENSITIVE_NAME_REGEX.test(name)) {
+  if (isSensitiveName(name)) {
     return "[REDACTED]";
   }
   if (raw.length <= MAX_VALUE_LENGTH) {
@@ -912,8 +1011,9 @@ 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 (depth > 0 && described.objectId !== void 0 && isExpandable(described.type)) {
+      if (!sensitive && depth > 0 && described.objectId !== void 0 && isExpandable(described.type)) {
         try {
           const nested = await captureProperties(
             session,
@@ -927,7 +1027,7 @@ async function captureProperties(session, objectId, limit, depth) {
         } catch {
         }
       }
-      const sanitizedValue = sanitizeValue(name, described.value);
+      const sanitizedValue = sensitive ? "[REDACTED]" : sanitizeValue(name, 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 };
@@ -985,7 +1085,6 @@ 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 = [];
@@ -1012,12 +1111,10 @@ 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
   };