@saptools/cf-debugger 0.1.0

package/dist/cli.js

@@ -0,0 +1,1088 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import process4 from "process";
+import { Command } from "commander";
+
+// src/debugger.ts
+import { mkdir as mkdir3, rm } from "fs/promises";
+import { hostname as getHostname2 } from "os";
+import process3 from "process";
+
+// src/cf.ts
+import { execFile, spawn } from "child_process";
+import { promisify } from "util";
+
+// src/types.ts
+var CfDebuggerError = class extends Error {
+  code;
+  stderr;
+  constructor(code, message, stderr) {
+    super(message);
+    this.name = "CfDebuggerError";
+    this.code = code;
+    if (stderr !== void 0) {
+      this.stderr = stderr;
+    }
+  }
+};
+
+// src/cf.ts
+var execFileAsync = promisify(execFile);
+var MAX_BUFFER = 16 * 1024 * 1024;
+var CF_CLI_TIMEOUT_MS = 3e4;
+var CF_RESTART_TIMEOUT_MS = 12e4;
+var CF_SSH_SIGNAL_TIMEOUT_MS = 15e3;
+var CF_AUTH_MAX_ATTEMPTS = 3;
+function buildEnv(cfHome) {
+  return { ...process.env, CF_HOME: cfHome };
+}
+function resolveBin(context) {
+  return context.command ?? process.env["CF_DEBUGGER_CF_BIN"] ?? "cf";
+}
+async function runCf(args, context, timeoutMs = CF_CLI_TIMEOUT_MS) {
+  try {
+    const { stdout } = await execFileAsync(resolveBin(context), [...args], {
+      env: buildEnv(context.cfHome),
+      maxBuffer: MAX_BUFFER,
+      timeout: timeoutMs
+    });
+    return stdout;
+  } catch (err) {
+    const e = err;
+    const stderr = e.stderr?.trim() ?? "";
+    throw new CfDebuggerError(
+      "CF_CLI_FAILED",
+      `cf ${args.join(" ")} failed: ${stderr.length > 0 ? stderr : e.message}`,
+      stderr
+    );
+  }
+}
+async function cfApi(apiEndpoint, context) {
+  await runCf(["api", apiEndpoint], context);
+}
+async function cfAuth(email, password, context) {
+  let lastError;
+  for (let attempt = 0; attempt < CF_AUTH_MAX_ATTEMPTS; attempt++) {
+    try {
+      await runCf(["auth", email, password], context);
+      return;
+    } catch (err) {
+      lastError = err;
+      if (attempt < CF_AUTH_MAX_ATTEMPTS - 1) {
+        await new Promise((resolve) => {
+          setTimeout(resolve, 1e3 * (attempt + 1));
+        });
+      }
+    }
+  }
+  if (lastError instanceof Error) {
+    throw lastError;
+  }
+  throw new CfDebuggerError("CF_AUTH_FAILED", `cf auth failed: ${String(lastError)}`);
+}
+async function cfLogin(apiEndpoint, email, password, context) {
+  try {
+    await cfApi(apiEndpoint, context);
+    await cfAuth(email, password, context);
+  } catch (err) {
+    if (err instanceof CfDebuggerError) {
+      throw new CfDebuggerError("CF_LOGIN_FAILED", err.message, err.stderr);
+    }
+    throw err;
+  }
+}
+async function cfTarget(org, space, context) {
+  try {
+    await runCf(["target", "-o", org, "-s", space], context);
+  } catch (err) {
+    if (err instanceof CfDebuggerError) {
+      throw new CfDebuggerError("CF_TARGET_FAILED", err.message, err.stderr);
+    }
+    throw err;
+  }
+}
+async function cfSshEnabled(appName, context) {
+  try {
+    const stdout = await runCf(["ssh-enabled", appName], context);
+    return stdout.toLowerCase().includes("ssh support is enabled");
+  } catch {
+    return false;
+  }
+}
+async function cfEnableSsh(appName, context) {
+  try {
+    await runCf(["enable-ssh", appName], context);
+  } catch (err) {
+    if (err instanceof CfDebuggerError) {
+      throw new CfDebuggerError("SSH_NOT_ENABLED", err.message, err.stderr);
+    }
+    throw err;
+  }
+}
+async function cfRestartApp(appName, context) {
+  await runCf(["restart", appName], context, CF_RESTART_TIMEOUT_MS);
+}
+async function cfSshOneShot(appName, command, context) {
+  return await new Promise((resolve) => {
+    const child = spawn(resolveBin(context), ["ssh", appName, "-c", command], {
+      env: buildEnv(context.cfHome),
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stderrBuf = "";
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      try {
+        child.kill();
+      } catch {
+      }
+      resolve({ exitCode: null, stderr: stderrBuf });
+    }, CF_SSH_SIGNAL_TIMEOUT_MS);
+    child.stderr.on("data", (data) => {
+      stderrBuf += data.toString();
+    });
+    child.on("close", (code) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      resolve({ exitCode: code, stderr: stderrBuf });
+    });
+    child.on("error", (err) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      resolve({ exitCode: null, stderr: err.message });
+    });
+  });
+}
+function isSshDisabledError(stderr) {
+  const lower = stderr.toLowerCase();
+  return lower.includes("not authorized") || lower.includes("ssh support is disabled");
+}
+function spawnSshTunnel(appName, localPort, remotePort, context) {
+  const tunnelArg = `${localPort.toString()}:localhost:${remotePort.toString()}`;
+  const isWindows = process.platform === "win32";
+  return spawn(resolveBin(context), ["ssh", appName, "-N", "-L", tunnelArg], {
+    env: buildEnv(context.cfHome),
+    shell: isWindows,
+    detached: !isWindows
+  });
+}
+
+// src/paths.ts
+import { homedir } from "os";
+import { join } from "path";
+var SAPTOOLS_DIR_NAME = ".saptools";
+var CF_DEBUGGER_STATE_FILENAME = "cf-debugger-state.json";
+var CF_DEBUGGER_LOCK_FILENAME = "cf-debugger-state.lock";
+var CF_DEBUGGER_HOMES_DIRNAME = "cf-debugger-homes";
+function saptoolsDir() {
+  return join(homedir(), SAPTOOLS_DIR_NAME);
+}
+function stateFilePath() {
+  return join(saptoolsDir(), CF_DEBUGGER_STATE_FILENAME);
+}
+function stateLockPath() {
+  return join(saptoolsDir(), CF_DEBUGGER_LOCK_FILENAME);
+}
+function sessionCfHomeDir(sessionId) {
+  return join(saptoolsDir(), CF_DEBUGGER_HOMES_DIRNAME, sessionId);
+}
+
+// src/port.ts
+import { execFile as execFile2 } from "child_process";
+import { createConnection, createServer } from "net";
+import { promisify as promisify2 } from "util";
+var execFileAsync2 = promisify2(execFile2);
+async function isPortFree(port) {
+  return await new Promise((resolve) => {
+    const server = createServer();
+    server.once("error", () => {
+      resolve(false);
+    });
+    server.once("listening", () => {
+      server.close(() => {
+        resolve(true);
+      });
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+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);
+      });
+    });
+    if (connected) {
+      return true;
+    }
+    await new Promise((resolve) => {
+      setTimeout(resolve, pollIntervalMs);
+    });
+  }
+  return false;
+}
+async function killProcessOnPort(port) {
+  const portStr = port.toString();
+  if (process.platform === "win32") {
+    try {
+      const { stdout } = await execFileAsync2("netstat", ["-ano"]);
+      const pids = /* @__PURE__ */ new Set();
+      for (const line of stdout.split("\n")) {
+        if (line.includes(`:${portStr}`) && line.includes("LISTENING")) {
+          const parts = line.trim().split(/\s+/);
+          const last = parts[parts.length - 1];
+          if (last !== void 0) {
+            const pid = Number.parseInt(last, 10);
+            if (!Number.isNaN(pid)) {
+              pids.add(pid);
+            }
+          }
+        }
+      }
+      for (const pid of pids) {
+        try {
+          await execFileAsync2("taskkill", ["/F", "/PID", pid.toString()]);
+        } catch {
+        }
+      }
+    } catch {
+    }
+    return;
+  }
+  try {
+    const { stdout } = await execFileAsync2("lsof", ["-t", "-i", `tcp:${portStr}`]);
+    const lines = stdout.trim().split("\n").filter((l) => l.length > 0);
+    for (const pidStr of lines) {
+      const pid = Number.parseInt(pidStr, 10);
+      if (!Number.isNaN(pid)) {
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+}
+
+// src/regions.ts
+var REGION_API_ENDPOINTS = {
+  ae01: "https://api.cf.ae01.hana.ondemand.com",
+  ap01: "https://api.cf.ap01.hana.ondemand.com",
+  ap10: "https://api.cf.ap10.hana.ondemand.com",
+  ap11: "https://api.cf.ap11.hana.ondemand.com",
+  ap12: "https://api.cf.ap12.hana.ondemand.com",
+  ap20: "https://api.cf.ap20.hana.ondemand.com",
+  ap21: "https://api.cf.ap21.hana.ondemand.com",
+  ap30: "https://api.cf.ap30.hana.ondemand.com",
+  br10: "https://api.cf.br10.hana.ondemand.com",
+  br20: "https://api.cf.br20.hana.ondemand.com",
+  br30: "https://api.cf.br30.hana.ondemand.com",
+  ca10: "https://api.cf.ca10.hana.ondemand.com",
+  ca20: "https://api.cf.ca20.hana.ondemand.com",
+  ch20: "https://api.cf.ch20.hana.ondemand.com",
+  eu10: "https://api.cf.eu10.hana.ondemand.com",
+  eu11: "https://api.cf.eu11.hana.ondemand.com",
+  eu12: "https://api.cf.eu12.hana.ondemand.com",
+  eu20: "https://api.cf.eu20.hana.ondemand.com",
+  eu21: "https://api.cf.eu21.hana.ondemand.com",
+  eu30: "https://api.cf.eu30.hana.ondemand.com",
+  eu31: "https://api.cf.eu31.hana.ondemand.com",
+  in30: "https://api.cf.in30.hana.ondemand.com",
+  jp10: "https://api.cf.jp10.hana.ondemand.com",
+  jp20: "https://api.cf.jp20.hana.ondemand.com",
+  jp30: "https://api.cf.jp30.hana.ondemand.com",
+  kr30: "https://api.cf.kr30.hana.ondemand.com",
+  us10: "https://api.cf.us10.hana.ondemand.com",
+  us11: "https://api.cf.us11.hana.ondemand.com",
+  us20: "https://api.cf.us20.hana.ondemand.com",
+  us21: "https://api.cf.us21.hana.ondemand.com",
+  us30: "https://api.cf.us30.hana.ondemand.com",
+  us31: "https://api.cf.us31.hana.ondemand.com"
+};
+function resolveApiEndpoint(regionKey, override) {
+  if (override !== void 0 && override !== "") {
+    return override;
+  }
+  const endpoint = REGION_API_ENDPOINTS[regionKey];
+  if (endpoint === void 0) {
+    throw new Error(
+      `Unknown region key: ${regionKey}. Pass \`apiEndpoint\` explicitly to override.`
+    );
+  }
+  return endpoint;
+}
+
+// src/state.ts
+import { randomUUID } from "crypto";
+import { mkdir as mkdir2, readFile, rename, writeFile } from "fs/promises";
+import { hostname as getHostname } from "os";
+import { dirname as dirname2 } from "path";
+import process2 from "process";
+
+// src/lock.ts
+import { mkdir, open, unlink } from "fs/promises";
+import { dirname } from "path";
+var DEFAULT_POLL_MS = 50;
+var DEFAULT_TIMEOUT_MS = 1e4;
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function acquireFileLock(lockPath, timeoutMs, pollMs) {
+  const deadline = Date.now() + timeoutMs;
+  await mkdir(dirname(lockPath), { recursive: true });
+  for (; ; ) {
+    try {
+      return await open(lockPath, "wx");
+    } catch (err) {
+      const code = err.code;
+      if (code !== "EEXIST") {
+        throw err;
+      }
+    }
+    if (Date.now() > deadline) {
+      throw new Error(`Timed out acquiring file lock at ${lockPath}`);
+    }
+    await sleep(pollMs);
+  }
+}
+async function releaseFileLock(lockPath, handle) {
+  await handle.close();
+  await unlink(lockPath).catch((err) => {
+    const code = err.code;
+    if (code !== "ENOENT") {
+      throw err;
+    }
+  });
+}
+async function withFileLock(lockPath, work, options) {
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const pollMs = options?.pollMs ?? DEFAULT_POLL_MS;
+  const handle = await acquireFileLock(lockPath, timeoutMs, pollMs);
+  try {
+    return await work();
+  } finally {
+    await releaseFileLock(lockPath, handle);
+  }
+}
+
+// src/state.ts
+async function readJsonFile(path) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") {
+      return void 0;
+    }
+    throw err;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    process2.stderr.write(
+      `[cf-debugger] warning: state file at ${path} is not valid JSON; resetting to empty.
+`
+    );
+    return void 0;
+  }
+}
+async function writeJsonFileAtomic(path, value) {
+  const tempPath = `${path}.${randomUUID()}.tmp`;
+  await mkdir2(dirname2(path), { recursive: true });
+  await writeFile(tempPath, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+  await rename(tempPath, path);
+}
+function emptyState() {
+  return { version: "1", sessions: [] };
+}
+function isValidState(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  return candidate.version === "1" && Array.isArray(candidate.sessions);
+}
+function isPidAlive(pid) {
+  try {
+    process2.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err.code;
+    if (code === "ESRCH") {
+      return false;
+    }
+    return true;
+  }
+}
+function filterStaleSessions(sessions) {
+  const host = getHostname();
+  return sessions.filter((session) => {
+    if (session.hostname !== host) {
+      return true;
+    }
+    return isPidAlive(session.pid);
+  });
+}
+async function readStateRaw() {
+  const parsed = await readJsonFile(stateFilePath());
+  if (!isValidState(parsed)) {
+    return emptyState();
+  }
+  return parsed;
+}
+async function writeState(state) {
+  await writeJsonFileAtomic(stateFilePath(), state);
+}
+async function readAndPruneLocked() {
+  const raw = await readStateRaw();
+  const pruned = filterStaleSessions(raw.sessions);
+  const removed = raw.sessions.filter(
+    (session) => !pruned.some((active) => active.sessionId === session.sessionId)
+  );
+  if (removed.length > 0) {
+    await writeState({ version: "1", sessions: pruned });
+  }
+  return { sessions: pruned, removed };
+}
+async function readAndPruneActiveSessions() {
+  return await withFileLock(stateLockPath(), readAndPruneLocked);
+}
+function sessionKeyString(key) {
+  return `${key.region}:${key.org}:${key.space}:${key.app}`;
+}
+function matchesKey(session, key) {
+  return session.region === key.region && session.org === key.org && session.space === key.space && session.app === key.app;
+}
+var DEFAULT_BASE_PORT = 2e4;
+var DEFAULT_MAX_PORT = 20999;
+async function pickPort(preferred, reserved, probe, basePort, maxPort) {
+  const tryOrder = [];
+  if (preferred !== void 0) {
+    tryOrder.push(preferred);
+  }
+  for (let port = basePort; port <= maxPort; port++) {
+    if (port !== preferred) {
+      tryOrder.push(port);
+    }
+  }
+  for (const port of tryOrder) {
+    if (reserved.has(port)) {
+      continue;
+    }
+    const free = await probe(port);
+    if (free) {
+      return port;
+    }
+  }
+  throw new CfDebuggerError(
+    "PORT_UNAVAILABLE",
+    `No free local port available in range ${basePort.toString()}\u2013${maxPort.toString()}`
+  );
+}
+async function registerNewSession(input) {
+  return await withFileLock(stateLockPath(), async () => {
+    const pruneResult = await readAndPruneLocked();
+    const existing = pruneResult.sessions.find((session2) => matchesKey(session2, input));
+    if (existing) {
+      return { session: existing, existing };
+    }
+    const reservedPorts = new Set(pruneResult.sessions.map((session2) => session2.localPort));
+    const localPort = await pickPort(
+      input.preferredPort,
+      reservedPorts,
+      input.portProbe,
+      input.basePort ?? DEFAULT_BASE_PORT,
+      input.maxPort ?? DEFAULT_MAX_PORT
+    );
+    const sessionId = (input.sessionIdFactory ?? randomUUID)();
+    const cfHomeDir = input.cfHomeForSession(sessionId);
+    const session = {
+      sessionId,
+      pid: process2.pid,
+      hostname: getHostname(),
+      region: input.region,
+      org: input.org,
+      space: input.space,
+      app: input.app,
+      apiEndpoint: input.apiEndpoint,
+      localPort,
+      remotePort: 9229,
+      cfHomeDir,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      status: "starting"
+    };
+    const nextSessions = [...pruneResult.sessions, session];
+    await writeState({ version: "1", sessions: nextSessions });
+    return { session };
+  });
+}
+async function updateSessionStatus(sessionId, status, message) {
+  return await withFileLock(stateLockPath(), async () => {
+    const raw = await readStateRaw();
+    let updated;
+    const nextSessions = raw.sessions.map((session) => {
+      if (session.sessionId !== sessionId) {
+        return session;
+      }
+      const base = {
+        sessionId: session.sessionId,
+        pid: session.pid,
+        hostname: session.hostname,
+        region: session.region,
+        org: session.org,
+        space: session.space,
+        app: session.app,
+        apiEndpoint: session.apiEndpoint,
+        localPort: session.localPort,
+        remotePort: session.remotePort,
+        cfHomeDir: session.cfHomeDir,
+        startedAt: session.startedAt,
+        status
+      };
+      const next = message === void 0 ? base : { ...base, message };
+      updated = next;
+      return next;
+    });
+    if (updated) {
+      await writeState({ version: "1", sessions: nextSessions });
+    }
+    return updated;
+  });
+}
+async function removeSession(sessionId) {
+  return await withFileLock(stateLockPath(), async () => {
+    const raw = await readStateRaw();
+    const target = raw.sessions.find((session) => session.sessionId === sessionId);
+    if (!target) {
+      return void 0;
+    }
+    const remaining = raw.sessions.filter((session) => session.sessionId !== sessionId);
+    await writeState({ version: "1", sessions: remaining });
+    return target;
+  });
+}
+
+// src/debugger.ts
+var DEFAULT_TUNNEL_READY_TIMEOUT_MS = 3e4;
+var POST_USR1_DELAY_MS = 300;
+var PORT_CLEANUP_DELAY_MS = 600;
+var CHILD_SIGTERM_GRACE_MS = 2e3;
+var PORT_RECLAIM_DELAY_MS = 250;
+async function killProcessGroupOrProc(child, timeoutMs = CHILD_SIGTERM_GRACE_MS) {
+  if (child.pid === void 0) {
+    return;
+  }
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return;
+  }
+  const isWindows = process3.platform === "win32";
+  const send = (sig) => {
+    try {
+      if (!isWindows && child.pid !== void 0) {
+        process3.kill(-child.pid, sig);
+      } else {
+        child.kill(sig);
+      }
+    } catch {
+    }
+  };
+  send("SIGTERM");
+  const closed = await new Promise((resolve) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolve(true);
+      return;
+    }
+    const t = setTimeout(() => {
+      resolve(false);
+    }, timeoutMs);
+    child.once("close", () => {
+      clearTimeout(t);
+      resolve(true);
+    });
+  });
+  if (!closed) {
+    send("SIGKILL");
+  }
+}
+async function pruneAndCleanupOrphans() {
+  const result = await readAndPruneActiveSessions();
+  const host = getHostname2();
+  for (const removed of result.removed) {
+    if (removed.hostname === host) {
+      void killProcessOnPort(removed.localPort);
+    }
+  }
+  return result.sessions;
+}
+function checkAbort(signal) {
+  if (signal?.aborted) {
+    throw new CfDebuggerError("ABORTED", "Operation aborted by caller");
+  }
+}
+function requireCredentials(options) {
+  const email = options.email ?? process3.env["SAP_EMAIL"];
+  const password = options.password ?? process3.env["SAP_PASSWORD"];
+  if (email === void 0 || email === "") {
+    throw new CfDebuggerError(
+      "MISSING_CREDENTIALS",
+      "SAP email is required. Pass `email` or set SAP_EMAIL env var."
+    );
+  }
+  if (password === void 0 || password === "") {
+    throw new CfDebuggerError(
+      "MISSING_CREDENTIALS",
+      "SAP password is required. Pass `password` or set SAP_PASSWORD env var."
+    );
+  }
+  return { email, password };
+}
+async function startDebugger(options) {
+  const { email, password } = requireCredentials(options);
+  const apiEndpoint = resolveApiEndpoint(options.region, options.apiEndpoint);
+  const tunnelReadyTimeoutMs = options.tunnelReadyTimeoutMs ?? DEFAULT_TUNNEL_READY_TIMEOUT_MS;
+  const emit = (status, message) => {
+    options.onStatus?.(status, message);
+  };
+  checkAbort(options.signal);
+  await pruneAndCleanupOrphans();
+  const registration = await registerNewSession({
+    region: options.region,
+    org: options.org,
+    space: options.space,
+    app: options.app,
+    apiEndpoint,
+    ...options.preferredPort === void 0 ? {} : { preferredPort: options.preferredPort },
+    portProbe: isPortFree,
+    cfHomeForSession: sessionCfHomeDir
+  });
+  if (registration.existing) {
+    throw new CfDebuggerError(
+      "SESSION_ALREADY_RUNNING",
+      `A debugger session is already running for ${sessionKeyString(options)} on port ${registration.existing.localPort.toString()} (pid ${registration.existing.pid.toString()}, sessionId ${registration.existing.sessionId}). Stop it first with \`cf-debugger stop\`.`
+    );
+  }
+  const session = registration.session;
+  const context = { cfHome: session.cfHomeDir };
+  let child;
+  let tunnelClosed = false;
+  let exitResolve;
+  const exitPromise = new Promise((resolve) => {
+    exitResolve = resolve;
+  });
+  const cleanupFilesystem = async () => {
+    try {
+      await rm(session.cfHomeDir, { recursive: true, force: true });
+    } catch {
+    }
+  };
+  const finalize = async () => {
+    if (!tunnelClosed) {
+      tunnelClosed = true;
+      if (child) {
+        await killProcessGroupOrProc(child);
+      }
+      setTimeout(() => {
+        void killProcessOnPort(session.localPort);
+      }, PORT_CLEANUP_DELAY_MS);
+    }
+    await removeSession(session.sessionId);
+    await cleanupFilesystem();
+    emit("stopped");
+  };
+  try {
+    await mkdir3(session.cfHomeDir, { recursive: true });
+    emit("logging-in");
+    await updateSessionStatus(session.sessionId, "logging-in");
+    await cfLogin(apiEndpoint, email, password, context);
+    checkAbort(options.signal);
+    emit("targeting");
+    await updateSessionStatus(session.sessionId, "targeting");
+    await cfTarget(options.org, options.space, context);
+    checkAbort(options.signal);
+    await killProcessOnPort(session.localPort);
+    await new Promise((resolve) => {
+      setTimeout(resolve, 200);
+    });
+    emit("signaling");
+    await updateSessionStatus(session.sessionId, "signaling");
+    const signalResult = await cfSshOneShot(
+      options.app,
+      `kill -s USR1 $(pidof node)`,
+      context
+    );
+    if (isSshDisabledError(signalResult.stderr)) {
+      const alreadyEnabled = await cfSshEnabled(options.app, context);
+      if (!alreadyEnabled) {
+        emit("ssh-enabling", "Enabling SSH on the app");
+        await updateSessionStatus(session.sessionId, "ssh-enabling");
+        await cfEnableSsh(options.app, context);
+      }
+      emit("ssh-restarting", "Restarting app so SSH becomes active");
+      await updateSessionStatus(session.sessionId, "ssh-restarting");
+      await cfRestartApp(options.app, context);
+      checkAbort(options.signal);
+      emit("signaling");
+      await updateSessionStatus(session.sessionId, "signaling");
+      const retrySignalResult = await cfSshOneShot(
+        options.app,
+        `kill -s USR1 $(pidof node)`,
+        context
+      );
+      if (retrySignalResult.exitCode !== 0) {
+        const detail = retrySignalResult.stderr.trim().length > 0 ? retrySignalResult.stderr.trim() : `exit code ${String(retrySignalResult.exitCode)}`;
+        throw new CfDebuggerError(
+          "USR1_SIGNAL_FAILED",
+          `Failed to send SIGUSR1 to the Node.js process on ${options.app} after enabling SSH: ${detail}`,
+          retrySignalResult.stderr
+        );
+      }
+    } else if (signalResult.exitCode !== 0) {
+      const detail = signalResult.stderr.trim().length > 0 ? signalResult.stderr.trim() : `exit code ${String(signalResult.exitCode)}`;
+      throw new CfDebuggerError(
+        "USR1_SIGNAL_FAILED",
+        `Failed to send SIGUSR1 to the Node.js process on ${options.app}: ${detail}`,
+        signalResult.stderr
+      );
+    }
+    await new Promise((resolve) => {
+      setTimeout(resolve, POST_USR1_DELAY_MS);
+    });
+    checkAbort(options.signal);
+    emit("tunneling");
+    await updateSessionStatus(session.sessionId, "tunneling");
+    if (!await isPortFree(session.localPort)) {
+      await killProcessOnPort(session.localPort);
+      await new Promise((resolve) => {
+        setTimeout(resolve, PORT_RECLAIM_DELAY_MS);
+      });
+      if (!await isPortFree(session.localPort)) {
+        throw new CfDebuggerError(
+          "PORT_UNAVAILABLE",
+          `Local port ${session.localPort.toString()} is in use and could not be reclaimed for the tunnel.`
+        );
+      }
+    }
+    child = spawnSshTunnel(options.app, session.localPort, session.remotePort, context);
+    child.on("close", (code) => {
+      tunnelClosed = true;
+      exitResolve?.(code);
+    });
+    child.on("error", (err) => {
+      emit("error", err.message);
+    });
+    const ready = await probeTunnelReady(session.localPort, tunnelReadyTimeoutMs);
+    checkAbort(options.signal);
+    if (!ready) {
+      throw new CfDebuggerError(
+        "TUNNEL_NOT_READY",
+        `SSH tunnel on port ${session.localPort.toString()} did not become ready within ${Math.round(tunnelReadyTimeoutMs / 1e3).toString()}s.`
+      );
+    }
+    emit("ready");
+    const readySession = await updateSessionStatus(session.sessionId, "ready");
+    const activeSession = readySession ?? { ...session, status: "ready" };
+    let disposePromise;
+    const handle = {
+      session: activeSession,
+      dispose: async () => {
+        disposePromise ??= (async () => {
+          emit("stopping");
+          await updateSessionStatus(session.sessionId, "stopping");
+          await finalize();
+        })();
+        await disposePromise;
+      },
+      waitForExit: async () => {
+        return await exitPromise;
+      }
+    };
+    return handle;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    emit("error", message);
+    await finalize();
+    throw err;
+  }
+}
+async function stopDebugger(options) {
+  const sessions = await pruneAndCleanupOrphans();
+  let target;
+  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));
+  }
+  if (target === void 0) {
+    return void 0;
+  }
+  if (target.pid !== process3.pid) {
+    try {
+      process3.kill(target.pid, "SIGTERM");
+    } catch {
+    }
+  }
+  setTimeout(() => {
+    void killProcessOnPort(target.localPort);
+  }, PORT_CLEANUP_DELAY_MS);
+  const removed = await removeSession(target.sessionId);
+  try {
+    await rm(target.cfHomeDir, { recursive: true, force: true });
+  } catch {
+  }
+  return removed;
+}
+async function stopAllDebuggers() {
+  const sessions = await pruneAndCleanupOrphans();
+  let stopped = 0;
+  for (const session of sessions) {
+    const result = await stopDebugger({ sessionId: session.sessionId });
+    if (result) {
+      stopped += 1;
+    }
+  }
+  return stopped;
+}
+async function listSessions() {
+  return await pruneAndCleanupOrphans();
+}
+async function getSession(key) {
+  const sessions = await pruneAndCleanupOrphans();
+  return sessions.find((s) => matchesKey(s, key));
+}
+
+// src/cli.ts
+function readRequiredOption(value, flag) {
+  if (value === void 0 || value === "") {
+    process4.stderr.write(`Missing required option ${flag}
+`);
+    process4.exit(1);
+  }
+  return value;
+}
+function parseOptionalPort(raw) {
+  if (raw === void 0) {
+    return void 0;
+  }
+  const port = Number.parseInt(raw, 10);
+  if (Number.isNaN(port) || port <= 0 || port > 65535) {
+    process4.stderr.write(`Invalid port: ${raw}
+`);
+    process4.exit(1);
+  }
+  return port;
+}
+function parseOptionalTimeout(raw) {
+  if (raw === void 0) {
+    return void 0;
+  }
+  const seconds = Number.parseInt(raw, 10);
+  if (Number.isNaN(seconds) || seconds <= 0) {
+    process4.stderr.write(`Invalid timeout: ${raw}
+`);
+    process4.exit(1);
+  }
+  return seconds * 1e3;
+}
+function logStatus(verbose, status, message) {
+  if (verbose) {
+    const suffix = message === void 0 ? "" : `: ${message}`;
+    process4.stdout.write(`[cf-debugger] ${status}${suffix}
+`);
+  }
+}
+async function handleStart(opts) {
+  const region = readRequiredOption(opts.region, "--region");
+  const org = readRequiredOption(opts.org, "--org");
+  const space = readRequiredOption(opts.space, "--space");
+  const app = readRequiredOption(opts.app, "--app");
+  const verbose = opts.verbose ?? false;
+  const preferredPort = parseOptionalPort(opts.port);
+  const tunnelReadyTimeoutMs = parseOptionalTimeout(opts.timeout);
+  const abortController = new AbortController();
+  const onStartupSignal = (exitCode) => () => {
+    abortController.abort();
+    process4.stderr.write(`
+Aborting startup for ${app}...
+`);
+    setTimeout(() => {
+      process4.exit(exitCode);
+    }, 5e3).unref();
+  };
+  const startupSigint = onStartupSignal(130);
+  const startupSigterm = onStartupSignal(143);
+  process4.on("SIGINT", startupSigint);
+  process4.on("SIGTERM", startupSigterm);
+  let handle;
+  try {
+    handle = await startDebugger({
+      region,
+      org,
+      space,
+      app,
+      verbose,
+      signal: abortController.signal,
+      ...preferredPort === void 0 ? {} : { preferredPort },
+      ...tunnelReadyTimeoutMs === void 0 ? {} : { tunnelReadyTimeoutMs },
+      onStatus: (status, message) => {
+        logStatus(verbose, status, message);
+      }
+    });
+  } finally {
+    process4.off("SIGINT", startupSigint);
+    process4.off("SIGTERM", startupSigterm);
+  }
+  process4.stdout.write(
+    `Debugger ready for ${app} (${region}/${org}/${space}).
+  Local port:  ${handle.session.localPort.toString()}
+  Remote port: ${handle.session.remotePort.toString()}
+  Session id:  ${handle.session.sessionId}
+  PID:         ${handle.session.pid.toString()}
+Press Ctrl+C to stop.
+`
+  );
+  let disposePromise;
+  const dispose = async () => {
+    disposePromise ??= (async () => {
+      process4.stdout.write(`
+Stopping debugger for ${app}...
+`);
+      try {
+        await handle.dispose();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process4.stderr.write(`Error during stop: ${msg}
+`);
+      }
+    })();
+    await disposePromise;
+  };
+  process4.on("SIGINT", () => {
+    void dispose().then(() => {
+      process4.exit(130);
+    });
+  });
+  process4.on("SIGTERM", () => {
+    void dispose().then(() => {
+      process4.exit(143);
+    });
+  });
+  const code = await handle.waitForExit();
+  await dispose();
+  process4.exit(code ?? 0);
+}
+function resolveKeyFromOpts(opts) {
+  if (opts.region !== void 0 && opts.org !== void 0 && opts.space !== void 0 && opts.app !== void 0) {
+    return {
+      region: opts.region,
+      org: opts.org,
+      space: opts.space,
+      app: opts.app
+    };
+  }
+  return void 0;
+}
+async function handleStop(opts) {
+  if (opts.all === true) {
+    const count = await stopAllDebuggers();
+    process4.stdout.write(`Stopped ${count.toString()} session(s).
+`);
+    return;
+  }
+  const key = resolveKeyFromOpts(opts);
+  const result = await stopDebugger({
+    ...opts.sessionId === void 0 ? {} : { sessionId: opts.sessionId },
+    ...key === void 0 ? {} : { key }
+  });
+  if (result === void 0) {
+    process4.stderr.write("No matching session found.\n");
+    process4.exit(1);
+  }
+  process4.stdout.write(
+    `Stopped session ${result.sessionId} (${result.app}, port ${result.localPort.toString()}).
+`
+  );
+}
+async function handleList() {
+  const sessions = await listSessions();
+  process4.stdout.write(`${JSON.stringify(sessions, null, 2)}
+`);
+}
+async function handleStatus(opts) {
+  const session = await getSession({
+    region: opts.region,
+    org: opts.org,
+    space: opts.space,
+    app: opts.app
+  });
+  process4.stdout.write(`${JSON.stringify(session ?? null, null, 2)}
+`);
+}
+async function main(argv) {
+  const program = new Command();
+  program.name("cf-debugger").description("Open an SSH debug tunnel to a SAP BTP Cloud Foundry app's Node.js inspector");
+  program.command("start").description("Open a debug tunnel for one app").requiredOption("--region <key>", "CF region key (e.g. eu10)").requiredOption("--org <name>", "CF org name").requiredOption("--space <name>", "CF space name").requiredOption("--app <name>", "CF app name").option("--port <number>", "Preferred local port (auto-assigned if omitted)").option("--timeout <seconds>", "Tunnel-ready timeout in seconds (default: 30)").option("--verbose", "Print status transitions", false).action(async (opts) => {
+    await handleStart(opts);
+  });
+  program.command("stop").description("Stop one session (by key or id) or all sessions with --all").option("--region <key>").option("--org <name>").option("--space <name>").option("--app <name>").option("--session-id <id>").option("--all", "Stop every active session", false).action(async (opts) => {
+    await handleStop(opts);
+  });
+  program.command("list").description("Print every active debugger session as JSON").action(async () => {
+    await handleList();
+  });
+  program.command("status").description("Print one session by key as JSON (null if not active)").requiredOption("--region <key>").requiredOption("--org <name>").requiredOption("--space <name>").requiredOption("--app <name>").action(async (opts) => {
+    await handleStatus(opts);
+  });
+  await program.parseAsync([...argv]);
+}
+try {
+  await main(process4.argv);
+} catch (err) {
+  if (err instanceof CfDebuggerError) {
+    if (err.code === "ABORTED") {
+      process4.stderr.write(`Aborted: ${err.message}
+`);
+      process4.exit(130);
+    }
+    process4.stderr.write(`Error [${err.code}]: ${err.message}
+`);
+  } else {
+    const msg = err instanceof Error ? err.message : String(err);
+    process4.stderr.write(`Error: ${msg}
+`);
+  }
+  process4.exit(1);
+}
+export {
+  main
+};
+//# sourceMappingURL=cli.js.map