@fenwave/agent 1.1.0

package/index.js

@@ -0,0 +1,988 @@
+#!/usr/bin/env node
+
+import http from "http";
+import fs from "fs";
+import os from "os";
+import axios from "axios";
+import chalk from "chalk";
+import path from "path";
+import { program } from "commander";
+import { v4 as uuidv4 } from "uuid";
+import { fileURLToPath } from "url";
+import { dirname } from "path";
+import dotenv from "dotenv";
+
+// ES module helpers
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Ensure environment files exist
+import { ensureEnvironmentFiles } from "./utils/envSetup.js";
+const agentEnvPath = ensureEnvironmentFiles(__dirname);
+
+// Load environment variables from .env.agent
+dotenv.config({ path: agentEnvPath });
+
+// Load environment variables
+dotenv.config();
+
+// Import ES modules
+import { setupWebSocketServer, readWsToken } from "./websocket-server.js";
+import { setupCLICommands } from "./cli-commands.js";
+import containerManager from "./containerManager.js";
+import registryStore from "./store/registryStore.js";
+import agentStore from "./store/agentStore.js";
+import { loadConfig } from "./store/configStore.js";
+import { initializeAgentStartTime } from "./docker-actions/general.js";
+import { checkAppHasBeenRun } from "./docker-actions/apps.js";
+import {
+  loadSession,
+  isSessionValid,
+  handleSessionExpiry,
+  createSession,
+  saveSession,
+  clearSession,
+  setupSessionWatcher,
+  loadBackendUrl,
+} from "./auth.js";
+
+// Version from package.json
+const packageJson = JSON.parse(
+  fs.readFileSync(new URL("./package.json", import.meta.url), "utf8")
+);
+const { version } = packageJson;
+
+// Store active connections
+const clients = new Map();
+
+// Load configuration from config file (saved during fenwave init) or fall back to env variables/defaults
+const config = loadConfig();
+const BACKEND_URL = config.backendUrl;
+const FRONTEND_URL = config.frontendUrl;
+const AUTH_TIMEOUT_MS = config.authTimeoutMs;
+const WS_PORT = config.wsPort;
+const CONTAINER_PORT = config.containerPort;
+
+/**
+ * Acknowledge a version_published event after it has been displayed
+ */
+async function acknowledgeVersionPublishedEvent(
+  sessionToken,
+  eventId,
+  changeId
+) {
+  try {
+    await axios.post(
+      `${BACKEND_URL}/api/agent-cli/acknowledge-event`,
+      {
+        token: sessionToken,
+        eventId: eventId,
+        changeId: changeId,
+      },
+      {
+        headers: {
+          "Content-Type": "application/json",
+        },
+        timeout: 5000,
+      }
+    );
+  } catch (error) {
+    console.log(
+      chalk.yellow(
+        `⚠️  Failed to acknowledge event ${changeId}: ${error.message}`
+      )
+    );
+  }
+}
+
+/**
+ * Poll for app update events and broadcast to connected clients
+ */
+async function pollAppUpdates(sessionToken, wss) {
+  try {
+    const response = await axios.post(
+      `${BACKEND_URL}/api/agent-cli/poll-events`,
+      {
+        token: sessionToken,
+      },
+      {
+        headers: {
+          "Content-Type": "application/json",
+        },
+        timeout: 10000,
+      }
+    );
+
+    if (
+      response.data &&
+      response.data.events &&
+      response.data.events.length > 0
+    ) {
+      const events = response.data.events;
+
+      // Filter and process events
+      let broadcastedCount = 0;
+
+      for (const event of events) {
+        const eventType = event.event_type || "blueprint_changed";
+
+        // For blueprint_changed events, check if the app has ever been run locally
+        // If not, skip broadcasting (app modifications before first run are part of initial setup)
+        if (eventType === "blueprint_changed") {
+          const hasBeenRun = await checkAppHasBeenRun(event.app_name);
+
+          if (!hasBeenRun) {
+            acknowledgeVersionPublishedEvent(
+              sessionToken,
+              event.id,
+              event.change_id
+            );
+            continue;
+          }
+        }
+
+        broadcastedCount++;
+
+        const message = JSON.stringify({
+          type: eventType,
+          appId: event.app_id,
+          backstageId: event.app_id,
+          appName: event.app_name,
+          version: event.version,
+          changeId: event.change_id,
+          timestamp: event.created_at,
+          actor: event.actor,
+          changedAt: event.created_at,
+        });
+
+        wss.clients.forEach((client) => {
+          if (client.readyState === 1) {
+            // WebSocket.OPEN
+            client.send(message);
+          }
+        });
+
+        // Auto-acknowledge version_published events after broadcasting
+        // (these are just notifications, not sync requests)
+        if (eventType === "version_published") {
+          setTimeout(() => {
+            acknowledgeVersionPublishedEvent(
+              sessionToken,
+              event.id,
+              event.change_id
+            );
+          }, 2000); // 2 second delay to ensure devapp receives it
+        }
+      }
+
+      if (broadcastedCount > 0) {
+        console.log(
+          chalk.blue(
+            `📢 Received ${broadcastedCount} app update ${
+              broadcastedCount === 1 ? "event" : "events"
+            }`
+          )
+        );
+      }
+    }
+  } catch (error) {
+    // Silently handle polling errors
+    if (error.response?.status !== 401) {
+      const isConnRefused =
+        (error.message && error.message.includes("ECONNREFUSED")) ||
+        error.code === "ECONNREFUSED";
+
+      if (isConnRefused) {
+        console.error(
+          chalk.red(
+            "❌ App update polling error: Please ensure backstage is running."
+          )
+        );
+      } else {
+        console.error(
+          chalk.red(`❌ App update polling error: ${error.message}`)
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Start periodic polling for app updates
+ */
+function startAppUpdatePolling(sessionToken, wss) {
+  // Poll every 30 seconds
+  const pollInterval = setInterval(() => {
+    pollAppUpdates(sessionToken, wss);
+  }, 30000);
+
+  console.log(
+    chalk.blue("🔄 Started polling for app updates (every 30 seconds)")
+  );
+
+  return pollInterval;
+}
+
+// Store server instances for graceful shutdown
+let serverInstances = null;
+
+// Graceful shutdown handler
+function gracefulShutdown() {
+  console.log(chalk.red("\n🔒 Fenwave Agent shutting down gracefully..."));
+
+  if (serverInstances) {
+    // Clear polling interval
+    if (serverInstances.pollInterval) {
+      clearInterval(serverInstances.pollInterval);
+    }
+
+    // Close session watcher
+    if (serverInstances.sessionWatcher) {
+      serverInstances.sessionWatcher.close();
+    }
+
+    // Close WebSocket connections
+    if (serverInstances.wss) {
+      serverInstances.wss.clients.forEach((client) => {
+        client.send(
+          JSON.stringify({
+            type: "agent_shutdown",
+            message: "Agent is shutting down",
+          })
+        );
+        client.close();
+      });
+      serverInstances.wss.close();
+    }
+
+    // Close HTTP server
+    if (serverInstances.server) {
+      serverInstances.server.close();
+    }
+  }
+
+  // Clear agent info from persistent storage
+  agentStore.clearAgentInfo().catch((err) => {
+    console.error("Failed to clear agent info:", err);
+  });
+
+  // Stop container
+  containerManager
+    .stopContainerGracefully()
+    .catch((error) => console.error("Error stopping container:", error.message))
+    .finally(() => process.exit(0));
+  process.exit(0);
+}
+
+// Handle graceful shutdown signals
+process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+
+// Start the WebSocket server
+async function startServer(port = WS_PORT) {
+  return new Promise(async (resolve, reject) => {
+    try {
+      // Check for existing session first and validate it
+      console.log(chalk.blue("🔍 Checking for existing session..."));
+      const existingSession = loadSession();
+      if (existingSession) {
+        if (isSessionValid(existingSession)) {
+          console.log(
+            chalk.green("✅ Found valid session, using existing credentials")
+          );
+
+          // Initialize registry store
+          await registryStore.initialize();
+
+          // Start local-env container
+          console.log(chalk.blue("🐳 Starting container..."));
+          try {
+            await containerManager.startContainer();
+            console.log(chalk.cyan("✅ Container started successfully"));
+          } catch (containerError) {
+            console.warn(
+              chalk.yellow("⚠️ Failed to start container:"),
+              containerError.message
+            );
+            console.log(chalk.blue("📡 Starting agent without container..."));
+          }
+
+          // Start WebSocket server with existing session
+          const agentId = uuidv4();
+
+          // Try to read existing WebSocket token
+          const existingWsToken = readWsToken();
+
+          const server = http.createServer();
+
+          server.listen(port, async () => {
+            // Initialize agent start time
+            await initializeAgentStartTime();
+            console.log(chalk.blue("📡 Agent is ready to receive connections"));
+
+            // Display connection information
+            console.log(
+              chalk.green(
+                "\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+              )
+            );
+            console.log(chalk.green("✅ Fenwave Agent Started Successfully"));
+            console.log(
+              chalk.green(
+                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"
+              )
+            );
+            console.log(chalk.white("🌐 Fenwave DevApp Dashboard:"));
+            console.log(chalk.cyan(`   http://localhost:${CONTAINER_PORT}\n`));
+            console.log(chalk.white("🔌 WebSocket Server:"));
+            console.log(chalk.cyan(`   ws://localhost:${port}\n`));
+            console.log(chalk.white("👤 User:"));
+            console.log(chalk.cyan(`   ${existingSession.userEntityRef}\n`));
+            console.log(
+              chalk.green(
+                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"
+              )
+            );
+
+            try {
+              const wss = setupWebSocketServer(
+                server,
+                clients,
+                agentId,
+                {
+                  userEntityRef: existingSession.userEntityRef,
+                  expiresAt: existingSession.expiresAt,
+                },
+                existingWsToken
+              ); // Pass the existing token to reuse it
+
+              // Set up file watcher for session monitoring
+              const sessionWatcher = setupSessionWatcher(
+                handleSessionExpiry,
+                server,
+                wss
+              );
+
+              // Start app update polling
+              const pollInterval = startAppUpdatePolling(
+                existingSession.token,
+                wss
+              );
+
+              resolve({
+                server,
+                wss,
+                sessionToken: existingSession.token,
+                userEntityRef: existingSession.userEntityRef,
+                agentId,
+                sessionWatcher,
+                pollInterval,
+              });
+            } catch (error) {
+              console.error(
+                chalk.red("❌ Failed to setup WebSocket server:"),
+                error.message
+              );
+              reject(error);
+            }
+          });
+
+          return;
+        } else {
+          // Session expired, clear it immediately
+          clearSession();
+        }
+      } else {
+        console.log(
+          chalk.blue(
+            "🔑 No existing session found, proceeding with new authentication"
+          )
+        );
+      }
+
+      // Pre-check: Test Backstage connectivity before opening browser
+      try {
+        await axios.get(`${BACKEND_URL}`, {
+          timeout: 5000,
+          validateStatus: () => true, // Accept any HTTP status code (404, 401, etc. - they all mean server is up)
+        });
+      } catch (connectivityError) {
+        console.error(chalk.red("❌ Cannot connect to Backstage backend"));
+        console.log(
+          chalk.yellow(
+            "💡 Please ensure Backstage is running and you are properly authenticated, then try again."
+          )
+        );
+        return reject(new Error("Backstage backend not available"));
+      }
+
+      console.log(
+        chalk.blue("🌐 Redirecting to the browser for authentication...")
+      );
+
+      // Set up authentication timeout (1 minute)
+      const authTimeout = setTimeout(() => {
+        console.log(chalk.red("❌ Authorization timed out"));
+        console.log(
+          chalk.yellow(
+            "💡 Please ensure Backstage is running and you are properly authenticated, then try again."
+          )
+        );
+        process.exit(1);
+      }, AUTH_TIMEOUT_MS);
+
+      // Step 1: Start a local HTTP server to handle the loopback redirect on port 3005
+      const loopbackServer = http.createServer(async (req, res) => {
+        const url = new URL(req.url, `http://${req.headers.host}`);
+        if (url.pathname === "/verify-auth") {
+          if (req.method === "POST") {
+            // Handle POST request with JSON body
+            let body = "";
+            req.on("data", (chunk) => {
+              body += chunk.toString();
+            });
+
+            req.on("end", async () => {
+              try {
+                const { jwt, entityRef } = JSON.parse(body);
+
+                if (!jwt || !entityRef) {
+                  res.writeHead(400, { "Content-Type": "application/json" });
+                  res.end(
+                    JSON.stringify({
+                      error: "Authentication failed. Missing JWT or user info.",
+                    })
+                  );
+                  setTimeout(() => {
+                    loopbackServer.close();
+                    clearTimeout(authTimeout);
+                  }, 2000);
+                  return reject(new Error("Authentication failed."));
+                }
+
+                // Clear the authentication timeout since we got a successful response
+                clearTimeout(authTimeout);
+                console.log(chalk.green("✅ Authentication successful!"));
+
+                try {
+                  // Step 2: Create session with Backstage backend
+                  console.log(
+                    chalk.blue("🔑 Creating session with Backstage backend...")
+                  );
+                  const sessionData = await createSession(jwt, BACKEND_URL);
+
+                  // Step 3: Save session locally
+                  saveSession(
+                    sessionData.token,
+                    sessionData.expiresAt,
+                    entityRef
+                  );
+
+                  // Initialize registry store
+                  await registryStore.initialize();
+
+                  // Start local-env container
+                  console.log(chalk.cyan("🐳 Starting container..."));
+                  try {
+                    await containerManager.startContainer();
+                    console.log(
+                      chalk.cyan("✅ Container started successfully")
+                    );
+                  } catch (containerError) {
+                    console.warn(
+                      chalk.yellow("⚠️ Failed to start container:"),
+                      containerError.message
+                    );
+                    console.log(
+                      chalk.blue("📡 Starting agent without container...")
+                    );
+                  }
+
+                  // Generate WebSocket token NOW (before sending response)
+                  // Import crypto to generate token
+                  const crypto = await import("crypto");
+                  const wsToken = crypto.randomBytes(32).toString("hex");
+
+                  // Save token to file for later use
+                  const wsTokenPath = path.join(
+                    os.homedir(),
+                    process.env.AGENT_ROOT_DIR || ".fenwave",
+                    "ws-token"
+                  );
+                  try {
+                    fs.writeFileSync(wsTokenPath, wsToken, { mode: 0o600 });
+                  } catch (error) {
+                    console.warn("⚠️ Could not save ws-token:", error.message);
+                  }
+
+                  // Send success response with WebSocket token
+                  res.writeHead(200, {
+                    "Content-Type": "application/json",
+                    "Access-Control-Allow-Origin": "*",
+                    "Access-Control-Allow-Methods": "POST, OPTIONS",
+                    "Access-Control-Allow-Headers": "Content-Type",
+                  });
+                  res.end(
+                    JSON.stringify({
+                      message: "Authentication successful",
+                      wsToken: wsToken,
+                      wsPort: port,
+                      containerPort: CONTAINER_PORT,
+                    })
+                  );
+
+                  // Close the loopback server after a short delay to allow the success page redirect
+                  setTimeout(() => {
+                    loopbackServer.close();
+                  }, 2000);
+
+                  // Step 4: Start WebSocket server on the requested port
+                  const agentId = uuidv4();
+                  const wsServer = http.createServer();
+
+                  wsServer.listen(port, async () => {
+                    // Initialize agent start time
+                    await initializeAgentStartTime();
+
+                    console.log(
+                      chalk.blue("📡 Agent is ready to receive connections")
+                    );
+
+                    // Display connection information
+                    console.log(
+                      chalk.green(
+                        "\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+                      )
+                    );
+                    console.log(
+                      chalk.green("✅ Fenwave Agent Started Successfully")
+                    );
+                    console.log(
+                      chalk.green(
+                        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"
+                      )
+                    );
+                    console.log(chalk.white("🌐 Fenwave DevApp Dashboard:"));
+                    console.log(
+                      chalk.cyan(`   http://localhost:${CONTAINER_PORT}\n`)
+                    );
+                    console.log(chalk.white("🔌 WebSocket Server:"));
+                    console.log(chalk.cyan(`   ws://localhost:${port}\n`));
+                    console.log(chalk.white("👤 User:"));
+                    console.log(chalk.cyan(`   ${entityRef}\n`));
+                    console.log(
+                      chalk.green(
+                        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"
+                      )
+                    );
+
+                    try {
+                      const wss = setupWebSocketServer(
+                        wsServer,
+                        clients,
+                        agentId,
+                        {
+                          userEntityRef: entityRef,
+                          expiresAt: sessionData.expiresAt,
+                        },
+                        wsToken // Pass the token we generated earlier
+                      );
+
+                      // Set up file watcher for session monitoring
+                      const sessionWatcher = setupSessionWatcher(
+                        handleSessionExpiry,
+                        wsServer,
+                        wss
+                      );
+
+                      // Start app update polling
+                      startAppUpdatePolling(sessionData.token, wss);
+                      resolve({
+                        server: wsServer,
+                        wss,
+                        sessionToken: sessionData.token,
+                        userEntityRef: entityRef,
+                        agentId,
+                        sessionWatcher,
+                      });
+                    } catch (error) {
+                      console.error(
+                        chalk.red("❌ Failed to setup WebSocket server:"),
+                        error.message
+                      );
+                      reject(error);
+                    }
+                  });
+                } catch (sessionError) {
+                  res.writeHead(500, { "Content-Type": "application/json" });
+                  res.end(
+                    JSON.stringify({
+                      error: "Failed to create session with Backstage backend.",
+                    })
+                  );
+                  setTimeout(() => {
+                    loopbackServer.close();
+                    clearTimeout(authTimeout);
+                  }, 2000);
+                  reject(sessionError);
+                }
+              } catch (parseError) {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(
+                  JSON.stringify({ error: "Invalid JSON in request body." })
+                );
+                setTimeout(() => {
+                  loopbackServer.close();
+                  clearTimeout(authTimeout);
+                }, 2000);
+                reject(parseError);
+              }
+            });
+          } else if (req.method === "OPTIONS") {
+            // Handle CORS preflight request
+            res.writeHead(200, {
+              "Access-Control-Allow-Origin": "*",
+              "Access-Control-Allow-Methods": "POST, OPTIONS",
+              "Access-Control-Allow-Headers": "Content-Type",
+            });
+            res.end();
+          } else {
+            res.writeHead(405, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Method not allowed. Use POST." }));
+          }
+        } else if (url.pathname === "/auth-success") {
+          // Serve the authentication success page
+          const filePath = path.join(process.cwd(), "index.html");
+          fs.readFile(filePath, (err, data) => {
+            if (err) {
+              console.error("Failed to read HTML file:", err);
+              res.writeHead(500, { "Content-Type": "text/plain" });
+              res.end("Internal Server Error");
+              return;
+            }
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(data);
+          });
+        } else {
+          res.writeHead(404, { "Content-Type": "text/plain" });
+          res.end("Not Found");
+        }
+      });
+
+      // Use port 3005 for loopback to avoid conflict with WebSocket server
+      loopbackServer.listen(3005, async () => {
+        const open = (await import("open")).default;
+        // Open the Backstage frontend in the default browser
+        const authUrl = `${FRONTEND_URL}/agent-cli`;
+        open(authUrl);
+      });
+    } catch (error) {
+      console.error(chalk.red("Failed to start server:"), error);
+      reject(error);
+    }
+  });
+}
+
+// Initialize the CLI
+program
+  .name("fenwave")
+  .description("Fenwave - Developer Platform CLI")
+  .version(version);
+
+// Setup CLI commands
+setupCLICommands(program, startServer);
+
+// Custom unknown command handler
+program.on("command:*", ([cmd]) => {
+  console.error(`error: unknown command '${cmd}'`);
+
+  const available = program.commands.map((c) => c.name());
+
+  // First, try prefix matches
+  let matches = available.filter((c) => c.startsWith(cmd));
+
+  // If no prefix matches, try bidirectional substring matches
+  if (matches.length === 0) {
+    matches = available.filter((c) => cmd.includes(c) || c.includes(cmd));
+  }
+
+  if (matches.length > 0) {
+    if (matches.length === 1) {
+      console.error(`(Did you mean '${matches[0]}'?)`);
+    } else {
+      console.error(`(Did you mean one of ${matches.join(", ")}?)`);
+    }
+  }
+
+  process.exit(1);
+});
+
+// Pre-process arguments to handle incomplete options before Commander.js
+function preprocessArguments() {
+  const args = process.argv.slice(2);
+
+  if (args.length >= 2) {
+    const commandName = args[0];
+    const lastArg = args[args.length - 1];
+
+    // Check if user typed incomplete option (just - or --)
+    if (lastArg === "-" || lastArg === "--") {
+      // Find the command
+      const command = program.commands.find(
+        (cmd) =>
+          cmd.name() === commandName || cmd.aliases().includes(commandName)
+      );
+
+      if (command) {
+        console.error(`error: unknown option '${lastArg}'`);
+
+        // Get all options for this command
+        const options = command.options || [];
+        const availableOptions = [];
+
+        // Add command-specific options
+        options.forEach((option) => {
+          if (option.short) availableOptions.push(option.short);
+          if (option.long) availableOptions.push(option.long);
+        });
+
+        // Always add help option
+        if (!availableOptions.includes("-h")) availableOptions.push("-h");
+        if (!availableOptions.includes("--help"))
+          availableOptions.push("--help");
+
+        let suggestions = [];
+
+        if (lastArg === "--") {
+          // User typed just '--', suggest all long options
+          suggestions = availableOptions.filter((opt) => opt.startsWith("--"));
+        } else if (lastArg === "-") {
+          // User typed just '-', suggest all short options with their long equivalents
+          const shortOpts = availableOptions.filter(
+            (opt) => opt.startsWith("-") && !opt.startsWith("--")
+          );
+          const longOpts = availableOptions.filter((opt) =>
+            opt.startsWith("--")
+          );
+
+          // Pair short and long options
+          suggestions = shortOpts.map((shortOpt) => {
+            const longEquivalent = longOpts.find(
+              (longOpt) =>
+                longOpt.substring(2) === shortOpt.substring(1) ||
+                (shortOpt === "-h" && longOpt === "--help") ||
+                (shortOpt === "-a" && longOpt === "--all") ||
+                (shortOpt === "-f" &&
+                  (longOpt === "--force" || longOpt === "--follow")) ||
+                (shortOpt === "-d" && longOpt === "--driver") ||
+                (shortOpt === "-p" && longOpt === "--port") ||
+                (shortOpt === "-t" && longOpt === "--tail")
+            );
+            return longEquivalent ? `${shortOpt}, ${longEquivalent}` : shortOpt;
+          });
+        }
+
+        if (suggestions.length > 0) {
+          const formattedSuggestions = suggestions.map((suggestion) => {
+            // Add argument placeholder for options that require arguments
+            let displaySuggestion = suggestion;
+
+            // Find the matching option object to check if it requires an argument
+            const option = options.find(
+              (opt) =>
+                opt.long === suggestion ||
+                opt.short === suggestion ||
+                (suggestion.includes(opt.long) && opt.long) ||
+                (suggestion.includes(opt.short) && opt.short)
+            );
+
+            if (option && option.required) {
+              // Use a more descriptive argument name based on the option's own description
+              let argName = "<value>";
+              if (option.argChoices) {
+                argName = `<${option.argChoices.join("|")}>`;
+              } else if (option.long) {
+                // Map common option names to better argument descriptions
+                const optName = option.long.replace("--", "");
+                const argNameMap = {
+                  tail: "lines",
+                  port: "port",
+                  driver: "driver",
+                  "backend-url": "url",
+                  "frontend-url": "url",
+                  token: "token",
+                  "aws-region": "region",
+                  "aws-account-id": "id",
+                };
+                argName = `<${argNameMap[optName] || optName}>`;
+              }
+              displaySuggestion = `${suggestion} ${argName}`;
+            }
+
+            return `'${displaySuggestion}'`;
+          });
+
+          console.error(`(Did you mean ${formattedSuggestions.join(", ")}?)`);
+        }
+
+        process.exit(1);
+      }
+    }
+  }
+}
+
+// Run preprocessing before parsing
+preprocessArguments();
+
+// Handle unknown options
+program.exitOverride((err) => {
+  if (err.code === "commander.unknownOption") {
+    const args = process.argv.slice(2);
+    const commandName = args[0];
+    const invalidOption = err.message.match(/unknown option '([^']+)'/)?.[1];
+
+    if (invalidOption) {
+      // Find the command
+      const command = program.commands.find(
+        (cmd) =>
+          cmd.name() === commandName || cmd.aliases().includes(commandName)
+      );
+
+      if (command) {
+        console.error(`error: unknown option '${invalidOption}'`);
+
+        // Get all options for this command
+        const options = command.options || [];
+        const availableOptions = [];
+
+        // Add command-specific options
+        options.forEach((option) => {
+          if (option.short) availableOptions.push(option.short);
+          if (option.long) availableOptions.push(option.long);
+        });
+
+        // Always add help option
+        if (!availableOptions.includes("-h")) availableOptions.push("-h");
+        if (!availableOptions.includes("--help"))
+          availableOptions.push("--help");
+
+        // Find suggestions for partial/incorrect options
+        const suggestions = availableOptions.filter(
+          (opt) =>
+            opt.startsWith(invalidOption) ||
+            opt.includes(invalidOption.replace(/^-+/, "")) ||
+            invalidOption.includes(opt.replace(/^-+/, ""))
+        );
+
+        if (suggestions.length > 0) {
+          // Group short and long options together
+          const pairedSuggestions = [];
+          const processed = new Set();
+
+          suggestions.forEach((suggestion) => {
+            if (processed.has(suggestion)) return;
+
+            const option = options.find(
+              (opt) => opt.long === suggestion || opt.short === suggestion
+            );
+
+            if (option) {
+              let displaySuggestion = "";
+
+              // Check if both short and long forms are in suggestions
+              const hasShort =
+                option.short && suggestions.includes(option.short);
+              const hasLong = option.long && suggestions.includes(option.long);
+
+              if (hasShort && hasLong) {
+                displaySuggestion = `${option.short}, ${option.long}`;
+                processed.add(option.short);
+                processed.add(option.long);
+              } else if (hasShort) {
+                // If only short form matched, still pair it with long form if available
+                displaySuggestion = option.long
+                  ? `${option.short}, ${option.long}`
+                  : option.short;
+                processed.add(option.short);
+                if (option.long) processed.add(option.long);
+              } else if (hasLong) {
+                // If only long form matched, still pair it with short form if available
+                displaySuggestion = option.short
+                  ? `${option.short}, ${option.long}`
+                  : option.long;
+                if (option.short) processed.add(option.short);
+                processed.add(option.long);
+              }
+
+              // Add argument placeholder for options that require arguments
+              if (option.required) {
+                let argName = "<value>";
+                if (option.argChoices) {
+                  argName = `<${option.argChoices.join("|")}>`;
+                } else if (option.long) {
+                  const optName = option.long.replace("--", "");
+                  const argNameMap = {
+                    tail: "lines",
+                    port: "port",
+                    driver: "driver",
+                    "backend-url": "url",
+                    "frontend-url": "url",
+                    token: "token",
+                    "aws-region": "region",
+                    "aws-account-id": "id",
+                  };
+                  argName = `<${argNameMap[optName] || optName}>`;
+                }
+                displaySuggestion = `${displaySuggestion} ${argName}`;
+              }
+
+              pairedSuggestions.push(`'${displaySuggestion}'`);
+            } else {
+              // Fallback for options without Option object (like help)
+              processed.add(suggestion);
+
+              // Pair -h with --help
+              if (suggestion === "-h" && suggestions.includes("--help")) {
+                pairedSuggestions.push(`'${suggestion}, --help'`);
+                processed.add("--help");
+              } else if (
+                suggestion === "--help" &&
+                suggestions.includes("-h")
+              ) {
+                // Skip, already handled
+              } else {
+                pairedSuggestions.push(`'${suggestion}'`);
+              }
+            }
+          });
+
+          console.error(`(Did you mean ${pairedSuggestions.join(", ")}?)`);
+        }
+      }
+    }
+
+    process.exit(1);
+  }
+
+  // For other errors (like help), exit normally with the error's exit code
+  process.exit(err.exitCode || 1);
+});
+
+// Parse command line arguments
+program.parse(process.argv);
+
+// If no arguments, show help
+if (process.argv.length === 2) {
+  program.help();
+}
+
+// Process error handling
+process.on("uncaughtException", (error) => {
+  console.error("Uncaught exception:", error);
+});
+
+process.on("unhandledRejection", (reason, promise) => {
+  console.error("Unhandled rejection at:", promise, "reason:", reason);
+});
+
+export { startServer, clients };