@saptools/cf-inspector 0.4.1 → 0.4.2

package/README.md

@@ -101,9 +101,17 @@ cf-inspector snapshot --port 9229 \
 | `--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 |
+| `--quiet` | Suppress snapshot progress messages on stderr |
 | `--keep-paused` | Skip `Debugger.resume` after capture |
 | `--fail-on-unmatched-pause` | Fail immediately if the target pauses somewhere else instead of waiting cooperatively |
 
+Snapshot progress is printed to `stderr` by default, including Cloud Foundry
+login/tunnel setup, inspector connection, breakpoint binding, the breakpoint
+wait, capture, resume, and cleanup phases. The final JSON document remains the
+only content written to `stdout`, so piping it to `jq` or another parser stays
+safe. Pass `--quiet` to suppress these progress lines; warnings and errors still
+use `stderr`.
+
 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

package/dist/cli.js

@@ -280,6 +280,10 @@ async function fetchInspectorVersion(host, port, timeoutMs) {
 
 // src/cli/output.ts
 import process from "process";
+function writeProgress(message) {
+  process.stderr.write(`[cf-inspector] ${message}
+`);
+}
 function writeJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}
 `);
@@ -394,7 +398,8 @@ async function openCfTunnel(target) {
     ...target.tunnelReadyTimeoutMs === void 0 ? {} : { tunnelReadyTimeoutMs: target.tunnelReadyTimeoutMs },
     ...target.preferredPort === void 0 ? {} : { preferredPort: target.preferredPort },
     ...target.verbose === void 0 ? {} : { verbose: target.verbose },
-    ...target.signal === void 0 ? {} : { signal: target.signal }
+    ...target.signal === void 0 ? {} : { signal: target.signal },
+    ...target.onStatus === void 0 ? {} : { onStatus: target.onStatus }
   };
   const handle = await startDebugger(opts);
   return {
@@ -843,6 +848,22 @@ var DEFAULT_CF_TIMEOUT_SEC = 60;
 var DEFAULT_EXCEPTION_TIMEOUT_SEC = 30;
 
 // src/cli/target.ts
+var CF_TUNNEL_STATUS_MESSAGES = {
+  starting: "Preparing the Cloud Foundry debugger...",
+  "logging-in": "Logging in to Cloud Foundry...",
+  targeting: "Targeting the Cloud Foundry org and space...",
+  "ssh-enabling": "Enabling SSH for the Cloud Foundry app...",
+  "ssh-restarting": "Restarting the Cloud Foundry app to activate SSH...",
+  signaling: "Starting the remote Node.js inspector...",
+  tunneling: "Opening the SSH inspector tunnel...",
+  ready: "Cloud Foundry inspector tunnel is ready.",
+  stopping: "Closing the Cloud Foundry inspector tunnel...",
+  stopped: "Cloud Foundry inspector tunnel closed.",
+  error: "Cloud Foundry inspector tunnel failed."
+};
+function formatCfTunnelStatus(status) {
+  return CF_TUNNEL_STATUS_MESSAGES[status];
+}
 function parsePositiveInt(raw, label) {
   if (raw === void 0) {
     return void 0;
@@ -877,20 +898,26 @@ function resolveTarget(opts) {
 function hasCfTarget(opts) {
   return opts.region !== void 0 && opts.org !== void 0 && opts.space !== void 0 && opts.app !== void 0;
 }
-async function withSession(target, fn) {
-  const tunnel = await openTarget(target);
+async function withSession(target, fn, reportProgress) {
+  const tunnel = await openTarget(target, reportProgress);
   let session;
   try {
+    reportProgress?.(
+      `Connecting to the Node.js inspector at ${tunnel.host}:${tunnel.port.toString()}...`
+    );
     session = await connectInspector({ port: tunnel.port, host: tunnel.host });
+    reportProgress?.("Inspector session is ready.");
     return await fn(session, tunnel.port);
   } finally {
     if (session) {
+      reportProgress?.("Closing the inspector session...");
       await session.dispose();
+      reportProgress?.("Inspector session closed.");
     }
     await tunnel.dispose();
   }
 }
-async function openTarget(target) {
+async function openTarget(target, reportProgress) {
   if (target.kind === "port") {
     return {
       port: target.port,
@@ -898,12 +925,18 @@ async function openTarget(target) {
       dispose: () => Promise.resolve()
     };
   }
+  reportProgress?.(formatCfTunnelStatus("starting"));
   const tunnel = await openCfTunnel({
     region: target.region,
     org: target.org,
     space: target.space,
     app: target.app,
-    tunnelReadyTimeoutMs: target.cfTimeoutMs
+    tunnelReadyTimeoutMs: target.cfTimeoutMs,
+    ...reportProgress === void 0 ? {} : {
+      onStatus: (status) => {
+        reportProgress(formatCfTunnelStatus(status));
+      }
+    }
   });
   return {
     port: tunnel.localPort,
@@ -2449,12 +2482,14 @@ import process9 from "process";
 init_types();
 async function handleSnapshot(opts) {
   const prepared = prepareSnapshotCommand(opts);
-  const result = await runSnapshotCommand(prepared, opts);
+  const reportProgress = opts.quiet === true ? void 0 : writeProgress;
+  const result = await runSnapshotCommand(prepared, opts, reportProgress);
   if (opts.json) {
     writeJson(result);
   } else {
     writeHumanSnapshot(result);
   }
+  reportProgress?.("Snapshot complete.");
 }
 function prepareSnapshotCommand(opts) {
   const target = resolveTarget(opts);
@@ -2482,24 +2517,34 @@ function prepareSnapshotCommand(opts) {
     stackCaptures: parseCaptureList(opts.stackCaptures)
   };
 }
-async function runSnapshotCommand(command, opts) {
+async function runSnapshotCommand(command, opts, reportProgress) {
   return await withSession(command.target, async (session) => {
     if (command.condition !== void 0) {
+      reportProgress?.("Validating the breakpoint condition...");
       await validateExpression(session, command.condition);
+      reportProgress?.("Breakpoint condition is valid.");
     }
-    const handles = await Promise.all(
-      command.breakpoints.map(
-        (bp) => setBreakpoint(session, {
-          file: bp.file,
-          line: bp.line,
-          remoteRoot: command.remoteRoot,
-          ...command.condition === void 0 ? {} : { condition: command.condition },
-          ...command.hitCount === void 0 ? {} : { hitCount: command.hitCount }
-        })
-      )
+    const breakpointCount = command.breakpoints.length;
+    reportProgress?.(
+      `Setting ${breakpointCount.toString()} ${breakpointCount === 1 ? "breakpoint" : "breakpoints"}...`
+    );
+    const handles = await setCommandBreakpoints(session, command);
+    const resolvedCount = handles.reduce(
+      (total, handle) => total + handle.resolvedLocations.length,
+      0
+    );
+    reportProgress?.(
+      `Breakpoint setup complete: ${resolvedCount.toString()} resolved ${resolvedCount === 1 ? "location" : "locations"}.`
     );
     warnOnUnboundBreakpoints(handles);
+    reportProgress?.(
+      `Waiting up to ${(command.timeoutMs / 1e3).toString()}s for a breakpoint hit...`
+    );
     const pause = await waitForCommandPause(session, opts, handles, command.timeoutMs);
+    const captureCount = command.captures.length;
+    reportProgress?.(
+      `Breakpoint hit; capturing ${captureCount.toString()} ${captureCount === 1 ? "expression" : "expressions"}...`
+    );
     const pausedStartedAt = pause.receivedAtMs ?? performance4.now();
     const snapshot = await captureSnapshot(session, pause, {
       captures: command.captures,
@@ -2509,10 +2554,25 @@ async function runSnapshotCommand(command, opts) {
       stackCaptures: command.stackCaptures
     });
     if (opts.keepPaused === true) {
+      reportProgress?.("Snapshot captured; leaving the target paused as requested.");
       return withPausedDuration(snapshot, null);
     }
-    return await resumeAfterSnapshot(session, snapshot, pausedStartedAt);
-  });
+    reportProgress?.("Snapshot captured; resuming the target...");
+    return await resumeAfterSnapshot(session, snapshot, pausedStartedAt, reportProgress);
+  }, reportProgress);
+}
+async function setCommandBreakpoints(session, command) {
+  return await Promise.all(
+    command.breakpoints.map(
+      (bp) => setBreakpoint(session, {
+        file: bp.file,
+        line: bp.line,
+        remoteRoot: command.remoteRoot,
+        ...command.condition === void 0 ? {} : { condition: command.condition },
+        ...command.hitCount === void 0 ? {} : { hitCount: command.hitCount }
+      })
+    )
+  );
 }
 async function waitForCommandPause(session, opts, handles, timeoutMs) {
   let warnedUnmatchedPause = false;
@@ -2529,9 +2589,10 @@ async function waitForCommandPause(session, opts, handles, timeoutMs) {
     }
   });
 }
-async function resumeAfterSnapshot(session, snapshot, pausedStartedAt) {
+async function resumeAfterSnapshot(session, snapshot, pausedStartedAt, reportProgress) {
   try {
     await resume(session);
+    reportProgress?.("Target resumed.");
     return withPausedDuration(snapshot, roundDurationMs(performance4.now() - pausedStartedAt));
   } catch {
     process9.stderr.write(
@@ -2786,7 +2847,7 @@ async function main(argv) {
 function registerSnapshot(program) {
   applyTargetOptions(
     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", 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("--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("--hit-count <n>", "Only pause after the breakpoint has been hit N or more times").option("--stack-depth <n>", "Walk this many call frames when capturing (default: 1, only top frame)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame in the stack").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) => {
+  ).option("--bp <file:line>", "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("--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("--hit-count <n>", "Only pause after the breakpoint has been hit N or more times").option("--stack-depth <n>", "Walk this many call frames when capturing (default: 1, only top frame)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame in the stack").option("--include-scopes", "Include expanded paused-frame scopes in the snapshot").option("--no-json", "Print a human-readable summary instead of JSON").option("--quiet", "Suppress progress messages on stderr").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);
   });
 }