vibe-pal 0.42.0

package/bin/viba.mjs

@@ -0,0 +1,489 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "../src/lib/cli-args.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const APP_ROOT = path.resolve(__dirname, "..");
+const require = createRequire(import.meta.url);
+const DEFAULT_PORT = 3200;
+const CODEX_SKILL_TARGET_AGENTS = ["codex", "cursor", "gemini-cli"];
+const CODEX_SKILL_DEFINITIONS = [
+  {
+    name: "agent-browser",
+    sourceUrl: "https://skills.sh/vercel-labs/agent-browser/agent-browser",
+    repoUrl: "https://github.com/vercel-labs/agent-browser",
+  },
+  {
+    name: "systematic-debugging",
+    sourceUrl: "https://github.com/obra/superpowers",
+    repoUrl: "https://github.com/obra/superpowers",
+  },
+];
+
+function getNextBin() {
+  return require.resolve("next/dist/bin/next");
+}
+
+function isCommandAvailable(command) {
+  const probe = process.platform === "win32" ? "where" : "which";
+  const result = spawnSync(probe, [command], {
+    stdio: "ignore",
+    env: process.env,
+  });
+  return result.status === 0;
+}
+
+function runCommand(command, args) {
+  const result = spawnSync(command, args, {
+    cwd: APP_ROOT,
+    env: process.env,
+    stdio: "inherit",
+  });
+  return result.status === 0;
+}
+
+export function getBrowserOpenCommand(url, platform = process.platform) {
+  if (platform === "darwin") {
+    return {
+      command: "open",
+      args: [url],
+    };
+  }
+
+  if (platform === "win32") {
+    return {
+      command: "cmd",
+      args: ["/c", "start", "", url],
+    };
+  }
+
+  if (platform === "linux") {
+    return {
+      command: "xdg-open",
+      args: [url],
+    };
+  }
+
+  return null;
+}
+
+export function shouldAutoOpenBrowser(env = process.env, mode = "start") {
+  if (mode === "dev") {
+    return false;
+  }
+
+  const browserSetting = env.BROWSER?.trim().toLowerCase();
+  if (browserSetting === "none" || browserSetting === "false" || browserSetting === "0") {
+    return false;
+  }
+  return true;
+}
+
+export function getInstallStrategies(packageName) {
+  if (process.platform === "darwin") {
+    return [
+      {
+        label: "Homebrew",
+        requiredCommands: ["brew"],
+        command: "brew",
+        args: ["install", packageName],
+      },
+      {
+        label: "MacPorts",
+        requiredCommands: ["sudo", "port"],
+        command: "sudo",
+        args: ["port", "install", packageName],
+      },
+    ];
+  }
+
+  if (process.platform === "linux") {
+    return [
+      {
+        label: "apt-get",
+        requiredCommands: ["apt-get"],
+        command: "apt-get",
+        args: ["install", "-y", packageName],
+      },
+      {
+        label: "sudo apt-get",
+        requiredCommands: ["sudo", "apt-get"],
+        command: "sudo",
+        args: ["apt-get", "install", "-y", packageName],
+      },
+      {
+        label: "dnf",
+        requiredCommands: ["dnf"],
+        command: "dnf",
+        args: ["install", "-y", packageName],
+      },
+      {
+        label: "sudo dnf",
+        requiredCommands: ["sudo", "dnf"],
+        command: "sudo",
+        args: ["dnf", "install", "-y", packageName],
+      },
+      {
+        label: "yum",
+        requiredCommands: ["yum"],
+        command: "yum",
+        args: ["install", "-y", packageName],
+      },
+      {
+        label: "sudo yum",
+        requiredCommands: ["sudo", "yum"],
+        command: "sudo",
+        args: ["yum", "install", "-y", packageName],
+      },
+      {
+        label: "pacman",
+        requiredCommands: ["pacman"],
+        command: "pacman",
+        args: ["-S", "--noconfirm", packageName],
+      },
+      {
+        label: "sudo pacman",
+        requiredCommands: ["sudo", "pacman"],
+        command: "sudo",
+        args: ["pacman", "-S", "--noconfirm", packageName],
+      },
+      {
+        label: "zypper",
+        requiredCommands: ["zypper"],
+        command: "zypper",
+        args: ["--non-interactive", "install", packageName],
+      },
+      {
+        label: "sudo zypper",
+        requiredCommands: ["sudo", "zypper"],
+        command: "sudo",
+        args: ["zypper", "--non-interactive", "install", packageName],
+      },
+    ];
+  }
+
+  if (process.platform === "win32") {
+    if (packageName !== "ttyd") {
+      return [];
+    }
+
+    return [
+      {
+        label: "winget",
+        requiredCommands: ["winget"],
+        command: "winget",
+        args: ["install", "tsl0922.ttyd"],
+      },
+      {
+        label: "scoop",
+        requiredCommands: ["scoop"],
+        command: "scoop",
+        args: ["install", "ttyd"],
+      },
+    ];
+  }
+
+  return [];
+}
+
+function ensureCommandInstalled(commandName) {
+  if (isCommandAvailable(commandName)) {
+    return;
+  }
+
+  console.log(`${commandName} is not installed. Attempting automatic installation...`);
+
+  const installStrategies = getInstallStrategies(commandName);
+  const availableManagers = installStrategies
+    .map((strategy) => strategy.label)
+    .join(", ");
+
+  let attempted = false;
+
+  for (const strategy of installStrategies) {
+    const canUseStrategy = strategy.requiredCommands.every((command) => isCommandAvailable(command));
+    if (!canUseStrategy) {
+      continue;
+    }
+
+    attempted = true;
+    console.log(`Trying to install ${commandName} via ${strategy.label}...`);
+
+    if (runCommand(strategy.command, strategy.args) && isCommandAvailable(commandName)) {
+      console.log(`${commandName} installed successfully.`);
+      return;
+    }
+  }
+
+  if (!attempted) {
+    throw new Error(
+      `${commandName} is required, but no supported package manager was found on this machine. Checked: ${availableManagers || "none"}. Install ${commandName} manually and restart.`,
+    );
+  }
+
+  throw new Error(`${commandName} is required, but automatic installation failed. Install ${commandName} manually and restart.`);
+}
+
+function getCodexSkillsDirectory() {
+  const codexHome = process.env.CODEX_HOME?.trim() || path.join(os.homedir(), ".codex");
+  return path.join(codexHome, "skills");
+}
+
+function getGlobalAgentsSkillsDirectory() {
+  return path.join(os.homedir(), ".agents", "skills");
+}
+
+function ensureCodexSkillsInstalled() {
+  const missingSkills = CODEX_SKILL_DEFINITIONS.filter((skillDefinition) => {
+    const targetSkillManifests = [
+      path.join(getGlobalAgentsSkillsDirectory(), skillDefinition.name, "SKILL.md"),
+      path.join(getCodexSkillsDirectory(), skillDefinition.name, "SKILL.md"),
+    ];
+    return !targetSkillManifests.some((manifestPath) => fs.existsSync(manifestPath));
+  });
+
+  if (missingSkills.length === 0) {
+    return;
+  }
+
+  if (!isCommandAvailable("npx")) {
+    console.warn("Skipping Codex skill installation: npx is not available.");
+    return;
+  }
+
+  for (const skillDefinition of missingSkills) {
+    console.log(`Ensuring Codex skill '${skillDefinition.name}' is installed from ${skillDefinition.sourceUrl}...`);
+    const addResult = spawnSync(
+      "npx",
+      [
+        "skills",
+        "add",
+        skillDefinition.repoUrl,
+        "--skill",
+        skillDefinition.name,
+        "--agent",
+        ...CODEX_SKILL_TARGET_AGENTS,
+        "-g",
+        "-y",
+      ],
+      { cwd: APP_ROOT, env: process.env, stdio: "pipe" },
+    );
+    if (addResult.status !== 0) {
+      const detail = addResult.stderr?.toString().trim() || addResult.stdout?.toString().trim() || "unknown error";
+      console.warn(`Failed to install Codex ${skillDefinition.name} skill via npx skills add: ${detail}`);
+    }
+  }
+}
+
+function printHelp() {
+  console.log(`Usage: vibe-pal [options]
+
+Options:
+  -p, --port <port>  Port to run on (default: 3200)
+  --dev              Run in development mode
+  -h, --help         Show this help message
+`);
+}
+
+function checkPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+
+    server.once("error", () => resolve(false));
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+async function findAvailablePort(startPort, maxAttempts = 20) {
+  for (let i = 0; i < maxAttempts; i += 1) {
+    const candidate = startPort + i;
+    const available = await checkPortAvailable(candidate);
+    if (available) {
+      return candidate;
+    }
+  }
+  throw new Error(`Could not find an available port in range ${startPort}-${startPort + maxAttempts - 1}.`);
+}
+
+function runNext(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [getNextBin(), ...args], {
+      cwd: APP_ROOT,
+      stdio: "inherit",
+      env: process.env,
+    });
+
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        process.kill(process.pid, signal);
+        return;
+      }
+      resolve(code === null ? 1 : code);
+    });
+  });
+}
+
+function ensureBuildExists() {
+  const buildIdPath = path.join(APP_ROOT, ".next", "BUILD_ID");
+  if (!fs.existsSync(buildIdPath)) {
+    throw new Error(
+      "No production build found in this package (.next/BUILD_ID is missing). The npm package must be published with prebuilt assets.",
+    );
+  }
+}
+
+function isPortListening(port, host = "127.0.0.1", connectTimeoutMs = 1000) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ port, host });
+    const onSuccess = () => {
+      socket.destroy();
+      resolve(true);
+    };
+    const onFailure = () => {
+      socket.destroy();
+      resolve(false);
+    };
+
+    socket.setTimeout(connectTimeoutMs, onFailure);
+    socket.once("connect", onSuccess);
+    socket.once("error", onFailure);
+    socket.once("timeout", onFailure);
+  });
+}
+
+async function waitForPortListening(port, { timeoutMs = 30000, intervalMs = 250 } = {}) {
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeoutMs) {
+    const listening = await isPortListening(port);
+    if (listening) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  return false;
+}
+
+function openInDefaultBrowser(url) {
+  const openCommand = getBrowserOpenCommand(url);
+  if (!openCommand) {
+    return false;
+  }
+  if (!isCommandAvailable(openCommand.command)) {
+    return false;
+  }
+
+  try {
+    const child = spawn(openCommand.command, openCommand.args, {
+      cwd: APP_ROOT,
+      env: process.env,
+      stdio: "ignore",
+      detached: true,
+      windowsHide: true,
+    });
+    child.once("error", (error) => {
+      const detail = error instanceof Error ? error.message : String(error);
+      console.warn(`Failed to auto-open browser: ${detail}`);
+    });
+    child.unref();
+    return true;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    console.warn(`Failed to auto-open browser: ${detail}`);
+    return false;
+  }
+}
+
+async function autoOpenBrowserWhenReady(url, port, mode = "start") {
+  if (!shouldAutoOpenBrowser(process.env, mode)) {
+    return;
+  }
+
+  const ready = await waitForPortListening(port);
+  if (!ready) {
+    return;
+  }
+
+  const opened = openInDefaultBrowser(url);
+  if (opened) {
+    console.log(`Opened ${url} in your default browser.`);
+  }
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      printHelp();
+      process.exit(0);
+    }
+
+    ensureCommandInstalled("ttyd");
+    if (process.platform !== "win32") {
+      ensureCommandInstalled("tmux");
+    }
+    ensureCodexSkillsInstalled();
+
+    const envPort = Number.parseInt(process.env.PORT || "", 10);
+    const preferredPort =
+      options.port ??
+      (Number.isInteger(envPort) && envPort > 0 && envPort <= 65535 ? envPort : DEFAULT_PORT);
+
+    let port = preferredPort;
+    if (!options.portExplicit && !process.env.PORT) {
+      port = await findAvailablePort(preferredPort);
+      if (port !== preferredPort) {
+        console.log(`Port ${preferredPort} is in use. Using ${port} instead.`);
+      }
+    }
+
+    if (options.mode === "dev") {
+      const url = `http://localhost:${port}`;
+      console.log(`Starting Palx in development mode on ${url}`);
+      const nextPromise = runNext(["dev", "--webpack", "-p", String(port)]);
+      void autoOpenBrowserWhenReady(url, port, options.mode);
+      process.exit(await nextPromise);
+    }
+
+    ensureBuildExists();
+    const url = `http://localhost:${port}`;
+    console.log(`Starting Palx on ${url}`);
+    const nextPromise = runNext(["start", "-p", String(port)]);
+    void autoOpenBrowserWhenReady(url, port, options.mode);
+    process.exit(await nextPromise);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.error(`Palx failed to start: ${errorMessage}`);
+    process.exit(1);
+  }
+}
+
+function isDirectExecution() {
+  if (!process.argv[1]) {
+    return false;
+  }
+
+  try {
+    const invokedPath = fs.realpathSync(path.resolve(process.argv[1]));
+    const modulePath = fs.realpathSync(fileURLToPath(import.meta.url));
+    return invokedPath === modulePath;
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectExecution()) {
+  void main();
+}

package/next.config.mjs

@@ -0,0 +1,25 @@
+/** @type {import("next").NextConfig} */
+const nextConfig = {
+  allowedDevOrigins: ["localhost", "*.localhost", "127.0.0.1"],
+  serverExternalPackages: ["keytar"],
+  devIndicators: {
+    position: "top-right",
+  },
+  experimental: {
+    serverActions: {
+      // Allow loopback iframe/proxy origins in local development previews.
+      // Example host values: 127.0.0.1:55700
+      allowedOrigins: ["127.0.0.*"],
+    },
+  },
+  async rewrites() {
+    return [
+      {
+        source: "/terminal/:path*",
+        destination: "http://127.0.0.1:7681/:path*",
+      },
+    ];
+  },
+};
+
+export default nextConfig;

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "vibe-pal",
+  "version": "0.42.0",
+  "private": false,
+  "description": "Local session manager for AI coding agents.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/m0o0scar/viba"
+  },
+  "bin": {
+    "vibe-pal": "bin/viba.mjs"
+  },
+  "files": [
+    "bin",
+    "src/lib/cli-args.mjs",
+    ".next/BUILD_ID",
+    ".next/server",
+    ".next/static",
+    ".next/*.json",
+    ".next/*.js",
+    "public",
+    "next.config.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "npx gfport 3200 -- node ./bin/viba.mjs --dev --port {PORT}",
+    "build": "next build",
+    "prepack": "rm -rf .next && npm run build",
+    "start": "node ./bin/viba.mjs",
+    "lint": "eslint",
+    "test": "node --experimental-strip-types --test src/**/*.test.ts test/**/*.test.mjs",
+    "cli": "node ./bin/viba.mjs",
+    "pack:preview": "npm pack --dry-run"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "git-worktree",
+    "nextjs"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@alexbruf/react-diff-viewer": "^3.1.5",
+    "@tanstack/react-query": "^5.90.21",
+    "@types/uuid": "^10.0.0",
+    "clsx": "^2.1.1",
+    "daisyui": "^5.5.18",
+    "http-proxy-middleware": "^3.0.5",
+    "keytar": "^7.9.0",
+    "lucide-react": "^0.563.0",
+    "next": "16.1.6",
+    "next-themes": "^0.4.6",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "simple-git": "^3.30.0",
+    "tailwind-merge": "^3.4.0",
+    "uuid": "^13.0.0",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@types/ws": "^8.18.1",
+    "eslint": "^9",
+    "eslint-config-next": "16.1.6",
+    "gfport": "^1.0.1",
+    "tailwindcss": "^4",
+    "typescript": "5.9.3"
+  }
+}

package/public/file.svg

@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

package/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

package/public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

package/public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

package/public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

package/src/lib/cli-args.mjs

@@ -0,0 +1,41 @@
+export function parseArgs(argv) {
+  const options = {
+    mode: "start",
+    port: undefined,
+    portExplicit: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      return options;
+    }
+
+    if (arg === "--dev") {
+      options.mode = "dev";
+      continue;
+    }
+
+    if (arg === "--port" || arg === "-p") {
+      const value = argv[i + 1];
+      if (!value) {
+        throw new Error("Missing value for --port.");
+      }
+      const parsed = Number.parseInt(value, 10);
+      if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        throw new Error(`Invalid port: ${value}`);
+      }
+      options.port = parsed;
+      options.portExplicit = true;
+      i += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return options;
+}