@vellumai/cli 0.8.4 → 0.8.5

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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "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__/retire.test.ts

@@ -0,0 +1,241 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { AssistantEntry } from "../lib/assistant-config.js";
+import { loadAllAssistants } from "../lib/assistant-config.js";
+import * as retireLocalModule from "../lib/retire-local.js";
+
+const testDir = mkdtempSync(join(tmpdir(), "cli-retire-test-"));
+const originalArgv = [...process.argv];
+const originalExit = process.exit;
+const originalLockfileDir = process.env.VELLUM_LOCKFILE_DIR;
+const originalStdinIsTTY = process.stdin.isTTY;
+const originalStdoutIsTTY = process.stdout.isTTY;
+const originalStdinIsRaw = process.stdin.isRaw;
+const originalSetRawMode = process.stdin.setRawMode;
+const originalStdoutWrite = process.stdout.write;
+const realRetireLocalModule = { ...retireLocalModule };
+
+const retireLocalMock = mock(async () => {});
+
+mock.module("../lib/retire-local.js", () => ({
+  ...realRetireLocalModule,
+  retireLocal: retireLocalMock,
+}));
+
+import { retire } from "../commands/retire.js";
+
+let consoleLogSpy: ReturnType<typeof spyOn>;
+let consoleErrorSpy: ReturnType<typeof spyOn>;
+
+function makeEntry(
+  assistantId: string,
+  extra: Partial<AssistantEntry> = {},
+): AssistantEntry {
+  return {
+    assistantId,
+    runtimeUrl: `http://127.0.0.1:${7800 + assistantId.length}`,
+    cloud: "local",
+    resources: {
+      instanceDir: join(testDir, assistantId),
+      daemonPort: 7801,
+      gatewayPort: 7831,
+      qdrantPort: 6334,
+      cesPort: 7790,
+    },
+    ...extra,
+  };
+}
+
+function writeLockfile(entries: AssistantEntry[]): void {
+  mkdirSync(testDir, { recursive: true });
+  writeFileSync(
+    join(testDir, ".vellum.lock.json"),
+    JSON.stringify({ assistants: entries }, null, 2) + "\n",
+  );
+}
+
+function readLockfile(): string {
+  return readFileSync(join(testDir, ".vellum.lock.json"), "utf-8");
+}
+
+function setTerminalMode(isTTY: boolean): void {
+  Object.defineProperty(process.stdin, "isTTY", {
+    configurable: true,
+    value: isTTY,
+  });
+  Object.defineProperty(process.stdout, "isTTY", {
+    configurable: true,
+    value: isTTY,
+  });
+}
+
+function setInteractiveTerminal(): void {
+  setTerminalMode(true);
+  Object.defineProperty(process.stdin, "isRaw", {
+    configurable: true,
+    value: false,
+  });
+  Object.defineProperty(process.stdin, "setRawMode", {
+    configurable: true,
+    value: mock(() => process.stdin),
+  });
+  process.stdout.write = (() => true) as typeof process.stdout.write;
+}
+
+function restoreTerminal(): void {
+  Object.defineProperty(process.stdin, "isTTY", {
+    configurable: true,
+    value: originalStdinIsTTY,
+  });
+  Object.defineProperty(process.stdout, "isTTY", {
+    configurable: true,
+    value: originalStdoutIsTTY,
+  });
+  Object.defineProperty(process.stdin, "isRaw", {
+    configurable: true,
+    value: originalStdinIsRaw,
+  });
+  Object.defineProperty(process.stdin, "setRawMode", {
+    configurable: true,
+    value: originalSetRawMode,
+  });
+  process.stdout.write = originalStdoutWrite;
+}
+
+describe("vellum retire", () => {
+  beforeEach(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+    rmSync(join(testDir, ".vellum.lock.json"), { force: true });
+    process.argv = ["bun", "vellum", "retire"];
+    process.exit = ((code?: number) => {
+      throw new Error(`process.exit:${code}`);
+    }) as typeof process.exit;
+    retireLocalMock.mockReset();
+    retireLocalMock.mockResolvedValue(undefined);
+    setTerminalMode(false);
+    consoleLogSpy = spyOn(console, "log").mockImplementation(() => {});
+    consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    process.argv = originalArgv;
+    process.exit = originalExit;
+    restoreTerminal();
+    consoleLogSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+  });
+
+  afterAll(() => {
+    mock.module("../lib/retire-local.js", () => realRetireLocalModule);
+    if (originalLockfileDir === undefined) {
+      delete process.env.VELLUM_LOCKFILE_DIR;
+    } else {
+      process.env.VELLUM_LOCKFILE_DIR = originalLockfileDir;
+    }
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test("--yes retires by unquoted display name and removes by assistant ID", async () => {
+    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
+    writeLockfile([entry]);
+    process.argv = ["bun", "vellum", "retire", "Example", "Assistant", "--yes"];
+
+    await retire();
+
+    expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
+    expect(loadAllAssistants()).toEqual([]);
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Name: Example Assistant");
+    expect(output).toContain("ID: assistant-1");
+    expect(output).toContain(
+      "Removed Example Assistant (assistant-1) from config.",
+    );
+  });
+
+  test("non-interactive retire without --yes fails before deleting", async () => {
+    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
+    writeLockfile([entry]);
+    const before = readLockfile();
+    process.argv = ["bun", "vellum", "retire", "Example", "Assistant"];
+
+    await expect(retire()).rejects.toThrow("process.exit:1");
+
+    expect(retireLocalMock).not.toHaveBeenCalled();
+    expect(readLockfile()).toBe(before);
+    const output = consoleErrorSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Refusing to retire without confirmation");
+    expect(output).toContain("--yes");
+  });
+
+  test("interactive cancel leaves the assistant untouched", async () => {
+    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
+    writeLockfile([entry]);
+    const before = readLockfile();
+    setInteractiveTerminal();
+    process.argv = ["bun", "vellum", "retire", "Example", "Assistant"];
+
+    const pending = retire();
+    queueMicrotask(() => {
+      process.stdin.emit("data", Buffer.from("q"));
+    });
+
+    await expect(pending).rejects.toThrow("process.exit:1");
+    expect(retireLocalMock).not.toHaveBeenCalled();
+    expect(readLockfile()).toBe(before);
+    expect(consoleLogSpy.mock.calls.flat().join("\n")).toContain(
+      "Retire cancelled.",
+    );
+  });
+
+  test("interactive confirmation retires the assistant", async () => {
+    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
+    writeLockfile([entry]);
+    setInteractiveTerminal();
+    process.argv = ["bun", "vellum", "retire", "Example", "Assistant"];
+
+    const pending = retire();
+    queueMicrotask(() => {
+      process.stdin.emit("data", Buffer.from([13]));
+    });
+
+    await pending;
+    expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
+    expect(loadAllAssistants()).toEqual([]);
+  });
+
+  test("ambiguous display names fail before deleting", async () => {
+    writeLockfile([
+      makeEntry("assistant-1", { name: "Example Assistant" }),
+      makeEntry("assistant-2", { name: "Example Assistant" }),
+    ]);
+    const before = readLockfile();
+    process.argv = ["bun", "vellum", "retire", "Example", "Assistant", "--yes"];
+
+    await expect(retire()).rejects.toThrow("process.exit:1");
+
+    expect(retireLocalMock).not.toHaveBeenCalled();
+    expect(readLockfile()).toBe(before);
+    const output = consoleErrorSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Multiple assistants match 'Example Assistant'");
+    expect(output).toContain("assistant-1");
+    expect(output).toContain("assistant-2");
+  });
+});

package/src/commands/retire.ts

@@ -2,30 +2,34 @@ import { existsSync, unlinkSync } from "fs";
 import { join } from "path";
 
 import {
-  findAssistantByName,
+  formatAssistantLookupError,
+  formatAssistantReference,
+  getAssistantDisplayName,
   loadAllAssistants,
+  lookupAssistantByIdentifier,
   removeAssistantEntry,
-} from "../lib/assistant-config";
-import type { AssistantEntry } from "../lib/assistant-config";
-import { getConfigDir } from "../lib/environments/paths";
-import { getCurrentEnvironment } from "../lib/environments/resolve";
+} from "../lib/assistant-config.js";
+import type { AssistantEntry } from "../lib/assistant-config.js";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+import { getConfigDir } from "../lib/environments/paths.js";
+import { getCurrentEnvironment } from "../lib/environments/resolve.js";
 import {
   authHeaders,
   getPlatformUrl,
   readPlatformToken,
-} from "../lib/platform-client";
-import { retireInstance as retireAwsInstance } from "../lib/aws";
-import { retireDocker } from "../lib/docker";
-import { retireInstance as retireGcpInstance } from "../lib/gcp";
-import { retireLocal } from "../lib/retire-local";
-import { retireAppleContainer } from "../lib/retire-apple-container";
-import { exec } from "../lib/step-runner";
+} from "../lib/platform-client.js";
+import { retireInstance as retireAwsInstance } from "../lib/aws.js";
+import { retireDocker } from "../lib/docker.js";
+import { retireInstance as retireGcpInstance } from "../lib/gcp.js";
+import { retireLocal } from "../lib/retire-local.js";
+import { retireAppleContainer } from "../lib/retire-apple-container.js";
+import { exec } from "../lib/step-runner.js";
 import {
   openLogFile,
   closeLogFile,
   resetLogFile,
   writeToLogFile,
-} from "../lib/xdg-log";
+} from "../lib/xdg-log.js";
 
 function resolveCloud(entry: AssistantEntry): string {
   if (entry.cloud) {
@@ -51,6 +55,12 @@ function extractHostFromUrl(url: string): string {
 
 export { retireLocal };
 
+interface RetireArgs {
+  name?: string;
+  source?: string;
+  yes: boolean;
+}
+
 async function retireCustom(entry: AssistantEntry): Promise<void> {
   const host = extractHostFromUrl(entry.runtimeUrl);
   const sshUser = entry.sshUser ?? "root";
@@ -129,14 +139,82 @@ async function retireVellum(
   }
 }
 
-function parseSource(): string | undefined {
-  const args = process.argv.slice(4);
+function parseRetireArgs(args: string[]): RetireArgs {
+  let source: string | undefined;
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--source" && args[i + 1]) {
-      return args[i + 1];
+      source = args[i + 1];
+      i++;
     }
   }
-  return undefined;
+
+  return {
+    name: parseAssistantTargetArg(args, ["--source"]),
+    source,
+    yes: args.includes("--yes"),
+  };
+}
+
+function formatRuntimeUrl(entry: AssistantEntry): string {
+  return entry.localUrl ?? entry.runtimeUrl;
+}
+
+function printRetireTarget(entry: AssistantEntry, cloud: string): void {
+  const displayName = getAssistantDisplayName(entry);
+
+  console.log("Assistant to retire:");
+  if (displayName !== entry.assistantId) {
+    console.log(`  Name: ${displayName}`);
+  }
+  console.log(`  ID: ${entry.assistantId}`);
+  console.log(`  Cloud: ${cloud}`);
+  console.log(`  Runtime: ${formatRuntimeUrl(entry)}`);
+  console.log("");
+}
+
+function canPromptForRetireConfirmation(): boolean {
+  return (
+    process.stdin.isTTY === true &&
+    process.stdout.isTTY === true &&
+    typeof process.stdin.setRawMode === "function"
+  );
+}
+
+async function confirmRetireInteractive(): Promise<boolean> {
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+  const wasRaw = stdin.isRaw === true;
+  const wasPaused = stdin.isPaused();
+
+  stdout.write("Press Enter to retire, or Esc/q to cancel: ");
+  stdin.setRawMode(true);
+  stdin.resume();
+
+  return await new Promise<boolean>((resolve) => {
+    const cleanup = () => {
+      stdin.off("data", onData);
+      stdin.setRawMode(wasRaw);
+      if (wasPaused) {
+        stdin.pause();
+      }
+      stdout.write("\n");
+    };
+
+    const onData = (chunk: Buffer) => {
+      const byte = chunk[0];
+      if (byte === 13 || byte === 10) {
+        cleanup();
+        resolve(true);
+        return;
+      }
+      if (byte === 27 || byte === 3 || byte === 113 || byte === 81) {
+        cleanup();
+        resolve(false);
+      }
+    };
+
+    stdin.on("data", onData);
+  });
 }
 
 /** Patch console methods to also append output to the given log file descriptor. */
@@ -188,38 +266,70 @@ export async function retire(): Promise<void> {
 async function retireInner(): Promise<void> {
   const args = process.argv.slice(3);
   if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum retire <name> [--source <source>]");
+    console.log(
+      "Usage: vellum retire <name-or-id> [--source <source>] [--yes]",
+    );
     console.log("");
     console.log("Delete an assistant instance and archive its data.");
+    console.log(
+      "By default, retire prints the assistant name, ID, cloud, and runtime before asking for confirmation.",
+    );
     console.log("");
     console.log("Arguments:");
-    console.log("  <name>               Name of the assistant to retire");
+    console.log(
+      "  <name-or-id>         Assistant display name or ID to retire",
+    );
     console.log("");
     console.log("Options:");
     console.log("  --source <source>    Source identifier for the retirement");
+    console.log(
+      "  --yes                Skip the interactive confirmation prompt",
+    );
     process.exit(0);
   }
 
-  const name = process.argv[3];
+  const parsed = parseRetireArgs(args);
+  const name = parsed.name;
 
   if (!name) {
-    console.error("Error: Instance name is required.");
-    console.error("Usage: vellum retire <name> [--source <source>]");
+    console.error("Error: Assistant name or ID is required.");
+    console.error(
+      "Usage: vellum retire <name-or-id> [--source <source>] [--yes]",
+    );
     process.exit(1);
   }
 
-  const entry = findAssistantByName(name);
-  if (!entry) {
-    console.error(`No assistant found with name '${name}'.`);
+  const lookup = lookupAssistantByIdentifier(name);
+  if (lookup.status !== "found") {
+    console.error(formatAssistantLookupError(name, lookup));
     console.error("Run 'vellum hatch' first, or check the instance name.");
     process.exit(1);
   }
 
-  const source = parseSource();
+  const entry = lookup.entry;
+  const assistantId = entry.assistantId;
+  const source = parsed.source;
   const cloud = resolveCloud(entry);
+  printRetireTarget(entry, cloud);
+
+  if (!parsed.yes) {
+    if (!canPromptForRetireConfirmation()) {
+      console.error(
+        "Error: Refusing to retire without confirmation in a non-interactive terminal.",
+      );
+      console.error("Re-run with --yes to confirm from automation.");
+      process.exit(1);
+    }
+
+    const confirmed = await confirmRetireInteractive();
+    if (!confirmed) {
+      console.log("Retire cancelled.");
+      process.exit(1);
+    }
+  }
 
   if (cloud === "apple-container") {
-    await retireAppleContainer(name, entry);
+    await retireAppleContainer(assistantId, entry);
   } else if (cloud === "gcp") {
     const project = entry.project;
     const zone = entry.zone;
@@ -229,29 +339,29 @@ async function retireInner(): Promise<void> {
       );
       process.exit(1);
     }
-    await retireGcpInstance(name, project, zone, source);
+    await retireGcpInstance(assistantId, project, zone, source);
   } else if (cloud === "aws") {
     const region = entry.region;
     if (!region) {
       console.error("Error: AWS region not found in assistant config.");
       process.exit(1);
     }
-    await retireAwsInstance(name, region, source);
+    await retireAwsInstance(assistantId, region, source);
   } else if (cloud === "docker") {
-    await retireDocker(name);
+    await retireDocker(assistantId);
   } else if (cloud === "local") {
-    await retireLocal(name, entry);
+    await retireLocal(assistantId, entry);
   } else if (cloud === "custom") {
     await retireCustom(entry);
   } else if (cloud === "vellum") {
-    await retireVellum(entry.assistantId, entry.runtimeUrl);
+    await retireVellum(assistantId, entry.runtimeUrl);
   } else {
     console.error(`Error: Unknown cloud type '${cloud}'.`);
     process.exit(1);
   }
 
-  removeAssistantEntry(name);
-  console.log(`Removed ${name} from config.`);
+  removeAssistantEntry(assistantId);
+  console.log(`Removed ${formatAssistantReference(entry)} from config.`);
 
   // When no assistants remain, remove the dock-display-name sentinel so
   // the next build.sh run falls back to "Vellum" instead of using the