fix: add edge runtime compatibility for Cloudflare Workers

Make the SDK compatible with edge runtimes (Cloudflare Workers, Vercel Edge,
Deno Deploy) by gracefully handling missing Node.js APIs:

- Lazy-load fs module for context_line extraction in exceptions.ts
- Guard process.once signal handlers in eventQueue.ts
- Lazy-load fs/os/path modules in logging.ts with console fallback
- Guard process.cwd() calls which may not exist in edge environments
- Update mcpcat-api dependency to 0.1.6

Add comprehensive test suite for edge runtime compatibility scenarios.

Author: naji247

package.json

@@ -73,7 +73,7 @@
   },
   "dependencies": {
     "@opentelemetry/otlp-transformer": "^0.203.0",
-    "mcpcat-api": "0.1.3",
+    "mcpcat-api": "0.1.6",
     "redact-pii": "3.4.0",
     "zod": "3.25.30"
   },

pnpm-lock.yaml

@@ -189,9 +189,18 @@ class EventQueue {
 }
 
 export const eventQueue = new EventQueue();
-process.once("SIGINT", () => eventQueue.destroy());
-process.once("SIGTERM", () => eventQueue.destroy());
-process.once("beforeExit", () => eventQueue.destroy());
+
+// Register graceful shutdown handlers if available (Node.js only)
+// Edge environments (Cloudflare Workers, etc.) don't have process signals
+try {
+  if (typeof process !== "undefined" && typeof process.once === "function") {
+    process.once("SIGINT", () => eventQueue.destroy());
+    process.once("SIGTERM", () => eventQueue.destroy());
+    process.once("beforeExit", () => eventQueue.destroy());
+  }
+} catch {
+  // process.once not available in this environment - graceful shutdown handlers not registered
+}
 
 export function setTelemetryManager(telemetryManager: TelemetryManager): void {
   eventQueue.setTelemetryManager(telemetryManager);

src/modules/eventQueue.ts

@@ -1,5 +1,21 @@
 import { ErrorData, StackFrame, ChainedErrorData } from "../types.js";
-import { readFileSync } from "fs";
+
+// Lazy-loaded fs module for context_line extraction (Node.js only)
+// Edge environments don't have filesystem access
+let fsModule: typeof import("fs") | null = null;
+let fsInitAttempted = false;
+
+function getFsSync(): typeof import("fs") | null {
+  if (!fsInitAttempted) {
+    fsInitAttempted = true;
+    try {
+      fsModule = require("fs");
+    } catch {
+      fsModule = null;
+    }
+  }
+  return fsModule;
+}
 
 // Maximum number of exceptions to capture in a cause chain
 const MAX_EXCEPTION_CHAIN_DEPTH = 10;
@@ -120,8 +136,14 @@ function addContextToFrame(frame: StackFrame): StackFrame {
     return frame;
   }
 
+  // Get fs module lazily - returns null in edge environments
+  const fs = getFsSync();
+  if (!fs) {
+    return frame; // File reading not available in this environment
+  }
+
   try {
-    const source = readFileSync(frame.abs_path, "utf8");
+    const source = fs.readFileSync(frame.abs_path, "utf8");
     const lines = source.split("\n");
     const lineIndex = frame.lineno - 1; // Convert to 0-based index
 
@@ -635,9 +657,18 @@ function makeRelativePath(filename: string): string {
   // Step 7: Strip deployment-specific paths
   result = stripDeploymentPaths(result);
 
-  // Step 8: Strip current working directory
-  const cwd = process.cwd();
-  if (result.startsWith(cwd)) {
+  // Step 8: Strip current working directory (if available)
+  // process.cwd() may not be available in edge environments
+  let cwd: string | null = null;
+  try {
+    if (typeof process !== "undefined" && typeof process.cwd === "function") {
+      cwd = process.cwd();
+    }
+  } catch {
+    // process.cwd() not available in this environment
+  }
+
+  if (cwd && result.startsWith(cwd)) {
     result = result.substring(cwd.length + 1); // +1 to remove leading /
   }
 

src/modules/exceptions.ts

@@ -1,33 +1,63 @@
-import { writeFileSync, appendFileSync, existsSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
-
-// Safely determine log file path, handling environments where homedir() may return null
-let LOG_FILE: string | null = null;
-try {
-  const home = homedir();
-  if (home && home !== null && home !== undefined) {
-    LOG_FILE = join(home, "mcpcat.log");
+// Lazy-loaded module references for Node.js file logging
+// These are loaded dynamically to support edge environments (Cloudflare Workers, etc.)
+let fsModule: typeof import("fs") | null = null;
+let logFilePath: string | null = null;
+let initAttempted = false;
+let useConsoleFallback = false;
+
+/**
+ * Attempts to initialize Node.js file logging.
+ * Falls back to console.log in edge environments where fs/os modules are unavailable.
+ */
+function tryInitSync(): void {
+  if (initAttempted) return;
+  initAttempted = true;
+
+  try {
+    // Use dynamic require for sync initialization
+    // Works in Node.js, fails gracefully in Workers/edge environments
+    const fs = require("fs");
+    const os = require("os");
+    const path = require("path");
+
+    const home = os.homedir?.();
+    if (home) {
+      fsModule = fs;
+      logFilePath = path.join(home, "mcpcat.log");
+    } else {
+      // homedir() returned null/undefined - use console fallback
+      useConsoleFallback = true;
+    }
+  } catch {
+    // Module not available or homedir() not implemented - use console fallback
+    useConsoleFallback = true;
+    fsModule = null;
+    logFilePath = null;
   }
-} catch {
-  // If homedir() or join() fails, LOG_FILE remains null
-  LOG_FILE = null;
 }
 
 export function writeToLog(message: string): void {
-  // Skip logging if we don't have a valid log file path
-  if (!LOG_FILE) {
+  tryInitSync();
+
+  const timestamp = new Date().toISOString();
+  const logEntry = `[${timestamp}] ${message}`;
+
+  // Edge environment: use console.log as fallback
+  if (useConsoleFallback) {
+    console.log(`[mcpcat] ${logEntry}`);
     return;
   }
 
-  const timestamp = new Date().toISOString();
-  const logEntry = `[${timestamp}] ${message}\n`;
+  // Node.js environment: write to file
+  if (!logFilePath || !fsModule) {
+    return;
+  }
 
   try {
-    if (!existsSync(LOG_FILE)) {
-      writeFileSync(LOG_FILE, logEntry);
+    if (!fsModule.existsSync(logFilePath)) {
+      fsModule.writeFileSync(logFilePath, logEntry + "\n");
     } else {
-      appendFileSync(LOG_FILE, logEntry);
+      fsModule.appendFileSync(logFilePath, logEntry + "\n");
     }
   } catch {
     // Silently fail to avoid breaking the server