@vellumai/cli 0.8.4 → 0.8.6

package/AGENTS.md

@@ -16,7 +16,17 @@ Examples: `hatch`, `wake`, `sleep`, `retire`, `ps`, `ssh` belong here. `config`,
 
 ## Assistant targeting convention
 
-Commands that act on a specific assistant should accept an assistant name or ID as an argument. When none is specified, default to the most recently created local assistant. Use `loadAllAssistants()` and `findAssistantByName()` from `lib/assistant-config` for resolution.
+New or modified commands that act on a specific assistant should accept an assistant display name or ID as an argument. Exact assistant ID matches must win over display-name matches. Unique display-name matches may resolve to the matching assistant ID, but ambiguous display names must fail with an error that lists the matching IDs.
+
+Use the shared helpers from `lib/assistant-config` instead of hand-rolled lookup:
+
+- `lookupAssistantByIdentifier()` for commands that require an explicit target and need custom error handling.
+- `resolveTargetAssistant()` for commands that may fall back to the active assistant or sole lockfile entry.
+- `formatAssistantReference()` for user-facing output that should include both display name and ID when they differ.
+
+Use `parseAssistantTargetArg()` from `lib/assistant-target-args` when parsing command arguments that may contain an unquoted multi-word display name. Do not store raw display names in `activeAssistant`; persist the resolved `assistantId`.
+
+New or modified destructive lifecycle commands must be explicit and safe. A command that deletes, retires, archives, or removes assistant state must print the resolved assistant identity before acting and require an interactive confirmation, with a documented `--yes` bypass only for automation or higher-level clients that already own confirmation. Do not expose destructive lifecycle actions as `vellum client` slash commands.
 
 ## Conventions
 
@@ -53,6 +63,12 @@ The CLI must **never** read from or write to the `.vellum/` directory (e.g. `~/.
 
 For example, the signing key used for JWT auth between the daemon and gateway is persisted in the lockfile (`resources.signingKey`) so that client actor tokens survive daemon/gateway restarts. On first start (or when the key is missing), the CLI generates a new key via `generateLocalSigningKey()` in `lib/local.ts`, saves it to the lockfile entry, and passes it to both `startLocalDaemon` and `startGateway` as the `ACTOR_TOKEN_SIGNING_KEY` env var. The CLI does **not** read or write to the `.vellum/` directory for signing keys — it uses the lockfile instead.
 
+## Process liveness
+
+Use `resolveProcessState()` from `lib/process.ts` when checking whether a daemon or gateway should be (re)started. It combines PID existence with an HTTP `/healthz` probe, a readiness grace period, and a [`isVellumProcess()`](https://man7.org/linux/man-pages/man1/ps.1.html) guard against PID reuse — see the function's JSDoc for the full flow.
+
+Reserve `isProcessAlive()` for teardown paths (`sleep`, `retire`) where you need to kill a process regardless of its health.
+
 ## Docker Volume Management
 
 The CLI creates and manages six per-instance Docker volumes with strict per-service access boundaries (least-privilege at the container level).

package/knip.json

@@ -7,5 +7,6 @@
     "src/lib/platform-releases.ts",
     "src/lib/cli-error.ts"
   ],
-  "project": ["src/**/*.ts", "src/**/*.tsx"]
+  "project": ["src/**/*.ts", "src/**/*.tsx"],
+  "ignoreDependencies": ["@vellumai/web"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/api-key-check.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { checkProviderApiKey } from "../lib/api-key-check.js";
+
+const PROVIDER_KEYS = [
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+  "GEMINI_API_KEY",
+  "FIREWORKS_API_KEY",
+  "OPENROUTER_API_KEY",
+] as const;
+
+beforeEach(() => {
+  for (const key of PROVIDER_KEYS) {
+    delete process.env[key];
+  }
+});
+
+afterEach(() => {
+  for (const key of PROVIDER_KEYS) {
+    delete process.env[key];
+  }
+});
+
+describe("checkProviderApiKey", () => {
+  test("returns hasKey:false when no provider keys are in process.env", () => {
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(false);
+  });
+
+  test("returns hasKey:false when ANTHROPIC_API_KEY is a placeholder", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-...";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(false);
+  });
+
+  test("returns hasKey:false when OPENAI_API_KEY is a placeholder", () => {
+    process.env.OPENAI_API_KEY = "sk-...";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(false);
+  });
+
+  test("returns hasKey:false when key is empty", () => {
+    process.env.ANTHROPIC_API_KEY = "";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(false);
+  });
+
+  test("returns hasKey:true when ANTHROPIC_API_KEY is a real key", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-api03-realkey123";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(true);
+  });
+
+  test("returns hasKey:true when OPENAI_API_KEY is a real key", () => {
+    process.env.OPENAI_API_KEY = "sk-proj-realkey123";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(true);
+  });
+
+  test("returns hasKey:true when GEMINI_API_KEY is a real key", () => {
+    process.env.GEMINI_API_KEY = "AIzaSyRealKey123";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(true);
+  });
+
+  test("returns hasKey:true when FIREWORKS_API_KEY is a real key", () => {
+    process.env.FIREWORKS_API_KEY = "fw-realkey123";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(true);
+  });
+
+  test("returns hasKey:true when OPENROUTER_API_KEY is a real key", () => {
+    process.env.OPENROUTER_API_KEY = "sk-or-realkey123";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(true);
+  });
+});

package/src/__tests__/backup.test.ts

@@ -162,6 +162,16 @@ beforeEach(() => {
   });
   getBackupsDirMock.mockReset();
   getBackupsDirMock.mockReturnValue("/tmp/backups-default");
+  loadGuardianTokenSpy.mockReset();
+  loadGuardianTokenSpy.mockReturnValue({
+    accessToken: "local-token",
+    accessTokenExpiresAt: new Date(Date.now() + 60_000).toISOString(),
+  } as unknown as ReturnType<typeof guardianToken.loadGuardianToken>);
+  leaseGuardianTokenSpy.mockReset();
+  leaseGuardianTokenSpy.mockResolvedValue({
+    accessToken: "leased-token",
+    accessTokenExpiresAt: new Date(Date.now() + 60_000).toISOString(),
+  } as unknown as Awaited<ReturnType<typeof guardianToken.leaseGuardianToken>>);
   mkdirSyncMock.mockReset();
   mkdirSyncMock.mockImplementation((() => undefined) as never);
   writeFileSyncMock.mockReset();
@@ -207,6 +217,34 @@ function mockGcsDownload(body: Uint8Array, ok = true, status = 200) {
   }) as unknown as typeof globalThis.fetch;
 }
 
+describe("vellum backup <local>: guardian bootstrap secret", () => {
+  test("passes the lockfile bootstrap secret when leasing a fresh guardian token", async () => {
+    const localEntry = {
+      assistantId: "local-assistant",
+      runtimeUrl: "http://127.0.0.1:7830",
+      cloud: "local",
+      guardianBootstrapSecret: "bootstrap-secret-value",
+    } satisfies assistantConfig.AssistantEntry;
+    findAssistantByNameMock.mockReturnValue(localEntry);
+    loadGuardianTokenSpy.mockReturnValue(null);
+    setArgv("my-local", "--output", "/tmp/local-backup.vbundle");
+
+    globalThis.fetch = mock(async () => {
+      return new Response(new Uint8Array([1, 2, 3]), {
+        status: 200,
+      });
+    }) as unknown as typeof globalThis.fetch;
+
+    await backup();
+
+    expect(leaseGuardianTokenSpy).toHaveBeenCalledWith(
+      "http://127.0.0.1:7830",
+      "local-assistant",
+      "bootstrap-secret-value",
+    );
+  });
+});
+
 describe("vellum backup <platform-managed>: GCS happy path", () => {
   test("requests upload URL → kicks off runtime export → polls → downloads from GCS → writes file", async () => {
     findAssistantByNameMock.mockReturnValue(VELLUM_ENTRY);

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 });
+  });
+});