@saptools/cf-inspector 0.4.10 → 0.4.12

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { DebuggerHandle, SessionStatus } from '@saptools/cf-debugger';
 
-type CfInspectorErrorCode = "INVALID_ARGUMENT" | "INVALID_BREAKPOINT" | "INVALID_REMOTE_ROOT" | "INVALID_EXPRESSION" | "INVALID_HIT_COUNT" | "INVALID_PAUSE_TYPE" | "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";
+type CfInspectorErrorCode = "INVALID_ARGUMENT" | "INVALID_BREAKPOINT" | "INVALID_REMOTE_ROOT" | "INVALID_EXPRESSION" | "SETUP_EVAL_FAILED" | "INVALID_HIT_COUNT" | "INVALID_PAUSE_TYPE" | "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;
@@ -265,6 +265,7 @@ declare function resume(session: InspectorSession): Promise<void>;
 declare function setPauseOnExceptions(session: InspectorSession, state: PauseOnExceptionsState): Promise<void>;
 declare function evaluateOnFrame(session: InspectorSession, callFrameId: string, expression: string): Promise<CdpEvalResult>;
 declare function evaluateGlobal(session: InspectorSession, expression: string): Promise<CdpEvalResult>;
+declare function runSetupEvals(session: InspectorSession, expressions: readonly string[]): Promise<void>;
 declare function listScripts(session: InspectorSession): readonly ScriptInfo[];
 declare function validateExpression(session: InspectorSession, expression: string): Promise<void>;
 declare function getProperties(session: InspectorSession, objectId: string): Promise<readonly CdpProperty[]>;
@@ -344,4 +345,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 DebuggerState, type ExceptionSnapshot, type FrameSnapshot, type InspectorConnectOptions, type InspectorSession, type InspectorTarget, type LogpointConditionOptions, type LogpointEvent, type LogpointStopReason, type LogpointStreamOptions, type LogpointStreamResult, type OpenedTunnel, type PauseEvent, type PauseOnExceptionsState, type RemoteRootSetting, type ResolvedLocation, type ScopeInfo, type ScopeSnapshot, type ScriptInfo, type SetBreakpointInput, type SnapshotCaptureResult, type SnapshotResult, type TunnelTarget, type VariableSnapshot, type WaitForPauseOptions, type WalkStackOptions, type WatchEvent, buildBreakpointUrlRegex, buildHitCountedCondition, buildLogpointCondition, captureException, captureSnapshot, connectInspector, discoverInspectorTargets, evaluateGlobal, evaluateOnFrame, fetchInspectorVersion, getProperties, listScripts, openCfTunnel, parseBreakpointSpec, parseRemoteRoot, removeBreakpoint, resume, setBreakpoint, setPauseOnExceptions, streamLogpoint, validateExpression, waitForPause, walkStack };
+export { type BreakpointHandle, type BreakpointLocation, type CallFrameInfo, type CaptureSnapshotOptions, type CapturedExpression, CfInspectorError, type CfInspectorErrorCode, type DebuggerState, type ExceptionSnapshot, type FrameSnapshot, type InspectorConnectOptions, type InspectorSession, type InspectorTarget, type LogpointConditionOptions, type LogpointEvent, type LogpointStopReason, type LogpointStreamOptions, type LogpointStreamResult, type OpenedTunnel, type PauseEvent, type PauseOnExceptionsState, type RemoteRootSetting, type ResolvedLocation, type ScopeInfo, type ScopeSnapshot, type ScriptInfo, type SetBreakpointInput, type SnapshotCaptureResult, type SnapshotResult, type TunnelTarget, type VariableSnapshot, type WaitForPauseOptions, type WalkStackOptions, type WatchEvent, buildBreakpointUrlRegex, buildHitCountedCondition, buildLogpointCondition, captureException, captureSnapshot, connectInspector, discoverInspectorTargets, evaluateGlobal, evaluateOnFrame, fetchInspectorVersion, getProperties, listScripts, openCfTunnel, parseBreakpointSpec, parseRemoteRoot, removeBreakpoint, resume, runSetupEvals, setBreakpoint, setPauseOnExceptions, streamLogpoint, validateExpression, waitForPause, walkStack };

package/dist/index.js

@@ -501,16 +501,39 @@ async function fetchJson(url, timeoutMs) {
       );
     });
     req.on("error", (err) => {
-      reject(
-        err instanceof CfInspectorError ? err : new CfInspectorError(
-          "INSPECTOR_DISCOVERY_FAILED",
-          `Inspector discovery at ${url} failed: ${err.message}`
-        )
-      );
+      reject(err instanceof CfInspectorError ? err : formatDiscoveryRequestError(url, err));
     });
     req.end();
   });
 }
+function isNodeSystemError(err) {
+  return err instanceof Error;
+}
+function isConnectionRefusedOrUnreachable(code) {
+  return code === "ECONNREFUSED" || code === "ECONNRESET" || code === "ETIMEDOUT" || code === "EHOSTUNREACH" || code === "ENETUNREACH";
+}
+function formatEndpoint(url, err) {
+  if (typeof err.address === "string" && typeof err.port === "number") {
+    return `${err.address}:${err.port.toString()}`;
+  }
+  const parsed = new URL(url);
+  return parsed.host;
+}
+function formatDiscoveryRequestError(url, err) {
+  const detail = err instanceof Error ? err.message : String(err);
+  if (!isNodeSystemError(err) || !isConnectionRefusedOrUnreachable(err.code)) {
+    return new CfInspectorError(
+      "INSPECTOR_DISCOVERY_FAILED",
+      `Inspector discovery at ${url} failed: ${detail}`
+    );
+  }
+  const endpoint = formatEndpoint(url, err);
+  return new CfInspectorError(
+    "INSPECTOR_DISCOVERY_FAILED",
+    `Cannot reach Node inspector discovery at ${url}. Nothing is listening on ${endpoint}, or the inspector tunnel is stale/closed. Restart the local inspector or tunnel and retry. If this port came from cf-debugger, stop the stale session and start a fresh tunnel, or run cf-inspector with --app/--region/--org/--space so it can open a tunnel.`,
+    detail
+  );
+}
 function parseJsonResponse(chunks) {
   const text = Buffer.concat(chunks).toString("utf8");
   return JSON.parse(text);
@@ -723,6 +746,20 @@ async function evaluateGlobal(session, expression) {
     silent: true
   });
 }
+async function runSetupEvals(session, expressions) {
+  for (const expression of expressions) {
+    const result = await evaluateGlobal(session, expression);
+    if (result.exceptionDetails !== void 0) {
+      throw new CfInspectorError(
+        "SETUP_EVAL_FAILED",
+        exceptionDetailsMessage(result, "setup evaluation failed")
+      );
+    }
+  }
+}
+function exceptionDetailsMessage(result, fallback) {
+  return typeof result.exceptionDetails?.exception?.description === "string" ? result.exceptionDetails.exception.description : typeof result.exceptionDetails?.text === "string" ? result.exceptionDetails.text : fallback;
+}
 function listScripts(session) {
   return [...session.scripts.values()];
 }
@@ -1939,6 +1976,7 @@ export {
   parseRemoteRoot,
   removeBreakpoint,
   resume,
+  runSetupEvals,
   setBreakpoint,
   setPauseOnExceptions,
   streamLogpoint,