@saptools/cf-inspector 0.4.11 → 0.4.12

package/README.md

@@ -40,6 +40,8 @@ Built so an AI agent (or a CI job) can drive a debugger from a single shell comm
 npm install -g @saptools/cf-inspector
 # or
 pnpm add @saptools/cf-inspector
+
+cf-inspector --version
 ```
 
 > [!NOTE]
@@ -284,6 +286,8 @@ cf-inspector list-targets --port 9229
 cf-inspector snapshot --port 9229 --target 1 --bp dist/worker.js:42
 ```
 
+If `list-targets`, `attach`, or another command reports `ECONNREFUSED`, the local inspector or tunnel on that port is usually stale/closed. Restart the local Node inspector or tunnel and retry; for Cloud Foundry targets, prefer `--app/--region/--org/--space` so `cf-inspector` can open a fresh tunnel.
+
 ### 🔗 `cf-inspector attach`
 
 Connect, fetch the runtime version, print it, disconnect. Useful as a smoke-test that the tunnel is healthy.

package/dist/cli.js

@@ -155,6 +155,9 @@ var init_wsTransport = __esm({
 import process12 from "process";
 
 // src/cli/program.ts
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
 import { Command } from "commander";
 
 // src/cli/commands/attach.ts
@@ -190,16 +193,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);
@@ -2742,54 +2768,57 @@ function prepareSnapshotCommand(opts, target) {
 }
 async function runSnapshotCommand(command, opts, reportProgress) {
   return await withSession(command.target, async (session) => {
-    if (command.setupEvals.length > 0) {
-      const setupCount = command.setupEvals.length;
-      reportProgress?.(`Running ${setupCount.toString()} setup ${setupCount === 1 ? "evaluation" : "evaluations"}...`);
-      await runSetupEvals(session, command.setupEvals);
-      reportProgress?.("Setup evaluation complete.");
-    }
-    if (command.condition !== void 0) {
-      reportProgress?.("Validating the breakpoint condition...");
-      await validateExpression(session, command.condition);
-      reportProgress?.("Breakpoint condition is valid.");
-    }
-    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,
-      includeScopes: opts.includeScopes === true,
-      ...command.maxValueLength === void 0 ? {} : { maxValueLength: command.maxValueLength },
-      ...command.stackDepth === void 0 ? {} : { stackDepth: command.stackDepth },
-      stackCaptures: command.stackCaptures
-    });
-    if (opts.keepPaused === true) {
-      reportProgress?.("Snapshot captured; leaving the target paused as requested.");
-      return withPausedDuration(snapshot, null);
-    }
-    reportProgress?.("Snapshot captured; resuming the target...");
-    return await resumeAfterSnapshot(session, snapshot, pausedStartedAt, reportProgress);
+    return await runSnapshotOnSession(session, command, opts, reportProgress);
   }, reportProgress);
 }
+async function runSnapshotOnSession(session, command, opts, reportProgress) {
+  if (command.setupEvals.length > 0) {
+    const setupCount = command.setupEvals.length;
+    reportProgress?.(`Running ${setupCount.toString()} setup ${setupCount === 1 ? "evaluation" : "evaluations"}...`);
+    await runSetupEvals(session, command.setupEvals);
+    reportProgress?.("Setup evaluation complete.");
+  }
+  if (command.condition !== void 0) {
+    reportProgress?.("Validating the breakpoint condition...");
+    await validateExpression(session, command.condition);
+    reportProgress?.("Breakpoint condition is valid.");
+  }
+  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,
+    includeScopes: opts.includeScopes === true,
+    ...command.maxValueLength === void 0 ? {} : { maxValueLength: command.maxValueLength },
+    ...command.stackDepth === void 0 ? {} : { stackDepth: command.stackDepth },
+    stackCaptures: command.stackCaptures
+  });
+  if (opts.keepPaused === true) {
+    reportProgress?.("Snapshot captured; leaving the target paused as requested.");
+    return withPausedDuration(snapshot, null);
+  }
+  reportProgress?.("Snapshot captured; resuming the target...");
+  return await resumeAfterSnapshot(session, snapshot, pausedStartedAt, reportProgress);
+}
 async function setCommandBreakpoints(session, command) {
   return await Promise.all(
     command.breakpoints.map(
@@ -3075,9 +3104,27 @@ var collectStrings = (value, prev = []) => [
   ...prev,
   value
 ];
+function readPackageVersion() {
+  let current = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 4; depth += 1) {
+    const candidate = join(current, "package.json");
+    try {
+      const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+      if (typeof parsed === "object" && parsed !== null) {
+        const record = parsed;
+        if (record["name"] === "@saptools/cf-inspector" && typeof record["version"] === "string") {
+          return record["version"];
+        }
+      }
+    } catch {
+    }
+    current = dirname(current);
+  }
+  throw new Error("Unable to read @saptools/cf-inspector package version");
+}
 async function main(argv) {
   const program = new Command();
-  program.name("cf-inspector").description("Drive a Node.js inspector from the command line \u2014 set breakpoints, capture snapshots, evaluate expressions");
+  program.name("cf-inspector").version(readPackageVersion()).description("Drive a Node.js inspector from the command line \u2014 set breakpoints, capture snapshots, evaluate expressions");
   registerSnapshot(program);
   registerLog(program);
   registerWatch(program);