@vellumai/cli 0.10.11 → 0.10.12-dev.202607242227.e52a30c

package/src/lib/local.ts

@@ -105,7 +105,7 @@ function hasLocalRuntimeComponents(installDir: string): boolean {
  * (`assistant`, `credential-executor`) collide with app-bundle binary names
  * and point at whatever version happens to be installed globally.
  */
-function isCompiledCli(): boolean {
+export function isCompiledCli(): boolean {
   const execBase = basename(process.execPath);
   return (
     execBase !== "bun" && execBase !== "bunx" && !execBase.startsWith("bun-")
@@ -548,6 +548,7 @@ export function generateLocalSigningKey(): string {
 type DaemonStartOptions = {
   foreground?: boolean;
   defaultWorkspaceConfigPath?: string;
+  requireReady?: boolean;
   signingKey?: string;
 };
 
@@ -597,7 +598,10 @@ function applyDaemonEnvOverrides(
   applyIpcSocketDirOverride(env);
 }
 
-function logDaemonReadiness(readiness: DaemonReadiness): void {
+function logDaemonReadiness(
+  readiness: DaemonReadiness,
+  requireReady = false,
+): void {
   switch (readiness) {
     case "ready":
       console.log("   Assistant ready\n");
@@ -613,6 +617,11 @@ function logDaemonReadiness(readiness: DaemonReadiness): void {
       );
       break;
     default:
+      if (requireReady) {
+        throw new Error(
+          "Assistant did not bind its local port within 60 seconds.",
+        );
+      }
       console.log(
         "   ⚠️  Assistant did not become ready within 60s — continuing anyway\n",
       );
@@ -1320,6 +1329,7 @@ export async function startLocalDaemon(
           resources.daemonPort,
           Date.now() + 60000,
         ),
+        options?.requireReady,
       );
     }
     return;
@@ -1362,6 +1372,7 @@ export async function startLocalDaemon(
         // classifies it without blocking on an in-flight migration.
         logDaemonReadiness(
           await probeDaemonReadinessWithRetry(resources.daemonPort),
+          options?.requireReady,
         );
         return;
       }
@@ -1513,7 +1524,7 @@ export async function startLocalDaemon(
         readiness = await probeDaemonReadiness(resources.daemonPort);
       }
 
-      logDaemonReadiness(readiness);
+      logDaemonReadiness(readiness, options?.requireReady);
     }
   } else {
     console.log("🔨 Starting local assistant...");
@@ -1535,6 +1546,7 @@ export async function startLocalDaemon(
           resources.daemonPort,
           Date.now() + 60000,
         ),
+        options?.requireReady,
       );
     }
   }
@@ -1547,6 +1559,7 @@ export async function startGateway(
     signingKey?: string;
     bootstrapSecret?: string;
     envOverrides?: Record<string, string>;
+    requireReady?: boolean;
   },
 ): Promise<string> {
   const effectiveGatewayPort = resources?.gatewayPort ?? GATEWAY_PORT;
@@ -1676,6 +1689,11 @@ export async function startGateway(
   // connection-refused errors.
   const ready = await waitForDaemonReady(effectiveGatewayPort, 30000);
   if (!ready) {
+    if (options?.requireReady) {
+      throw new Error(
+        "Assistant gateway did not bind its local port within 30 seconds.",
+      );
+    }
     console.warn(
       "⚠ Gateway started but health check did not respond within 30s",
     );

package/src/lib/loopback-fetch.ts

@@ -6,7 +6,7 @@
  * connection per request; remote hosts are unaffected.
  */
 
-function isLoopbackUrl(url: string): boolean {
+export function isLoopbackUrl(url: string): boolean {
   try {
     // WHATWG URL canonicalizes hostnames, so IPv6 loopback is always "[::1]".
     const h = new URL(url).hostname;

package/src/lib/nginx-ingress.ts

@@ -17,6 +17,8 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 
 import { GATEWAY_PORT } from "./constants.js";
+import { waitForDaemonReady } from "./http-client.js";
+import { loadRawConfig, saveRawConfig } from "./ingress-config.js";
 
 /**
  * CLI-managed nginx reverse proxy that fronts the gateway for remote web
@@ -58,28 +60,6 @@ export function getIngressPaths(workspaceDir: string): IngressPaths {
   };
 }
 
-function getConfigPath(workspaceDir: string): string {
-  return join(workspaceDir, "config.json");
-}
-
-function loadRawConfig(workspaceDir: string): Record<string, unknown> {
-  const configPath = getConfigPath(workspaceDir);
-  if (!existsSync(configPath)) return {};
-  return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
-    string,
-    unknown
-  >;
-}
-
-function saveRawConfig(
-  workspaceDir: string,
-  config: Record<string, unknown>,
-): void {
-  const configPath = getConfigPath(workspaceDir);
-  mkdirSync(dirname(configPath), { recursive: true });
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-}
-
 /**
  * Locate the pre-built @vellumai/web dist directory.
  *
@@ -230,6 +210,13 @@ http {
     listen 127.0.0.1:${opts.listenPort};
     client_max_body_size 512m;
 
+    # This edge sits behind a TLS-terminating front (tunnel or tailscale serve),
+    # so redirects must be relative: emit "Location: /assistant/" and let the
+    # client resolve it against the origin it used, rather than an absolute URL
+    # built from nginx's own loopback scheme and port.
+    absolute_redirect off;
+    port_in_redirect off;
+
 ${serverLocations}
   }
 }
@@ -554,6 +541,95 @@ export async function stopIngressNginx(workspaceDir: string): Promise<boolean> {
   return true;
 }
 
+/** Probe budget for confirming the freshly-spawned edge answers /healthz. */
+export const INGRESS_READY_TIMEOUT_MS = 5_000;
+
+/**
+ * Outcome of an attempt to bring up the remote-web nginx ingress edge. Callers
+ * render their own messaging per variant: `nginx-ingress up` prints
+ * install/build guidance and exits non-zero, while the wake restore path warns
+ * and continues.
+ */
+export type StartRemoteWebIngressResult =
+  | {
+      status: "started";
+      listenPort: number;
+      webDistDir: string;
+      version: string;
+    }
+  | { status: "already-running"; listenPort: number }
+  | { status: "nginx-missing" }
+  | { status: "web-dist-missing" }
+  | { status: "unreachable"; listenPort: number; logPath: string };
+
+/**
+ * Generate the nginx config and start the remote-web ingress edge, then probe
+ * /healthz through it to prove the ingress → gateway path is live. A spawned
+ * but unreachable nginx is rolled back so a failed attempt leaves no half-up
+ * edge behind.
+ *
+ * Pure mechanism: it performs no console output and never exits the process, so
+ * both the `nginx-ingress up` command and the wake restore path can share one
+ * implementation and map the returned result to their own UX.
+ */
+export async function startRemoteWebIngress(opts: {
+  workspaceDir: string;
+  gatewayPort: number;
+  listenPort?: number;
+  readyTimeoutMs?: number;
+  /**
+   * Invoked once, after every preflight check passes and immediately before
+   * nginx is spawned, so callers can emit their own "starting" progress line
+   * with the resolved version/dist/port. Never fires on a preflight bail-out
+   * (nginx-missing, already-running, web-dist-missing).
+   */
+  onStarting?: (info: {
+    version: string;
+    webDistDir: string;
+    listenPort: number;
+  }) => void;
+}): Promise<StartRemoteWebIngressResult> {
+  const listenPort = opts.listenPort ?? getNginxIngressPort();
+
+  const version = getNginxVersion();
+  if (!version) {
+    return { status: "nginx-missing" };
+  }
+
+  if (isIngressRunning(opts.workspaceDir)) {
+    return { status: "already-running", listenPort };
+  }
+
+  const webDistDir = findWebDistDir();
+  if (!webDistDir) {
+    return { status: "web-dist-missing" };
+  }
+
+  opts.onStarting?.({ version, webDistDir, listenPort });
+
+  const child = startIngressNginx({
+    workspaceDir: opts.workspaceDir,
+    gatewayPort: opts.gatewayPort,
+    listenPort,
+    remoteWebIngress: { webDistDir },
+  });
+  child.unref();
+
+  // /healthz proxies through nginx to the gateway, so a 200 proves the whole
+  // ingress → gateway path works.
+  const ready = await waitForDaemonReady(
+    listenPort,
+    opts.readyTimeoutMs ?? INGRESS_READY_TIMEOUT_MS,
+  );
+  if (!ready) {
+    const { logPath } = getIngressPaths(opts.workspaceDir);
+    await stopIngressNginx(opts.workspaceDir);
+    return { status: "unreachable", listenPort, logPath };
+  }
+
+  return { status: "started", listenPort, webDistDir, version };
+}
+
 /**
  * Resolve the local port a tunnel should target: the nginx ingress when it is
  * recorded AND its process is alive, otherwise the gateway port directly

package/src/lib/ngrok.ts

@@ -1,49 +1,17 @@
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
-import {
-  closeSync,
-  existsSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  writeFileSync,
-} from "node:fs";
-import { homedir } from "node:os";
+import { closeSync, existsSync, mkdirSync, openSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { GATEWAY_PORT } from "./constants.js";
+import {
+  clearIngressUrl,
+  getDefaultWorkspaceDir,
+  loadRawConfig,
+  saveIngressUrl,
+} from "./ingress-config.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
 import { resolveTunnelTargetPort } from "./nginx-ingress.js";
 
-function getDefaultWorkspaceDir(): string {
-  return (
-    process.env.VELLUM_WORKSPACE_DIR?.trim() ||
-    join(homedir(), ".vellum", "workspace")
-  );
-}
-
-function getConfigPath(workspaceDir: string): string {
-  return join(workspaceDir, "config.json");
-}
-
-function loadRawConfig(workspaceDir: string): Record<string, unknown> {
-  const configPath = getConfigPath(workspaceDir);
-  if (!existsSync(configPath)) return {};
-  return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
-    string,
-    unknown
-  >;
-}
-
-function saveRawConfig(
-  workspaceDir: string,
-  config: Record<string, unknown>,
-): void {
-  const configPath = getConfigPath(workspaceDir);
-  const dir = dirname(configPath);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-}
-
 const NGROK_API_URL = "http://127.0.0.1:4040/api/tunnels";
 const NGROK_POLL_INTERVAL_MS = 500;
 const NGROK_POLL_TIMEOUT_MS = 15_000;
@@ -190,29 +158,6 @@ export async function waitForNgrokUrl(
   );
 }
 
-/**
- * Persist a public ingress URL to the workspace config and enable ingress.
- */
-function saveIngressUrl(workspaceDir: string, publicUrl: string): void {
-  const config = loadRawConfig(workspaceDir);
-  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
-  ingress.publicBaseUrl = publicUrl;
-  ingress.enabled = true;
-  config.ingress = ingress;
-  saveRawConfig(workspaceDir, config);
-}
-
-/**
- * Clear the ingress public base URL from the workspace config.
- */
-function clearIngressUrl(workspaceDir: string): void {
-  const config = loadRawConfig(workspaceDir);
-  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
-  delete ingress.publicBaseUrl;
-  config.ingress = ingress;
-  saveRawConfig(workspaceDir, config);
-}
-
 /**
  * Check whether any webhook-based integrations (e.g. Telegram, Twilio) are
  * configured that require a public ingress URL.
@@ -312,6 +257,8 @@ export interface RunNgrokTunnelOptions {
   workspaceDir?: string;
   /** Prefer nginx ingress over the gateway port when it is running. */
   preferNginxIngress?: boolean;
+  /** Lockfile entry to mirror the ingress URL onto (`ingressUrl`). */
+  assistantId?: string;
 }
 
 /**
@@ -355,7 +302,7 @@ export async function runNgrokTunnel(
   const existingUrl = await findExistingTunnel(port);
   if (existingUrl) {
     console.log(`Found existing ngrok tunnel: ${existingUrl}`);
-    saveIngressUrl(workspaceDir, existingUrl);
+    saveIngressUrl(workspaceDir, existingUrl, opts.assistantId);
     console.log("Ingress URL saved to config.");
     console.log("");
     console.log(
@@ -382,7 +329,7 @@ export async function runNgrokTunnel(
     }
     if (publicUrl) {
       console.log("\nClearing ingress URL from config...");
-      clearIngressUrl(workspaceDir);
+      clearIngressUrl(workspaceDir, opts.assistantId);
     }
   };
 
@@ -431,7 +378,7 @@ export async function runNgrokTunnel(
   console.log(`Tunnel established: ${publicUrl}`);
   console.log(`Forwarding to:     localhost:${port}`);
 
-  saveIngressUrl(workspaceDir, publicUrl);
+  saveIngressUrl(workspaceDir, publicUrl, opts.assistantId);
   console.log("Ingress URL saved to config.");
   console.log("");
   console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");

package/src/lib/retire-apple-container.ts

@@ -13,7 +13,9 @@ export async function retireAppleContainer(
   name: string,
   entry: AssistantEntry,
 ): Promise<void> {
-  console.log(`\u{1F5D1}\ufe0f  Retiring Apple Container assistant '${name}'...\n`);
+  console.log(
+    `\u{1F5D1}\ufe0f  Retiring Apple Container assistant '${name}'...\n`,
+  );
 
   const mgmtSocket = entry.mgmtSocket as string | undefined;
   if (!mgmtSocket) {
@@ -46,7 +48,9 @@ export async function retireAppleContainer(
 
     socket.setTimeout(TIMEOUT_MS);
     socket.on("timeout", () => {
-      console.error("Timed out waiting for retire response from the macOS app.");
+      console.error(
+        "Timed out waiting for retire response from the macOS app.",
+      );
       socket.destroy();
       process.exit(1);
     });
@@ -77,9 +81,7 @@ export async function retireAppleContainer(
         resolve();
       } else {
         reject(
-          new Error(
-            `Retire failed: ${response.message || "unknown error"}`,
-          ),
+          new Error(`Retire failed: ${response.message || "unknown error"}`),
         );
       }
     });

package/src/lib/stale-cli-hint.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared tail for errors where this CLI doesn't recognize an option or provider
+ * the user named. The name may be valid in a newer release, so point the user
+ * at the self-update path before they conclude the feature doesn't exist.
+ *
+ * `bun install -g vellum@latest` refreshes the `vellum` binary directly — the
+ * mechanism the installer and the CLI's own self-update use. (`vellum upgrade`
+ * targets the assistant runtime, not the CLI binary, for local assistants.)
+ */
+export const STALE_CLI_UPDATE_HINT =
+  "your CLI may be out of date — update it with `bun install -g vellum@latest` and retry.";