@vellumai/cli 0.10.11-dev.202607242127.a6bf2b2 → 0.10.11-staging.2

package/src/commands/client.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { closeSync, existsSync } from "node:fs";
+import { existsSync } from "node:fs";
 import path from "node:path";
 
 import {
@@ -61,8 +61,6 @@ import { tuiLog } from "../lib/tui-log";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 import { probePort } from "../lib/port-probe.js";
 import { openBrowser } from "../lib/open-browser";
-import { isCompiledCli } from "../lib/local.js";
-import { getLogDir, openLogFile, resetLogFile } from "../lib/xdg-log.js";
 
 const SUPPORTED_INTERFACES = ["cli", "web"] as const;
 type SupportedInterface = (typeof SUPPORTED_INTERFACES)[number];
@@ -95,10 +93,6 @@ interface ParsedArgs {
   disablePlatform: boolean;
   /** Auto-open the web interface in the default browser (--interface web only). */
   openBrowser: boolean;
-  /** Explicit web server port (--interface web only). Binds strictly — no scan. */
-  webPort?: number;
-  /** Run the web server as a detached background process (--interface web only). */
-  background: boolean;
 }
 
 function readAssistantName(entry: AssistantEntry | null): string | undefined {
@@ -144,12 +138,9 @@ export function parseArgs(): ParsedArgs {
     "-i",
     "--token",
     "-t",
-    "--port",
   ]);
   // Auto-open the web interface in the browser by default; --no-open opts out.
   let openBrowserPref = true;
-  let webPort: number | undefined;
-  let background = false;
   const flagArgs: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -160,19 +151,6 @@ export function parseArgs(): ParsedArgs {
       disablePlatform = true;
     } else if (arg === "--no-open") {
       openBrowserPref = false;
-    } else if (arg === "--background") {
-      background = true;
-    } else if (arg === "--port") {
-      const value = args[++i];
-      const parsed =
-        value === undefined ? Number.NaN : Number.parseInt(value, 10);
-      if (String(parsed) !== value || parsed < 1 || parsed > 65535) {
-        console.error(
-          `Invalid --port '${value ?? ""}'. Expected an integer between 1 and 65535.`,
-        );
-        process.exit(1);
-      }
-      webPort = parsed;
     } else if (
       (arg === "--url" ||
         arg === "-u" ||
@@ -281,17 +259,6 @@ export function parseArgs(): ParsedArgs {
     }
   }
 
-  if (interfaceId !== WEB_INTERFACE_ID) {
-    if (webPort !== undefined) {
-      console.error("--port requires --interface web.");
-      process.exit(1);
-    }
-    if (background) {
-      console.error("--background requires --interface web.");
-      process.exit(1);
-    }
-  }
-
   return {
     runtimeUrl: normalizeRuntimeUrl(runtimeUrl),
     assistantId,
@@ -305,8 +272,6 @@ export function parseArgs(): ParsedArgs {
     parsedFlagOverrides,
     disablePlatform,
     openBrowser: openBrowserPref,
-    webPort,
-    background,
   };
 }
 
@@ -327,12 +292,6 @@ ${ANSI.bold}OPTIONS:${ANSI.reset}
     -a, --assistant-id <id>    Assistant ID
     -i, --interface <id>       Interface identifier: cli (default) or web
     --no-open                  Don't auto-open the browser (--interface web)
-    --port <port>              Web server port, 1-65535 (--interface web).
-                              Errors if the port is taken. Default: 3000,
-                              scanning upward when busy.
-    --background               Run the web server as a background process
-                              (--interface web). Prints the URL, PID, and log
-                              path, then returns to the shell.
     --flag <key=value>         Feature flag override (repeatable, kebab-case key)
     --disable-platform         Suppress all outbound platform API calls
     -h, --help                 Show this help message
@@ -352,9 +311,6 @@ ${ANSI.bold}EXAMPLES:${ANSI.reset}
     # Ephemeral: connect to another machine's assistant with a paired token
     # (no lockfile entry, nothing persisted):
     vellum client --url https://your-tunnel.example --token <jwt>
-
-    # Web interface on a fixed port, detached from the shell:
-    vellum client --interface web --port 4000 --background
 `);
 }
 
@@ -819,12 +775,12 @@ function tryBindLoopback(
  * Never binds wildcard interfaces (`0.0.0.0`/`::`): the server exposes
  * `/__local/*` control endpoints, so it must stay loopback-only.
  */
-function serveLoopback(
-  preferredPort: number,
-  fetchHandler: WebFetchHandler,
-  scanLimit = WEB_PORT_SCAN_LIMIT,
-) {
-  for (let port = preferredPort; port < preferredPort + scanLimit; port++) {
+function serveLoopback(preferredPort: number, fetchHandler: WebFetchHandler) {
+  for (
+    let port = preferredPort;
+    port < preferredPort + WEB_PORT_SCAN_LIMIT;
+    port++
+  ) {
     const primary = tryBindLoopback(port, "127.0.0.1", fetchHandler);
     if (!primary) continue;
 
@@ -848,21 +804,10 @@ function serveLoopback(
     }
   }
   throw new Error(
-    scanLimit === 1
-      ? `Port ${preferredPort} is already in use`
-      : `Could not bind a free loopback port in [${preferredPort}, ${preferredPort + scanLimit - 1}]`,
+    `Could not bind a free loopback port in [${preferredPort}, ${preferredPort + WEB_PORT_SCAN_LIMIT - 1}]`,
   );
 }
 
-/** True when neither loopback family has a listener on `port`. */
-async function isDualLoopbackPortFree(port: number): Promise<boolean> {
-  const [busyV4, busyV6] = await Promise.all([
-    probePort(port, "127.0.0.1"),
-    probePort(port, "::1"),
-  ]);
-  return !busyV4 && !busyV6;
-}
-
 /**
  * Find the first port at/above `preferred` with nothing listening on either
  * loopback family. Used for the Vite dev server, which binds the port itself
@@ -871,29 +816,15 @@ async function isDualLoopbackPortFree(port: number): Promise<boolean> {
  */
 async function findFreeDualLoopbackPort(preferred: number): Promise<number> {
   for (let port = preferred; port < preferred + WEB_PORT_SCAN_LIMIT; port++) {
-    if (await isDualLoopbackPortFree(port)) {
-      return port;
-    }
+    const [busyV4, busyV6] = await Promise.all([
+      probePort(port, "127.0.0.1"),
+      probePort(port, "::1"),
+    ]);
+    if (!busyV4 && !busyV6) return port;
   }
   return preferred;
 }
 
-/**
- * Resolve the port for a probe-based web server launch: an explicit --port
- * must be free (exit 1 otherwise — strict, no silent move), the default picks
- * the first free port at/above 3000.
- */
-async function resolveWebPort(webPort: number | undefined): Promise<number> {
-  if (webPort === undefined) {
-    return findFreeDualLoopbackPort(3000);
-  }
-  if (!(await isDualLoopbackPortFree(webPort))) {
-    console.error(`Port ${webPort} is already in use`);
-    process.exit(1);
-  }
-  return webPort;
-}
-
 /**
  * Open `url` in the browser once `port` is accepting connections, polling for
  * up to ~10s. Used for the Vite dev server, which binds the port asynchronously
@@ -909,118 +840,11 @@ async function openBrowserWhenReady(url: string, port: number): Promise<void> {
   }
 }
 
-const WEB_BACKGROUND_LOG_FILE = "client-web.log";
-// Generous cap so a cold Vite dev-server boot (dependency optimization) still
-// counts as a successful start.
-const WEB_BACKGROUND_START_TIMEOUT_MS = 30_000;
-
-/**
- * Launch `vellum client --interface web` as a detached background process.
- *
- * The port is resolved up front (explicit --port must be free; otherwise the
- * first free port at/above 3000) and pinned via `--port` on the child so the
- * URL printed here is the one the child binds. The child's stdout/stderr go to
- * `<xdg-log-dir>/client-web.log` — same detach idiom as the nginx/ngrok
- * spawns. Success is only reported once the child is accepting connections on
- * the port; an early child exit (e.g. missing @vellumai/web assets) or a
- * startup timeout fails with a pointer at the log file.
- */
-async function spawnBackgroundWebInterface(
-  webPort: number | undefined,
-): Promise<void> {
-  const port = await resolveWebPort(webPort);
-
-  // Rebuild the argv without --background, pinning the resolved port.
-  const childArgs: string[] = ["client"];
-  const rawArgs = process.argv.slice(3);
-  for (let i = 0; i < rawArgs.length; i++) {
-    const arg = rawArgs[i];
-    if (arg === "--background") {
-      continue;
-    }
-    // A dangling --port can't reach here — parseArgs already rejected it.
-    if (arg === "--port") {
-      i++;
-      continue;
-    }
-    childArgs.push(arg);
-  }
-  childArgs.push("--port", String(port));
-
-  // A compiled binary re-invokes itself; under plain bun (source tree, npm
-  // install) the entry script is argv[1].
-  const spawnArgs = isCompiledCli()
-    ? childArgs
-    : [process.argv[1], ...childArgs];
-
-  resetLogFile(WEB_BACKGROUND_LOG_FILE);
-  const fd = openLogFile(WEB_BACKGROUND_LOG_FILE);
-  const child = spawn(process.execPath, spawnArgs, {
-    detached: true,
-    stdio: ["ignore", fd, fd],
-  });
-  if (typeof fd === "number") {
-    closeSync(fd);
-  }
-  child.unref();
-
-  const logPath = path.join(getLogDir(), WEB_BACKGROUND_LOG_FILE);
-
-  // Don't report success until the child is actually serving: watch for an
-  // early exit (e.g. missing @vellumai/web assets, port lost to the TOCTOU
-  // window) and poll the port until it accepts connections.
-  let exit: { code: number | null } | undefined;
-  child.on("error", () => {
-    exit = { code: null };
-  });
-  child.on("exit", (code) => {
-    exit = { code };
-  });
-
-  const deadline = Date.now() + WEB_BACKGROUND_START_TIMEOUT_MS;
-  let listening = false;
-  while (Date.now() < deadline && !exit) {
-    if (await probePort(port, "127.0.0.1")) {
-      listening = true;
-      break;
-    }
-    await new Promise((resolve) => setTimeout(resolve, 200));
-  }
-
-  if (exit) {
-    console.error(
-      `Web interface exited during startup${exit.code !== null ? ` (exit code ${exit.code})` : ""}. Logs: ${logPath}`,
-    );
-    process.exit(1);
-  }
-  if (!listening) {
-    // Kill the detached child (its whole process group — the Vite path spawns
-    // grandchildren) so a slow startup can't bind the port and linger after
-    // we've reported failure.
-    if (child.pid !== undefined) {
-      try {
-        process.kill(-child.pid, "SIGTERM");
-      } catch {
-        child.kill("SIGTERM");
-      }
-    }
-    console.error(
-      `Web interface did not start listening on port ${port} within ${WEB_BACKGROUND_START_TIMEOUT_MS / 1000}s; terminated it. Logs: ${logPath}`,
-    );
-    process.exit(1);
-  }
-
-  console.log(`Vellum web interface: http://localhost:${port}${SPA_BASE}`);
-  console.log(`Running in background (pid ${child.pid}). Logs: ${logPath}`);
-  console.log(`Stop with: kill ${child.pid}`);
-}
-
 async function runWebInterface(
   flagEnvVars: Record<string, string>,
   parsedFlagOverrides: Record<string, boolean | string>,
   disablePlatform: boolean,
   openInBrowser: boolean,
-  webPort: number | undefined,
 ): Promise<void> {
   // Propagate flag env vars so child processes (e.g. hatch from the web UI) inherit them.
   Object.assign(process.env, flagEnvVars);
@@ -1034,7 +858,6 @@ async function runWebInterface(
       flagEnvVars,
       disablePlatform,
       openInBrowser,
-      webPort,
     );
   }
 
@@ -1178,23 +1001,9 @@ async function runWebInterface(
     return new Response("Not Found", { status: 404 });
   };
 
-  // An explicit --port binds strictly (no scan) so the user gets the port they
-  // asked for or a clear error.
-  const preferredPort = webPort ?? 3000;
-  let bound: ReturnType<typeof serveLoopback>;
-  try {
-    bound = serveLoopback(
-      preferredPort,
-      fetchHandler,
-      webPort !== undefined ? 1 : WEB_PORT_SCAN_LIMIT,
-    );
-  } catch (err) {
-    console.error(err instanceof Error ? err.message : String(err));
-    process.exit(1);
-  }
-  const { port, servers } = bound;
-  if (port !== preferredPort) {
-    console.log(`Port ${preferredPort} in use; using ${port}.`);
+  const { port, servers } = serveLoopback(3000, fetchHandler);
+  if (port !== 3000) {
+    console.log(`Port 3000 in use; using ${port}.`);
   }
   // Advertise `localhost` (not `127.0.0.1`) so the app origin matches the host
   // the platform hardcodes in its loopback callback. We bind both loopback
@@ -1218,7 +1027,6 @@ async function runViteDevServer(
   flagEnvVars: Record<string, string>,
   disablePlatform: boolean,
   openInBrowser: boolean,
-  webPort: number | undefined,
 ): Promise<void> {
   const platformUrl = getPlatformUrl();
 
@@ -1231,9 +1039,8 @@ async function runViteDevServer(
   // Auto-pick a free port (Vite uses strictPort) so a running `vel up` stack
   // on :3000 doesn't wedge dev. The loopback callback port follows
   // window.location.port, so a non-3000 port propagates automatically.
-  // An explicit --port is strict: error rather than silently moving.
-  const port = await resolveWebPort(webPort);
-  if (webPort === undefined && port !== 3000) {
+  const port = await findFreeDualLoopbackPort(3000);
+  if (port !== 3000) {
     console.log(`Port 3000 in use; using ${port}.`);
   }
 
@@ -1332,8 +1139,6 @@ export async function client(): Promise<void> {
     parsedFlagOverrides,
     disablePlatform,
     openBrowser: openInBrowser,
-    webPort,
-    background,
   } = parseArgs();
 
   if (disablePlatform) {
@@ -1341,16 +1146,11 @@ export async function client(): Promise<void> {
   }
 
   if (interfaceId === WEB_INTERFACE_ID) {
-    if (background) {
-      await spawnBackgroundWebInterface(webPort);
-      return;
-    }
     await runWebInterface(
       flagEnvVars,
       parsedFlagOverrides,
       disablePlatform,
       openInBrowser,
-      webPort,
     );
     return;
   }

package/src/commands/exec.ts

@@ -220,11 +220,7 @@ export async function exec(): Promise<void> {
 
     if (interactive) {
       // Interactive mode: shell-escape argv and delegate to full terminal
-      await interactiveSession(
-        assistant,
-        shellEscapeArgs(command),
-        serviceParam,
-      );
+      await interactiveSession(assistant, shellEscapeArgs(command), serviceParam);
       return;
     }
 

package/src/commands/flags.ts

@@ -4,7 +4,6 @@ import {
   formatAssistantLookupError,
   lookupAssistantByIdentifier,
 } from "../lib/assistant-config.js";
-import { crossEnvironmentAssistantHint } from "../lib/environments/detect.js";
 
 type FeatureFlagEntry = {
   key: string;
@@ -133,9 +132,7 @@ function rethrowFetchError(err: unknown): never {
     (err.message.includes("fetch") || err.message.includes("connect"))
   ) {
     throw new Error(
-      `Could not reach the assistant gateway. Is it running? Try 'vellum wake'.${
-        crossEnvironmentAssistantHint() ?? ""
-      }`,
+      "Could not reach the assistant gateway. Is it running? Try 'vellum wake'.",
     );
   }
   throw err;

package/src/commands/nginx-ingress.ts

@@ -14,16 +14,22 @@ import {
   isAssistantFeatureFlagEnabled,
   WEB_REMOTE_INGRESS_FLAG,
 } from "../lib/feature-flags.js";
+import { waitForDaemonReady } from "../lib/http-client.js";
 import {
   DEFAULT_NGINX_INGRESS_PORT,
+  findWebDistDir,
   getIngressPaths,
   getIngressPid,
+  getNginxIngressPort,
+  getNginxVersion,
   isIngressRunning,
   resolveTunnelTargetPort,
-  startRemoteWebIngress,
+  startIngressNginx,
   stopIngressNginx,
 } from "../lib/nginx-ingress.js";
 
+const READY_TIMEOUT_MS = 5_000;
+
 function printHelp(): void {
   console.log("Usage: vellum nginx-ingress <subcommand> [<name>] [options]");
   console.log("");
@@ -158,71 +164,79 @@ async function assertWebRemoteIngressEnabled(
 
 async function up(target: NginxIngressTarget): Promise<void> {
   const { workspaceDir, gatewayPort } = target;
+  const listenPort = getNginxIngressPort();
 
   await assertWebRemoteIngressEnabled(target);
 
-  const result = await startRemoteWebIngress({
+  const version = getNginxVersion();
+  if (!version) {
+    console.error("Error: nginx is not installed.");
+    console.error("");
+    console.error("Install nginx:");
+    console.error("  macOS:  brew install nginx");
+    console.error("  Linux:  sudo apt install nginx");
+    console.error("");
+    console.error(
+      "Or point NGINX_BIN at an existing binary: NGINX_BIN=/path/to/nginx",
+    );
+    process.exit(1);
+  }
+
+  if (isIngressRunning(workspaceDir)) {
+    console.log("nginx ingress is already running.");
+    await status(target);
+    return;
+  }
+
+  const webDistDir = findWebDistDir();
+  if (!webDistDir) {
+    console.error(
+      "Error: unable to locate built web assets for remote web ingress.",
+    );
+    console.error("");
+    console.error("Build the SPA first:");
+    console.error("  cd clients/web && VITE_PLATFORM_MODE=false bun run build");
+    console.error("");
+    console.error(
+      "Or install @vellumai/web so its packaged dist directory is available.",
+    );
+    process.exit(1);
+  }
+
+  console.log(`Using ${version}`);
+  console.log(
+    `Starting nginx ingress on 127.0.0.1:${listenPort} → web ${webDistDir} + gateway 127.0.0.1:${gatewayPort}...`,
+  );
+
+  const child = startIngressNginx({
     workspaceDir,
     gatewayPort,
-    onStarting: ({ version, webDistDir, listenPort }) => {
-      console.log(`Using ${version}`);
-      console.log(
-        `Starting nginx ingress on 127.0.0.1:${listenPort} → web ${webDistDir} + gateway 127.0.0.1:${gatewayPort}...`,
-      );
-    },
+    listenPort,
+    remoteWebIngress: { webDistDir },
   });
+  child.unref();
 
-  switch (result.status) {
-    case "already-running":
-      console.log("nginx ingress is already running.");
-      await status(target);
-      return;
-    case "started":
-      console.log("");
-      console.log(
-        `nginx ingress running: http://127.0.0.1:${result.listenPort}`,
-      );
-      console.log("");
-      console.log("Next steps:");
-      console.log(
-        "  vellum tunnel --provider ngrok   # tunnel now targets nginx ingress",
-      );
-      console.log("  vellum nginx-ingress down        # stop the proxy");
-      return;
-    case "nginx-missing":
-      console.error("Error: nginx is not installed.");
-      console.error("");
-      console.error("Install nginx:");
-      console.error("  macOS:  brew install nginx");
-      console.error("  Linux:  sudo apt install nginx");
-      console.error("");
-      console.error(
-        "Or point NGINX_BIN at an existing binary: NGINX_BIN=/path/to/nginx",
-      );
-      break;
-    case "web-dist-missing":
-      console.error(
-        "Error: unable to locate built web assets for remote web ingress.",
-      );
-      console.error("");
-      console.error("Build the SPA first:");
-      console.error(
-        "  cd clients/web && VITE_PLATFORM_MODE=false bun run build",
-      );
-      console.error("");
-      console.error(
-        "Or install @vellumai/web so its packaged dist directory is available.",
-      );
-      break;
-    case "unreachable":
-      console.error(
-        `Error: nginx ingress did not become reachable on 127.0.0.1:${result.listenPort}.`,
-      );
-      console.error(`Check the nginx log: ${result.logPath}`);
-      break;
+  // /healthz proxies through nginx to the gateway, so a 200 proves the whole
+  // ingress → gateway path works.
+  const ready = await waitForDaemonReady(listenPort, READY_TIMEOUT_MS);
+  if (!ready) {
+    const { logPath } = getIngressPaths(workspaceDir);
+    await stopIngressNginx(workspaceDir);
+    console.error(
+      `Error: nginx ingress did not become reachable on 127.0.0.1:${listenPort}.`,
+    );
+    console.error(`Check the nginx log: ${logPath}`);
+    process.exit(1);
   }
 
-  process.exit(1);
+  console.log("");
+  console.log(`nginx ingress running: http://127.0.0.1:${listenPort}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(
+    "  vellum tunnel --provider ngrok   # tunnel now targets nginx ingress",
+  );
+  console.log("  vellum nginx-ingress down        # stop the proxy");
 }
 
 async function down(target: NginxIngressTarget): Promise<void> {