@vellumai/cli 0.10.11-dev.202607232226.bf9eaf3 → 0.10.11-dev.202607240043.b26a41c

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.11-dev.202607232226.bf9eaf3",
+  "version": "0.10.11-dev.202607240043.b26a41c",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/wake.test.ts

@@ -14,8 +14,11 @@ import { join } from "node:path";
 
 import * as assistantConfig from "../lib/assistant-config.js";
 import * as docker from "../lib/docker.js";
+import * as featureFlags from "../lib/feature-flags.js";
 import * as guardianToken from "../lib/guardian-token.js";
+import * as ingressConfig from "../lib/ingress-config.js";
 import * as local from "../lib/local.js";
+import * as nginxIngress from "../lib/nginx-ingress.js";
 import * as ngrok from "../lib/ngrok.js";
 import * as processLib from "../lib/process.js";
 import type { AssistantEntry } from "../lib/assistant-config.js";
@@ -138,11 +141,50 @@ mock.module("../lib/ngrok", () => ({
   maybeStartNgrokTunnel: maybeStartNgrokTunnelMock,
 }));
 
+const realFeatureFlags = { ...featureFlags };
+const realIngressConfig = { ...ingressConfig };
+const realNginxIngress = { ...nginxIngress };
+
+const isAssistantFeatureFlagEnabledMock = mock<
+  typeof featureFlags.isAssistantFeatureFlagEnabled
+>(async () => true);
+
+mock.module("../lib/feature-flags.js", () => ({
+  ...realFeatureFlags,
+  isAssistantFeatureFlagEnabled: isAssistantFeatureFlagEnabledMock,
+}));
+
+const loadRawConfigMock = mock<typeof ingressConfig.loadRawConfig>(() => ({}));
+
+mock.module("../lib/ingress-config.js", () => ({
+  ...realIngressConfig,
+  loadRawConfig: loadRawConfigMock,
+}));
+
+const isIngressRunningMock = mock<typeof nginxIngress.isIngressRunning>(
+  () => false,
+);
+const startRemoteWebIngressMock = mock<
+  typeof nginxIngress.startRemoteWebIngress
+>(async () => ({
+  status: "started",
+  listenPort: 7840,
+  webDistDir: "/tmp/web/dist",
+  version: "nginx/1.25.3",
+}));
+
+mock.module("../lib/nginx-ingress.js", () => ({
+  ...realNginxIngress,
+  isIngressRunning: isIngressRunningMock,
+  startRemoteWebIngress: startRemoteWebIngressMock,
+}));
+
 const { wake } = await import("../commands/wake.js");
 
 let tempDir: string;
 let originalArgv: string[];
 let logSpy: ReturnType<typeof spyOn>;
+let warnSpy: ReturnType<typeof spyOn>;
 
 function makeLocalEntry(): AssistantEntry {
   tempDir = mkdtempSync(join(tmpdir(), "vellum-wake-test-"));
@@ -167,6 +209,7 @@ beforeEach(() => {
   tempDir = "";
   process.argv = ["bun", "vellum", "wake", "--watch", "local-assistant"];
   logSpy = spyOn(console, "log").mockImplementation(() => {});
+  warnSpy = spyOn(console, "warn").mockImplementation(() => {});
 
   const entry = makeLocalEntry();
   resolveTargetAssistantMock.mockReset();
@@ -213,11 +256,25 @@ beforeEach(() => {
   );
   maybeStartNgrokTunnelMock.mockReset();
   maybeStartNgrokTunnelMock.mockResolvedValue(null);
+  isAssistantFeatureFlagEnabledMock.mockReset();
+  isAssistantFeatureFlagEnabledMock.mockResolvedValue(true);
+  loadRawConfigMock.mockReset();
+  loadRawConfigMock.mockReturnValue({});
+  isIngressRunningMock.mockReset();
+  isIngressRunningMock.mockReturnValue(false);
+  startRemoteWebIngressMock.mockReset();
+  startRemoteWebIngressMock.mockResolvedValue({
+    status: "started",
+    listenPort: 7840,
+    webDistDir: "/tmp/web/dist",
+    version: "nginx/1.25.3",
+  });
 });
 
 afterEach(() => {
   process.argv = originalArgv;
   logSpy.mockRestore();
+  warnSpy.mockRestore();
   if (tempDir) {
     rmSync(tempDir, { recursive: true, force: true });
   }
@@ -230,6 +287,9 @@ afterAll(() => {
   mock.module("../lib/process", () => realProcessLib);
   mock.module("../lib/local", () => realLocal);
   mock.module("../lib/ngrok", () => realNgrok);
+  mock.module("../lib/feature-flags.js", () => realFeatureFlags);
+  mock.module("../lib/ingress-config.js", () => realIngressConfig);
+  mock.module("../lib/nginx-ingress.js", () => realNginxIngress);
 });
 
 describe("vellum wake", () => {
@@ -342,3 +402,121 @@ describe("vellum wake", () => {
     expect(startLocalDaemonMock).not.toHaveBeenCalled();
   });
 });
+
+describe("vellum wake — web ingress restore", () => {
+  const enabledConfig = {
+    ingress: { enabled: true, publicBaseUrl: "https://assistant.example.com" },
+  };
+
+  beforeEach(() => {
+    process.argv = ["bun", "vellum", "wake", "local-assistant"];
+  });
+
+  test("restores the edge when ingress is enabled, the flag is on, and it is not already running", async () => {
+    loadRawConfigMock.mockReturnValue(enabledConfig);
+
+    await wake();
+
+    expect(isAssistantFeatureFlagEnabledMock).toHaveBeenCalledWith(
+      "local-assistant",
+      "web-remote-ingress",
+      { runtimeUrl: "http://127.0.0.1:7830" },
+    );
+    expect(startRemoteWebIngressMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        workspaceDir: join(tempDir, ".vellum", "workspace"),
+        gatewayPort: 7830,
+      }),
+    );
+    expect(logSpy).toHaveBeenCalledWith("Wake complete.");
+  });
+
+  test("does not attempt a restore when ingress is disabled", async () => {
+    loadRawConfigMock.mockReturnValue({ ingress: { enabled: false } });
+
+    await wake();
+
+    expect(isAssistantFeatureFlagEnabledMock).not.toHaveBeenCalled();
+    expect(startRemoteWebIngressMock).not.toHaveBeenCalled();
+  });
+
+  test("does not attempt a restore when ingress config is absent", async () => {
+    loadRawConfigMock.mockReturnValue({});
+
+    await wake();
+
+    expect(isAssistantFeatureFlagEnabledMock).not.toHaveBeenCalled();
+    expect(startRemoteWebIngressMock).not.toHaveBeenCalled();
+  });
+
+  test("does not attempt a restore when enabled but the public URL is missing", async () => {
+    loadRawConfigMock.mockReturnValue({ ingress: { enabled: true } });
+
+    await wake();
+
+    expect(isAssistantFeatureFlagEnabledMock).not.toHaveBeenCalled();
+    expect(startRemoteWebIngressMock).not.toHaveBeenCalled();
+  });
+
+  test("does not start a second edge when one is already running", async () => {
+    loadRawConfigMock.mockReturnValue(enabledConfig);
+    isIngressRunningMock.mockReturnValue(true);
+
+    await wake();
+
+    // Already up — skip the flag probe and the start entirely.
+    expect(isAssistantFeatureFlagEnabledMock).not.toHaveBeenCalled();
+    expect(startRemoteWebIngressMock).not.toHaveBeenCalled();
+  });
+
+  test("skips the restore quietly with a hint when the flag is off", async () => {
+    loadRawConfigMock.mockReturnValue(enabledConfig);
+    isAssistantFeatureFlagEnabledMock.mockResolvedValue(false);
+
+    await wake();
+
+    expect(startRemoteWebIngressMock).not.toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining("web-remote-ingress"),
+    );
+    expect(logSpy).toHaveBeenCalledWith("Wake complete.");
+  });
+
+  test("a thrown restore failure warns but does not fail the wake", async () => {
+    loadRawConfigMock.mockReturnValue(enabledConfig);
+    startRemoteWebIngressMock.mockRejectedValue(new Error("nginx boom"));
+
+    await wake();
+
+    expect(startRemoteWebIngressMock).toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith("Wake complete.");
+  });
+
+  test("an unreachable edge warns but does not fail the wake", async () => {
+    loadRawConfigMock.mockReturnValue(enabledConfig);
+    startRemoteWebIngressMock.mockResolvedValue({
+      status: "unreachable",
+      listenPort: 7840,
+      logPath: "/tmp/nginx-ingress.log",
+    });
+
+    await wake();
+
+    expect(warnSpy).toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith("Wake complete.");
+  });
+
+  test("a failed flag probe warns and leaves the edge down without failing the wake", async () => {
+    loadRawConfigMock.mockReturnValue(enabledConfig);
+    isAssistantFeatureFlagEnabledMock.mockRejectedValue(
+      new Error("gateway unreachable"),
+    );
+
+    await wake();
+
+    expect(startRemoteWebIngressMock).not.toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith("Wake complete.");
+  });
+});

package/src/commands/nginx-ingress.ts

@@ -14,22 +14,16 @@ 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,
-  startIngressNginx,
+  startRemoteWebIngress,
   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("");
@@ -164,79 +158,71 @@ async function assertWebRemoteIngressEnabled(
 
 async function up(target: NginxIngressTarget): Promise<void> {
   const { workspaceDir, gatewayPort } = target;
-  const listenPort = getNginxIngressPort();
 
   await assertWebRemoteIngressEnabled(target);
 
-  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({
+  const result = await startRemoteWebIngress({
     workspaceDir,
     gatewayPort,
-    listenPort,
-    remoteWebIngress: { webDistDir },
+    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}...`,
+      );
+    },
   });
-  child.unref();
 
-  // /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);
+  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;
   }
 
-  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");
+  process.exit(1);
 }
 
 async function down(target: NginxIngressTarget): Promise<void> {

package/src/commands/wake.ts

@@ -30,6 +30,15 @@ import {
   startGateway,
 } from "../lib/local";
 import { maybeStartNgrokTunnel } from "../lib/ngrok";
+import {
+  isAssistantFeatureFlagEnabled,
+  WEB_REMOTE_INGRESS_FLAG,
+} from "../lib/feature-flags.js";
+import { loadRawConfig } from "../lib/ingress-config.js";
+import {
+  isIngressRunning,
+  startRemoteWebIngress,
+} from "../lib/nginx-ingress.js";
 
 export async function wake(): Promise<void> {
   const args = process.argv.slice(3);
@@ -379,6 +388,17 @@ export async function wake(): Promise<void> {
     writeFileSync(ngrokPidFile, String(ngrokChild.pid));
   }
 
+  // Restore the nginx web ingress edge when the workspace config still wants
+  // it. A TLS-terminating front (tailscale serve / tunnel) persists across
+  // restarts and keeps proxying to the edge's loopback port, but the edge has
+  // a manual lifecycle — so a routine restart otherwise leaves the self-hosted
+  // remote-web path dead (502 / blank page) until someone runs it back up.
+  await restoreWebIngressIfEnabled(
+    entry.assistantId,
+    resources.gatewayPort,
+    workspaceDir,
+  );
+
   if (daemonMigrationsFailed) {
     console.log(
       "Assistant database migrations FAILED — DB-backed routes will return 503 until the assistant is restarted. Check the daemon logs.",
@@ -404,3 +424,101 @@ export async function wake(): Promise<void> {
     });
   }
 }
+
+/**
+ * Bring the nginx web ingress edge back up after a wake when the workspace
+ * config still wants it. Only restores when ingress is explicitly enabled with
+ * a saved public URL and the `web-remote-ingress` flag is on — the edge is
+ * pointless without the flag, so a disabled flag skips quietly with a hint.
+ *
+ * Reads the same workspace config the edge serves. Any failure to restore
+ * warns with the manual `vellum nginx-ingress up` command and never fails the
+ * wake — a down edge is a degraded remote-web path, not a broken assistant.
+ */
+async function restoreWebIngressIfEnabled(
+  assistantId: string,
+  gatewayPort: number,
+  workspaceDir: string,
+): Promise<void> {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = config.ingress as
+    | { enabled?: unknown; publicBaseUrl?: unknown }
+    | undefined;
+  const enabled = ingress?.enabled === true;
+  const publicBaseUrl =
+    typeof ingress?.publicBaseUrl === "string"
+      ? ingress.publicBaseUrl.trim()
+      : "";
+  if (!enabled || !publicBaseUrl) {
+    return;
+  }
+
+  // The edge already survived (or was manually brought back) — nothing to do.
+  if (isIngressRunning(workspaceDir)) {
+    return;
+  }
+
+  let flagEnabled: boolean;
+  try {
+    flagEnabled = await isAssistantFeatureFlagEnabled(
+      assistantId,
+      WEB_REMOTE_INGRESS_FLAG,
+      { runtimeUrl: `http://127.0.0.1:${gatewayPort}` },
+    );
+  } catch (err) {
+    console.warn(
+      `   Could not verify the \`${WEB_REMOTE_INGRESS_FLAG}\` flag to restore the web ingress edge; leaving it down. Bring it up manually with \`vellum nginx-ingress up\`. ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return;
+  }
+  if (!flagEnabled) {
+    console.log(
+      `   Web ingress edge not restored: the \`${WEB_REMOTE_INGRESS_FLAG}\` flag is off. Enable it and run \`vellum nginx-ingress up\` to serve remote web access.`,
+    );
+    return;
+  }
+
+  try {
+    const result = await startRemoteWebIngress({
+      workspaceDir,
+      gatewayPort,
+      onStarting: ({ listenPort }) => {
+        console.log(
+          `Restoring web ingress edge on 127.0.0.1:${listenPort} (ingress.enabled)...`,
+        );
+      },
+    });
+    switch (result.status) {
+      case "started":
+        console.log(
+          `   Web ingress edge running: http://127.0.0.1:${result.listenPort}`,
+        );
+        break;
+      case "already-running":
+        break;
+      case "nginx-missing":
+        console.warn(
+          "   Could not restore the web ingress edge: nginx is not installed. Bring it up manually with `vellum nginx-ingress up`.",
+        );
+        break;
+      case "web-dist-missing":
+        console.warn(
+          "   Could not restore the web ingress edge: built web assets were not found. Bring it up manually with `vellum nginx-ingress up`.",
+        );
+        break;
+      case "unreachable":
+        console.warn(
+          `   Web ingress edge did not become reachable on 127.0.0.1:${result.listenPort}; check ${result.logPath}. Bring it up manually with \`vellum nginx-ingress up\`.`,
+        );
+        break;
+    }
+  } catch (err) {
+    console.warn(
+      `   Failed to restore the web ingress edge: ${
+        err instanceof Error ? err.message : String(err)
+      }. Bring it up manually with \`vellum nginx-ingress up\`.`,
+    );
+  }
+}

package/src/lib/nginx-ingress.ts

@@ -17,6 +17,7 @@ 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";
 
 /**
@@ -540,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