@saptools/cf-live-trace 0.1.8 → 0.2.0

package/README.md

@@ -9,7 +9,7 @@
 [![node](https://img.shields.io/node/v/@saptools/cf-live-trace.svg?style=flat&color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
 [![types](https://img.shields.io/npm/types/@saptools/cf-live-trace.svg?style=flat&color=3178C6&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 
-[Install](#install) - [Quick Start](#quick-start) - [CLI](#cli) - [API](#programmatic-usage) - [Security](#security-notes)
+[Install](#install) - [Quick Start](#quick-start) - [CLI](#cli) - [Security](#security-notes)
 
 </div>
 
@@ -152,15 +152,19 @@ cf-live-trace \
   --format json
 ```
 
-Inspect a saved session after or during a trace run:
+Inspect, export, or replay a saved session after or during a trace run:
 
 ```bash
 cf-live-trace session events s1a2b3c4d5e6f7a8b --method POST --limit 20
-cf-live-trace session search s1a2b3c4d5e6f7a8b orderId --body both --length 256
+cf-live-trace session search s1a2b3c4d5e6f7a8b orderId --body response --length 256
 cf-live-trace session body s1a2b3c4d5e6f7a8b r1a2b3c4d5e6f7a8 --body response --path /data/items/0 --limit 4000 --rows 100
+cf-live-trace session curl s1a2b3c4d5e6f7a8b r1a2b3c4d5e6f7a8 --target http://localhost:4004 --out replay.sh
+cf-live-trace session replay s1a2b3c4d5e6f7a8b r1a2b3c4d5e6f7a8 --target http://localhost:4004
 cf-live-trace session prune
 ```
 
+`session curl` reconstructs an absolute URL from `x-forwarded-proto`, `x-forwarded-host`, or `host` when `--target` is omitted. Without `--copy` or `--out`, it truncates displayed header values and request bodies to keep terminals responsive; use `--copy` or `--out` for the full command. Both `session curl` and `session replay` refuse to run when the captured request body was already truncated by `--max-body-bytes`, because replaying an incomplete payload is usually misleading. Hop-by-hop headers such as `host` and `content-length` are omitted from generated and replayed requests so the target HTTP client can recalculate them safely.
+
 ---
 
 ## How It Works
@@ -180,39 +184,6 @@ The injected global is named `__SAPTOOLS_CF_LIVE_TRACE__` so CLI sessions do not
 
 ---
 
-## Programmatic Usage
-
-```ts
-import { LiveTraceSession } from "@saptools/cf-live-trace";
-
-const session = new LiveTraceSession({
-  target: {
-    region: "ap10",
-    email: process.env["SAP_EMAIL"] ?? "",
-    password: process.env["SAP_PASSWORD"] ?? "",
-    org: "sample-org",
-    space: "dev",
-    app: "orders-api",
-    instanceIndex: 0,
-  },
-  onEvents(events) {
-    for (const event of events) {
-      process.stdout.write(`${event.method} ${event.normalizedUrl} ${String(event.status)}\n`);
-    }
-  },
-});
-
-await session.start({ maxBodyBytes: 4096 });
-
-process.once("SIGINT", () => {
-  void session.stop({ uninstallRuntimeHook: true, reason: "user" });
-});
-```
-
-The public API also exports helpers for payload parsing, runtime expression construction, CF SSH argument construction, and URL summaries.
-
----
-
 ## Security Notes
 
 - This tool injects JavaScript into a running Node.js process through the Node inspector. Use it only for apps and spaces you are authorized to inspect.

package/dist/cli.js

@@ -421,7 +421,7 @@ function buildCfEnvForTarget(overrides) {
 }
 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)); }',
+  '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",
@@ -2139,6 +2139,10 @@ function writeSummaryLine(event) {
 `);
 }
 
+// src/cli/session-commands.ts
+import { spawn as spawn2 } from "child_process";
+import { writeFile as writeFile2 } from "fs/promises";
+
 // src/trace-inspect.ts
 var DEFAULT_BODY_LIMIT = 4e3;
 function inspectTraceBodyResult(record, options) {
@@ -2381,6 +2385,23 @@ function isRecord4(value) {
 }
 
 // src/cli/session-commands.ts
+var DISPLAY_HEADER_VALUE_LIMIT = 128;
+var DISPLAY_BODY_LIMIT = 2e3;
+var DISPLAY_RESPONSE_BODY_LIMIT = 4e3;
+var REPLAY_OMITTED_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "connection",
+  "content-length",
+  "expect",
+  "host",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade"
+]);
+var TRUNCATED_MARKER = "... [Truncated for display]";
 function registerSessionCommands(program) {
   const session = program.command("session").description("inspect saved live trace sessions");
   session.command("list").description("list active trace sessions").action(async () => {
@@ -2389,12 +2410,18 @@ function registerSessionCommands(program) {
   session.command("events <sessionId>").description("list compact events saved for a trace session").option("--method <method>", "filter by HTTP method").option("--status <code>", "filter by HTTP status", parseIntOption).option("--path <text>", "filter by URL/path substring").option("--limit <count>", "maximum events to print", parseIntOption).action(async (sessionId, _options, command) => {
     await runEvents(sessionId, command.opts());
   });
-  session.command("search <sessionId> <text>").description("search saved request and response bodies").option("--body <side>", "request, response, or both", parseSearchBodySide, "both").option("--limit <count>", "maximum matches to print", parseIntOption).option("--length <chars>", "maximum preview characters", parseIntOption).action(async (sessionId, text, _options, command) => {
+  session.command("search <sessionId> <text>").description("search saved request and response bodies").option("--body <side>", "request, response, or both", parseSearchBodySide, "response").option("--limit <count>", "maximum matches to print", parseIntOption).option("--length <chars>", "maximum preview characters", parseIntOption).action(async (sessionId, text, _options, command) => {
     await runSearch(sessionId, text, command.opts());
   });
   session.command("body <sessionId> <requestId>").description("inspect a saved JSON request or response body").option("--body <side>", "request or response", parseBodySide, "response").option("--path <pointer>", "JSON Pointer inside the saved body").option("--limit <chars>", "maximum characters per value", parseIntOption).option("--rows <count>", "maximum structure rows to print", parseIntOption).action(async (sessionId, requestId, _options, command) => {
     await runBody(sessionId, requestId, command.opts());
   });
+  session.command("curl <sessionId> <requestId>").description("export a saved request as a ready-to-run curl command").option("--target <baseUrl>", "rewrite the request URL to a target base URL, for example http://localhost:4004").option("--copy", "copy the full curl command to the clipboard").option("--out <file>", "write the full curl command to a shell script file").action(async (sessionId, requestId, _options, command) => {
+    await runCurl(sessionId, requestId, command.opts());
+  });
+  session.command("replay <sessionId> <requestId>").description("replay a saved request directly from the CLI").option("--target <baseUrl>", "rewrite the request URL to a target base URL, for example http://localhost:4004").action(async (sessionId, requestId, _options, command) => {
+    await runReplay(sessionId, requestId, command.opts());
+  });
   session.command("prune").description("remove expired trace event files").action(async () => {
     writeJson({ removed: await pruneTraceSessions() });
   });
@@ -2413,7 +2440,7 @@ async function runEvents(sessionId, options) {
 }
 async function runSearch(sessionId, text, options) {
   const limit = positive2("--limit", options.limit, 20);
-  const body = options.body ?? "both";
+  const body = options.body ?? "response";
   const previewLength = positive2("--length", options.length, 128);
   const matches = [];
   await visitTraceEvents(sessionId, (record) => {
@@ -2444,6 +2471,165 @@ async function runBody(sessionId, requestId, options) {
     ...inspection
   });
 }
+async function runCurl(sessionId, requestId, options) {
+  const record = await readSafeTraceEvent(sessionId, requestId);
+  const curlOptions = curlCommandOptions(options.target);
+  const fullCommand = buildCurlCommand(record, curlOptions).command;
+  if (options.out !== void 0) {
+    await writeFile2(options.out, `#!/usr/bin/env sh
+${fullCommand}
+`, { mode: 448 });
+  }
+  if (options.copy === true) {
+    await copyToClipboard(fullCommand);
+  }
+  if (options.out === void 0 && options.copy !== true) {
+    const displayCommand = buildCurlCommand(record, { ...curlOptions, display: true });
+    process.stdout.write(`${displayCommand.command}
+`);
+    if (displayCommand.truncated) {
+      process.stderr.write("[cf-live-trace] warning: displayed curl was truncated to avoid flooding the terminal. Use --copy or --out to obtain the full command.\n");
+    }
+    return;
+  }
+  writeJson({ sessionId, requestId, copied: options.copy === true, out: options.out ?? null });
+}
+async function runReplay(sessionId, requestId, options) {
+  const record = await readSafeTraceEvent(sessionId, requestId);
+  const url = buildRequestUrl(record, options.target);
+  const body = requestBodyForFetch(record);
+  const response = await fetch(url, {
+    method: record.event.method,
+    headers: replayHeaders(record.event.requestHeaders),
+    ...body === void 0 ? {} : { body }
+  });
+  const responseBody = await response.text();
+  writeJson({
+    sessionId,
+    requestId,
+    url,
+    status: response.status,
+    statusText: response.statusText,
+    body: truncateForDisplay(responseBody, DISPLAY_RESPONSE_BODY_LIMIT).value,
+    bodyTruncatedForDisplay: responseBody.length > DISPLAY_RESPONSE_BODY_LIMIT
+  });
+}
+async function readSafeTraceEvent(sessionId, requestId) {
+  const record = await readTraceEvent(sessionId, requestId);
+  if (record.event.requestBodyTruncated) {
+    throw new Error("Request body was truncated during capture. Cannot safely replay. Please re-run the trace with a larger --max-body-bytes.");
+  }
+  return record;
+}
+function curlCommandOptions(target) {
+  return target === void 0 ? {} : { target };
+}
+function buildCurlCommand(record, options = {}) {
+  const headers = options.display === true ? displayHeaders(record.event.requestHeaders) : { values: curlHeaders(record.event.requestHeaders), truncated: false };
+  const body = options.display === true ? truncateForDisplay(record.event.requestBodyPreview, DISPLAY_BODY_LIMIT) : { value: record.event.requestBodyPreview, truncated: false };
+  const parts = ["curl", "-i", "-X", shellQuote(record.event.method), shellQuote(buildRequestUrl(record, options.target))];
+  for (const [name, value] of Object.entries(headers.values)) {
+    parts.push("-H", shellQuote(`${name}: ${value}`));
+  }
+  if (body.value.length > 0 && allowsRequestBody(record.event.method)) {
+    parts.push("--data-raw", shellQuote(body.value));
+  }
+  return { command: parts.join(" "), truncated: headers.truncated || body.truncated };
+}
+function buildRequestUrl(record, target) {
+  const rawUrl = record.event.url.length > 0 ? record.event.url : record.event.normalizedUrl;
+  if (target !== void 0) {
+    return new URL(rawUrl, ensureTrailingSlash(target)).toString();
+  }
+  if (/^[a-z][a-z0-9+.-]*:/i.test(rawUrl)) {
+    return rawUrl;
+  }
+  const headers = lowerCaseHeaders(record.event.requestHeaders);
+  const proto = firstHeaderValue(headers["x-forwarded-proto"]) ?? "http";
+  const host = firstHeaderValue(headers["x-forwarded-host"]) ?? firstHeaderValue(headers["host"]);
+  if (host === void 0 || host.trim().length === 0) {
+    throw new Error("Cannot reconstruct absolute request URL because the trace has no host or x-forwarded-host header. Use --target <baseUrl>.");
+  }
+  return `${proto}://${host}${rawUrl.startsWith("/") ? rawUrl : `/${rawUrl}`}`;
+}
+function ensureTrailingSlash(target) {
+  return target.endsWith("/") ? target : `${target}/`;
+}
+function lowerCaseHeaders(headers) {
+  const lowered = {};
+  for (const [name, value] of Object.entries(headers)) {
+    lowered[name.toLowerCase()] = value;
+  }
+  return lowered;
+}
+function displayHeaders(headers) {
+  const displayed = {};
+  let truncated = false;
+  for (const [name, value] of Object.entries(curlHeaders(headers))) {
+    const displayValue = truncateForDisplay(value, DISPLAY_HEADER_VALUE_LIMIT);
+    displayed[name] = displayValue.value;
+    truncated ||= displayValue.truncated;
+  }
+  return { values: displayed, truncated };
+}
+function curlHeaders(headers) {
+  const output = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (!REPLAY_OMITTED_HEADER_NAMES.has(name.toLowerCase())) {
+      output[name] = value;
+    }
+  }
+  return output;
+}
+function truncateForDisplay(value, limit) {
+  return value.length > limit ? { value: `${value.slice(0, limit)}${TRUNCATED_MARKER}`, truncated: true } : { value, truncated: false };
+}
+function requestBodyForFetch(record) {
+  if (!allowsRequestBody(record.event.method) || record.event.requestBodyPreview.length === 0) {
+    return void 0;
+  }
+  return record.event.requestBodyPreview;
+}
+function allowsRequestBody(method) {
+  return !["GET", "HEAD"].includes(method.toUpperCase());
+}
+function replayHeaders(headers) {
+  return curlHeaders(headers);
+}
+function firstHeaderValue(value) {
+  const first = value?.split(",")[0]?.trim();
+  return first === void 0 || first.length === 0 ? void 0 : first;
+}
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+async function copyToClipboard(text) {
+  const candidates = process.platform === "darwin" ? [["pbcopy"]] : process.platform === "win32" ? [["clip"]] : [["wl-copy"], [["x", "clip"].join(""), "-selection", "clipboard"], [["x", "sel"].join(""), "--clipboard", "--input"]];
+  const errors = [];
+  for (const candidate of candidates) {
+    try {
+      await writeToClipboardCommand(candidate, text);
+      return;
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  throw new Error(`Unable to copy to clipboard. Install a supported clipboard tool or use --out. ${errors.join(" ")}`.trim());
+}
+async function writeToClipboardCommand(command, text) {
+  const child = spawn2(command[0] ?? "", command.slice(1), { stdio: ["pipe", "ignore", "ignore"] });
+  child.stdin.end(text);
+  await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`${command.join(" ")} exited with code ${String(code)}`));
+    });
+  });
+}
 function matchesEvent(record, options, status) {
   const method = options.method?.trim().toUpperCase();
   const path = options.path?.trim().toLowerCase();
@@ -2584,18 +2770,19 @@ function writeSessionHints(traceSession, options) {
 }
 async function runUntilStopped(session, options, eventLimit, runtimeError) {
   const abort = createAbortPromise();
-  const duration = createDurationStopWaiter(options.limits.durationMs);
+  let duration;
   let stopReason = "user";
   let failed = false;
   try {
     await session.start(options.trace);
+    duration = createDurationStopWaiter(options.limits.durationMs);
     stopReason = await waitForStop([abort, eventLimit, duration, runtimeError]);
   } catch (error) {
     failed = true;
     throw error;
   } finally {
     abort.cleanup();
-    duration.cleanup();
+    duration?.cleanup();
     eventLimit.cleanup();
     runtimeError.cleanup();
     await session.stop({ uninstallRuntimeHook: options.uninstallOnExit, reason: failed ? "error" : stopReason });