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

package/src/__tests__/assistant-client-refresh.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Tests for AssistantClient's reactive 401 -> refresh -> retry: a paired/local
+ * guardian access token that 401s is refreshed once via the stored refresh
+ * credential and the request retried. Self-gating (no refresh token => no
+ * retry) and never applied to the platform session-auth path.
+ */
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  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(), "client-refresh-test-"));
+const ORIGINAL_LOCKFILE_DIR = process.env.VELLUM_LOCKFILE_DIR;
+const ORIGINAL_CONFIG_HOME = process.env.XDG_CONFIG_HOME;
+const ORIGINAL_FETCH = globalThis.fetch;
+
+import { AssistantClient } from "../lib/assistant-client.js";
+import { saveAssistantEntry } from "../lib/assistant-config.js";
+import { loadGuardianToken, saveGuardianToken } from "../lib/guardian-token.js";
+
+const RUNTIME = "http://10.0.0.9:7830";
+const FUTURE = new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString();
+
+function seedPaired(refreshToken: string): void {
+  saveAssistantEntry({
+    assistantId: "px",
+    name: "Paired",
+    runtimeUrl: RUNTIME,
+    cloud: "paired",
+    paired: true,
+    species: "vellum",
+  });
+  saveGuardianToken("px", {
+    guardianPrincipalId: "imported",
+    accessToken: "old-acc",
+    accessTokenExpiresAt: FUTURE,
+    refreshToken,
+    refreshTokenExpiresAt: refreshToken ? FUTURE : 0,
+    refreshAfter: "",
+    isNew: false,
+    deviceId: "dev",
+    leasedAt: new Date().toISOString(),
+  });
+}
+
+interface Call {
+  url: string;
+  headers: Record<string, string>;
+}
+
+/** Replace global fetch with a URL-routed stub; returns the call log. */
+function stubFetch(handler: (url: string, calls: Call[]) => Response): Call[] {
+  const calls: Call[] = [];
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : String(input);
+    calls.push({
+      url,
+      headers: (init?.headers ?? {}) as Record<string, string>,
+    });
+    return handler(url, calls);
+  }) as typeof fetch;
+  return calls;
+}
+
+const isRefresh = (url: string) => url.includes("/v1/guardian/refresh");
+
+function refreshResponse(): Response {
+  return new Response(
+    JSON.stringify({
+      accessToken: "new-acc",
+      refreshToken: "new-ref",
+      accessTokenExpiresAt: FUTURE,
+      refreshTokenExpiresAt: FUTURE,
+      refreshAfter: "",
+    }),
+    { status: 200, headers: { "content-type": "application/json" } },
+  );
+}
+
+describe("AssistantClient 401 -> refresh -> retry", () => {
+  beforeEach(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+    process.env.XDG_CONFIG_HOME = testDir;
+  });
+
+  afterEach(() => {
+    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 });
+  });
+
+  test("refreshes and retries once on 401, persisting the new token", async () => {
+    seedPaired("refresh-tok");
+    let assistantAttempts = 0;
+    const calls = stubFetch((url) => {
+      if (isRefresh(url)) return refreshResponse();
+      assistantAttempts++;
+      return new Response("", { status: assistantAttempts === 1 ? 401 : 200 });
+    });
+
+    const client = new AssistantClient({ assistantId: "px" });
+    const res = await client.get("/messages/");
+
+    expect(res.status).toBe(200);
+    expect(assistantAttempts).toBe(2); // original + one retry
+    expect(calls.filter((c) => isRefresh(c.url))).toHaveLength(1);
+    // The retry carried the refreshed bearer token.
+    const assistantCalls = calls.filter((c) => !isRefresh(c.url));
+    expect(assistantCalls[1].headers["Authorization"]).toBe("Bearer new-acc");
+    // refreshGuardianToken persisted the rotated token.
+    expect(loadGuardianToken("px")?.accessToken).toBe("new-acc");
+  });
+
+  test("does not retry when there is no stored refresh token", async () => {
+    seedPaired(""); // access-only
+    let assistantAttempts = 0;
+    const calls = stubFetch((url) => {
+      if (isRefresh(url)) return refreshResponse();
+      assistantAttempts++;
+      return new Response("", { status: 401 });
+    });
+
+    const client = new AssistantClient({ assistantId: "px" });
+    const res = await client.get("/messages/");
+
+    expect(res.status).toBe(401);
+    expect(assistantAttempts).toBe(1); // no retry
+    expect(calls.filter((c) => isRefresh(c.url))).toHaveLength(0);
+  });
+
+  test("never refreshes on the platform session-auth path", async () => {
+    seedPaired("refresh-tok"); // entry must exist; session auth ignores it
+    let assistantAttempts = 0;
+    const calls = stubFetch((url) => {
+      if (isRefresh(url)) return refreshResponse();
+      assistantAttempts++;
+      return new Response("", { status: 401 });
+    });
+
+    const client = new AssistantClient({
+      assistantId: "px",
+      sessionToken: "sess-tok",
+      orgId: "org-1",
+    });
+    const res = await client.get("/messages/");
+
+    expect(res.status).toBe(401);
+    expect(assistantAttempts).toBe(1);
+    expect(calls.filter((c) => isRefresh(c.url))).toHaveLength(0);
+  });
+
+  test("retries at most once (second 401 is not refreshed again)", async () => {
+    seedPaired("refresh-tok");
+    let assistantAttempts = 0;
+    const calls = stubFetch((url) => {
+      if (isRefresh(url)) return refreshResponse();
+      assistantAttempts++;
+      return new Response("", { status: 401 }); // always 401
+    });
+
+    const client = new AssistantClient({ assistantId: "px" });
+    const res = await client.get("/messages/");
+
+    expect(res.status).toBe(401);
+    expect(assistantAttempts).toBe(2); // original + one retry, no more
+    expect(calls.filter((c) => isRefresh(c.url))).toHaveLength(1);
+  });
+});

package/src/__tests__/clean.test.ts

@@ -0,0 +1,179 @@
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+
+import type { OrphanedProcess } from "../lib/orphan-detection.js";
+
+// ── Module mocks (must be set up before importing the command) ───────────────
+
+const detectOrphansMock = mock(async (): Promise<OrphanedProcess[]> => []);
+const stopProcessMock = mock(
+  async (_pid: number, _label: string): Promise<boolean> => true,
+);
+
+beforeAll(() => {
+  mock.module("../lib/orphan-detection.js", () => ({
+    detectOrphanedProcesses: detectOrphansMock,
+  }));
+  mock.module("../lib/process.js", () => ({
+    stopProcess: stopProcessMock,
+  }));
+});
+
+import { clean } from "../commands/clean.js";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function makeOrphan(
+  name: string,
+  pid: string,
+  source = "process table",
+): OrphanedProcess {
+  return { name, pid, source };
+}
+
+const originalArgv = [...process.argv];
+
+let consoleLogSpy: ReturnType<typeof spyOn>;
+let consoleErrorSpy: ReturnType<typeof spyOn>;
+let exitSpy: ReturnType<typeof spyOn>;
+
+beforeEach(() => {
+  consoleLogSpy = spyOn(console, "log").mockImplementation(() => {});
+  consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+  exitSpy = spyOn(process, "exit").mockImplementation((_code?: number) => {
+    throw new Error(`process.exit(${_code})`);
+  });
+  detectOrphansMock.mockClear();
+  stopProcessMock.mockClear();
+});
+
+afterEach(() => {
+  process.argv = [...originalArgv];
+  consoleLogSpy.mockRestore();
+  consoleErrorSpy.mockRestore();
+  exitSpy.mockRestore();
+});
+
+afterAll(() => {
+  process.argv = [...originalArgv];
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("vellum clean --help", () => {
+  test("prints usage and exits 0", async () => {
+    process.argv = ["bun", "vellum", "clean", "--help"];
+    await expect(clean()).rejects.toThrow("process.exit(0)");
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Usage: vellum clean");
+    expect(output).toContain("orphaned");
+  });
+
+  test("-h is accepted as an alias for --help", async () => {
+    process.argv = ["bun", "vellum", "clean", "-h"];
+    await expect(clean()).rejects.toThrow("process.exit(0)");
+  });
+});
+
+describe("vellum clean — no orphans", () => {
+  test("prints nothing-to-do message when no orphans are found", async () => {
+    detectOrphansMock.mockResolvedValueOnce([]);
+    process.argv = ["bun", "vellum", "clean"];
+    await clean();
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("No orphaned processes found.");
+    expect(stopProcessMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("vellum clean — single orphan", () => {
+  test("kills the orphan and prints singular 'process'", async () => {
+    detectOrphansMock.mockResolvedValueOnce([makeOrphan("assistant", "12345")]);
+    stopProcessMock.mockResolvedValueOnce(true);
+    process.argv = ["bun", "vellum", "clean"];
+    await clean();
+
+    expect(stopProcessMock).toHaveBeenCalledTimes(1);
+    expect(stopProcessMock).toHaveBeenCalledWith(
+      12345,
+      "assistant (PID 12345)",
+    );
+
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Found 1 orphaned process");
+    expect(output).not.toContain("processes");
+    expect(output).toContain("Cleaned up 1 process.");
+    expect(output).not.toContain("processes.");
+  });
+
+  test("reports 0 cleaned when stopProcess returns false", async () => {
+    detectOrphansMock.mockResolvedValueOnce([makeOrphan("gateway", "99999")]);
+    stopProcessMock.mockResolvedValueOnce(false);
+    process.argv = ["bun", "vellum", "clean"];
+    await clean();
+
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Cleaned up 0 process");
+  });
+});
+
+describe("vellum clean — multiple orphans", () => {
+  test("uses plural 'processes' with multiple orphans", async () => {
+    detectOrphansMock.mockResolvedValueOnce([
+      makeOrphan("assistant", "1001"),
+      makeOrphan("gateway", "1002"),
+      makeOrphan("qdrant", "1003"),
+    ]);
+    stopProcessMock.mockResolvedValue(true);
+    process.argv = ["bun", "vellum", "clean"];
+    await clean();
+
+    expect(stopProcessMock).toHaveBeenCalledTimes(3);
+
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Found 3 orphaned processes");
+    expect(output).toContain("Cleaned up 3 processes.");
+  });
+
+  test("counts only successfully stopped processes in the total", async () => {
+    detectOrphansMock.mockResolvedValueOnce([
+      makeOrphan("assistant", "2001"),
+      makeOrphan("qdrant", "2002"),
+      makeOrphan("gateway", "2003"),
+    ]);
+    // Only the first and third succeed
+    stopProcessMock
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce(false)
+      .mockResolvedValueOnce(true);
+    process.argv = ["bun", "vellum", "clean"];
+    await clean();
+
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Found 3 orphaned processes");
+    expect(output).toContain("Cleaned up 2 processes.");
+  });
+
+  test("passes the correct PID and label to stopProcess for each orphan", async () => {
+    detectOrphansMock.mockResolvedValueOnce([
+      makeOrphan("assistant", "3001"),
+      makeOrphan("gateway", "3002"),
+    ]);
+    stopProcessMock.mockResolvedValue(true);
+    process.argv = ["bun", "vellum", "clean"];
+    await clean();
+
+    const calls = stopProcessMock.mock.calls as [number, string][];
+    expect(calls[0]).toEqual([3001, "assistant (PID 3001)"]);
+    expect(calls[1]).toEqual([3002, "gateway (PID 3002)"]);
+  });
+});

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

@@ -0,0 +1,87 @@
+/**
+ * Tests for `vellum client --token <jwt> --url <gateway>`: an ephemeral session
+ * that authenticates with a handed-over token and needs no lockfile entry.
+ */
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// NB: do NOT mock.module("../lib/guardian-token.js") here — that mock is
+// process-global in Bun and leaks into other test files (it dropped the
+// module's other exports and broke guardian-token-paths / setup suites in CI).
+// The "--token skips the credential lookup" behavior is enforced structurally
+// in parseArgs (the lookup is gated on the override) and reviewed there.
+
+// An EMPTY temp dir so there is no lockfile entry — the ephemeral path must
+// work without one. Env mutation is scoped to each test and restored after, so
+// it can't leak into other test files in the same Bun run.
+const testDir = mkdtempSync(join(tmpdir(), "client-token-test-"));
+const ORIGINAL_LOCKFILE_DIR = process.env.VELLUM_LOCKFILE_DIR;
+const ORIGINAL_ARGV = [...process.argv];
+
+import { parseArgs } from "../commands/client.js";
+
+// A clearly non-local URL so maybeSwapToLocalhost won't rewrite it to 127.0.0.1.
+const REMOTE_URL = "http://192.0.2.50:7830";
+
+describe("client --token (ephemeral)", () => {
+  beforeEach(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+  });
+
+  afterEach(() => {
+    process.argv = [...ORIGINAL_ARGV];
+    if (ORIGINAL_LOCKFILE_DIR === undefined) {
+      delete process.env.VELLUM_LOCKFILE_DIR;
+    } else {
+      process.env.VELLUM_LOCKFILE_DIR = ORIGINAL_LOCKFILE_DIR;
+    }
+  });
+
+  afterAll(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test("--url + --token resolves to a bearer session with no lockfile entry", () => {
+    process.argv = [
+      "bun",
+      "vellum",
+      "client",
+      "--url",
+      REMOTE_URL,
+      "--token",
+      "test-jwt-token",
+    ];
+    const parsed = parseArgs();
+
+    expect(parsed.runtimeUrl).toBe(REMOTE_URL);
+    expect(parsed.assistantId).toBe("self"); // DAEMON_INTERNAL_ASSISTANT_ID
+    expect(parsed.bearerToken).toBe("test-jwt-token");
+    expect(parsed.platformToken).toBeUndefined();
+  });
+
+  test("--assistant-id overrides the default 'self' segment", () => {
+    process.argv = [
+      "bun",
+      "vellum",
+      "client",
+      "--url",
+      REMOTE_URL,
+      "--token",
+      "tok",
+      "--assistant-id",
+      "remote-xyz",
+    ];
+    const parsed = parseArgs();
+    expect(parsed.assistantId).toBe("remote-xyz");
+    expect(parsed.bearerToken).toBe("tok");
+  });
+});

package/src/__tests__/client-tui-refresh.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Tests for resolveFreshBearerToken: the `vellum client` TUI proactively
+ * refreshes a stale STORED guardian token at startup, while leaving platform
+ * session auth, ephemeral --token overrides, and still-fresh tokens untouched.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const ORIGINAL_XDG = process.env.XDG_CONFIG_HOME;
+const ORIGINAL_ENV = process.env.VELLUM_ENVIRONMENT;
+const ORIGINAL_FETCH = globalThis.fetch;
+
+import { resolveFreshBearerToken } from "../commands/client.js";
+import { saveGuardianToken } from "../lib/guardian-token.js";
+
+const RUNTIME = "http://10.0.0.9:7830";
+const past = () => new Date(Date.now() - 60_000).toISOString();
+const future = () => new Date(Date.now() + 60 * 60 * 1000).toISOString();
+
+function seed(opts: {
+  accessToken: string;
+  refreshToken: string;
+  refreshAfter: string;
+}): void {
+  saveGuardianToken("px", {
+    guardianPrincipalId: "imported",
+    accessToken: opts.accessToken,
+    accessTokenExpiresAt: future(),
+    refreshToken: opts.refreshToken,
+    refreshTokenExpiresAt: future(),
+    refreshAfter: opts.refreshAfter,
+    isNew: false,
+    deviceId: "dev",
+    leasedAt: new Date().toISOString(),
+  });
+}
+
+/** Stub global fetch; returns whether the refresh endpoint was hit. */
+function stubRefresh(ok: boolean): { hit: () => boolean } {
+  let called = false;
+  globalThis.fetch = (async (url: unknown, _init?: RequestInit) => {
+    if (String(url).includes("/v1/guardian/refresh")) {
+      called = true;
+      return new Response(
+        ok ? JSON.stringify({ accessToken: "new-acc" }) : "nope",
+        {
+          status: ok ? 200 : 401,
+          headers: { "content-type": "application/json" },
+        },
+      );
+    }
+    return new Response("", { status: 200 });
+  }) as typeof fetch;
+  return { hit: () => called };
+}
+
+describe("resolveFreshBearerToken", () => {
+  let tempHome: string;
+
+  beforeEach(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "client-tui-refresh-test-"));
+    process.env.XDG_CONFIG_HOME = tempHome;
+    delete process.env.VELLUM_ENVIRONMENT; // prod config dir
+  });
+
+  afterEach(() => {
+    globalThis.fetch = ORIGINAL_FETCH;
+    if (ORIGINAL_XDG === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = ORIGINAL_XDG;
+    if (ORIGINAL_ENV === undefined) delete process.env.VELLUM_ENVIRONMENT;
+    else process.env.VELLUM_ENVIRONMENT = ORIGINAL_ENV;
+    rmSync(tempHome, { recursive: true, force: true });
+  });
+
+  test("refreshes a stale stored token and returns the new access token", async () => {
+    seed({ accessToken: "old-acc", refreshToken: "ref", refreshAfter: past() });
+    const refresh = stubRefresh(true);
+
+    const token = await resolveFreshBearerToken(
+      RUNTIME,
+      "px",
+      "old-acc",
+      "paired",
+    );
+
+    expect(token).toBe("new-acc");
+    expect(refresh.hit()).toBe(true);
+  });
+
+  test("leaves a still-fresh stored token unchanged (no refresh)", async () => {
+    seed({
+      accessToken: "old-acc",
+      refreshToken: "ref",
+      refreshAfter: future(),
+    });
+    const refresh = stubRefresh(true);
+
+    const token = await resolveFreshBearerToken(
+      RUNTIME,
+      "px",
+      "old-acc",
+      "paired",
+    );
+
+    expect(token).toBe("old-acc");
+    expect(refresh.hit()).toBe(false);
+  });
+
+  test("does not refresh an ephemeral --token (mismatches the store)", async () => {
+    seed({ accessToken: "old-acc", refreshToken: "ref", refreshAfter: past() });
+    const refresh = stubRefresh(true);
+
+    // bearerToken differs from the stored accessToken => ephemeral override.
+    const token = await resolveFreshBearerToken(
+      RUNTIME,
+      "px",
+      "ephemeral-tok",
+      "paired",
+    );
+
+    expect(token).toBe("ephemeral-tok");
+    expect(refresh.hit()).toBe(false);
+  });
+
+  test("never refreshes on the platform session-auth path", async () => {
+    seed({ accessToken: "old-acc", refreshToken: "ref", refreshAfter: past() });
+    const refresh = stubRefresh(true);
+
+    const token = await resolveFreshBearerToken(
+      RUNTIME,
+      "px",
+      "old-acc",
+      "vellum",
+    );
+
+    expect(token).toBe("old-acc");
+    expect(refresh.hit()).toBe(false);
+  });
+
+  test("falls back to the existing token when refresh fails", async () => {
+    seed({ accessToken: "old-acc", refreshToken: "ref", refreshAfter: past() });
+    stubRefresh(false); // refresh endpoint returns non-ok
+
+    const token = await resolveFreshBearerToken(
+      RUNTIME,
+      "px",
+      "old-acc",
+      "paired",
+    );
+
+    expect(token).toBe("old-acc");
+  });
+
+  test("does not refresh an access-only stored token (no refresh credential)", async () => {
+    seed({ accessToken: "old-acc", refreshToken: "", refreshAfter: past() });
+    const refresh = stubRefresh(true);
+
+    const token = await resolveFreshBearerToken(
+      RUNTIME,
+      "px",
+      "old-acc",
+      "paired",
+    );
+
+    expect(token).toBe("old-acc");
+    expect(refresh.hit()).toBe(false);
+  });
+});