@vellumai/cli 0.10.12-staging.1 → 0.10.12-staging.3

package/node_modules/@vellumai/local-mode/src/lockfile-contract.test.ts

@@ -24,6 +24,7 @@ describe("parseLockfile", () => {
           platformAssistantId: "platform-assistant-1",
           platformBaseUrl: "https://platform.example.com",
           platformOrganizationId: "org_1",
+          ingressUrl: "https://tunnel.example.ts.net",
           resources: { gatewayPort: 7777, daemonPort: 7778 },
         },
       ],
@@ -186,6 +187,30 @@ describe("parseLockfile", () => {
     ]);
   });
 
+  test("keeps a well-typed ingressUrl and drops it when mistyped", () => {
+    // The tunnel-recorded public URL rides the entry so remote-web pairing
+    // surfaces can prefill it; a mistyped value is dropped, entry preserved.
+    const raw = {
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          ingressUrl: "https://tunnel.example.ts.net",
+        },
+        { assistantId: "asst_2", cloud: "local", ingressUrl: 7 }, // mistyped
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([
+      {
+        assistantId: "asst_1",
+        cloud: "local",
+        ingressUrl: "https://tunnel.example.ts.net",
+      },
+      { assistantId: "asst_2", cloud: "local" },
+    ]);
+  });
+
   test("drops a resources object missing its numeric ports", () => {
     const raw = {
       assistants: [

package/node_modules/@vellumai/local-mode/src/lockfile-contract.ts

@@ -115,6 +115,13 @@ export const LockfileAssistantSchema = z.object({
   platformBaseUrl: z.string().optional(),
   /** Platform organization UUID used for a self-hosted local assistant registration. */
   platformOrganizationId: z.string().optional(),
+  /**
+   * Public https URL a `vellum tunnel` provider recorded for this assistant
+   * (mirrored from the workspace ingress config). A public address, so it is
+   * renderer-safe: remote-web pairing surfaces (the CLI `--qr` flow, the web
+   * "Pair a device" card) default to it instead of asking the user to retype it.
+   */
+  ingressUrl: z.string().optional(),
   resources: LocalAssistantResourcesSchema.optional(),
 });
 

package/node_modules/@vellumai/local-mode/src/lockfile.test.ts

@@ -81,6 +81,30 @@ describe("getLockfileData", () => {
     }
   });
 
+  test("surfaces a tunnel-recorded ingressUrl to the renderer", () => {
+    // The exact read the "Pair a device" card relies on: `vellum tunnel` stamps
+    // ingressUrl onto the entry, and the host read must carry it through.
+    writeOnDisk({
+      activeAssistant: "asst_1",
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          runtimeUrl: "http://127.0.0.1:7777",
+          ingressUrl: "https://tunnel.example.ts.net",
+        },
+      ],
+    });
+
+    const result = getLockfileData([lockfilePath]);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data.assistants[0]?.ingressUrl).toBe(
+        "https://tunnel.example.ts.net",
+      );
+    }
+  });
+
   test("fails with status 500 on malformed JSON", () => {
     fs.writeFileSync(lockfilePath, "{ not json");
     const result = getLockfileData([lockfilePath]);

package/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -109,12 +109,77 @@ export type RemoteWebPairingTokenResponse =
 // only) so both Node and browser callers share one implementation.
 
 /** Why a public base URL can't be advertised in a pairing challenge. */
-export type PublicBaseUrlRejection = "unparseable" | "loopback" | "non-https";
+export type PublicBaseUrlRejection =
+  | "unparseable"
+  | "loopback"
+  | "non-https"
+  | "service-website";
 
 export type PublicBaseUrlResult =
   | { ok: true; url: string }
   | { ok: false; reason: PublicBaseUrlRejection };
 
+/**
+ * Hosts that are a tunnel/ingress vendor's own website, not a user's assistant
+ * endpoint. These are the tunnel vendors our docs mention, and their sites are
+ * exactly where a lost user grabs a URL from — e.g. a Tailscale admin invite
+ * link (`login.tailscale.com/admin/invite/…`), which is https and non-loopback
+ * and so clears every other check. Pairing refuses them with a targeted message
+ * rather than minting a challenge the scanning device can never reach.
+ */
+export const TUNNEL_PROVIDER_WEBSITE_HOSTS = [
+  "login.tailscale.com",
+  "tailscale.com",
+  "www.tailscale.com",
+  "ngrok.com",
+  "dashboard.ngrok.com",
+  "dash.cloudflare.com",
+  "cloudflare.com",
+  "www.cloudflare.com",
+] as const;
+
+/**
+ * A URL whose exact host is a tunnel/ingress vendor's own website (see
+ * {@link TUNNEL_PROVIDER_WEBSITE_HOSTS}). Exact-host only: a user's real
+ * Tailscale endpoint (`*.ts.net`) or Cloudflare-fronted domain is never a
+ * listed host, so a legitimate address is never mistaken for a vendor site.
+ */
+export function isTunnelProviderWebsiteUrl(url: string): boolean {
+  let hostname: string;
+  try {
+    // WHATWG URL lowercases the hostname during parsing.
+    hostname = new URL(url).hostname;
+  } catch {
+    return false;
+  }
+  return (TUNNEL_PROVIDER_WEBSITE_HOSTS as readonly string[]).includes(
+    hostname,
+  );
+}
+
+/**
+ * The display name of the tunnel/ingress vendor a service-website URL points
+ * at (`"Tailscale"` / `"ngrok"` / `"Cloudflare"`), or null when the host is not
+ * a known vendor site. Drives the "This is <Name>'s website" pairing guidance.
+ */
+export function tunnelProviderWebsiteName(url: string): string | null {
+  let hostname: string;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return null;
+  }
+  if (
+    !(TUNNEL_PROVIDER_WEBSITE_HOSTS as readonly string[]).includes(hostname)
+  ) {
+    return null;
+  }
+  if (hostname.includes("tailscale")) return "Tailscale";
+  if (hostname.includes("ngrok")) return "ngrok";
+  if (hostname.includes("cloudflare")) return "Cloudflare";
+  return null;
+}
+
 /**
  * A loopback URL — `localhost`, `[::1]`, or `127.x.x.x`. A pairing link that
  * encodes a loopback address is unreachable from the scanning device.
@@ -167,6 +232,9 @@ export function resolvePublicBaseUrl(raw: string): PublicBaseUrlResult {
   if (isLoopbackPublicUrl(normalized)) {
     return { ok: false, reason: "loopback" };
   }
+  if (isTunnelProviderWebsiteUrl(normalized)) {
+    return { ok: false, reason: "service-website" };
+  }
   if (new URL(normalized).protocol !== "https:") {
     return { ok: false, reason: "non-https" };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.12-staging.1",
+  "version": "0.10.12-staging.3",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/assistant-config.test.ts

@@ -1,5 +1,19 @@
-import { describe, test, expect, beforeEach, afterAll } from "bun:test";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  describe,
+  test,
+  expect,
+  beforeEach,
+  afterEach,
+  afterAll,
+  spyOn,
+} from "bun:test";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -16,6 +30,7 @@ import {
   lookupAssistantByIdentifier,
   removeAssistantEntry,
   loadAllAssistants,
+  resolveTargetAssistant,
   saveAssistantEntry,
   getActiveAssistant,
   migrateLegacyEntry,
@@ -700,3 +715,104 @@ describe("env-scoped lockfile and migration", () => {
     }
   });
 });
+
+describe("cross-environment hint on resolution failure", () => {
+  let dataHome: string;
+  let prevXdg: string | undefined;
+  let prevEnv: string | undefined;
+
+  beforeEach(() => {
+    prevXdg = process.env.XDG_DATA_HOME;
+    prevEnv = process.env.VELLUM_ENVIRONMENT;
+    dataHome = mkdtempSync(join(tmpdir(), "cli-config-xdg-"));
+    process.env.XDG_DATA_HOME = dataHome;
+    // Pin the current env to production so the detector skips it and the hint
+    // copy is deterministic. The current-env lockfile is emptied so resolution
+    // genuinely finds nothing.
+    process.env.VELLUM_ENVIRONMENT = "production";
+    rmSync(join(testDir, ".vellum.lock.json"), { force: true });
+    rmSync(join(testDir, ".vellum.lockfile.json"), { force: true });
+  });
+
+  afterEach(() => {
+    if (prevXdg === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = prevXdg;
+    }
+    if (prevEnv === undefined) {
+      delete process.env.VELLUM_ENVIRONMENT;
+    } else {
+      process.env.VELLUM_ENVIRONMENT = prevEnv;
+    }
+    rmSync(dataHome, { recursive: true, force: true });
+  });
+
+  // A dev-env assistant lives under the dev data dir, invisible to this
+  // production CLI — the exact split the hint explains.
+  function seedDevAssistant(): void {
+    mkdirSync(join(dataHome, "vellum-dev", "assistants", "dev-bot"), {
+      recursive: true,
+    });
+  }
+
+  function captureResolveTargetAssistantError(): string {
+    const errors: string[] = [];
+    const errorSpy = spyOn(console, "error").mockImplementation(
+      (...args: unknown[]) => {
+        errors.push(args.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      _code?: number,
+    ) => {
+      throw new Error("exit");
+    }) as typeof process.exit);
+    try {
+      expect(() => resolveTargetAssistant()).toThrow("exit");
+    } finally {
+      errorSpy.mockRestore();
+      exitSpy.mockRestore();
+    }
+    return errors.join("\n");
+  }
+
+  test("formatAssistantLookupError appends the hint when another env has assistants", () => {
+    seedDevAssistant();
+    const msg = formatAssistantLookupError("ghost", { status: "not_found" });
+    expect(msg).toContain("No assistant found with name or ID 'ghost'.");
+    expect(msg).toContain("Install vellum Command");
+    expect(msg).toContain("VELLUM_ENVIRONMENT=dev");
+  });
+
+  test("formatAssistantLookupError stays bare when no other env has assistants", () => {
+    // dataHome is empty — detection finds nothing, so the message is intact.
+    const msg = formatAssistantLookupError("ghost", { status: "not_found" });
+    expect(msg).toBe("No assistant found with name or ID 'ghost'.");
+  });
+
+  test("ambiguous lookup never gets the hint", () => {
+    seedDevAssistant();
+    const msg = formatAssistantLookupError("Alice", {
+      status: "ambiguous",
+      matches: [
+        makeEntry("assistant-1", "http://localhost:7821", { name: "Alice" }),
+        makeEntry("assistant-2", "http://localhost:7822", { name: "Alice" }),
+      ],
+    });
+    expect(msg).not.toContain("Install vellum Command");
+  });
+
+  test("resolveTargetAssistant zero-assistants error carries the hint", () => {
+    seedDevAssistant();
+    const combined = captureResolveTargetAssistantError();
+    expect(combined).toContain("No assistant found. Run 'vellum hatch' first.");
+    expect(combined).toContain("Install vellum Command");
+  });
+
+  test("resolveTargetAssistant zero-assistants error stays bare without other envs", () => {
+    const combined = captureResolveTargetAssistantError();
+    expect(combined).toContain("No assistant found. Run 'vellum hatch' first.");
+    expect(combined).not.toContain("Install vellum Command");
+  });
+});

package/src/__tests__/flags.test.ts

@@ -239,3 +239,80 @@ describe("vellum flags --assistant routing", () => {
     expect(fetchCalls.length).toBe(0);
   });
 });
+
+describe("vellum flags cross-environment hint", () => {
+  let xdgDataHome: string;
+  let prevXdg: string | undefined;
+  let prevEnv: string | undefined;
+
+  beforeEach(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+    rmSync(join(testDir, ".vellum.lock.json"), { force: true });
+    prevXdg = process.env.XDG_DATA_HOME;
+    prevEnv = process.env.VELLUM_ENVIRONMENT;
+    xdgDataHome = mkdtempSync(join(tmpdir(), "cli-flags-hint-xdg-"));
+    process.env.XDG_DATA_HOME = xdgDataHome;
+    // Pin production so the detector skips it and the lockfile routes to
+    // testDir; the VELLUM_ENVIRONMENT var beats this machine's env config.
+    process.env.VELLUM_ENVIRONMENT = "production";
+    // An unreachable gateway: every request throws like a dead socket would.
+    // Cast through `unknown` since an always-throwing stub returns
+    // `Promise<never>`, which does not structurally overlap with `fetch`.
+    globalThis.fetch = (async () => {
+      throw new TypeError("fetch failed");
+    }) as unknown as typeof globalThis.fetch;
+    process.exit = ((code?: number) => {
+      throw new Error(`process.exit:${code}`);
+    }) as typeof process.exit;
+    consoleLogSpy = spyOn(console, "log").mockImplementation(() => {});
+    consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    process.argv = originalArgv;
+    process.exit = originalExit;
+    globalThis.fetch = originalFetch;
+    consoleLogSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+    if (prevXdg === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = prevXdg;
+    }
+    if (prevEnv === undefined) {
+      delete process.env.VELLUM_ENVIRONMENT;
+    } else {
+      process.env.VELLUM_ENVIRONMENT = prevEnv;
+    }
+    rmSync(xdgDataHome, { recursive: true, force: true });
+  });
+
+  // A dev-env assistant lives under the dev data dir, invisible to this
+  // production CLI — the split the hint explains.
+  function seedDevAssistant(): void {
+    mkdirSync(join(xdgDataHome, "vellum-dev", "assistants", "dev-bot"), {
+      recursive: true,
+    });
+  }
+
+  test("gateway-unreachable error gains the hint when another env has assistants", async () => {
+    writeLockfile([makeEntry("alice-1", { name: "Alice" })], "alice-1");
+    seedDevAssistant();
+    process.argv = ["bun", "vellum", "flags", "set", "voice-mode", "true"];
+    await expect(flags()).rejects.toThrow(/Install vellum Command/);
+  });
+
+  test("gateway-unreachable error stays bare when no other env has assistants", async () => {
+    writeLockfile([makeEntry("alice-1", { name: "Alice" })], "alice-1");
+    // xdgDataHome is empty — detection finds nothing, so the message is intact.
+    process.argv = ["bun", "vellum", "flags", "set", "voice-mode", "true"];
+    let error: Error | undefined;
+    try {
+      await flags();
+    } catch (e) {
+      error = e as Error;
+    }
+    expect(error?.message).toContain("Could not reach the assistant gateway");
+    expect(error?.message).not.toContain("Install vellum Command");
+  });
+});

package/src/__tests__/pair.test.ts

@@ -159,6 +159,100 @@ describe("pair command", () => {
     expect(fetchCalled).toBe(true);
   });
 
+  test("rejects an unknown --flag before any network call", 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", "--frobnicate"];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    // A `--` flag this version doesn't know is a hard error, and it points at
+    // the CLI self-update path — never a silent fall-through to another flow.
+    expect(exited).toBe(true);
+    const joined = errors.join("\n");
+    expect(joined).toContain("unknown option '--frobnicate'");
+    expect(joined).toContain("your CLI may be out of date");
+    expect(joined).toContain("bun install -g vellum@latest");
+    expect(fetchCalled).toBe(false);
+  });
+
+  test("rejects an unknown --flag even alongside a multi-word positional name", async () => {
+    writeFileSync(
+      join(testDir, ".vellum.lock.json"),
+      JSON.stringify({
+        assistants: [
+          {
+            assistantId: "pair-test",
+            name: "My Assistant",
+            runtimeUrl: RUNTIME_URL,
+            localUrl: LOCAL_URL,
+            cloud: "local",
+          },
+        ],
+        activeAssistant: "pair-test",
+      }),
+    );
+
+    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);
+
+    // Positional name tokens must not rescue an unknown flag from rejection.
+    process.argv = ["bun", "vellum", "pair", "My", "Assistant", "--frobnicate"];
+    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("unknown option '--frobnicate'");
+    expect(fetchCalled).toBe(false);
+  });
+
   test("refuses to advertise a loopback URL without --url (suggests the assistant's own port)", async () => {
     // Local hatch on a NON-default gateway port (e.g. a 2nd instance).
     const LOOPBACK_CUSTOM = "http://127.0.0.1:7842";
@@ -211,6 +305,11 @@ describe("pair command", () => {
     expect(errors.join("\n")).toContain(":7842");
     expect(errors.join("\n")).not.toContain(":7830");
 
+    // The refusal cross-points to the QR flow (the phone-pairing path) and its
+    // https prerequisite, so a user who wanted a QR isn't left at a dead end.
+    expect(errors.join("\n")).toContain("vellum pair --qr");
+    expect(errors.join("\n")).toContain("vellum tunnel --provider tailscale");
+
     // Exited with an error before minting — no token created for a dead URL.
     expect(exited).toBe(true);
     expect(fetchCalled).toBe(false);
@@ -748,6 +847,53 @@ describe("pair command", () => {
     expect(fetchCalled).toBe(false);
   });
 
+  test("--qr refuses a tunnel-provider website URL (Tailscale admin invite) without minting", 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",
+      "--qr",
+      "--url",
+      "https://login.tailscale.com/admin/invite/abc123",
+    ];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    // The admin-invite link is a vendor website — named as such, not mislabeled
+    // as non-https, and refused before any challenge is minted.
+    expect(exited).toBe(true);
+    const joined = errors.join("\n");
+    expect(joined).toContain("Tailscale's website");
+    expect(joined).not.toContain("is not https");
+    expect(fetchCalled).toBe(false);
+  });
+
   test("--qr refuses when the web remote ingress feature flag is off", async () => {
     const calls: Array<[string, RequestInit | undefined]> = [];
     const origFetch = globalThis.fetch;

package/src/__tests__/tunnel.test.ts

@@ -5,6 +5,7 @@ import {
   describe,
   expect,
   mock,
+  spyOn,
   test,
 } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
@@ -162,4 +163,56 @@ describe("tunnel nginx ingress feature flag", () => {
     expect(runNgrokTunnelMock).not.toHaveBeenCalled();
     expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
   });
+
+  test("rejects an unknown --provider with a stale-CLI hint", async () => {
+    process.argv = ["bun", "vellum", "tunnel", "--provider", "bogus"];
+    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);
+
+    let exited = false;
+    try {
+      await tunnel();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+    }
+
+    expect(exited).toBe(true);
+    const joined = errors.join("\n");
+    expect(joined).toContain("unknown tunnel provider 'bogus'");
+    expect(joined).toContain("your CLI may be out of date");
+    expect(joined).toContain("bun install -g vellum@latest");
+    expect(runNgrokTunnelMock).not.toHaveBeenCalled();
+    expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
+  });
+
+  test("a not-yet-implemented provider error carries the stale-CLI hint", async () => {
+    // The default `vellum` provider has no runtime yet, so it exercises the
+    // not-yet-implemented path without any network call.
+    process.argv = ["bun", "vellum", "tunnel", "--provider", "vellum"];
+
+    let err: Error | undefined;
+    try {
+      await tunnel();
+    } catch (e) {
+      err = e as Error;
+    }
+
+    expect(err?.message).toContain("is not yet implemented");
+    expect(err?.message).toContain("your CLI may be out of date");
+    expect(err?.message).toContain("bun install -g vellum@latest");
+    expect(runNgrokTunnelMock).not.toHaveBeenCalled();
+    expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
+  });
 });