@vellumai/cli 0.6.3 → 0.6.5

package/src/__tests__/multi-local.test.ts

@@ -94,22 +94,99 @@ describe("multi-local", () => {
   });
 
   describe("allocateLocalResources() produces non-conflicting ports", () => {
-    test("first instance gets home directory and default ports", async () => {
-      // GIVEN no local assistants exist in the lockfile
-
-      // WHEN we allocate resources for the first instance
-      const res = await allocateLocalResources("instance-a");
+    test("first instance (prod) gets XDG multi-instance dir with default ports", async () => {
+      // GIVEN XDG_DATA_HOME points at a scratch directory and no local
+      // assistants exist in the lockfile
+      const prevXdg = process.env.XDG_DATA_HOME;
+      const xdgDataHome = mkdtempSync(join(tmpdir(), "cli-multi-xdg-data-"));
+      process.env.XDG_DATA_HOME = xdgDataHome;
+      try {
+        // WHEN we allocate resources for the first instance
+        const res = await allocateLocalResources("instance-a");
+
+        // THEN it lands under the XDG multi-instance dir (no "first = home"
+        // special case anymore)
+        expect(res.instanceDir).toBe(
+          join(xdgDataHome, "vellum", "assistants", "instance-a"),
+        );
+
+        // AND it gets the default ports since no other instances exist
+        expect(res.daemonPort).toBe(DEFAULT_DAEMON_PORT);
+        expect(res.gatewayPort).toBe(DEFAULT_GATEWAY_PORT);
+        expect(res.qdrantPort).toBe(DEFAULT_QDRANT_PORT);
+
+        // AND the PID file is under the instance's .vellum/
+        expect(res.pidFile).toBe(
+          join(res.instanceDir, ".vellum", "vellum.pid"),
+        );
+      } finally {
+        if (prevXdg !== undefined) {
+          process.env.XDG_DATA_HOME = prevXdg;
+        } else {
+          delete process.env.XDG_DATA_HOME;
+        }
+        rmSync(xdgDataHome, { recursive: true, force: true });
+      }
+    });
 
-      // THEN it gets the home directory as its instance root
-      expect(res.instanceDir).toBe(testDir);
+    test("first instance (dev) uses env-scoped multi-instance dir", async () => {
+      // GIVEN VELLUM_ENVIRONMENT=dev and XDG_DATA_HOME set to scratch
+      const prevEnv = process.env.VELLUM_ENVIRONMENT;
+      const prevXdg = process.env.XDG_DATA_HOME;
+      const xdgDataHome = mkdtempSync(join(tmpdir(), "cli-multi-xdg-dev-"));
+      process.env.VELLUM_ENVIRONMENT = "dev";
+      process.env.XDG_DATA_HOME = xdgDataHome;
+      try {
+        // WHEN we allocate resources for the first instance
+        const res = await allocateLocalResources("instance-a");
 
-      // AND it gets the default ports since no other instances exist
-      expect(res.daemonPort).toBe(DEFAULT_DAEMON_PORT);
-      expect(res.gatewayPort).toBe(DEFAULT_GATEWAY_PORT);
-      expect(res.qdrantPort).toBe(DEFAULT_QDRANT_PORT);
+        // THEN it lands under the env-scoped multi-instance dir
+        expect(res.instanceDir).toBe(
+          join(xdgDataHome, "vellum-dev", "assistants", "instance-a"),
+        );
+      } finally {
+        if (prevEnv !== undefined) {
+          process.env.VELLUM_ENVIRONMENT = prevEnv;
+        } else {
+          delete process.env.VELLUM_ENVIRONMENT;
+        }
+        if (prevXdg !== undefined) {
+          process.env.XDG_DATA_HOME = prevXdg;
+        } else {
+          delete process.env.XDG_DATA_HOME;
+        }
+        rmSync(xdgDataHome, { recursive: true, force: true });
+      }
+    });
 
-      // AND the PID file is under ~/.vellum/
-      expect(res.pidFile).toBe(join(testDir, ".vellum", "vellum.pid"));
+    test("allocation picks env-specific port bases for non-prod envs", async () => {
+      // Each non-prod env sits in its own 1000-port window (see
+      // environments/seeds.ts). Hatching under VELLUM_ENVIRONMENT=dev should
+      // produce ports in the dev block (18000+), not the production defaults.
+      const prevEnv = process.env.VELLUM_ENVIRONMENT;
+      const prevXdg = process.env.XDG_DATA_HOME;
+      const xdgDataHome = mkdtempSync(join(tmpdir(), "cli-multi-xdg-ports-"));
+      process.env.VELLUM_ENVIRONMENT = "dev";
+      process.env.XDG_DATA_HOME = xdgDataHome;
+      try {
+        const res = await allocateLocalResources("dev-a");
+        expect(res.daemonPort).toBe(18000);
+        expect(res.gatewayPort).toBe(18100);
+        expect(res.qdrantPort).toBe(18200);
+        expect(res.cesPort).toBe(18300);
+      } finally {
+        if (prevEnv !== undefined) {
+          process.env.VELLUM_ENVIRONMENT = prevEnv;
+        } else {
+          delete process.env.VELLUM_ENVIRONMENT;
+        }
+        if (prevXdg !== undefined) {
+          process.env.XDG_DATA_HOME = prevXdg;
+        } else {
+          delete process.env.XDG_DATA_HOME;
+        }
+        rmSync(xdgDataHome, { recursive: true, force: true });
+      }
     });
 
     test("second instance gets distinct ports and dir when first instance is saved", async () => {

package/src/__tests__/orphan-detection.test.ts

@@ -0,0 +1,214 @@
+import { describe, test, expect, beforeEach, afterAll, mock } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Redirect lockfile reads/writes to a scratch directory so the test never
+// touches the real `~/.vellum.lock.json`.
+const testDir = mkdtempSync(join(tmpdir(), "cli-orphan-detection-test-"));
+process.env.VELLUM_LOCKFILE_DIR = testDir;
+
+// Mock homedir() so `join(homedir(), ".vellum")` inside orphan-detection
+// resolves under the scratch directory — the legacy fallback scan is part
+// of the behavior under test and we need to keep it off the real filesystem.
+const realOs = await import("node:os");
+const fakeHome = mkdtempSync(join(tmpdir(), "cli-orphan-detection-home-"));
+mock.module("node:os", () => ({
+  ...realOs,
+  homedir: () => fakeHome,
+}));
+mock.module("os", () => ({
+  ...realOs,
+  homedir: () => fakeHome,
+}));
+
+// Stub execOutput so the process-table scan never shells out to `ps`.
+// The PID-file scan is the surface we want to exercise here.
+mock.module("../lib/step-runner", () => ({
+  execOutput: () => Promise.resolve(""),
+  exec: () => Promise.resolve(undefined),
+}));
+
+// Every detected PID claims to be a live process so the scan surfaces it.
+const originalKill = process.kill;
+process.kill = ((pid: number, signal?: string | number) => {
+  if (signal === 0) return true;
+  return originalKill.call(process, pid, signal);
+}) as typeof process.kill;
+
+import { detectOrphanedProcesses } from "../lib/orphan-detection.js";
+import {
+  saveAssistantEntry,
+  type AssistantEntry,
+  type LocalInstanceResources,
+} from "../lib/assistant-config.js";
+import {
+  DEFAULT_CES_PORT,
+  DEFAULT_DAEMON_PORT,
+  DEFAULT_GATEWAY_PORT,
+  DEFAULT_QDRANT_PORT,
+} from "../lib/constants.js";
+
+afterAll(() => {
+  process.kill = originalKill;
+  rmSync(testDir, { recursive: true, force: true });
+  rmSync(fakeHome, { recursive: true, force: true });
+  delete process.env.VELLUM_LOCKFILE_DIR;
+});
+
+function resetLockfile(): void {
+  for (const name of [".vellum.lock.json", ".vellum.lockfile.json"]) {
+    try {
+      rmSync(join(testDir, name));
+    } catch {
+      // file may not exist
+    }
+  }
+}
+
+function resetFakeHome(): void {
+  rmSync(fakeHome, { recursive: true, force: true });
+  mkdirSync(fakeHome, { recursive: true });
+}
+
+function makeResources(
+  instanceDir: string,
+  ports: Partial<LocalInstanceResources> = {},
+): LocalInstanceResources {
+  return {
+    instanceDir,
+    daemonPort: ports.daemonPort ?? DEFAULT_DAEMON_PORT,
+    gatewayPort: ports.gatewayPort ?? DEFAULT_GATEWAY_PORT,
+    qdrantPort: ports.qdrantPort ?? DEFAULT_QDRANT_PORT,
+    cesPort: ports.cesPort ?? DEFAULT_CES_PORT,
+    pidFile: join(instanceDir, ".vellum", "vellum.pid"),
+  };
+}
+
+function makeEntry(
+  id: string,
+  instanceDir: string,
+  extra?: Partial<AssistantEntry>,
+): AssistantEntry {
+  return {
+    assistantId: id,
+    runtimeUrl: `http://localhost:${DEFAULT_GATEWAY_PORT}`,
+    cloud: "local",
+    resources: makeResources(instanceDir),
+    ...extra,
+  };
+}
+
+function writePidFile(
+  instanceDir: string,
+  name: "vellum" | "gateway" | "qdrant",
+  pid: number,
+): void {
+  const dir = join(instanceDir, ".vellum");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${name}.pid`), String(pid));
+}
+
+describe("detectOrphanedProcesses", () => {
+  beforeEach(() => {
+    resetLockfile();
+    resetFakeHome();
+  });
+
+  test("scans every local entry's instanceDir/.vellum and reports each PID", async () => {
+    // GIVEN two local entries in the lockfile, each pointing at its own
+    // instance directory with a stale PID file
+    const instanceA = mkdtempSync(join(tmpdir(), "orphan-instance-a-"));
+    const instanceB = mkdtempSync(join(tmpdir(), "orphan-instance-b-"));
+    try {
+      saveAssistantEntry(makeEntry("alpha", instanceA));
+      saveAssistantEntry(
+        makeEntry("beta", instanceB, {
+          runtimeUrl: "http://localhost:8821",
+        }),
+      );
+      writePidFile(instanceA, "vellum", 111111);
+      writePidFile(instanceB, "gateway", 222222);
+
+      // WHEN we run orphan detection
+      const orphans = await detectOrphanedProcesses();
+
+      // THEN both containers are scanned and each PID is surfaced
+      const pidFileOrphans = orphans.filter((o) => o.source === "pid file");
+      const pids = pidFileOrphans.map((o) => o.pid);
+      expect(pids).toContain("111111");
+      expect(pids).toContain("222222");
+
+      const byName = new Map(pidFileOrphans.map((o) => [o.pid, o.name]));
+      expect(byName.get("111111")).toBe("assistant");
+      expect(byName.get("222222")).toBe("gateway");
+    } finally {
+      rmSync(instanceA, { recursive: true, force: true });
+      rmSync(instanceB, { recursive: true, force: true });
+    }
+  });
+
+  test("still scans legacy ~/.vellum/ when no lockfile entry covers it", async () => {
+    // GIVEN no local entries in the lockfile but a stale PID file in the
+    // legacy `~/.vellum/` root (pre-upgrade install)
+    resetLockfile();
+    writePidFile(fakeHome, "vellum", 333333);
+
+    // WHEN we run orphan detection
+    const orphans = await detectOrphanedProcesses();
+
+    // THEN the legacy root is still scanned and the PID surfaces
+    const pids = orphans
+      .filter((o) => o.source === "pid file")
+      .map((o) => o.pid);
+    expect(pids).toContain("333333");
+  });
+
+  test("legacy ~/.vellum/ is scanned alongside multi-instance entries", async () => {
+    // GIVEN a local entry AND a legacy `~/.vellum/` PID file at the same time
+    const instanceA = mkdtempSync(join(tmpdir(), "orphan-instance-coexist-"));
+    try {
+      saveAssistantEntry(makeEntry("alpha", instanceA));
+      writePidFile(instanceA, "vellum", 444444);
+      writePidFile(fakeHome, "gateway", 555555);
+
+      // WHEN we run orphan detection
+      const orphans = await detectOrphanedProcesses();
+
+      // THEN both the entry's instance dir and the legacy root are scanned
+      const pids = orphans
+        .filter((o) => o.source === "pid file")
+        .map((o) => o.pid);
+      expect(pids).toContain("444444");
+      expect(pids).toContain("555555");
+    } finally {
+      rmSync(instanceA, { recursive: true, force: true });
+    }
+  });
+
+  test("ignores remote entries — only local entries with resources are scanned", async () => {
+    // GIVEN a remote entry (no resources) alongside a local entry
+    const instanceA = mkdtempSync(join(tmpdir(), "orphan-instance-local-"));
+    try {
+      saveAssistantEntry({
+        assistantId: "cloud-box",
+        runtimeUrl: "http://10.0.0.1:7821",
+        cloud: "gcp",
+      });
+      saveAssistantEntry(makeEntry("alpha", instanceA));
+      writePidFile(instanceA, "qdrant", 666666);
+
+      // WHEN we run orphan detection
+      const orphans = await detectOrphanedProcesses();
+
+      // THEN the local entry's PID still surfaces (the remote entry is
+      // silently skipped)
+      const pids = orphans
+        .filter((o) => o.source === "pid file")
+        .map((o) => o.pid);
+      expect(pids).toContain("666666");
+    } finally {
+      rmSync(instanceA, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -0,0 +1,204 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  clearPlatformToken,
+  getPlatformUrl,
+  readPlatformToken,
+  savePlatformToken,
+} from "../lib/platform-client.js";
+
+describe("platform-client token path is env-scoped", () => {
+  let tempHome: string;
+  let savedXdg: string | undefined;
+  let savedEnv: string | undefined;
+
+  beforeEach(() => {
+    savedXdg = process.env.XDG_CONFIG_HOME;
+    savedEnv = process.env.VELLUM_ENVIRONMENT;
+    tempHome = mkdtempSync(join(tmpdir(), "cli-platform-client-test-"));
+    process.env.XDG_CONFIG_HOME = tempHome;
+    delete process.env.VELLUM_ENVIRONMENT;
+  });
+
+  afterEach(() => {
+    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("prod (VELLUM_ENVIRONMENT unset) writes to $XDG_CONFIG_HOME/vellum/platform-token", () => {
+    const token = "vak_prod_token_123";
+    savePlatformToken(token);
+
+    const prodPath = join(tempHome, "vellum", "platform-token");
+    expect(existsSync(prodPath)).toBe(true);
+    expect(readFileSync(prodPath, "utf-8").trim()).toBe(token);
+    expect(readPlatformToken()).toBe(token);
+  });
+
+  test("dev (VELLUM_ENVIRONMENT=dev) writes to $XDG_CONFIG_HOME/vellum-dev/platform-token", () => {
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    const token = "vak_dev_token_456";
+    savePlatformToken(token);
+
+    const devPath = join(tempHome, "vellum-dev", "platform-token");
+    expect(existsSync(devPath)).toBe(true);
+    expect(readFileSync(devPath, "utf-8").trim()).toBe(token);
+
+    const prodPath = join(tempHome, "vellum", "platform-token");
+    expect(existsSync(prodPath)).toBe(false);
+
+    expect(readPlatformToken()).toBe(token);
+  });
+
+  test("prod and dev tokens are isolated on disk", () => {
+    // Save prod token
+    delete process.env.VELLUM_ENVIRONMENT;
+    savePlatformToken("prod-token");
+
+    // Switch to dev and save a different token
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    savePlatformToken("dev-token");
+
+    // Dev read returns dev
+    expect(readPlatformToken()).toBe("dev-token");
+
+    // Switch back to prod — prod value is unchanged
+    delete process.env.VELLUM_ENVIRONMENT;
+    expect(readPlatformToken()).toBe("prod-token");
+
+    // Files live at distinct paths
+    expect(
+      readFileSync(join(tempHome, "vellum", "platform-token"), "utf-8").trim(),
+    ).toBe("prod-token");
+    expect(
+      readFileSync(
+        join(tempHome, "vellum-dev", "platform-token"),
+        "utf-8",
+      ).trim(),
+    ).toBe("dev-token");
+  });
+
+  test("clearPlatformToken removes only the env-scoped token", () => {
+    // Prod token
+    delete process.env.VELLUM_ENVIRONMENT;
+    savePlatformToken("prod-token");
+
+    // Dev token
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    savePlatformToken("dev-token");
+
+    // Clear dev
+    clearPlatformToken();
+    expect(existsSync(join(tempHome, "vellum-dev", "platform-token"))).toBe(
+      false,
+    );
+
+    // Prod still there
+    expect(existsSync(join(tempHome, "vellum", "platform-token"))).toBe(true);
+  });
+});
+
+describe("getPlatformUrl resolution order", () => {
+  let tempLockDir: string;
+  let savedLockDir: string | undefined;
+  let savedEnv: string | undefined;
+  let savedPlatformUrl: string | undefined;
+
+  beforeEach(() => {
+    savedLockDir = process.env.VELLUM_LOCKFILE_DIR;
+    savedEnv = process.env.VELLUM_ENVIRONMENT;
+    savedPlatformUrl = process.env.VELLUM_PLATFORM_URL;
+    tempLockDir = mkdtempSync(join(tmpdir(), "cli-platform-url-test-"));
+    process.env.VELLUM_LOCKFILE_DIR = tempLockDir;
+    delete process.env.VELLUM_ENVIRONMENT;
+    delete process.env.VELLUM_PLATFORM_URL;
+  });
+
+  afterEach(() => {
+    if (savedLockDir === undefined) {
+      delete process.env.VELLUM_LOCKFILE_DIR;
+    } else {
+      process.env.VELLUM_LOCKFILE_DIR = savedLockDir;
+    }
+    if (savedEnv === undefined) {
+      delete process.env.VELLUM_ENVIRONMENT;
+    } else {
+      process.env.VELLUM_ENVIRONMENT = savedEnv;
+    }
+    if (savedPlatformUrl === undefined) {
+      delete process.env.VELLUM_PLATFORM_URL;
+    } else {
+      process.env.VELLUM_PLATFORM_URL = savedPlatformUrl;
+    }
+    rmSync(tempLockDir, { recursive: true, force: true });
+  });
+
+  function writeLockfile(data: Record<string, unknown>): void {
+    // VELLUM_ENVIRONMENT is unset → production env → `.vellum.lock.json`.
+    writeFileSync(
+      join(tempLockDir, ".vellum.lock.json"),
+      JSON.stringify(data, null, 2),
+    );
+  }
+
+  test("returns lockfile platformBaseUrl when set", () => {
+    writeLockfile({ platformBaseUrl: "https://staging.vellum.ai" });
+    expect(getPlatformUrl()).toBe("https://staging.vellum.ai");
+  });
+
+  test("lockfile platformBaseUrl takes priority over VELLUM_PLATFORM_URL", () => {
+    writeLockfile({ platformBaseUrl: "https://lockfile.vellum.ai" });
+    process.env.VELLUM_PLATFORM_URL = "https://env.vellum.ai";
+    expect(getPlatformUrl()).toBe("https://lockfile.vellum.ai");
+  });
+
+  test("falls back to VELLUM_PLATFORM_URL when lockfile is missing", () => {
+    process.env.VELLUM_PLATFORM_URL = "https://env-only.vellum.ai";
+    expect(getPlatformUrl()).toBe("https://env-only.vellum.ai");
+  });
+
+  test("falls back to VELLUM_PLATFORM_URL when lockfile has no platformBaseUrl", () => {
+    writeLockfile({ assistants: [] });
+    process.env.VELLUM_PLATFORM_URL = "https://env-fallback.vellum.ai";
+    expect(getPlatformUrl()).toBe("https://env-fallback.vellum.ai");
+  });
+
+  test("falls back to VELLUM_PLATFORM_URL when lockfile platformBaseUrl is blank", () => {
+    writeLockfile({ platformBaseUrl: "   " });
+    process.env.VELLUM_PLATFORM_URL = "https://env-after-blank.vellum.ai";
+    expect(getPlatformUrl()).toBe("https://env-after-blank.vellum.ai");
+  });
+
+  test("falls back to prod env seed URL when lockfile and VELLUM_PLATFORM_URL are unset (prod env)", () => {
+    // VELLUM_ENVIRONMENT is unset → production → prod seed URL.
+    expect(getPlatformUrl()).toBe("https://platform.vellum.ai");
+  });
+
+  test("falls back to dev env seed URL when VELLUM_ENVIRONMENT=dev", () => {
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    expect(getPlatformUrl()).toBe("https://dev-platform.vellum.ai");
+  });
+
+  test("trims whitespace from VELLUM_PLATFORM_URL", () => {
+    process.env.VELLUM_PLATFORM_URL = "  https://trimmed.vellum.ai  ";
+    expect(getPlatformUrl()).toBe("https://trimmed.vellum.ai");
+  });
+});

package/src/__tests__/preload.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared CLI test preload — runs before every test file.
+ *
+ * Sets VELLUM_WORKSPACE_DIR to a temporary directory so that any CLI helper
+ * that resolves workspace paths won't accidentally touch the real workspace.
+ *
+ * Cleanup: the temp dir is removed after all tests in the file complete.
+ */
+
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll } from "bun:test";
+
+const testDir = realpathSync(
+  mkdtempSync(join(tmpdir(), "vellum-cli-test-workspace-")),
+);
+process.env.VELLUM_WORKSPACE_DIR = testDir;
+
+afterAll(() => {
+  delete process.env.VELLUM_WORKSPACE_DIR;
+  try {
+    rmSync(testDir, { recursive: true, force: true });
+  } catch {
+    /* best-effort cleanup */
+  }
+});

package/src/__tests__/ssh-user-guard.test.ts

@@ -0,0 +1,28 @@
+import { describe, test, expect } from "bun:test";
+import { readFileSync } from "fs";
+import { join } from "path";
+
+// Regression guard for PR #25292: hatchAws/hatchGcp must abort before
+// launching a cloud instance when sshUser is empty. Otherwise `useradd ""`
+// in the generated startup script fails after billable resources are live.
+describe("sshUser empty-string guard", () => {
+  const files = [
+    join(import.meta.dir, "..", "lib", "aws.ts"),
+    join(import.meta.dir, "..", "lib", "gcp.ts"),
+  ];
+
+  for (const file of files) {
+    test(`${file.split("/").slice(-2).join("/")} aborts on empty sshUser`, () => {
+      const source = readFileSync(file, "utf8");
+      const fallbackIdx = source.indexOf('sshUser = process.env.USER ?? ""');
+      expect(fallbackIdx).toBeGreaterThan(-1);
+
+      const afterFallback = source.slice(fallbackIdx);
+      const guardIdx = afterFallback.search(/if\s*\(\s*!sshUser\s*\)/);
+      expect(guardIdx).toBeGreaterThan(-1);
+
+      const guardBlock = afterFallback.slice(guardIdx, guardIdx + 400);
+      expect(guardBlock).toContain("process.exit(1)");
+    });
+  }
+});