@saptools/cf-live-trace 0.1.0

package/dist/index.js

@@ -0,0 +1,1027 @@
+// src/runtime-source.ts
+var CF_LIVE_TRACE_GLOBAL_NAME = "__SAPTOOLS_CF_LIVE_TRACE__";
+var CF_LIVE_TRACE_RUNTIME_VERSION = 1;
+var CF_LIVE_TRACE_RUNTIME_SOURCE = `
+(() => {
+  const name = '${CF_LIVE_TRACE_GLOBAL_NAME}';
+  const runtimeVersion = ${String(CF_LIVE_TRACE_RUNTIME_VERSION)};
+  const existing = globalThis[name];
+  if (existing && typeof existing.version === 'number' && existing.version >= runtimeVersion) return existing;
+  if (existing && typeof existing.uninstall === 'function') {
+    try {
+      existing.uninstall();
+    } catch {}
+  }
+  let BufferCtor = globalThis.Buffer;
+  const state = {
+    version: runtimeVersion,
+    installed: false,
+    enabled: false,
+    options: { appId: '', instance: '0', captureHeaders: true, captureRequestBody: true, captureResponseBody: true, maxBodyBytes: 4096, maxEvents: 1000 },
+    queue: [],
+    droppedCount: 0,
+    originals: {},
+    seen: new WeakSet(),
+    nextId: 1
+  };
+  const loadRequire = () => {
+    if (typeof require === 'function') return require;
+    if (globalThis.process && globalThis.process.mainModule && typeof globalThis.process.mainModule.require === 'function') {
+      return globalThis.process.mainModule.require.bind(globalThis.process.mainModule);
+    }
+    return null;
+  };
+  const loadModule = async (moduleName) => {
+    const requireFn = loadRequire();
+    if (requireFn) return requireFn(moduleName);
+    if (globalThis.process && typeof globalThis.process.getBuiltinModule === 'function') {
+      return globalThis.process.getBuiltinModule(moduleName);
+    }
+    return await import('node:' + moduleName);
+  };
+  const toHeaderRecord = (headers) => {
+    const output = {};
+    if (!headers || !state.options.captureHeaders) return output;
+    for (const key of Object.keys(headers)) {
+      const value = headers[key];
+      output[key] = Array.isArray(value) ? value.join(', ') : String(value);
+    }
+    return output;
+  };
+  const chunkText = (chunk) => {
+    if (chunk === undefined || chunk === null) return '';
+    if (BufferCtor && BufferCtor.isBuffer(chunk)) return chunk.toString('utf8');
+    if (typeof chunk === 'string') return chunk;
+    if (chunk instanceof Uint8Array && BufferCtor) return BufferCtor.from(chunk).toString('utf8');
+    return '';
+  };
+  const byteLength = (text) => BufferCtor ? BufferCtor.byteLength(text) : text.length;
+  const appendPreview = (current, chunk, enabled) => {
+    if (!enabled) return current;
+    const text = chunkText(chunk);
+    if (state.options.maxBodyBytes <= 0) return current + text;
+    if (current.length >= state.options.maxBodyBytes) return current;
+    return (current + text).slice(0, state.options.maxBodyBytes);
+  };
+  const enqueue = (event) => {
+    if (state.queue.length >= state.options.maxEvents) {
+      state.queue.shift();
+      state.droppedCount += 1;
+    }
+    state.queue.push(event);
+  };
+  const observe = (req, res) => {
+    if (!state.enabled || !req || !res || state.seen.has(req)) return;
+    state.seen.add(req);
+    const started = Date.now();
+    const initialUrl = String(req.url || '');
+    const traceId = String(state.nextId++);
+    let requestBytes = 0;
+    let responseBytes = 0;
+    let requestPreview = '';
+    let responsePreview = '';
+    let finished = false;
+    const originalReqEmit = req.emit;
+    const originalWrite = res.write;
+    const originalEnd = res.end;
+    req.emit = function patchedReqEmit(eventName, ...args) {
+      if (eventName === 'data' && args[0] !== undefined) {
+        const text = chunkText(args[0]);
+        requestBytes += byteLength(text);
+        requestPreview = appendPreview(requestPreview, args[0], state.options.captureRequestBody);
+      }
+      return originalReqEmit.apply(this, [eventName, ...args]);
+    };
+    res.write = function patchedWrite(chunk, ...args) {
+      const text = chunkText(chunk);
+      responseBytes += byteLength(text);
+      responsePreview = appendPreview(responsePreview, chunk, state.options.captureResponseBody);
+      return originalWrite.apply(this, [chunk, ...args]);
+    };
+    res.end = function patchedEnd(chunk, ...args) {
+      if (chunk !== undefined) {
+        const text = chunkText(chunk);
+        responseBytes += byteLength(text);
+        responsePreview = appendPreview(responsePreview, chunk, state.options.captureResponseBody);
+      }
+      return originalEnd.apply(this, [chunk, ...args]);
+    };
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      req.emit = originalReqEmit;
+      res.write = originalWrite;
+      res.end = originalEnd;
+      const rawUrl = initialUrl || String(req.url || '');
+      enqueue({
+        id: traceId,
+        timestamp: new Date().toISOString(),
+        instance: state.options.instance,
+        method: String(req.method || 'GET').toUpperCase(),
+        path: rawUrl.split('?')[0] || rawUrl,
+        url: rawUrl,
+        normalizedUrl: rawUrl,
+        status: typeof res.statusCode === 'number' ? res.statusCode : null,
+        durationMs: Date.now() - started,
+        requestBytes,
+        responseBytes,
+        requestHeaders: toHeaderRecord(req.headers),
+        responseHeaders: toHeaderRecord(typeof res.getHeaders === 'function' ? res.getHeaders() : {}),
+        requestBodyPreview: requestPreview,
+        responseBodyPreview: responsePreview,
+        requestBodyTruncated: state.options.maxBodyBytes > 0 && requestPreview.length >= state.options.maxBodyBytes,
+        responseBodyTruncated: state.options.maxBodyBytes > 0 && responsePreview.length >= state.options.maxBodyBytes,
+        droppedBeforeEvent: state.droppedCount,
+        traceId,
+        correlationId: req.headers && typeof req.headers['x-saptools-trace-id'] === 'string' ? req.headers['x-saptools-trace-id'] : null
+      });
+    };
+    res.once('finish', finish);
+    res.once('close', finish);
+  };
+  const patchEmit = (serverPrototype) => {
+    if (!serverPrototype || serverPrototype.emit.__saptoolsCfLiveTracePatched) return undefined;
+    const original = serverPrototype.emit;
+    const patched = function patchedServerEmit(eventName, ...args) {
+      if (eventName === 'request') observe(args[0], args[1]);
+      return original.apply(this, [eventName, ...args]);
+    };
+    patched.__saptoolsCfLiveTracePatched = true;
+    serverPrototype.emit = patched;
+    return original;
+  };
+  const toTransportLimit = (value) => {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) && numeric > 0 ? Math.floor(numeric) : 0;
+  };
+  const limitPreview = (event, previewKey, truncatedKey, maxChars) => {
+    const preview = event[previewKey];
+    if (maxChars <= 0 || typeof preview !== 'string' || preview.length <= maxChars) return event;
+    return { ...event, [previewKey]: preview.slice(0, maxChars), [truncatedKey]: true };
+  };
+  const eventForDrain = (event, maxChars) => {
+    if (!event || typeof event !== 'object') return event;
+    let output = { ...event };
+    output = limitPreview(output, 'requestBodyPreview', 'requestBodyTruncated', maxChars);
+    output = limitPreview(output, 'responseBodyPreview', 'responseBodyTruncated', maxChars);
+    return output;
+  };
+  const api = {
+    version: runtimeVersion,
+    async install(options) {
+      state.options = { ...state.options, ...options };
+      if (!state.installed) {
+        if (!BufferCtor) {
+          const bufferModule = await loadModule('buffer');
+          BufferCtor = bufferModule && bufferModule.Buffer ? bufferModule.Buffer : BufferCtor;
+        }
+        const http = await loadModule('http');
+        const https = await loadModule('https');
+        state.originals.httpServerEmit = patchEmit(http && http.Server && http.Server.prototype);
+        state.originals.httpsServerEmit = patchEmit(https && https.Server && https.Server.prototype);
+        state.installed = true;
+      }
+      state.enabled = true;
+      return api.status();
+    },
+    disable() {
+      state.enabled = false;
+      return api.status();
+    },
+    drainEvents(maxCount, maxTransportBodyBytes) {
+      const count = Math.max(0, Math.min(Number(maxCount) || 0, state.queue.length));
+      const transportLimit = toTransportLimit(maxTransportBodyBytes);
+      const events = state.queue.splice(0, count).map((event) => eventForDrain(event, transportLimit));
+      return { events, droppedCount: state.droppedCount, queueSize: state.queue.length };
+    },
+    status() {
+      return { installed: state.installed, enabled: state.enabled, queueSize: state.queue.length, droppedCount: state.droppedCount, maxEvents: state.options.maxEvents };
+    },
+    uninstall() {
+      state.enabled = false;
+      const requireFn = loadRequire();
+      if (requireFn) {
+        const http = requireFn('http');
+        const https = requireFn('https');
+        if (state.originals.httpServerEmit && http && http.Server) http.Server.prototype.emit = state.originals.httpServerEmit;
+        if (state.originals.httpsServerEmit && https && https.Server) https.Server.prototype.emit = state.originals.httpsServerEmit;
+      }
+      state.installed = false;
+      return api.status();
+    }
+  };
+  globalThis[name] = api;
+  return api;
+})()
+`;
+function buildInstallExpression(options) {
+  return `${CF_LIVE_TRACE_RUNTIME_SOURCE}.install(${JSON.stringify(options)})`;
+}
+function buildDrainExpression(maxCount, maxTransportBodyBytes) {
+  return `globalThis.${CF_LIVE_TRACE_GLOBAL_NAME}?.drainEvents(${String(maxCount)}, ${String(maxTransportBodyBytes)}) ?? { events: [], droppedCount: 0, queueSize: 0 }`;
+}
+function buildStopExpression(options) {
+  return options.uninstallRuntimeHook ? `globalThis.${CF_LIVE_TRACE_GLOBAL_NAME}?.uninstall() ?? { installed: false, enabled: false }` : `globalThis.${CF_LIVE_TRACE_GLOBAL_NAME}?.disable() ?? { installed: false, enabled: false }`;
+}
+
+// src/preview.ts
+function truncatePreview(preview, maxChars) {
+  if (maxChars <= 0) {
+    return { preview, truncated: false };
+  }
+  if (preview.length <= maxChars) {
+    return { preview, truncated: false };
+  }
+  return { preview: preview.slice(0, maxChars), truncated: true };
+}
+
+// src/payload.ts
+var fallbackEventId = 0;
+function parseDrainResult(payload, options) {
+  if (!isRecord(payload)) {
+    return { events: [], droppedCount: 0, queueSize: 0 };
+  }
+  const rawEvents = Array.isArray(payload["events"]) ? payload["events"] : [];
+  return {
+    events: rawEvents.map((event) => parseRuntimeEvent(event, options)).filter((event) => event !== null),
+    droppedCount: readNonNegativeNumber(payload["droppedCount"]),
+    queueSize: readNonNegativeNumber(payload["queueSize"])
+  };
+}
+function parseRuntimeEvent(payload, options) {
+  if (!isRecord(payload)) {
+    return null;
+  }
+  const rawUrl = readString(payload["url"]) ?? readString(payload["normalizedUrl"]) ?? readString(payload["path"]);
+  if (rawUrl === null) {
+    return null;
+  }
+  const requestBody = limitBodyPreview(readString(payload["requestBodyPreview"]) ?? "", options.maxBodyBytes);
+  const responseBody = limitBodyPreview(readString(payload["responseBodyPreview"]) ?? "", options.maxBodyBytes);
+  return buildEvent(payload, rawUrl, requestBody, responseBody, options);
+}
+function buildEvent(payload, rawUrl, requestBody, responseBody, options) {
+  return {
+    id: readString(payload["id"]) ?? nextFallbackEventId(),
+    timestamp: readString(payload["timestamp"]) ?? (/* @__PURE__ */ new Date()).toISOString(),
+    appId: options.appId,
+    instance: readString(payload["instance"]) ?? "0",
+    method: (readString(payload["method"]) ?? "GET").toUpperCase(),
+    path: readString(payload["path"]) ?? normalizePath(rawUrl),
+    url: rawUrl,
+    normalizedUrl: readString(payload["normalizedUrl"]) ?? normalizePath(rawUrl),
+    status: readNullableNumber(payload["status"]),
+    durationMs: readNullableNumber(payload["durationMs"]),
+    requestBytes: readNonNegativeNumber(payload["requestBytes"]),
+    responseBytes: readNonNegativeNumber(payload["responseBytes"]),
+    requestHeaders: readHeaders(payload["requestHeaders"]),
+    responseHeaders: readHeaders(payload["responseHeaders"]),
+    requestBodyPreview: requestBody.preview,
+    responseBodyPreview: responseBody.preview,
+    requestBodyTruncated: payload["requestBodyTruncated"] === true || requestBody.truncated,
+    responseBodyTruncated: payload["responseBodyTruncated"] === true || responseBody.truncated,
+    droppedBeforeEvent: readNonNegativeNumber(payload["droppedBeforeEvent"]),
+    source: "runtime-http",
+    traceId: readString(payload["traceId"]) ?? readString(payload["id"]) ?? "",
+    correlationId: readString(payload["correlationId"])
+  };
+}
+function readHeaders(value) {
+  if (!isRecord(value)) {
+    return {};
+  }
+  const headers = {};
+  for (const [key, rawValue] of Object.entries(value)) {
+    const header = readHeaderValue(rawValue);
+    if (header !== null) {
+      headers[key] = header;
+    }
+  }
+  return headers;
+}
+function readHeaderValue(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item)).join(", ");
+  }
+  return null;
+}
+function limitBodyPreview(preview, maxChars) {
+  return truncatePreview(preview, maxChars);
+}
+function normalizePath(rawUrl) {
+  try {
+    const parsed = new URL(rawUrl, "https://saptools.local");
+    return `${parsed.pathname}${parsed.search}`;
+  } catch {
+    return rawUrl;
+  }
+}
+function readString(value) {
+  return typeof value === "string" ? value : null;
+}
+function readNullableNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function readNonNegativeNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+function nextFallbackEventId() {
+  fallbackEventId += 1;
+  return `runtime-${String(fallbackEventId)}`;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/summary.ts
+function buildUrlSummaries(events) {
+  const summaries = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const normalizedUrl = normalizeEventUrl(event);
+    const current = summaries.get(normalizedUrl) ?? createSummary(normalizedUrl);
+    updateSummary(current, event);
+    summaries.set(normalizedUrl, current);
+  }
+  return [...summaries.values()].map(toImmutableSummary).sort((left, right) => right.latestSeenAt.localeCompare(left.latestSeenAt));
+}
+function normalizeEventUrl(event) {
+  const candidate = event.normalizedUrl.length > 0 ? event.normalizedUrl : event.url.length > 0 ? event.url : event.path;
+  return normalizeUrl(candidate);
+}
+function updateSummary(summary, event) {
+  summary.methods.add(event.method);
+  summary.totalCount += 1;
+  summary.statusCounts[toStatusBucket(event.status)] += 1;
+  if (event.timestamp >= summary.latestSeenAt) {
+    summary.latestStatus = event.status;
+    summary.latestDurationMs = event.durationMs;
+    summary.latestSeenAt = event.timestamp;
+  }
+}
+function normalizeUrl(rawUrl) {
+  if (rawUrl.trim().length === 0) {
+    return rawUrl;
+  }
+  try {
+    const parsed = new URL(rawUrl, "https://saptools.local");
+    return `${parsed.pathname}${parsed.search}`;
+  } catch {
+    return rawUrl;
+  }
+}
+function createSummary(normalizedUrl) {
+  return {
+    normalizedUrl,
+    displayUrl: normalizedUrl,
+    methods: /* @__PURE__ */ new Set(),
+    totalCount: 0,
+    statusCounts: { "2xx": 0, "3xx": 0, "4xx": 0, "5xx": 0, unknown: 0 },
+    latestStatus: null,
+    latestDurationMs: null,
+    latestSeenAt: ""
+  };
+}
+function toImmutableSummary(summary) {
+  return {
+    normalizedUrl: summary.normalizedUrl,
+    displayUrl: summary.displayUrl,
+    methods: [...summary.methods].sort(),
+    totalCount: summary.totalCount,
+    statusCounts: { ...summary.statusCounts },
+    latestStatus: summary.latestStatus,
+    latestDurationMs: summary.latestDurationMs,
+    latestSeenAt: summary.latestSeenAt
+  };
+}
+function toStatusBucket(status) {
+  if (status === null) {
+    return "unknown";
+  }
+  if (status >= 200 && status < 300) {
+    return "2xx";
+  }
+  if (status >= 300 && status < 400) {
+    return "3xx";
+  }
+  if (status >= 400 && status < 500) {
+    return "4xx";
+  }
+  if (status >= 500 && status < 600) {
+    return "5xx";
+  }
+  return "unknown";
+}
+
+// src/cf.ts
+import { execFile, spawn } from "child_process";
+import { mkdtemp, rm } from "fs/promises";
+import { connect as netConnect, createServer } from "net";
+import { tmpdir } from "os";
+import { join } from "path";
+import { promisify } from "util";
+import { getAllRegions } from "@saptools/cf-sync";
+var execFileAsync = promisify(execFile);
+var CF_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+var CF_COMMAND_TIMEOUT_MS = 18e4;
+var CF_SSH_READY_TIMEOUT_MS = 6e4;
+var INSPECTOR_SIGNAL_TIMEOUT_MS = 15e3;
+var INSPECTOR_REMOTE_HOST = "127.0.0.1";
+var INSPECTOR_REMOTE_PORT = 9229;
+var TUNNEL_KEEPALIVE_SECONDS = 6 * 60 * 60;
+var TUNNEL_READY_TIMEOUT_MS = 2e4;
+var TUNNEL_READY_POLL_MS = 200;
+async function prepareCfSession(target, dependencies = defaultCfDependencies) {
+  const apiEndpoint = resolveApiEndpoint(target);
+  const redactor = createSecretRedactor([target.email, target.password]);
+  const baseOptions = buildRunOptions(target, redactor);
+  await dependencies.runCf(["api", apiEndpoint], baseOptions);
+  await dependencies.runCf(["auth"], {
+    ...baseOptions,
+    envOverrides: { CF_USERNAME: target.email, CF_PASSWORD: target.password }
+  });
+  await dependencies.runCf(["target", "-o", target.org, "-s", target.space], baseOptions);
+}
+async function ensureSshEnabled(target, dependencies = defaultCfDependencies) {
+  const redactor = createSecretRedactor([target.email, target.password]);
+  const options = buildRunOptions(target, redactor);
+  const status = await dependencies.runCf(["ssh-enabled", target.app], options);
+  if (parseSshStatus(status) === "enabled") {
+    return;
+  }
+  await dependencies.runCf(["enable-ssh", target.app], options);
+  await dependencies.runCf(["restart", target.app], options);
+  await dependencies.runCf(buildCfSshArgs(target.app, target.instanceIndex, ["-c", "true"]), {
+    ...options,
+    timeoutMs: CF_SSH_READY_TIMEOUT_MS
+  });
+}
+async function tryStartNodeInspector(target, dependencies = defaultCfDependencies) {
+  try {
+    const redactor = createSecretRedactor([target.email, target.password]);
+    const stdout = await dependencies.runCf(
+      buildCfSshArgs(target.app, target.instanceIndex, ["-c", buildInspectorSignalCommand()]),
+      { ...buildRunOptions(target, redactor), timeoutMs: INSPECTOR_SIGNAL_TIMEOUT_MS }
+    );
+    return hasInspectorReadyMarker(stdout);
+  } catch {
+    return false;
+  }
+}
+async function openInspectorTunnel(target, dependencies = defaultTunnelDependencies) {
+  const localPort = await dependencies.allocatePort();
+  const handle = dependencies.spawnPortForward(buildPortForwardParams(target, localPort));
+  const ready = await raceForwardReadiness(handle, dependencies);
+  if (!ready) {
+    handle.stop();
+    return { status: "not-reachable" };
+  }
+  return { status: "ready", handle };
+}
+function buildCfSshArgs(appName, instanceIndex, tail) {
+  const args = ["ssh", appName];
+  if (instanceIndex !== void 0) {
+    args.push("-i", String(instanceIndex));
+  }
+  return [...args, ...tail];
+}
+function buildInspectorSignalCommand() {
+  return INSPECTOR_SIGNAL_COMMAND;
+}
+function createSecretRedactor(secrets) {
+  const values = secrets.map((secret) => secret.trim()).filter((secret) => secret.length > 0);
+  return (message) => values.reduce((current, secret) => current.split(secret).join("<redacted>"), message);
+}
+async function runCfCommand(args, options) {
+  const command = resolveCommand(options.command);
+  try {
+    const { stdout } = await execFileAsync(command.bin, [...command.argsPrefix, ...args], {
+      env: buildCfEnv(options.cfHomeDir, options.envOverrides),
+      maxBuffer: CF_MAX_BUFFER_BYTES,
+      timeout: options.timeoutMs ?? CF_COMMAND_TIMEOUT_MS
+    });
+    return stdout;
+  } catch (error) {
+    throw new Error(formatCfError(args, error, options.redactor), { cause: error });
+  }
+}
+function spawnPortForward(params) {
+  const command = resolveCommand(params.command);
+  const forwardSpec = `${String(params.localPort)}:${params.remoteHost}:${String(params.remotePort)}`;
+  const sshArgs = buildCfSshArgs(params.appName, params.instanceIndex, ["-L", forwardSpec, "-c", `sleep ${String(params.keepAliveSeconds)}`]);
+  const child = spawn(command.bin, [...command.argsPrefix, ...sshArgs], {
+    env: buildCfEnv(params.cfHomeDir),
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  return {
+    process: child,
+    localPort: params.localPort,
+    stop() {
+      if (!child.killed) {
+        child.kill();
+      }
+    }
+  };
+}
+var defaultCfDependencies = {
+  runCf: runCfCommand
+};
+var defaultTunnelDependencies = {
+  allocatePort: findFreePort,
+  spawnPortForward,
+  waitForLocalPort
+};
+function buildRunOptions(target, redactor) {
+  return {
+    ...target.cfHomeDir === void 0 ? {} : { cfHomeDir: target.cfHomeDir },
+    ...target.command === void 0 ? {} : { command: target.command },
+    redactor
+  };
+}
+function resolveApiEndpoint(target) {
+  if (target.apiEndpoint !== void 0 && target.apiEndpoint.trim().length > 0) {
+    return target.apiEndpoint.trim();
+  }
+  const region = getAllRegions().find((item) => item.key === target.region);
+  if (region === void 0) {
+    throw new Error(`Unknown CF region: ${target.region ?? "<missing>"}`);
+  }
+  return region.apiEndpoint;
+}
+function parseSshStatus(stdout) {
+  return stdout.toLowerCase().includes("enabled") && !stdout.toLowerCase().includes("disabled") ? "enabled" : "disabled";
+}
+function buildPortForwardParams(target, localPort) {
+  return {
+    appName: resolveTunnelAppName(target),
+    localPort,
+    remoteHost: INSPECTOR_REMOTE_HOST,
+    remotePort: INSPECTOR_REMOTE_PORT,
+    keepAliveSeconds: TUNNEL_KEEPALIVE_SECONDS,
+    ...target.cfHomeDir === void 0 ? {} : { cfHomeDir: target.cfHomeDir },
+    ...target.command === void 0 ? {} : { command: target.command },
+    ...target.instanceIndex === void 0 ? {} : { instanceIndex: target.instanceIndex }
+  };
+}
+function resolveTunnelAppName(target) {
+  const appName = target.appName ?? target.app;
+  if (appName === void 0 || appName.trim().length === 0) {
+    throw new Error("CF app name is required for the inspector tunnel.");
+  }
+  return appName;
+}
+async function raceForwardReadiness(handle, dependencies) {
+  let markFailed = () => {
+    return;
+  };
+  const failedEarly = new Promise((resolve) => {
+    markFailed = () => {
+      resolve(false);
+    };
+    handle.process.once("exit", markFailed);
+    handle.process.once("error", markFailed);
+  });
+  const ready = dependencies.waitForLocalPort(handle.localPort, TUNNEL_READY_TIMEOUT_MS);
+  const outcome = await Promise.race([ready, failedEarly]);
+  handle.process.removeListener("exit", markFailed);
+  handle.process.removeListener("error", markFailed);
+  return outcome;
+}
+function resolveCommand(command) {
+  const resolvedBin = command ?? process.env["CF_LIVE_TRACE_CF_BIN"] ?? "cf";
+  return /\.(?:c|m)?js$/i.test(resolvedBin) ? { bin: process.execPath, argsPrefix: [resolvedBin] } : { bin: resolvedBin, argsPrefix: [] };
+}
+function buildCfEnv(cfHomeDir, envOverrides) {
+  const env = { ...process.env };
+  delete env["SAP_EMAIL"];
+  delete env["SAP_PASSWORD"];
+  if (cfHomeDir !== void 0 && cfHomeDir.length > 0) {
+    env["CF_HOME"] = cfHomeDir;
+  }
+  return envOverrides === void 0 ? env : { ...env, ...envOverrides };
+}
+function formatCfError(args, error, redactor) {
+  const detail = extractErrorDetail(error);
+  const message = `cf ${formatArgs(args)} failed${detail.length > 0 ? `: ${detail}` : "."}`;
+  return redactor?.(message) ?? message;
+}
+function extractErrorDetail(error) {
+  if (!isRecord2(error)) {
+    return "";
+  }
+  const stderr = typeof error["stderr"] === "string" ? error["stderr"].trim() : "";
+  if (stderr.length > 0) {
+    return stderr;
+  }
+  return error["message"] instanceof Error ? error["message"].message : "";
+}
+function formatArgs(args) {
+  return args.join(" ");
+}
+function hasInspectorReadyMarker(stdout) {
+  return stdout.split(/\r?\n/).map((line) => line.trim()).includes("saptools-inspector-ready");
+}
+function findFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : 0;
+      server.close(() => {
+        if (port === 0) {
+          reject(new Error("Failed to allocate a local port."));
+          return;
+        }
+        resolve(port);
+      });
+    });
+  });
+}
+function waitForLocalPort(port, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve) => {
+    const attempt = () => {
+      const socket = netConnect({ host: "127.0.0.1", port });
+      socket.once("connect", () => {
+        socket.destroy();
+        resolve(true);
+      });
+      socket.once("error", () => {
+        retryPortProbe(socket, deadline, attempt, resolve);
+      });
+    };
+    attempt();
+  });
+}
+function retryPortProbe(socket, deadline, attempt, resolve) {
+  socket.destroy();
+  if (Date.now() >= deadline) {
+    resolve(false);
+    return;
+  }
+  setTimeout(attempt, TUNNEL_READY_POLL_MS);
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var INSPECTOR_SIGNAL_COMMAND = [
+  'inspector_url="http://127.0.0.1:9229/json/list"',
+  'inspector_ready() { ((command -v curl >/dev/null 2>&1 && curl -fsS --max-time 1 "$inspector_url" >/dev/null 2>&1) || (command -v wget >/dev/null 2>&1 && wget -qO- -T 1 "$inspector_url" >/dev/null 2>&1)); }',
+  "if inspector_ready; then",
+  "echo saptools-inspector-ready",
+  "exit 0",
+  "fi",
+  'node_pid=""',
+  "best_score=-1",
+  "for pid_dir in /proc/[0-9]*; do",
+  '[ -d "$pid_dir" ] || continue',
+  'node_exe="$(readlink "$pid_dir/exe" 2>/dev/null || true)"',
+  '[ "${node_exe##*/}" = "node" ] || continue',
+  'node_cmdline="$(tr "\\000" " " < "$pid_dir/cmdline" 2>/dev/null || true)"',
+  '[ -n "$node_cmdline" ] || continue',
+  "score=10",
+  'if printf "%s\\n" "$node_cmdline" | grep -Eq "@sap/cds|cds/bin/serve|serve\\.js|server\\.js|app\\.js|dist|build|index\\.js"; then',
+  "score=20",
+  "fi",
+  'if [ "$score" -gt "$best_score" ]; then',
+  'best_score="$score"',
+  'node_pid="${pid_dir##*/}"',
+  "fi",
+  "done",
+  'if [ -z "$node_pid" ]; then',
+  "echo saptools-inspector-node-not-found",
+  "exit 0",
+  "fi",
+  'echo "saptools-inspector-node-pid=$node_pid"',
+  'if kill -USR1 "$node_pid" 2>/dev/null; then',
+  "echo saptools-inspector-signaled",
+  "else",
+  "echo saptools-inspector-signal-failed",
+  "exit 0",
+  "fi",
+  "attempt=0",
+  'while [ "$attempt" -lt 20 ]; do',
+  "if inspector_ready; then",
+  "echo saptools-inspector-ready",
+  "exit 0",
+  "fi",
+  "attempt=$((attempt + 1))",
+  "sleep 0.25",
+  "done",
+  "echo saptools-inspector-not-ready"
+].join("\\n");
+
+// src/inspector.ts
+import { connectInspector } from "@saptools/cf-inspector";
+async function connectRuntimeInspector(localPort) {
+  const session = await connectInspector({ port: localPort, host: "127.0.0.1" });
+  return new CdpRuntimeClient(session);
+}
+var CdpRuntimeClient = class {
+  constructor(session) {
+    this.session = session;
+  }
+  session;
+  async evaluate(expression, timeoutMs) {
+    const result = await raceEvaluate(
+      this.session.client.send("Runtime.evaluate", {
+        expression,
+        awaitPromise: true,
+        returnByValue: true,
+        silent: true
+      }),
+      timeoutMs
+    );
+    return extractEvaluateValue(result);
+  }
+  async close() {
+    await this.session.dispose();
+  }
+};
+async function raceEvaluate(promise, timeoutMs) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error("Runtime.evaluate timed out."));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer !== void 0) {
+      clearTimeout(timer);
+    }
+    promise.catch(() => {
+      return;
+    });
+  }
+}
+function extractEvaluateValue(result) {
+  if (result.exceptionDetails !== void 0) {
+    throw new Error("Runtime.evaluate failed.");
+  }
+  return result.result?.value;
+}
+
+// src/session.ts
+var DRAIN_INTERVAL_MS = 250;
+var DRAIN_BATCH_SIZE = 50;
+var RUNTIME_QUEUE_SIZE = 1e3;
+var CONTROL_EVALUATE_TIMEOUT_MS = 5e3;
+var DRAIN_EVALUATE_TIMEOUT_MS = 1e4;
+var DRAIN_TIMEOUT_RETRY_LIMIT = 3;
+var DRAIN_TRANSPORT_BODY_LIMIT = 2e4;
+var defaultDependencies = {
+  prepareCfSession,
+  ensureSshEnabled,
+  tryStartNodeInspector,
+  openInspectorTunnel,
+  connectInspector: connectRuntimeInspector,
+  setInterval,
+  clearInterval
+};
+var LiveTraceSession = class {
+  constructor(options, dependencies = {}) {
+    this.options = options;
+    this.dependencies = { ...defaultDependencies, ...dependencies };
+  }
+  options;
+  dependencies;
+  events = [];
+  consecutiveDrainTimeouts = 0;
+  drainInFlight = false;
+  inspectorClient;
+  pollTimer;
+  state = "idle";
+  stopRequested = false;
+  tunnelHandle;
+  async start(options = {}) {
+    if (this.isRunning()) {
+      return;
+    }
+    this.stopRequested = false;
+    await this.startRuntimeTrace(resolveStartOptions(options));
+  }
+  async stop(options) {
+    this.stopRequested = true;
+    if (!this.isRunning()) {
+      this.postState("stopped", `Trace stopped (${options.reason}).`, false, false);
+      return;
+    }
+    const hadRuntimeHook = this.inspectorClient !== void 0;
+    this.postState("stopping", `Stopping trace (${options.reason}).`, hadRuntimeHook, hadRuntimeHook);
+    const uninstalled = await this.stopRuntimeTrace(options.uninstallRuntimeHook);
+    this.postState("stopped", `Trace stopped (${options.reason}).`, false, hadRuntimeHook && !uninstalled);
+  }
+  isRunning() {
+    return ["preparing", "enabling-ssh", "starting-inspector", "opening-tunnel", "injecting", "streaming", "stopping"].includes(this.state);
+  }
+  async startRuntimeTrace(options) {
+    try {
+      this.postState("preparing", "Preparing Cloud Foundry session.", false, false);
+      await this.dependencies.prepareCfSession(this.options.target);
+      if (this.shouldStop()) {
+        return;
+      }
+      await this.startInspector(options);
+    } catch (error) {
+      this.log(`Live Trace startup failed for ${this.options.target.app}: ${formatError(error)}`);
+      await this.stopRuntimeTrace(false);
+      if (!this.shouldStop()) {
+        this.postState("error", "Runtime HTTP trace could not be started.", false, false);
+      }
+    }
+  }
+  async startInspector(options) {
+    this.postState("enabling-ssh", "Ensuring CF SSH access.", false, false);
+    await this.dependencies.ensureSshEnabled(this.options.target);
+    if (this.shouldStop()) {
+      return;
+    }
+    this.postState("starting-inspector", "Requesting Node Inspector startup.", false, false);
+    await this.dependencies.tryStartNodeInspector(this.options.target);
+    if (this.shouldStop()) {
+      return;
+    }
+    this.postState("opening-tunnel", "Opening Node Inspector tunnel.", false, false);
+    const tunnel = await this.dependencies.openInspectorTunnel(this.options.target);
+    await this.attachInspector(tunnel, options);
+  }
+  async attachInspector(tunnel, options) {
+    if (this.shouldStop()) {
+      stopLateTunnel(tunnel);
+      return;
+    }
+    if (tunnel.status !== "ready") {
+      this.postState("error", "Node Inspector is not reachable on 127.0.0.1:9229.", false, false);
+      return;
+    }
+    this.tunnelHandle = tunnel.handle;
+    this.inspectorClient = await this.dependencies.connectInspector(tunnel.handle.localPort);
+    this.postState("injecting", "Installing runtime HTTP trace hook.", false, false);
+    await this.installRuntimeHook(options);
+    this.startPolling(options.maxBodyBytes);
+    this.postState("streaming", "Streaming runtime HTTP trace events.", true, false);
+  }
+  async installRuntimeHook(options) {
+    await this.requireInspector().evaluate(buildInstallExpression({
+      appId: this.options.target.app,
+      instance: String(this.options.target.instanceIndex ?? 0),
+      captureHeaders: options.captureHeaders,
+      captureRequestBody: options.captureRequestBody,
+      captureResponseBody: options.captureResponseBody,
+      maxBodyBytes: options.maxBodyBytes,
+      maxEvents: options.runtimeQueueSize
+    }), CONTROL_EVALUATE_TIMEOUT_MS);
+  }
+  startPolling(maxBodyBytes) {
+    this.stopPolling();
+    this.consecutiveDrainTimeouts = 0;
+    this.pollTimer = this.dependencies.setInterval(() => {
+      void this.drainTraceEvents(maxBodyBytes);
+    }, DRAIN_INTERVAL_MS);
+  }
+  async drainTraceEvents(maxBodyBytes) {
+    if (this.drainInFlight || this.inspectorClient === void 0 || this.state !== "streaming") {
+      return;
+    }
+    this.drainInFlight = true;
+    try {
+      const payload = await this.inspectorClient.evaluate(
+        buildDrainExpression(DRAIN_BATCH_SIZE, resolveDrainTransportBodyLimit(maxBodyBytes)),
+        DRAIN_EVALUATE_TIMEOUT_MS
+      );
+      this.consecutiveDrainTimeouts = 0;
+      this.publishDrainedEvents(payload, maxBodyBytes);
+    } catch (error) {
+      await this.handleDrainFailure(error);
+    } finally {
+      this.drainInFlight = false;
+    }
+  }
+  publishDrainedEvents(payload, maxBodyBytes) {
+    const drained = parseDrainResult(payload, { appId: this.options.target.app, maxBodyBytes });
+    if (drained.events.length === 0) {
+      return;
+    }
+    this.events.push(...drained.events);
+    this.events.splice(0, Math.max(0, this.events.length - RUNTIME_QUEUE_SIZE));
+    this.options.onEvents?.(drained.events);
+    this.options.onSummary?.(buildUrlSummaries(this.events));
+  }
+  async handleDrainFailure(error) {
+    if (isEvaluateTimeout(error)) {
+      this.consecutiveDrainTimeouts += 1;
+      if (this.consecutiveDrainTimeouts < DRAIN_TIMEOUT_RETRY_LIMIT) {
+        this.log(`Live Trace drain timed out for ${this.options.target.app}; retrying (${String(this.consecutiveDrainTimeouts)}/${String(DRAIN_TIMEOUT_RETRY_LIMIT)}).`);
+        return;
+      }
+    }
+    this.log(`Live Trace stream failed for ${this.options.target.app}: ${formatError(error)}`);
+    await this.stopRuntimeTrace(false);
+    this.postState("error", "Runtime HTTP trace connection was lost.", false, true);
+  }
+  async stopRuntimeTrace(uninstallRuntimeHook) {
+    this.stopPolling();
+    this.consecutiveDrainTimeouts = 0;
+    const uninstalled = await this.stopInspectorHook(uninstallRuntimeHook);
+    await this.inspectorClient?.close();
+    this.inspectorClient = void 0;
+    this.tunnelHandle?.stop();
+    this.tunnelHandle = void 0;
+    return uninstalled;
+  }
+  async stopInspectorHook(uninstallRuntimeHook) {
+    if (this.inspectorClient === void 0) {
+      return true;
+    }
+    try {
+      await this.inspectorClient.evaluate(buildStopExpression({ uninstallRuntimeHook }), CONTROL_EVALUATE_TIMEOUT_MS);
+      return uninstallRuntimeHook;
+    } catch (error) {
+      this.log(`Live Trace cleanup failed for ${this.options.target.app}: ${formatError(error)}`);
+      return false;
+    }
+  }
+  stopPolling() {
+    if (this.pollTimer === void 0) {
+      return;
+    }
+    this.dependencies.clearInterval(this.pollTimer);
+    this.pollTimer = void 0;
+  }
+  postState(state, message, runtimeHookInstalled, runtimeHookMayRemain) {
+    this.state = state;
+    this.options.onState?.({
+      state,
+      app: this.options.target.app,
+      instance: String(this.options.target.instanceIndex ?? 0),
+      message,
+      runtimeHookInstalled,
+      runtimeHookMayRemain
+    });
+  }
+  requireInspector() {
+    if (this.inspectorClient === void 0) {
+      throw new Error("Inspector client is not connected.");
+    }
+    return this.inspectorClient;
+  }
+  shouldStop() {
+    return this.stopRequested;
+  }
+  log(message) {
+    this.options.onLog?.(message);
+  }
+};
+function resolveStartOptions(options) {
+  return {
+    captureHeaders: options.captureHeaders ?? true,
+    captureRequestBody: options.captureRequestBody ?? true,
+    captureResponseBody: options.captureResponseBody ?? true,
+    maxBodyBytes: options.maxBodyBytes ?? 4096,
+    runtimeQueueSize: options.runtimeQueueSize ?? RUNTIME_QUEUE_SIZE
+  };
+}
+function stopLateTunnel(tunnel) {
+  if (tunnel.status === "ready") {
+    tunnel.handle.stop();
+  }
+}
+function resolveDrainTransportBodyLimit(maxBodyBytes) {
+  return maxBodyBytes > 0 ? Math.min(maxBodyBytes, DRAIN_TRANSPORT_BODY_LIMIT) : DRAIN_TRANSPORT_BODY_LIMIT;
+}
+function isEvaluateTimeout(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("Runtime.evaluate timed out");
+}
+function formatError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.trim().length > 0 ? message.trim() : "Unknown error";
+}
+export {
+  CF_LIVE_TRACE_GLOBAL_NAME,
+  CF_LIVE_TRACE_RUNTIME_SOURCE,
+  CF_LIVE_TRACE_RUNTIME_VERSION,
+  LiveTraceSession,
+  buildCfSshArgs,
+  buildDrainExpression,
+  buildInspectorSignalCommand,
+  buildInstallExpression,
+  buildStopExpression,
+  buildUrlSummaries,
+  createSecretRedactor,
+  normalizeEventUrl,
+  openInspectorTunnel,
+  parseDrainResult,
+  prepareCfSession,
+  truncatePreview,
+  tryStartNodeInspector
+};
+//# sourceMappingURL=index.js.map