@vellumai/cli 0.8.5 → 0.8.7

package/src/__tests__/recover.test.ts

@@ -0,0 +1,307 @@
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, join } from "node:path";
+
+import type { AssistantEntry } from "../lib/assistant-config.js";
+import * as localModule from "../lib/local.js";
+import * as stepRunnerModule from "../lib/step-runner.js";
+
+// Captured real exports — afterAll restores these so module mocks don't
+// leak into other test files in the same `bun test` run.
+const realLocal = {
+  generateLocalSigningKey: localModule.generateLocalSigningKey,
+  startLocalDaemon: localModule.startLocalDaemon,
+  startGateway: localModule.startGateway,
+};
+const realExec = stepRunnerModule.exec;
+
+// Prevent real daemon / gateway from starting
+const startLocalDaemonMock = mock(async () => {});
+const startGatewayMock = mock(async () => {});
+
+// Capture exec calls without running real tar
+const execMock = mock(async (_cmd: string, _args: string[]) => {});
+
+beforeAll(() => {
+  mock.module("../lib/local.js", () => ({
+    generateLocalSigningKey: () => "deadbeefdeadbeefdeadbeefdeadbeef",
+    startLocalDaemon: startLocalDaemonMock,
+    startGateway: startGatewayMock,
+  }));
+  mock.module("../lib/step-runner.js", () => ({ exec: execMock }));
+});
+
+afterAll(() => {
+  mock.module("../lib/local.js", () => realLocal);
+  mock.module("../lib/step-runner.js", () => ({ exec: realExec }));
+});
+
+import { recover } from "../commands/recover.js";
+
+// ── Test fixtures ─────────────────────────────────────────────────────────────
+
+const testDir = mkdtempSync(join(tmpdir(), "cli-recover-test-"));
+const originalArgv = [...process.argv];
+const originalLockfileDir = process.env.VELLUM_LOCKFILE_DIR;
+const originalXdgData = process.env.XDG_DATA_HOME;
+
+// Directories that getRetiredDir() will use when XDG_DATA_HOME is overridden
+const retiredDir = join(testDir, "vellum", "retired");
+
+function makeEntry(assistantId: string, instanceDir: string): AssistantEntry {
+  return {
+    assistantId,
+    runtimeUrl: "http://127.0.0.1:7831",
+    cloud: "local",
+    resources: {
+      instanceDir,
+      daemonPort: 7801,
+      gatewayPort: 7831,
+      qdrantPort: 6334,
+      cesPort: 7790,
+    },
+  };
+}
+
+function writeArchiveFixtures(
+  name: string,
+  entry: AssistantEntry,
+): {
+  archivePath: string;
+  metadataPath: string;
+  extractedPath: string;
+} {
+  mkdirSync(retiredDir, { recursive: true });
+  const archivePath = join(retiredDir, `${name}.tar.gz`);
+  const metadataPath = join(retiredDir, `${name}.json`);
+  // The staging dir is what tar extracts — <archive>.staging relative to retiredDir
+  const extractedPath = join(retiredDir, basename(archivePath) + ".staging");
+
+  // Write a placeholder archive file (exec is mocked; content doesn't matter)
+  writeFileSync(archivePath, "");
+  writeFileSync(metadataPath, JSON.stringify(entry, null, 2) + "\n");
+  // Create the staging dir that tar would have created
+  mkdirSync(extractedPath, { recursive: true });
+
+  return { archivePath, metadataPath, extractedPath };
+}
+
+let consoleLogSpy: ReturnType<typeof spyOn>;
+let consoleErrorSpy: ReturnType<typeof spyOn>;
+let exitSpy: ReturnType<typeof spyOn>;
+
+beforeEach(() => {
+  // Route lockfile and retired archives to the temp directory
+  process.env.VELLUM_LOCKFILE_DIR = testDir;
+  process.env.XDG_DATA_HOME = testDir;
+  // Write an empty lockfile so saveAssistantEntry has a dir to write to
+  mkdirSync(testDir, { recursive: true });
+  writeFileSync(
+    join(testDir, ".vellum.lock.json"),
+    JSON.stringify({ assistants: [] }) + "\n",
+  );
+
+  consoleLogSpy = spyOn(console, "log").mockImplementation(() => {});
+  consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+  exitSpy = spyOn(process, "exit").mockImplementation((_code?: number) => {
+    throw new Error(`process.exit(${_code})`);
+  });
+
+  execMock.mockClear();
+  startLocalDaemonMock.mockClear();
+  startGatewayMock.mockClear();
+});
+
+afterEach(() => {
+  process.argv = [...originalArgv];
+  process.env.VELLUM_LOCKFILE_DIR = originalLockfileDir;
+  process.env.XDG_DATA_HOME = originalXdgData;
+  consoleLogSpy.mockRestore();
+  consoleErrorSpy.mockRestore();
+  exitSpy.mockRestore();
+  // Clean up per-test artifacts inside testDir/vellum/
+  if (existsSync(join(testDir, "vellum"))) {
+    rmSync(join(testDir, "vellum"), { recursive: true, force: true });
+  }
+});
+
+// Runs after all tests finish
+afterAll(() => {
+  rmSync(testDir, { recursive: true, force: true });
+  process.argv = [...originalArgv];
+  if (originalLockfileDir !== undefined) {
+    process.env.VELLUM_LOCKFILE_DIR = originalLockfileDir;
+  } else {
+    delete process.env.VELLUM_LOCKFILE_DIR;
+  }
+  if (originalXdgData !== undefined) {
+    process.env.XDG_DATA_HOME = originalXdgData;
+  } else {
+    delete process.env.XDG_DATA_HOME;
+  }
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("recover --help", () => {
+  test("prints usage, description, and examples then exits 0", async () => {
+    process.argv = ["bun", "vellum", "recover", "--help"];
+    await expect(recover()).rejects.toThrow("process.exit(0)");
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Usage: vellum recover <name>");
+    expect(output).toContain("Examples:");
+    expect(output).toContain("vellum recover");
+  });
+});
+
+describe("recover error cases", () => {
+  test("exits 1 when no name is given", async () => {
+    process.argv = ["bun", "vellum", "recover"];
+    await expect(recover()).rejects.toThrow("process.exit(1)");
+    expect(consoleErrorSpy.mock.calls[0][0]).toContain("Usage:");
+  });
+
+  test("exits 1 when archive is missing", async () => {
+    process.argv = ["bun", "vellum", "recover", "ghost-assistant"];
+    await expect(recover()).rejects.toThrow("process.exit(1)");
+    expect(consoleErrorSpy.mock.calls[0][0]).toContain(
+      "No retired archive found for 'ghost-assistant'",
+    );
+  });
+
+  test("throws when metadata has no resources", async () => {
+    const name = "no-resources";
+    mkdirSync(retiredDir, { recursive: true });
+    writeFileSync(join(retiredDir, `${name}.tar.gz`), "");
+    const entry: Partial<AssistantEntry> = {
+      assistantId: name,
+      runtimeUrl: "http://127.0.0.1:7831",
+      cloud: "local",
+      // resources intentionally omitted
+    };
+    writeFileSync(
+      join(retiredDir, `${name}.json`),
+      JSON.stringify(entry, null, 2) + "\n",
+    );
+    process.argv = ["bun", "vellum", "recover", name];
+    await expect(recover()).rejects.toThrow("missing resource configuration");
+  });
+
+  test("exits 1 when target .vellum/ already exists", async () => {
+    const name = "already-exists";
+    const instanceDir = join(testDir, name);
+    const entry = makeEntry(name, instanceDir);
+    writeArchiveFixtures(name, entry);
+    // Pre-create the collision path that recover checks
+    mkdirSync(join(instanceDir, ".vellum"), { recursive: true });
+    process.argv = ["bun", "vellum", "recover", name];
+    await expect(recover()).rejects.toThrow("process.exit(1)");
+    expect(consoleErrorSpy.mock.calls[0][0]).toContain("already exists");
+  });
+});
+
+describe("recover extraction path — default instance (instanceDir === homedir())", () => {
+  test("extracts to retiredDir and renames staging dir to instanceDir/.vellum", async () => {
+    const name = "default-instance";
+    // Default instance: instanceDir is the real home directory
+    const entry = makeEntry(name, homedir());
+    const { archivePath, extractedPath } = writeArchiveFixtures(name, entry);
+
+    const expectedTargetDir = join(homedir(), ".vellum");
+
+    process.argv = ["bun", "vellum", "recover", name];
+    await recover();
+
+    // exec must have been called with -C retiredDir, NOT -C homedir()
+    expect(execMock).toHaveBeenCalledTimes(1);
+    const [cmd, args] = execMock.mock.calls[0] as [string, string[]];
+    expect(cmd).toBe("tar");
+    expect(args).toContain("-C");
+    const cIndex = args.indexOf("-C");
+    expect(args[cIndex + 1]).toBe(retiredDir);
+    expect(args[cIndex + 1]).not.toBe(homedir());
+
+    // Staging dir was renamed to the correct target
+    expect(existsSync(extractedPath)).toBe(false);
+    expect(existsSync(expectedTargetDir)).toBe(true);
+
+    // Archive and metadata were cleaned up
+    expect(existsSync(archivePath)).toBe(false);
+
+    // Daemon and gateway were started
+    expect(startLocalDaemonMock).toHaveBeenCalledTimes(1);
+    expect(startGatewayMock).toHaveBeenCalledTimes(1);
+
+    // Clean up so we don't leave a .vellum dir in the real home dir
+    rmSync(expectedTargetDir, { recursive: true, force: true });
+  });
+});
+
+describe("recover extraction path — named instance (instanceDir !== homedir())", () => {
+  test("extracts to retiredDir and renames staging dir to instanceDir directly", async () => {
+    const name = "named-instance";
+    const instanceDir = join(testDir, "custom-location", name);
+    const entry = makeEntry(name, instanceDir);
+    const { archivePath, extractedPath } = writeArchiveFixtures(name, entry);
+
+    // Named instance: targetDir is instanceDir itself (not instanceDir/.vellum)
+    const expectedTargetDir = instanceDir;
+    // Parent dir must exist for renameSync
+    mkdirSync(join(testDir, "custom-location"), { recursive: true });
+
+    process.argv = ["bun", "vellum", "recover", name];
+    await recover();
+
+    // exec must have been called with -C retiredDir
+    expect(execMock).toHaveBeenCalledTimes(1);
+    const [cmd, args] = execMock.mock.calls[0] as [string, string[]];
+    expect(cmd).toBe("tar");
+    const cIndex = args.indexOf("-C");
+    expect(args[cIndex + 1]).toBe(retiredDir);
+
+    // Staging dir was renamed to instanceDir (not instanceDir/.vellum)
+    expect(existsSync(extractedPath)).toBe(false);
+    expect(existsSync(expectedTargetDir)).toBe(true);
+
+    // Archive cleaned up
+    expect(existsSync(archivePath)).toBe(false);
+
+    // Daemon and gateway were started
+    expect(startLocalDaemonMock).toHaveBeenCalledTimes(1);
+    expect(startGatewayMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("creates parent directories of instanceDir when they do not exist", async () => {
+    const name = "deep-nested-instance";
+    // Use a path whose parent directory does not yet exist
+    const instanceDir = join(testDir, "new-parent", "deeper", name);
+    const entry = makeEntry(name, instanceDir);
+    const { archivePath, extractedPath } = writeArchiveFixtures(name, entry);
+
+    process.argv = ["bun", "vellum", "recover", name];
+    await recover();
+
+    expect(existsSync(extractedPath)).toBe(false);
+    expect(existsSync(instanceDir)).toBe(true);
+    expect(existsSync(archivePath)).toBe(false);
+
+    rmSync(instanceDir, { recursive: true, force: true });
+  });
+});

package/src/__tests__/segments-to-plain-text.test.ts

@@ -0,0 +1,37 @@
+import { describe, test, expect } from "bun:test";
+import { segmentsToPlainText } from "../lib/segments-to-plain-text.js";
+
+describe("segmentsToPlainText", () => {
+  test("returns empty string for missing or empty segments", () => {
+    // GIVEN a message whose history payload carries no text segments
+    // WHEN deriving its flat body
+    // THEN it is the empty string (matching the daemon's old empty `content`)
+    expect(segmentsToPlainText(undefined)).toBe("");
+    expect(segmentsToPlainText([])).toBe("");
+  });
+
+  test("returns a single segment unchanged", () => {
+    // GIVEN a plain-text message with one segment
+    // WHEN deriving its flat body
+    // THEN the segment is returned verbatim
+    expect(segmentsToPlainText(["Real reply."])).toBe("Real reply.");
+  });
+
+  test("joins adjacent segments with a single inserted space", () => {
+    // GIVEN segments split at a tool_use boundary with no surrounding whitespace
+    // WHEN deriving the flat body
+    // THEN a single space is inserted between them
+    expect(segmentsToPlainText(["before", "after"])).toBe("before after");
+  });
+
+  test("does not double-space when either side already has whitespace", () => {
+    // GIVEN segments where one side already ends/starts with whitespace
+    // WHEN deriving the flat body
+    // THEN no extra space is inserted (mirrors daemon joinWithSpacing)
+    expect(segmentsToPlainText(["before ", "after"])).toBe("before after");
+    expect(segmentsToPlainText(["before", " after"])).toBe("before after");
+    expect(segmentsToPlainText(["line one\n", "line two"])).toBe(
+      "line one\nline two",
+    );
+  });
+});

package/src/__tests__/wake.test.ts

@@ -0,0 +1,215 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import * as assistantConfig from "../lib/assistant-config.js";
+import * as docker from "../lib/docker.js";
+import * as guardianToken from "../lib/guardian-token.js";
+import * as local from "../lib/local.js";
+import * as ngrok from "../lib/ngrok.js";
+import * as processLib from "../lib/process.js";
+import type { AssistantEntry } from "../lib/assistant-config.js";
+
+const realAssistantConfig = { ...assistantConfig };
+const realDocker = { ...docker };
+const realGuardianToken = { ...guardianToken };
+const realLocal = { ...local };
+const realNgrok = { ...ngrok };
+const realProcessLib = { ...processLib };
+
+const resolveTargetAssistantMock = mock<
+  typeof assistantConfig.resolveTargetAssistant
+>();
+const saveAssistantEntryMock = mock<typeof assistantConfig.saveAssistantEntry>(
+  () => {},
+);
+const getDaemonPidPathMock = mock<typeof assistantConfig.getDaemonPidPath>(
+  (resources) => join(resources!.instanceDir, ".vellum", "daemon.pid"),
+);
+
+mock.module("../lib/assistant-config.js", () => ({
+  ...realAssistantConfig,
+  resolveTargetAssistant: resolveTargetAssistantMock,
+  saveAssistantEntry: saveAssistantEntryMock,
+  getDaemonPidPath: getDaemonPidPathMock,
+}));
+
+const dockerResourceNamesMock = mock<typeof docker.dockerResourceNames>(
+  realDocker.dockerResourceNames,
+);
+const wakeContainersMock = mock<typeof docker.wakeContainers>(async () => {});
+
+mock.module("../lib/docker.js", () => ({
+  ...realDocker,
+  dockerResourceNames: dockerResourceNamesMock,
+  wakeContainers: wakeContainersMock,
+}));
+
+const seedGuardianTokenFromSiblingEnvMock = mock<
+  typeof guardianToken.seedGuardianTokenFromSiblingEnv
+>(() => false);
+
+mock.module("../lib/guardian-token.js", () => ({
+  ...realGuardianToken,
+  seedGuardianTokenFromSiblingEnv: seedGuardianTokenFromSiblingEnvMock,
+}));
+
+const resolveProcessStateMock = mock<typeof processLib.resolveProcessState>(
+  async (_pidFile, _port, label) => ({
+    status: "healthy",
+    pid: label === "Gateway" ? 456 : 123,
+  }),
+);
+const stopProcessByPidFileMock = mock<typeof processLib.stopProcessByPidFile>(
+  async () => true,
+);
+
+mock.module("../lib/process", () => ({
+  ...realProcessLib,
+  resolveProcessState: resolveProcessStateMock,
+  stopProcessByPidFile: stopProcessByPidFileMock,
+}));
+
+const generateLocalSigningKeyMock = mock<typeof local.generateLocalSigningKey>(
+  () => "generated-bootstrap-secret",
+);
+const isAssistantWatchModeAvailableMock = mock<
+  typeof local.isAssistantWatchModeAvailable
+>(() => false);
+const isGatewayWatchModeAvailableMock = mock<
+  typeof local.isGatewayWatchModeAvailable
+>(() => false);
+const startLocalDaemonMock = mock<typeof local.startLocalDaemon>(async () => {});
+const startGatewayMock = mock<typeof local.startGateway>(
+  async () => "http://127.0.0.1:7830",
+);
+
+mock.module("../lib/local", () => ({
+  ...realLocal,
+  generateLocalSigningKey: generateLocalSigningKeyMock,
+  isAssistantWatchModeAvailable: isAssistantWatchModeAvailableMock,
+  isGatewayWatchModeAvailable: isGatewayWatchModeAvailableMock,
+  startLocalDaemon: startLocalDaemonMock,
+  startGateway: startGatewayMock,
+}));
+
+const maybeStartNgrokTunnelMock = mock<typeof ngrok.maybeStartNgrokTunnel>(
+  async () => null,
+);
+
+mock.module("../lib/ngrok", () => ({
+  ...realNgrok,
+  maybeStartNgrokTunnel: maybeStartNgrokTunnelMock,
+}));
+
+const { wake } = await import("../commands/wake.js");
+
+let tempDir: string;
+let originalArgv: string[];
+let logSpy: ReturnType<typeof spyOn>;
+
+function makeLocalEntry(): AssistantEntry {
+  tempDir = mkdtempSync(join(tmpdir(), "vellum-wake-test-"));
+  mkdirSync(join(tempDir, ".vellum"), { recursive: true });
+  return {
+    assistantId: "local-assistant",
+    runtimeUrl: "http://127.0.0.1:7830",
+    cloud: "local",
+    resources: {
+      instanceDir: tempDir,
+      daemonPort: 7821,
+      gatewayPort: 7830,
+      qdrantPort: 6333,
+      cesPort: 7822,
+      signingKey: "existing-signing-key",
+    },
+  };
+}
+
+beforeEach(() => {
+  originalArgv = [...process.argv];
+  tempDir = "";
+  process.argv = ["bun", "vellum", "wake", "--watch", "local-assistant"];
+  logSpy = spyOn(console, "log").mockImplementation(() => {});
+
+  const entry = makeLocalEntry();
+  resolveTargetAssistantMock.mockReset();
+  resolveTargetAssistantMock.mockReturnValue(entry);
+  saveAssistantEntryMock.mockReset();
+  getDaemonPidPathMock.mockReset();
+  getDaemonPidPathMock.mockImplementation((resources) =>
+    join(resources!.instanceDir, ".vellum", "daemon.pid"),
+  );
+  resolveProcessStateMock.mockReset();
+  resolveProcessStateMock.mockImplementation(async (_pidFile, _port, label) => ({
+    status: "healthy",
+    pid: label === "Gateway" ? 456 : 123,
+  }));
+  stopProcessByPidFileMock.mockReset();
+  stopProcessByPidFileMock.mockResolvedValue(true);
+  generateLocalSigningKeyMock.mockReset();
+  generateLocalSigningKeyMock.mockReturnValue("generated-bootstrap-secret");
+  isAssistantWatchModeAvailableMock.mockReset();
+  isAssistantWatchModeAvailableMock.mockReturnValue(false);
+  isGatewayWatchModeAvailableMock.mockReset();
+  isGatewayWatchModeAvailableMock.mockReturnValue(false);
+  startLocalDaemonMock.mockReset();
+  startLocalDaemonMock.mockResolvedValue(undefined);
+  startGatewayMock.mockReset();
+  startGatewayMock.mockResolvedValue("http://127.0.0.1:7830");
+  seedGuardianTokenFromSiblingEnvMock.mockReset();
+  seedGuardianTokenFromSiblingEnvMock.mockReturnValue(false);
+  maybeStartNgrokTunnelMock.mockReset();
+  maybeStartNgrokTunnelMock.mockResolvedValue(null);
+});
+
+afterEach(() => {
+  process.argv = originalArgv;
+  logSpy.mockRestore();
+  if (tempDir) {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+});
+
+afterAll(() => {
+  mock.module("../lib/assistant-config.js", () => realAssistantConfig);
+  mock.module("../lib/docker.js", () => realDocker);
+  mock.module("../lib/guardian-token.js", () => realGuardianToken);
+  mock.module("../lib/process", () => realProcessLib);
+  mock.module("../lib/local", () => realLocal);
+  mock.module("../lib/ngrok", () => realNgrok);
+});
+
+describe("vellum wake", () => {
+  test("restarts a running gateway without watch mode when backfilling the bootstrap secret", async () => {
+    await wake();
+
+    expect(saveAssistantEntryMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        guardianBootstrapSecret: "generated-bootstrap-secret",
+      }),
+    );
+    expect(stopProcessByPidFileMock).toHaveBeenCalledWith(
+      join(tempDir, ".vellum", "gateway.pid"),
+      "gateway",
+    );
+    expect(startGatewayMock).toHaveBeenCalledWith(
+      false,
+      expect.objectContaining({ instanceDir: tempDir }),
+      {
+        signingKey: "existing-signing-key",
+        bootstrapSecret: "generated-bootstrap-secret",
+      },
+    );
+  });
+});

package/src/commands/backup.ts

@@ -93,6 +93,7 @@ export async function backup(): Promise<void> {
       const freshToken = await leaseGuardianToken(
         entry.runtimeUrl,
         entry.assistantId,
+        entry.guardianBootstrapSecret,
       );
       accessToken = freshToken.accessToken;
     } catch (err) {
@@ -129,6 +130,7 @@ export async function backup(): Promise<void> {
         const freshToken = await leaseGuardianToken(
           entry.runtimeUrl,
           entry.assistantId,
+          entry.guardianBootstrapSecret,
         );
         refreshedToken = freshToken.accessToken;
       } catch {