@vellumai/cli 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/src/__tests__/devices.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Tests for `vellum devices` (list) and `vellum devices revoke <hashedDeviceId>`:
+ * the host-side CLI that calls the loopback `GET /v1/devices` and
+ * `POST /v1/devices/revoke` endpoints. Verifies host-gating (refuses paired
+ * connections), the destructive-revoke confirmation, and that requests carry no
+ * browser/proxy headers.
+ */
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  spyOn,
+  test,
+} from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const testDir = mkdtempSync(join(tmpdir(), "devices-test-"));
+const ORIGINAL_LOCKFILE_DIR = process.env.VELLUM_LOCKFILE_DIR;
+const ORIGINAL_CONFIG_HOME = process.env.XDG_CONFIG_HOME;
+const ORIGINAL_ARGV = [...process.argv];
+const ORIGINAL_FETCH = globalThis.fetch;
+
+import { devices } from "../commands/devices.js";
+import { saveAssistantEntry } from "../lib/assistant-config.js";
+
+interface FetchCall {
+  url: string;
+  init?: RequestInit;
+}
+
+let fetchCalls: FetchCall[] = [];
+
+/** Stub global fetch (spyOn does not intercept fetch in Bun). */
+function stubFetch(
+  handler: (url: string, init?: RequestInit) => Response,
+): void {
+  globalThis.fetch = (async (url: unknown, init?: RequestInit) => {
+    fetchCalls.push({ url: String(url), init });
+    return handler(String(url), init);
+  }) as typeof fetch;
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+interface RunResult {
+  exited: boolean;
+  logs: string;
+  errors: string;
+}
+
+/** Run devices() with console + process.exit spied. */
+async function runDevices(): Promise<RunResult> {
+  const logs: string[] = [];
+  const errors: string[] = [];
+  const logSpy = spyOn(console, "log").mockImplementation((...a: unknown[]) => {
+    logs.push(a.join(" "));
+  });
+  const errSpy = spyOn(console, "error").mockImplementation(
+    (...a: unknown[]) => {
+      errors.push(a.join(" "));
+    },
+  );
+  const exitSpy = spyOn(process, "exit").mockImplementation(((c?: number) => {
+    throw new Error(`exit:${c}`);
+  }) as never);
+  let exited = false;
+  try {
+    await devices();
+  } catch (e) {
+    exited = (e as Error).message?.startsWith("exit:") ?? false;
+  } finally {
+    logSpy.mockRestore();
+    errSpy.mockRestore();
+    exitSpy.mockRestore();
+  }
+  return { exited, logs: logs.join("\n"), errors: errors.join("\n") };
+}
+
+function headerKeys(init?: RequestInit): string[] {
+  const h = init?.headers as Record<string, string> | undefined;
+  return h ? Object.keys(h).map((k) => k.toLowerCase()) : [];
+}
+
+describe("vellum devices", () => {
+  beforeEach(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+    process.env.XDG_CONFIG_HOME = testDir;
+    fetchCalls = [];
+    // Default stub: any unexpected call is recorded and 500s.
+    stubFetch(() => jsonResponse({ error: "unexpected" }, 500));
+  });
+
+  afterEach(() => {
+    process.argv = [...ORIGINAL_ARGV];
+    globalThis.fetch = ORIGINAL_FETCH;
+    if (ORIGINAL_LOCKFILE_DIR === undefined)
+      delete process.env.VELLUM_LOCKFILE_DIR;
+    else process.env.VELLUM_LOCKFILE_DIR = ORIGINAL_LOCKFILE_DIR;
+    if (ORIGINAL_CONFIG_HOME === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = ORIGINAL_CONFIG_HOME;
+  });
+
+  afterAll(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  function seedLocal(id: string, localUrl = "http://127.0.0.1:7830"): void {
+    saveAssistantEntry({
+      assistantId: id,
+      name: id,
+      runtimeUrl: "http://127.0.0.1:7830",
+      localUrl,
+      cloud: "local",
+      species: "vellum",
+    });
+  }
+
+  test("--help prints usage including Examples", async () => {
+    process.argv = ["bun", "vellum", "devices", "--help"];
+    const { logs } = await runDevices();
+    expect(logs).toContain("USAGE:");
+    expect(logs).toContain("EXAMPLES:");
+    expect(logs).toContain("vellum devices revoke");
+  });
+
+  test("lists active devices over loopback with no browser/proxy headers", async () => {
+    seedLocal("list-host", "http://127.0.0.1:7833");
+    stubFetch((url) => {
+      if (url.endsWith("/v1/devices")) {
+        return jsonResponse({
+          devices: [
+            {
+              hashedDeviceId: "hashAAA111",
+              platform: "cli",
+              issuedAt: 1_700_000_000_000,
+              expiresAt: 1_800_000_000_000,
+              lastUsedAt: 1_750_000_000_000,
+            },
+            {
+              hashedDeviceId: "hashBBB222",
+              platform: "webview",
+              issuedAt: 1_700_000_000_000,
+              expiresAt: null,
+              lastUsedAt: null,
+            },
+          ],
+        });
+      }
+      return jsonResponse({ error: "unexpected" }, 500);
+    });
+
+    process.argv = ["bun", "vellum", "devices", "list-host"];
+    const { exited, logs } = await runDevices();
+
+    expect(exited).toBe(false);
+    // Both full hashes + platforms surfaced; null lastUsedAt → "never".
+    expect(logs).toContain("hashAAA111");
+    expect(logs).toContain("hashBBB222");
+    expect(logs).toContain("cli");
+    expect(logs).toContain("webview");
+    expect(logs).toContain("never");
+
+    expect(fetchCalls).toHaveLength(1);
+    const call = fetchCalls[0];
+    expect(call.url).toBe("http://127.0.0.1:7833/v1/devices");
+    expect(call.init?.method).toBe("GET");
+    const keys = headerKeys(call.init);
+    expect(keys).not.toContain("origin");
+    expect(keys).not.toContain("x-forwarded-for");
+  });
+
+  test("prints a clear message when no devices are paired", async () => {
+    seedLocal("empty-host");
+    stubFetch(() => jsonResponse({ devices: [] }));
+
+    process.argv = ["bun", "vellum", "devices", "empty-host"];
+    const { exited, logs } = await runDevices();
+
+    expect(exited).toBe(false);
+    expect(logs).toContain("No devices are paired to empty-host");
+  });
+
+  test("revoke posts the hashedDeviceId with --yes (no prompt)", async () => {
+    seedLocal("revoke-host", "http://127.0.0.1:7834");
+    stubFetch((url) => {
+      if (url.endsWith("/v1/devices/revoke")) {
+        return jsonResponse({ revoked: true, hashedDeviceId: "hashAAA111" });
+      }
+      return jsonResponse({ error: "unexpected" }, 500);
+    });
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "devices",
+      "revoke",
+      "hashAAA111",
+      "revoke-host",
+      "--yes",
+    ];
+    const { exited, logs } = await runDevices();
+
+    expect(exited).toBe(false);
+    expect(logs).toContain("Revoked device hashAAA111");
+
+    expect(fetchCalls).toHaveLength(1);
+    const call = fetchCalls[0];
+    expect(call.url).toBe("http://127.0.0.1:7834/v1/devices/revoke");
+    expect(call.init?.method).toBe("POST");
+    expect(JSON.parse(String(call.init?.body))).toEqual({
+      hashedDeviceId: "hashAAA111",
+    });
+  });
+
+  test("revoke without a hashedDeviceId errors and makes no request", async () => {
+    process.argv = ["bun", "vellum", "devices", "revoke", "--yes"];
+    const { exited, errors } = await runDevices();
+
+    expect(exited).toBe(true);
+    expect(errors).toContain("hashedDeviceId is required");
+    expect(fetchCalls).toHaveLength(0);
+  });
+
+  test("revoke refuses without --yes in a non-interactive terminal", async () => {
+    seedLocal("rh3");
+    // process.stdin.isTTY is falsy under the test runner → not promptable.
+    process.argv = ["bun", "vellum", "devices", "revoke", "hashZZZ", "rh3"];
+    const { exited, errors } = await runDevices();
+
+    expect(exited).toBe(true);
+    expect(errors).toContain("--yes");
+    expect(fetchCalls).toHaveLength(0);
+  });
+
+  test("host-gates a paired connection (points to the host / unpair)", async () => {
+    saveAssistantEntry({
+      assistantId: "paired-box",
+      name: "Paired Box",
+      runtimeUrl: "http://10.0.0.9:7830",
+      cloud: "paired",
+      paired: true,
+      species: "vellum",
+    });
+
+    process.argv = ["bun", "vellum", "devices", "paired-box"];
+    const { exited, errors } = await runDevices();
+
+    expect(exited).toBe(true);
+    expect(errors).toContain("vellum unpair");
+    expect(fetchCalls).toHaveLength(0);
+  });
+
+  test("surfaces a non-2xx gateway response on list", async () => {
+    seedLocal("err-host");
+    stubFetch(() => jsonResponse({ error: { code: "FORBIDDEN" } }, 403));
+
+    process.argv = ["bun", "vellum", "devices", "err-host"];
+    const { exited, errors } = await runDevices();
+
+    expect(exited).toBe(true);
+    expect(errors).toContain("403");
+  });
+});

package/src/__tests__/guardian-token.test.ts

@@ -1,11 +1,20 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 import {
   getOrCreatePersistedDeviceId,
   loadGuardianToken,
+  refreshGuardianToken,
   saveGuardianToken,
   seedGuardianTokenFromSiblingEnv,
   type GuardianTokenData,
@@ -223,3 +232,118 @@ describe("guardian-token paths are env-scoped", () => {
     );
   });
 });
+
+describe("refreshGuardianToken", () => {
+  let tempHome: string;
+  let savedXdg: string | undefined;
+  let savedEnv: string | undefined;
+  const ORIGINAL_FETCH = globalThis.fetch;
+
+  const future = () => new Date(Date.now() + 60 * 60 * 1000).toISOString();
+
+  function lockPath(id: string): string {
+    return join(tempHome, "vellum", "assistants", id, "refresh.lock");
+  }
+
+  function seed(refreshExpiresAt: string | number): void {
+    saveGuardianToken("px", {
+      guardianPrincipalId: "imported",
+      accessToken: "old-acc",
+      accessTokenExpiresAt: future(),
+      refreshToken: "old-ref",
+      refreshTokenExpiresAt: refreshExpiresAt,
+      refreshAfter: "",
+      isNew: false,
+      deviceId: "dev",
+      leasedAt: new Date().toISOString(),
+    });
+  }
+
+  beforeEach(() => {
+    savedXdg = process.env.XDG_CONFIG_HOME;
+    savedEnv = process.env.VELLUM_ENVIRONMENT;
+    tempHome = mkdtempSync(join(tmpdir(), "cli-refresh-test-"));
+    process.env.XDG_CONFIG_HOME = tempHome;
+    delete process.env.VELLUM_ENVIRONMENT;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = ORIGINAL_FETCH;
+    if (savedXdg === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = savedXdg;
+    if (savedEnv === undefined) delete process.env.VELLUM_ENVIRONMENT;
+    else process.env.VELLUM_ENVIRONMENT = savedEnv;
+    rmSync(tempHome, { recursive: true, force: true });
+  });
+
+  test("refreshes, persists the rotated token, sends an abort signal, releases the lock", async () => {
+    seed(future());
+    let sawSignal = false;
+    globalThis.fetch = (async (_url: unknown, init?: RequestInit) => {
+      sawSignal = init?.signal instanceof AbortSignal;
+      return new Response(
+        JSON.stringify({
+          accessToken: "new-acc",
+          refreshToken: "new-ref",
+          accessTokenExpiresAt: future(),
+          refreshTokenExpiresAt: future(),
+          refreshAfter: "",
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    const result = await refreshGuardianToken("http://10.0.0.9:7830", "px");
+
+    expect(result?.accessToken).toBe("new-acc");
+    expect(loadGuardianToken("px")?.accessToken).toBe("new-acc");
+    expect(sawSignal).toBe(true); // fetch carries a timeout AbortSignal
+    expect(existsSync(lockPath("px"))).toBe(false); // lock released
+  });
+
+  test("returns null without calling the gateway when the refresh token is expired", async () => {
+    seed(new Date(Date.now() - 1000).toISOString());
+    let called = false;
+    globalThis.fetch = (async (_url: unknown, _init?: RequestInit) => {
+      called = true;
+      return new Response("", { status: 200 });
+    }) as typeof fetch;
+
+    expect(await refreshGuardianToken("http://10.0.0.9:7830", "px")).toBeNull();
+    expect(called).toBe(false);
+  });
+
+  test("returns null when there is no stored token", async () => {
+    let called = false;
+    globalThis.fetch = (async (_url: unknown, _init?: RequestInit) => {
+      called = true;
+      return new Response("", { status: 200 });
+    }) as typeof fetch;
+
+    expect(
+      await refreshGuardianToken("http://10.0.0.9:7830", "missing"),
+    ).toBeNull();
+    expect(called).toBe(false);
+  });
+
+  test("steals a stale lock and still refreshes", async () => {
+    seed(future());
+    // Pre-create a stale lock (mtime well in the past) as if a crashed holder
+    // left it behind; the refresh must steal it rather than block.
+    const lp = lockPath("px");
+    mkdirSync(dirname(lp), { recursive: true });
+    writeFileSync(lp, "99999");
+    const old = new Date(Date.now() - 60_000);
+    utimesSync(lp, old, old);
+
+    globalThis.fetch = (async (_url: unknown, _init?: RequestInit) =>
+      new Response(JSON.stringify({ accessToken: "new-acc" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })) as typeof fetch;
+
+    const result = await refreshGuardianToken("http://10.0.0.9:7830", "px");
+    expect(result?.accessToken).toBe("new-acc");
+    expect(existsSync(lp)).toBe(false); // stolen lock cleaned up after release
+  });
+});

package/src/__tests__/pair.test.ts

@@ -0,0 +1,271 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  spyOn,
+  test,
+} from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Real assistant-config reads the lockfile from VELLUM_LOCKFILE_DIR.
+const testDir = mkdtempSync(join(tmpdir(), "pair-command-test-"));
+process.env.VELLUM_LOCKFILE_DIR = testDir;
+
+import { 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";
+const RUNTIME_URL = "http://192.168.1.50:7830";
+
+function writeLockfile(): void {
+  writeFileSync(
+    join(testDir, ".vellum.lock.json"),
+    JSON.stringify({
+      assistants: [
+        {
+          assistantId: "pair-test",
+          runtimeUrl: RUNTIME_URL,
+          localUrl: LOCAL_URL,
+          cloud: "local",
+        },
+      ],
+      activeAssistant: "pair-test",
+    }),
+  );
+}
+
+// Capture the real argv ONCE, before any test mutates it, and restore after
+// every test — so a `['bun','vellum','pair',...]` argv can't leak into other
+// test files in the same Bun run.
+const ORIGINAL_ARGV = [...process.argv];
+
+describe("pair command", () => {
+  beforeEach(() => {
+    writeLockfile();
+  });
+
+  afterEach(() => {
+    process.argv = [...ORIGINAL_ARGV];
+  });
+
+  afterAll(() => {
+    rmSync(testDir, { recursive: true, force: true });
+    delete process.env.VELLUM_LOCKFILE_DIR;
+  });
+
+  test("POSTs a cli device-bound pair request and prints a decodable bundle", async () => {
+    const calls: Array<[string, RequestInit]> = [];
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string, init: RequestInit) => {
+      calls.push([url, init]);
+      return new Response(
+        JSON.stringify({
+          token: "test-access-token",
+          expiresAt: "2026-06-04T00:00:00.000Z",
+          guardianId: "guardian-001",
+          assistantId: "self",
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) 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", "--json"];
+    try {
+      await pair();
+    } finally {
+      logSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    // Mint over the loopback (localUrl), not the reachable runtime URL.
+    expect(calls).toHaveLength(1);
+    const [url, init] = calls[0];
+    expect(url).toBe(`${LOCAL_URL}/v1/pair`);
+    expect(init.method).toBe("POST");
+    const headers = Object.fromEntries(
+      Object.entries(init.headers as Record<string, string>).map(([k, v]) => [
+        k.toLowerCase(),
+        v,
+      ]),
+    );
+    expect(headers["x-vellum-interface-id"]).toBe("cli");
+    const body = JSON.parse(init.body as string);
+    expect(typeof body.deviceId).toBe("string");
+    expect(body.deviceId.length).toBeGreaterThan(0);
+    expect(body.platform).toBe("cli");
+
+    // The bundle advertises the REACHABLE runtime URL, not loopback.
+    const out = JSON.parse(logs.join("\n"));
+    expect(out.gatewayUrl).toBe(RUNTIME_URL);
+    expect(out.assistantId).toBe("self");
+    expect(out.token).toBe("test-access-token");
+    expect(out.deviceId).toBe(body.deviceId);
+  });
+
+  test("resolves an unquoted multi-word display name", async () => {
+    // Assistant whose display name has a space; passed as separate argv tokens.
+    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(
+        JSON.stringify({
+          token: "t",
+          expiresAt: "2026-06-04T00:00:00.000Z",
+          guardianId: "g",
+          assistantId: "self",
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as unknown as typeof fetch;
+    const logSpy = spyOn(console, "log").mockImplementation(() => {});
+
+    process.argv = ["bun", "vellum", "pair", "My", "Assistant", "--json"];
+    try {
+      await pair();
+    } finally {
+      logSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    // Resolution succeeded (no exit), so the mint request was made.
+    expect(fetchCalled).toBe(true);
+  });
+
+  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";
+    writeFileSync(
+      join(testDir, ".vellum.lock.json"),
+      JSON.stringify({
+        assistants: [
+          {
+            assistantId: "pair-test",
+            runtimeUrl: LOOPBACK_CUSTOM,
+            localUrl: LOOPBACK_CUSTOM,
+            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);
+
+    process.argv = ["bun", "vellum", "pair"];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    // The suggested --url uses the assistant's actual port, not the default.
+    expect(errors.join("\n")).toContain(":7842");
+    expect(errors.join("\n")).not.toContain(":7830");
+
+    // Exited with an error before minting — no token created for a dead URL.
+    expect(exited).toBe(true);
+    expect(fetchCalled).toBe(false);
+  });
+
+  test("--url override allows pairing even when the runtime URL is loopback", async () => {
+    writeFileSync(
+      join(testDir, ".vellum.lock.json"),
+      JSON.stringify({
+        assistants: [
+          {
+            assistantId: "pair-test",
+            runtimeUrl: LOCAL_URL,
+            localUrl: LOCAL_URL,
+            cloud: "local",
+          },
+        ],
+        activeAssistant: "pair-test",
+      }),
+    );
+
+    const calls: Array<[string, RequestInit]> = [];
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string, init: RequestInit) => {
+      calls.push([url, init]);
+      return new Response(
+        JSON.stringify({
+          token: "t",
+          expiresAt: "2026-06-04T00:00:00.000Z",
+          guardianId: "g",
+          assistantId: "self",
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as unknown as typeof fetch;
+    const logs: string[] = [];
+    const logSpy = spyOn(console, "log").mockImplementation(
+      (...a: unknown[]) => {
+        logs.push(a.join(" "));
+      },
+    );
+
+    const OVERRIDE = "https://abc123.ngrok.app";
+    process.argv = ["bun", "vellum", "pair", "--url", OVERRIDE, "--json"];
+    try {
+      await pair();
+    } finally {
+      logSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    // Mint still over loopback; bundle advertises the override.
+    expect(calls).toHaveLength(1);
+    expect(calls[0][0]).toBe(`${LOCAL_URL}/v1/pair`);
+    const out = JSON.parse(logs.join("\n"));
+    expect(out.gatewayUrl).toBe(OVERRIDE);
+  });
+});