@vellumai/cli 0.10.11-dev.202607220509.38c4eff → 0.10.11-dev.202607220859.296f4b0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.11-dev.202607220509.38c4eff",
+  "version": "0.10.11-dev.202607220859.296f4b0",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/flags.test.ts

@@ -188,14 +188,7 @@ describe("vellum flags --assistant routing", () => {
       ],
       "alice-1",
     );
-    process.argv = [
-      "bun",
-      "vellum",
-      "flags",
-      "set",
-      "voice-mode",
-      "true",
-    ];
+    process.argv = ["bun", "vellum", "flags", "set", "voice-mode", "true"];
 
     await flags();
 

package/src/__tests__/input-history.test.ts

@@ -1,10 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import {
-  existsSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync,
-} from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 

package/src/__tests__/login-loopback.test.ts

@@ -3,7 +3,9 @@ import { describe, expect, test } from "bun:test";
 import { startLoopbackListener } from "../commands/login.js";
 
 /** Resolve "settled"/"pending" — proves whether `waitForCode` resolved. */
-async function settleState(p: Promise<unknown>): Promise<"settled" | "pending"> {
+async function settleState(
+  p: Promise<unknown>,
+): Promise<"settled" | "pending"> {
   return Promise.race([
     p.then(
       () => "settled" as const,
@@ -49,7 +51,9 @@ describe("startLoopbackListener", () => {
         () => null,
         (e: Error) => e,
       );
-      const res = await fetch(`${listener.redirectUri}?error=access_denied&state=st`);
+      const res = await fetch(
+        `${listener.redirectUri}?error=access_denied&state=st`,
+      );
       expect(res.status).toBe(400);
       const err = await settled;
       expect(err?.message).toMatch(/access_denied/);

package/src/__tests__/pair.test.ts

@@ -15,7 +15,7 @@ import { join } from "node:path";
 const testDir = mkdtempSync(join(tmpdir(), "pair-command-test-"));
 process.env.VELLUM_LOCKFILE_DIR = testDir;
 
-import { pair } from "../commands/pair.js";
+import { buildAppConnectUrl, pair } from "../commands/pair.js";
 
 // Distinct loopback (mint) vs reachable (advertised) URLs to verify the split.
 const LOCAL_URL = "http://127.0.0.1:7830";
@@ -800,4 +800,135 @@ describe("pair command", () => {
       `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`,
     );
   });
+
+  test("buildAppConnectUrl composes and encodes the connect link", () => {
+    expect(
+      buildAppConnectUrl(
+        "vellum-assistant",
+        "https://pair.example.ts.net",
+        "device-code",
+      ),
+    ).toBe(
+      "vellum-assistant://connect?url=https%3A%2F%2Fpair.example.ts.net&code=device-code",
+    );
+    // Path prefixes and fragment-hostile characters survive the encoding.
+    expect(
+      buildAppConnectUrl(
+        "vellum-assistant-dev",
+        "https://host.example.ts.net/assistant-123",
+        "a+b/c=",
+      ),
+    ).toBe(
+      "vellum-assistant-dev://connect?url=https%3A%2F%2Fhost.example.ts.net%2Fassistant-123&code=a%2Bb%2Fc%3D",
+    );
+  });
+
+  test("--qr --app emits an app connect URL alongside the browser URL", async () => {
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string) => {
+      if (url === `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`) {
+        return new Response(
+          JSON.stringify({
+            flags: [{ key: "web-remote-ingress", enabled: true }],
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      if (url === `${LOCAL_URL}/v1/remote-web/pairing-challenge`) {
+        return new Response(
+          JSON.stringify({
+            deviceCode: "device-code",
+            userCode: "ABCD-EFGH",
+            verificationUri: "https://pair.example.ts.net/assistant/pair",
+            expiresAt: "2026-06-04T00:10:00.000Z",
+            expiresInSeconds: 600,
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      if (url === `${LOCAL_URL}/v1/remote-web/pairing-verification`) {
+        return new Response(
+          JSON.stringify({
+            status: "approved",
+            verificationUri: "https://pair.example.ts.net/assistant/pair",
+            expiresAt: "2026-06-04T00:10:00.000Z",
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      return new Response("not found", { status: 404 });
+    }) as unknown as typeof fetch;
+
+    const logs: string[] = [];
+    const logSpy = spyOn(console, "log").mockImplementation(
+      (...a: unknown[]) => {
+        logs.push(a.join(" "));
+      },
+    );
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "pair",
+      "--qr",
+      "--app",
+      "--app-scheme",
+      "vellum-assistant-dev",
+      "--url",
+      "https://pair.example.ts.net",
+      "--json",
+    ];
+    try {
+      await pair();
+    } finally {
+      logSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    const out = JSON.parse(logs.join("\n"));
+    expect(out.appUrl).toBe(
+      "vellum-assistant-dev://connect?url=https%3A%2F%2Fpair.example.ts.net&code=device-code",
+    );
+    // The browser URL stays available as the no-app fallback.
+    expect(out.pairUrl).toBe(
+      "https://pair.example.ts.net/assistant/pair#device_code=device-code",
+    );
+    expect(out.deviceCode).toBe("device-code");
+  });
+
+  test("--app without --qr is refused", async () => {
+    let fetchCalled = false;
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async () => {
+      fetchCalled = true;
+      return new Response("{}", { status: 200 });
+    }) as unknown as typeof fetch;
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation(
+      (...a: unknown[]) => {
+        errors.push(a.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    process.argv = ["bun", "vellum", "pair", "--app"];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    expect(exited).toBe(true);
+    expect(errors.join("\n")).toContain("--qr");
+    expect(fetchCalled).toBe(false);
+  });
 });

package/src/__tests__/platform-client.test.ts

@@ -240,7 +240,11 @@ describe("fetchAssistantDetail / fetchUpgradeInProgress", () => {
       current_release_version: "0.7.0",
       release_channel: "preview",
     });
-    const detail = await fetchAssistantDetail(TOKEN, ASSISTANT_ID, PLATFORM_URL);
+    const detail = await fetchAssistantDetail(
+      TOKEN,
+      ASSISTANT_ID,
+      PLATFORM_URL,
+    );
     expect(detail).toEqual({
       currentReleaseVersion: "0.7.0",
       releaseChannel: "preview",
@@ -251,7 +255,11 @@ describe("fetchAssistantDetail / fetchUpgradeInProgress", () => {
 
   test("fetchAssistantDetail defaults missing fields", async () => {
     mockFetchJson({});
-    const detail = await fetchAssistantDetail(TOKEN, ASSISTANT_ID, PLATFORM_URL);
+    const detail = await fetchAssistantDetail(
+      TOKEN,
+      ASSISTANT_ID,
+      PLATFORM_URL,
+    );
     expect(detail).toEqual({
       currentReleaseVersion: null,
       releaseChannel: "stable",

package/src/__tests__/statefulset.test.ts

@@ -56,7 +56,9 @@ describe("getBuilderManagedEnvKeys", () => {
 
   test("gateway hostForwarded equals the three spec host entries", () => {
     const { hostForwarded } = getBuilderManagedEnvKeys("gateway");
-    const sorted = [...hostForwarded].sort((a, b) => a.name.localeCompare(b.name));
+    const sorted = [...hostForwarded].sort((a, b) =>
+      a.name.localeCompare(b.name),
+    );
     expect(sorted).toEqual([
       { name: "VELAY_BASE_URL", hostVar: "VELAY_BASE_URL" },
       { name: "VELLUM_ENVIRONMENT", hostVar: "VELLUM_ENVIRONMENT" },

package/src/__tests__/tailscale-tunnel.test.ts

@@ -0,0 +1,229 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  normalizeDnsName,
+  resolveServeHostname,
+  shouldClearIngressUrl,
+  startTailscaleServe,
+  stopTailscaleServe,
+  type TailscaleCommandResult,
+  type TailscaleDeps,
+} from "../lib/tailscale-tunnel.js";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const tempDirs: string[] = [];
+
+function makeWorkspace(): string {
+  const dir = mkdtempSync(join(tmpdir(), "vellum-tailscale-test-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+const RUNNING_STATUS = JSON.stringify({
+  BackendState: "Running",
+  Self: { DNSName: "my-host.tail-scale.ts.net.", Online: true },
+});
+
+const ok = (stdout = "", stderr = ""): TailscaleCommandResult => ({
+  status: 0,
+  stdout,
+  stderr,
+});
+
+/**
+ * Build a fake {@link TailscaleDeps}. `binary` defaults to a present binary;
+ * pass `null` to simulate a missing install. `responses` is keyed by the
+ * space-joined args; unmatched calls return an empty success result.
+ */
+function makeDeps(opts: {
+  binary?: string | null;
+  responses?: Record<string, TailscaleCommandResult>;
+}): { deps: TailscaleDeps; calls: string[][] } {
+  const calls: string[][] = [];
+  const binary = opts.binary === undefined ? "tailscale" : opts.binary;
+  const deps: TailscaleDeps = {
+    findBinary: () => binary,
+    run: (_bin, args) => {
+      calls.push(args);
+      return opts.responses?.[args.join(" ")] ?? ok();
+    },
+  };
+  return { deps, calls };
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ── normalizeDnsName ────────────────────────────────────────────────────────
+
+describe("normalizeDnsName", () => {
+  test("trims the trailing MagicDNS dot", () => {
+    expect(normalizeDnsName("host.tailnet.ts.net.")).toBe(
+      "host.tailnet.ts.net",
+    );
+  });
+
+  test("leaves a name without a trailing dot unchanged", () => {
+    expect(normalizeDnsName("host.tailnet.ts.net")).toBe("host.tailnet.ts.net");
+  });
+});
+
+// ── resolveServeHostname ──────────────────────────────────────────────────────
+
+describe("resolveServeHostname", () => {
+  test("returns the trimmed Self.DNSName for a running node", () => {
+    expect(resolveServeHostname(RUNNING_STATUS)).toBe(
+      "my-host.tail-scale.ts.net",
+    );
+  });
+
+  test("throws a login hint when logged out", () => {
+    const json = JSON.stringify({ BackendState: "NeedsLogin", Self: {} });
+    expect(() => resolveServeHostname(json)).toThrow("not logged in");
+  });
+
+  test("throws when the backend is not running", () => {
+    const json = JSON.stringify({
+      BackendState: "Stopped",
+      Self: { DNSName: "host.ts.net." },
+    });
+    expect(() => resolveServeHostname(json)).toThrow("not ready");
+  });
+
+  test("throws when the DNS name is missing", () => {
+    const json = JSON.stringify({ BackendState: "Running", Self: {} });
+    expect(() => resolveServeHostname(json)).toThrow("DNS name");
+  });
+
+  test("throws on unparseable JSON", () => {
+    expect(() => resolveServeHostname("not json")).toThrow("Could not parse");
+  });
+});
+
+// ── startTailscaleServe ───────────────────────────────────────────────────────
+
+describe("startTailscaleServe", () => {
+  test("throws install guidance when the binary is missing", async () => {
+    const { deps, calls } = makeDeps({ binary: null });
+    await expect(
+      startTailscaleServe({ port: 7840, workspaceDir: makeWorkspace() }, deps),
+    ).rejects.toThrow("Tailscale is not installed");
+    expect(calls).toHaveLength(0);
+  });
+
+  test("throws a login hint when logged out and never calls serve", async () => {
+    const { deps, calls } = makeDeps({
+      responses: {
+        "status --json": ok(
+          JSON.stringify({ BackendState: "NeedsLogin", Self: {} }),
+        ),
+      },
+    });
+    await expect(
+      startTailscaleServe({ port: 7840, workspaceDir: makeWorkspace() }, deps),
+    ).rejects.toThrow("not logged in");
+    expect(calls).not.toContainEqual(["serve", "--bg", "7840"]);
+  });
+
+  test("throws when the status query fails (daemon down)", async () => {
+    const { deps } = makeDeps({
+      responses: {
+        "status --json": {
+          status: 1,
+          stdout: "",
+          stderr: "failed to connect to local tailscaled",
+        },
+      },
+    });
+    await expect(
+      startTailscaleServe({ port: 7840, workspaceDir: makeWorkspace() }, deps),
+    ).rejects.toThrow("Could not query Tailscale");
+  });
+
+  test("serves the target port and persists the ingress URL on success", async () => {
+    const workspaceDir = makeWorkspace();
+    const { deps, calls } = makeDeps({
+      responses: {
+        "status --json": ok(RUNNING_STATUS),
+        "serve --bg 7840": ok(),
+      },
+    });
+
+    const info = await startTailscaleServe({ port: 7840, workspaceDir }, deps);
+
+    expect(info.publicUrl).toBe("https://my-host.tail-scale.ts.net");
+    expect(info.port).toBe(7840);
+    expect(info.viaIngress).toBe(false);
+    expect(calls).toContainEqual(["serve", "--bg", "7840"]);
+
+    const config = JSON.parse(
+      readFileSync(join(workspaceDir, "config.json"), "utf-8"),
+    );
+    expect(config.ingress.publicBaseUrl).toBe(
+      "https://my-host.tail-scale.ts.net",
+    );
+    expect(config.ingress.enabled).toBe(true);
+  });
+
+  test("surfaces tailscale's enable-URL guidance when serve is not enabled", async () => {
+    const workspaceDir = makeWorkspace();
+    const enableUrl = "https://login.tailscale.com/f/serve?node=abc123";
+    const { deps } = makeDeps({
+      responses: {
+        "status --json": ok(RUNNING_STATUS),
+        "serve --bg 7840": {
+          status: 1,
+          stdout: "",
+          stderr: `error: Serve is not enabled on your tailnet.\n\nTo enable, visit:\n  ${enableUrl}`,
+        },
+      },
+    });
+
+    await expect(
+      startTailscaleServe({ port: 7840, workspaceDir }, deps),
+    ).rejects.toThrow(enableUrl);
+
+    // A failed serve must not persist an ingress URL.
+    expect(existsSync(join(workspaceDir, "config.json"))).toBe(false);
+  });
+});
+
+// ── stopTailscaleServe ────────────────────────────────────────────────────────
+
+describe("stopTailscaleServe", () => {
+  test("turns off the HTTPS:443 serve (narrow off form)", () => {
+    const { deps, calls } = makeDeps({
+      responses: { "serve --https=443 off": ok() },
+    });
+    const result = stopTailscaleServe("tailscale", deps);
+    expect(result.status).toBe(0);
+    expect(calls).toContainEqual(["serve", "--https=443", "off"]);
+  });
+});
+
+// ── shouldClearIngressUrl ─────────────────────────────────────────────────────
+
+describe("shouldClearIngressUrl", () => {
+  test("clears only after a confirmed successful stop", () => {
+    expect(shouldClearIngressUrl({ status: 0, stdout: "", stderr: "" })).toBe(
+      true,
+    );
+  });
+
+  test("keeps the URL when the stop command fails", () => {
+    expect(
+      shouldClearIngressUrl({ status: 1, stdout: "", stderr: "boom" }),
+    ).toBe(false);
+  });
+
+  test("keeps the URL when the stop command threw before running", () => {
+    expect(shouldClearIngressUrl(null)).toBe(false);
+  });
+});

package/src/__tests__/wake.test.ts

@@ -27,9 +27,8 @@ const realLocal = { ...local };
 const realNgrok = { ...ngrok };
 const realProcessLib = { ...processLib };
 
-const resolveTargetAssistantMock = mock<
-  typeof assistantConfig.resolveTargetAssistant
->();
+const resolveTargetAssistantMock =
+  mock<typeof assistantConfig.resolveTargetAssistant>();
 const saveAssistantEntryMock = mock<typeof assistantConfig.saveAssistantEntry>(
   () => {},
 );
@@ -61,9 +60,10 @@ const seedGuardianTokenFromSiblingEnvMock = mock<
 // Default: a token exists, so the re-provision recovery path is skipped. Tests
 // that exercise recovery override loadGuardianToken to return null.
 const loadGuardianTokenMock = mock<typeof guardianToken.loadGuardianToken>(
-  () => ({ accessToken: "existing" }) as ReturnType<
-    typeof guardianToken.loadGuardianToken
-  >,
+  () =>
+    ({ accessToken: "existing" }) as ReturnType<
+      typeof guardianToken.loadGuardianToken
+    >,
 );
 const resetGuardianBootstrapMock = mock<
   typeof guardianToken.resetGuardianBootstrap
@@ -111,7 +111,9 @@ const isAssistantWatchModeAvailableMock = mock<
 const isGatewayWatchModeAvailableMock = mock<
   typeof local.isGatewayWatchModeAvailable
 >(() => false);
-const startLocalDaemonMock = mock<typeof local.startLocalDaemon>(async () => {});
+const startLocalDaemonMock = mock<typeof local.startLocalDaemon>(
+  async () => {},
+);
 const startGatewayMock = mock<typeof local.startGateway>(
   async () => "http://127.0.0.1:7830",
 );
@@ -175,10 +177,12 @@ beforeEach(() => {
     join(resources!.instanceDir, ".vellum", "daemon.pid"),
   );
   resolveProcessStateMock.mockReset();
-  resolveProcessStateMock.mockImplementation(async (_pidFile, _port, label) => ({
-    status: "healthy",
-    pid: label === "Gateway" ? 456 : 123,
-  }));
+  resolveProcessStateMock.mockImplementation(
+    async (_pidFile, _port, label) => ({
+      status: "healthy",
+      pid: label === "Gateway" ? 456 : 123,
+    }),
+  );
   stopProcessByPidFileMock.mockReset();
   stopProcessByPidFileMock.mockResolvedValue(true);
   generateLocalSigningKeyMock.mockReset();
@@ -198,9 +202,9 @@ beforeEach(() => {
   seedGuardianTokenFromSiblingEnvMock.mockReset();
   seedGuardianTokenFromSiblingEnvMock.mockReturnValue(false);
   loadGuardianTokenMock.mockReset();
-  loadGuardianTokenMock.mockReturnValue({ accessToken: "existing" } as ReturnType<
-    typeof guardianToken.loadGuardianToken
-  >);
+  loadGuardianTokenMock.mockReturnValue({
+    accessToken: "existing",
+  } as ReturnType<typeof guardianToken.loadGuardianToken>);
   resetGuardianBootstrapMock.mockReset();
   resetGuardianBootstrapMock.mockResolvedValue(undefined);
   leaseGuardianTokenMock.mockReset();
@@ -252,7 +256,13 @@ describe("vellum wake", () => {
   });
 
   test("re-provisions the guardian token when missing and --repair-guardian is passed", async () => {
-    process.argv = ["bun", "vellum", "wake", "--repair-guardian", "local-assistant"];
+    process.argv = [
+      "bun",
+      "vellum",
+      "wake",
+      "--repair-guardian",
+      "local-assistant",
+    ];
     loadGuardianTokenMock.mockReturnValue(null);
 
     await wake();
@@ -288,7 +298,13 @@ describe("vellum wake", () => {
     // (revoked, mis-seeded, wrong principal). The user explicitly confirmed
     // the destructive repair, so the flag forces a re-lease instead of
     // guessing from local token state and recreating the no-op loop.
-    process.argv = ["bun", "vellum", "wake", "--repair-guardian", "local-assistant"];
+    process.argv = [
+      "bun",
+      "vellum",
+      "wake",
+      "--repair-guardian",
+      "local-assistant",
+    ];
     // loadGuardianToken returns a healthy-looking token by default.
     await wake();
 

package/src/commands/backup.ts

@@ -134,15 +134,18 @@ export async function backup(): Promise<void> {
   // Call the export endpoint
   let response: Response;
   try {
-    response = await loopbackSafeFetch(`${entry.runtimeUrl}/v1/migrations/export`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${accessToken}`,
-        "Content-Type": "application/json",
+    response = await loopbackSafeFetch(
+      `${entry.runtimeUrl}/v1/migrations/export`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ description: "CLI backup" }),
+        signal: AbortSignal.timeout(exportTimeoutMs),
       },
-      body: JSON.stringify({ description: "CLI backup" }),
-      signal: AbortSignal.timeout(exportTimeoutMs),
-    });
+    );
 
     // Retry once with a fresh token on 401 — the cached token may be stale
     // after a container restart that generated a new gateway signing key.
@@ -160,15 +163,18 @@ export async function backup(): Promise<void> {
       }
       if (refreshedToken) {
         accessToken = refreshedToken;
-        response = await loopbackSafeFetch(`${entry.runtimeUrl}/v1/migrations/export`, {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${accessToken}`,
-            "Content-Type": "application/json",
+        response = await loopbackSafeFetch(
+          `${entry.runtimeUrl}/v1/migrations/export`,
+          {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${accessToken}`,
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ description: "CLI backup" }),
+            signal: AbortSignal.timeout(exportTimeoutMs),
           },
-          body: JSON.stringify({ description: "CLI backup" }),
-          signal: AbortSignal.timeout(exportTimeoutMs),
-        });
+        );
       }
     }
   } catch (err) {

package/src/commands/exec.ts

@@ -220,7 +220,11 @@ 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;
     }