@saptools/cf-debugger 0.1.12 → 0.1.14

package/README.md

@@ -12,7 +12,7 @@ Signal the remote process, enable SSH if needed, forward `9229` to a free local
 [![install size](https://packagephobia.com/badge?p=@saptools/cf-debugger)](https://packagephobia.com/result?p=@saptools/cf-debugger)
 [![types](https://img.shields.io/npm/types/@saptools/cf-debugger.svg?style=flat&color=3178C6&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 
-[Install](#-install) • [Quick Start](#-quick-start) • [CLI](#-cli) • [API](#-programmatic-usage) • [How it works](#-how-it-works) • [FAQ](#-faq)
+[Install](#-install) • [Quick Start](#-quick-start) • [CLI](#-cli) • [How it works](#-how-it-works) • [FAQ](#-faq)
 
 </div>
 
@@ -23,7 +23,7 @@ Signal the remote process, enable SSH if needed, forward `9229` to a free local
 - 🚀 **One-shot tunnel** — auth, target, SSH-enable, USR1 signal, port forward, readiness probe — all hidden behind `cf-debugger start`
 - 🧵 **Multi-debugger concurrency** — run N debuggers for N apps at once; each session gets its own local port, isolated `CF_HOME`, and an entry in the shared state file
 - 🛡️ **Duplicate-session protection** — the same `region/org/space/app` cannot be debugged twice simultaneously (returns `SESSION_ALREADY_RUNNING`)
-- 🧹 **Crash-proof state** — stale session entries are auto-pruned on next read using PID liveness checks
+- 🧹 **Crash-proof state** — stale session entries are auto-pruned on list/status/start/stop using PID, ready-port health, and listener-owner checks
 - 🔌 **Deterministic ports** — auto-assigned from a safe range (`20000–20999`), or pick your own with `--port`
 - 🧩 **CLI & typed API** — every command has a zero-config Node.js equivalent with full TypeScript definitions
 - 🪶 **Small + boring** — one runtime dep (`commander`), no daemons, no magic
@@ -104,7 +104,7 @@ restart, and the one-shot SIGUSR1 SSH command) each allow up to 180 seconds.
 
 ### ⏹️ `cf-debugger stop`
 
-Stop a specific session or everything at once.
+Stop a specific session or everything at once. If a matching state entry is already stale, `stop --session-id` removes it idempotently and reports the stale cleanup instead of failing. For bare app names, matching still uses the current CF target; use `--session-id` or the full `region/org/space/app` selector when the listed session belongs to a different target.
 
 ```bash
 cf-debugger stop --region eu10 --org my-org --space dev --app my-app
@@ -120,7 +120,7 @@ cf-debugger stop --all
 
 ### 📋 `cf-debugger list`
 
-Print every active session this machine owns as JSON.
+Print healthy active sessions as JSON. `list` first prunes current-host entries whose PID is gone or whose `ready` local inspector port no longer accepts TCP connections.
 
 ```bash
 cf-debugger list | jq '.[] | {app, localPort, status}'
@@ -128,7 +128,7 @@ cf-debugger list | jq '.[] | {app, localPort, status}'
 
 ### 🔍 `cf-debugger status`
 
-Print one session by key (or `null` if no active session matches).
+Print one healthy session by key (or `null` if no active session matches after the same pruning used by `list`).
 
 ```bash
 cf-debugger status --region eu10 --org my-org --space dev --app my-app
@@ -136,70 +136,6 @@ cf-debugger status --region eu10 --org my-org --space dev --app my-app
 
 ---
 
-## 🧑‍💻 Programmatic Usage
-
-```ts
-import {
-  startDebugger,
-  stopDebugger,
-  listSessions,
-  getSession,
-  resolveApiEndpoint,
-} from "@saptools/cf-debugger";
-
-const handle = await startDebugger({
-  region: "eu10",
-  org: "my-org",
-  space: "dev",
-  app: "my-app",
-  email: process.env["SAP_EMAIL"],
-  password: process.env["SAP_PASSWORD"],
-  verbose: true,
-  onStatus: (status, message) => {
-    console.log(`[${status}]`, message ?? "");
-  },
-});
-
-console.log(`Attach your debugger to localhost:${handle.session.localPort}`);
-
-// Later — shut the tunnel down and clean up state:
-await handle.dispose();
-```
-
-<details>
-<summary><b>📚 Full export list</b></summary>
-
-| Export | Description |
-| --- | --- |
-| `startDebugger(options)` | Open a tunnel; returns a `DebuggerHandle` |
-| `stopDebugger({ sessionId?, key? })` | Stop one session by id or by key |
-| `stopAllDebuggers()` | Stop every session owned by this process/machine |
-| `listSessions()` | Return every live session as `ActiveSession[]` |
-| `getSession(key)` | Return one session matching `{ region, org, space, app }` |
-| `resolveApiEndpoint(key, override?)` | Map a region key to its API endpoint |
-| `sessionKeyString(key)` | Stable string form of a session key |
-| `CfDebuggerError` | Rich error class with typed `code` |
-
-</details>
-
-<details>
-<summary><b>🧪 Error codes</b></summary>
-
-| Code | When |
-| --- | --- |
-| `MISSING_CREDENTIALS` | No `SAP_EMAIL` / `SAP_PASSWORD` in env or options |
-| `SESSION_ALREADY_RUNNING` | A session already exists for the same `region/org/space/app` |
-| `CF_LOGIN_FAILED` | `cf api` / `cf auth` rejected the credentials |
-| `CF_TARGET_FAILED` | Org or space not reachable |
-| `SSH_NOT_ENABLED` | SSH disabled at space or app level and could not be enabled |
-| `USR1_SIGNAL_FAILED` | Remote `kill -s USR1` failed, timed out, or was terminated by a signal |
-| `TUNNEL_NOT_READY` | Inspector didn't respond on port 9229 before timeout |
-| `PORT_UNAVAILABLE` | Preferred local port is taken and could not be freed |
-
-</details>
-
----
-
 ## 🔭 How it works
 
 ```
@@ -220,8 +156,8 @@ Each step emits a status update (`logging-in`, `targeting`, `ssh-enabling`, `sig
 - **Atomic state** — `~/.saptools/cf-debugger-state.json` is written via temp-file + `rename`, guarded by a short-lived `.lock` file (`open(..., "wx")`).
 - **Port allocation** — on register, ports already used by other sessions are excluded; the first free port in `20000–20999` wins.
 - **Isolated CF homes** — each session runs with its own `CF_HOME` (`~/.saptools/cf-debugger-homes/<sessionId>/`), so `cf target` in one terminal can't clobber another.
-- **Stale pruning** — reading the state file checks every recorded PID with `process.kill(pid, 0)`; dead entries are dropped before returning the list.
-- **Duplicate guard** — trying to start a second tunnel for the same `region/org/space/app` fails fast with `SESSION_ALREADY_RUNNING` instead of racing for the port.
+- **Stale pruning** — list/status/start/stop check current-host PIDs with `process.kill(pid, 0)` and verify that `ready` sessions still accept TCP on `127.0.0.1:<localPort>` and, when detectable, that the listener is still the recorded tunnel PID; unhealthy entries are dropped before results or duplicate checks are returned.
+- **Duplicate guard** — trying to start a second healthy tunnel for the same `region/org/space/app` fails fast with `SESSION_ALREADY_RUNNING` instead of racing for the port; stale same-key entries are pruned so a fresh tunnel can recover.
 
 ---
 

package/dist/cli.js

@@ -482,26 +482,29 @@ async function isPortFree(port) {
     server.listen(port, "127.0.0.1");
   });
 }
+async function isPortListening(port, timeoutMs = 200) {
+  return await new Promise((resolve) => {
+    const socket = createConnection({ port, host: "127.0.0.1" });
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", () => {
+      socket.destroy();
+      resolve(false);
+    });
+    socket.once("timeout", () => {
+      socket.destroy();
+      resolve(false);
+    });
+  });
+}
 async function probeTunnelReady(port, timeoutMs) {
   const pollIntervalMs = 250;
   const started = Date.now();
   while (Date.now() - started < timeoutMs) {
-    const connected = await new Promise((resolve) => {
-      const socket = createConnection({ port, host: "127.0.0.1" });
-      socket.setTimeout(200);
-      socket.once("connect", () => {
-        socket.destroy();
-        resolve(true);
-      });
-      socket.once("error", () => {
-        socket.destroy();
-        resolve(false);
-      });
-      socket.once("timeout", () => {
-        socket.destroy();
-        resolve(false);
-      });
-    });
+    const connected = await isPortListening(port);
     if (connected) {
       return true;
     }
@@ -653,14 +656,31 @@ function isPidAlive(pid) {
     return true;
   }
 }
-function filterStaleSessions(sessions) {
+async function isSessionHealthy(session, host) {
+  if (session.hostname !== host) {
+    return true;
+  }
+  if (!isPidAlive(session.pid)) {
+    return false;
+  }
+  if (session.status !== "ready") {
+    return true;
+  }
+  if (!await isPortListening(session.localPort)) {
+    return false;
+  }
+  const listeningPid = await findListeningProcessId(session.localPort);
+  return listeningPid === void 0 || listeningPid === session.pid;
+}
+async function filterStaleSessions(sessions) {
   const host = getHostname();
-  return sessions.filter((session) => {
-    if (session.hostname !== host) {
-      return true;
-    }
-    return isPidAlive(session.pid);
-  });
+  const checks = await Promise.all(
+    sessions.map(async (session) => [
+      session,
+      await isSessionHealthy(session, host)
+    ])
+  );
+  return checks.filter(([, healthy]) => healthy).map(([session]) => session);
 }
 async function readStateRaw() {
   const parsed = await readJsonFile(stateFilePath());
@@ -674,7 +694,7 @@ async function writeState(state) {
 }
 async function readAndPruneLocked() {
   const raw = await readStateRaw();
-  const pruned = filterStaleSessions(raw.sessions);
+  const pruned = await filterStaleSessions(raw.sessions);
   const removed = raw.sessions.filter(
     (session) => !pruned.some((active) => active.sessionId === session.sessionId)
   );
@@ -683,11 +703,9 @@ async function readAndPruneLocked() {
   }
   return { sessions: pruned, removed };
 }
-async function readSessionSnapshot() {
-  return await withFileLock(stateLockPath(), async () => {
-    const raw = await readStateRaw();
-    return raw.sessions;
-  });
+async function readActiveSessions() {
+  const result = await withFileLock(stateLockPath(), readAndPruneLocked);
+  return result.sessions;
 }
 async function readAndPruneActiveSessions() {
   return await withFileLock(stateLockPath(), readAndPruneLocked);
@@ -858,7 +876,7 @@ async function pruneAndCleanupOrphans() {
       void killProcessOnPort(removed.localPort);
     }
   }
-  return result.sessions;
+  return result;
 }
 
 // src/debug-session/processes.ts
@@ -1158,19 +1176,18 @@ async function cleanupFilesystem(cfHomeDir) {
 // src/debug-session/sessions.ts
 import { rm as rm2 } from "fs/promises";
 import process5 from "process";
-async function stopDebugger(options) {
-  const sessions = await pruneAndCleanupOrphans();
-  let target;
+function findMatchingSession(sessions, options) {
   if (options.sessionId !== void 0) {
-    target = sessions.find((s) => s.sessionId === options.sessionId);
-  } else if (options.key !== void 0) {
-    const key = options.key;
-    target = sessions.find((s) => matchesKey(s, key));
+    return sessions.find((s) => s.sessionId === options.sessionId);
   }
-  if (target === void 0) {
-    return void 0;
+  if (options.key !== void 0) {
+    const key = options.key;
+    return sessions.find((s) => matchesKey(s, key));
   }
-  if (target.pid !== process5.pid) {
+  return void 0;
+}
+async function cleanupSession(target, stale) {
+  if (!stale && target.pid !== process5.pid) {
     try {
       await terminatePidOrGroup(target.pid);
     } catch {
@@ -1179,17 +1196,29 @@ async function stopDebugger(options) {
   setTimeout(() => {
     void killProcessOnPort(target.localPort);
   }, PORT_CLEANUP_DELAY_MS);
-  const removed = await removeSession(target.sessionId);
+  const removed = stale ? void 0 : await removeSession(target.sessionId);
   try {
     await rm2(target.cfHomeDir, { recursive: true, force: true });
   } catch {
   }
-  return removed ?? target;
+  return { ...removed ?? target, stale };
+}
+async function stopDebugger(options) {
+  const pruneResult = await pruneAndCleanupOrphans();
+  const activeTarget = findMatchingSession(pruneResult.sessions, options);
+  if (activeTarget !== void 0) {
+    return await cleanupSession(activeTarget, false);
+  }
+  const staleTarget = findMatchingSession(pruneResult.removed, options);
+  if (staleTarget !== void 0) {
+    return await cleanupSession(staleTarget, true);
+  }
+  return void 0;
 }
 async function stopAllDebuggers() {
-  const sessions = await pruneAndCleanupOrphans();
-  let stopped = 0;
-  for (const session of sessions) {
+  const pruneResult = await pruneAndCleanupOrphans();
+  let stopped = pruneResult.removed.length;
+  for (const session of pruneResult.sessions) {
     const result = await stopDebugger({ sessionId: session.sessionId });
     if (result) {
       stopped += 1;
@@ -1198,10 +1227,10 @@ async function stopAllDebuggers() {
   return stopped;
 }
 async function listSessions() {
-  return await readSessionSnapshot();
+  return await readActiveSessions();
 }
 async function getSession(key) {
-  const sessions = await readSessionSnapshot();
+  const sessions = await readActiveSessions();
   return sessions.find((s) => matchesKey(s, key));
 }
 
@@ -1404,9 +1433,18 @@ async function handleStop(selector, rawOpts) {
     ...key === void 0 ? {} : { key }
   });
   if (result === void 0) {
-    process6.stderr.write("No matching session found.\n");
+    process6.stderr.write(
+      "No matching session found. Use `cf-debugger list` and pass --session-id or region/org/space/app if the current CF target differs.\n"
+    );
     process6.exit(1);
   }
+  if (result.stale) {
+    process6.stdout.write(
+      `Removed stale session ${result.sessionId} (${result.app}, port ${result.localPort.toString()}).
+`
+    );
+    return;
+  }
   process6.stdout.write(
     `Stopped session ${result.sessionId} (${result.app}, port ${result.localPort.toString()}).
 `