@vellumai/cli 0.3.11 → 0.3.13

package/README.md

@@ -19,7 +19,7 @@ bun run ./src/index.ts <command> [options]
 Provision a new assistant instance and bootstrap the Vellum runtime on it.
 
 ```bash
-vellum-cli hatch [species] [options]
+vellum hatch [species] [options]
 ```
 
 #### Species
@@ -59,19 +59,19 @@ vellum-cli hatch [species] [options]
 
 ```bash
 # Hatch a local assistant (default)
-vellum-cli hatch
+vellum hatch
 
 # Hatch a vellum assistant on GCP
-vellum-cli hatch vellum --remote gcp
+vellum hatch vellum --remote gcp
 
 # Hatch an openclaw assistant on GCP in detached mode
-vellum-cli hatch openclaw --remote gcp -d
+vellum hatch openclaw --remote gcp -d
 
 # Hatch with a specific instance name
-vellum-cli hatch --name my-assistant --remote gcp
+vellum hatch --name my-assistant --remote gcp
 
 # Hatch on a custom SSH host
-VELLUM_CUSTOM_HOST=user@10.0.0.1 vellum-cli hatch --remote custom
+VELLUM_CUSTOM_HOST=user@10.0.0.1 vellum hatch --remote custom
 ```
 
 When hatching on GCP in interactive mode (without `-d`), the CLI displays an animated progress TUI that polls the instance's startup script output in real time. Press `Ctrl+C` to detach -- the instance will continue running in the background.
@@ -81,7 +81,7 @@ When hatching on GCP in interactive mode (without `-d`), the CLI displays an ani
 Delete a provisioned assistant instance. The cloud provider and connection details are automatically resolved from the saved assistant config (written during `hatch`).
 
 ```bash
-vellum-cli retire <name>
+vellum retire <name>
 ```
 
 The CLI looks up the instance by name in `~/.vellum.lock.json` and determines how to retire it based on the saved `cloud` field:
@@ -95,5 +95,5 @@ The CLI looks up the instance by name in `~/.vellum.lock.json` and determines ho
 
 ```bash
 # Retire an instance (cloud type resolved from config)
-vellum-cli retire my-assistant
+vellum retire my-assistant
 ```

package/bun.lock

@@ -6,11 +6,13 @@
       "name": "@vellumai/cli",
       "dependencies": {
         "ink": "^6.7.0",
+        "qrcode-terminal": "^0.12.0",
         "react": "^19.2.4",
         "react-devtools-core": "^6.1.2",
       },
       "devDependencies": {
         "@types/bun": "^1.2.4",
+        "@types/qrcode-terminal": "^0.12.2",
         "@types/react": "^19.2.14",
         "eslint": "^10.0.0",
         "typescript": "^5.9.3",
@@ -53,6 +55,8 @@
 
     "@types/node": ["@types/node@25.2.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ=="],
 
+    "@types/qrcode-terminal": ["@types/qrcode-terminal@0.12.2", "", {}, "sha512-v+RcIEJ+Uhd6ygSQ0u5YYY7ZM+la7GgPbs0V/7l/kFs2uO4S8BcIUEMoP7za4DNIqNnUD5npf0A/7kBhrCKG5Q=="],
+
     "@types/react": ["@types/react@19.2.14", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w=="],
 
     "@typescript-eslint/eslint-plugin": ["@typescript-eslint/eslint-plugin@8.56.0", "", { "dependencies": { "@eslint-community/regexpp": "^4.12.2", "@typescript-eslint/scope-manager": "8.56.0", "@typescript-eslint/type-utils": "8.56.0", "@typescript-eslint/utils": "8.56.0", "@typescript-eslint/visitor-keys": "8.56.0", "ignore": "^7.0.5", "natural-compare": "^1.4.0", "ts-api-utils": "^2.4.0" }, "peerDependencies": { "@typescript-eslint/parser": "^8.56.0", "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.0.0" } }, "sha512-lRyPDLzNCuae71A3t9NEINBiTn7swyOhvUj3MyUOxb8x6g6vPEFoOU+ZRmGMusNC3X3YMhqMIX7i8ShqhT74Pw=="],
@@ -217,6 +221,8 @@
 
     "punycode": ["punycode@2.3.1", "", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
 
+    "qrcode-terminal": ["qrcode-terminal@0.12.0", "", { "bin": { "qrcode-terminal": "./bin/qrcode-terminal.js" } }, "sha512-EXtzRZmC+YGmGlDFbXKxQiMZNwCLEO6BANKXG4iCtSIM0yqc/pappSx3RIKr4r0uh5JsBckOXeKrB3Iz7mdQpQ=="],
+
     "react": ["react@19.2.4", "", {}, "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ=="],
 
     "react-devtools-core": ["react-devtools-core@6.1.5", "", { "dependencies": { "shell-quote": "^1.6.1", "ws": "^7" } }, "sha512-ePrwPfxAnB+7hgnEr8vpKxL9cmnp7F322t8oqcPshbIQQhDKgFDW4tjhF2wjVbdXF9O/nyuy3sQWd9JGpiLPvA=="],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {
@@ -11,21 +11,24 @@
     "./src/commands/*": "./src/commands/*.ts"
   },
   "bin": {
-    "vellum-cli": "./src/index.ts"
+    "vellum": "./src/index.ts"
   },
   "scripts": {
     "lint": "eslint",
+    "test": "bun test",
     "typecheck": "bunx tsc --noEmit"
   },
   "author": "Vellum AI",
   "license": "MIT",
   "dependencies": {
     "ink": "^6.7.0",
+    "qrcode-terminal": "^0.12.0",
     "react": "^19.2.4",
     "react-devtools-core": "^6.1.2"
   },
   "devDependencies": {
     "@types/bun": "^1.2.4",
+    "@types/qrcode-terminal": "^0.12.2",
     "@types/react": "^19.2.14",
     "eslint": "^10.0.0",
     "typescript": "^5.9.3",

package/src/__tests__/assistant-config.test.ts

@@ -0,0 +1,139 @@
+import { describe, test, expect, beforeEach, afterAll } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Point lockfile operations at a temp directory
+const testDir = mkdtempSync(join(tmpdir(), "cli-assistant-config-test-"));
+process.env.BASE_DATA_DIR = testDir;
+
+import {
+  loadLatestAssistant,
+  findAssistantByName,
+  removeAssistantEntry,
+  loadAllAssistants,
+  saveAssistantEntry,
+  type AssistantEntry,
+} from "../lib/assistant-config.js";
+
+afterAll(() => {
+  rmSync(testDir, { recursive: true, force: true });
+  delete process.env.BASE_DATA_DIR;
+});
+
+function writeLockfile(data: unknown): void {
+  writeFileSync(
+    join(testDir, ".vellum.lock.json"),
+    JSON.stringify(data, null, 2),
+  );
+}
+
+const makeEntry = (id: string, runtimeUrl = "http://localhost:7821", extra?: Partial<AssistantEntry>): AssistantEntry => ({
+  assistantId: id,
+  runtimeUrl,
+  cloud: "local",
+  ...extra,
+});
+
+describe("assistant-config", () => {
+  beforeEach(() => {
+    // Reset lockfile between tests
+    try {
+      rmSync(join(testDir, ".vellum.lock.json"));
+    } catch {
+      // file may not exist
+    }
+    try {
+      rmSync(join(testDir, ".vellum.lockfile.json"));
+    } catch {
+      // file may not exist
+    }
+  });
+
+  test("loadAllAssistants returns empty array when no lockfile exists", () => {
+    expect(loadAllAssistants()).toEqual([]);
+  });
+
+  test("loadAllAssistants returns empty array for malformed lockfile", () => {
+    writeFileSync(join(testDir, ".vellum.lock.json"), "not json");
+    expect(loadAllAssistants()).toEqual([]);
+  });
+
+  test("loadAllAssistants returns empty array when assistants key is missing", () => {
+    writeLockfile({ someOtherKey: true });
+    expect(loadAllAssistants()).toEqual([]);
+  });
+
+  test("saveAssistantEntry and loadAllAssistants round-trip", () => {
+    const entry = makeEntry("test-1");
+    saveAssistantEntry(entry);
+    const all = loadAllAssistants();
+    expect(all).toHaveLength(1);
+    expect(all[0].assistantId).toBe("test-1");
+  });
+
+  test("findAssistantByName returns matching entry", () => {
+    writeLockfile({
+      assistants: [makeEntry("alpha"), makeEntry("beta")],
+    });
+    const result = findAssistantByName("beta");
+    expect(result).not.toBeNull();
+    expect(result!.assistantId).toBe("beta");
+  });
+
+  test("findAssistantByName returns null for non-existent name", () => {
+    writeLockfile({ assistants: [makeEntry("alpha")] });
+    expect(findAssistantByName("missing")).toBeNull();
+  });
+
+  test("removeAssistantEntry removes matching entry", () => {
+    writeLockfile({
+      assistants: [makeEntry("a"), makeEntry("b"), makeEntry("c")],
+    });
+    removeAssistantEntry("b");
+    const all = loadAllAssistants();
+    expect(all).toHaveLength(2);
+    expect(all.map((e) => e.assistantId)).toEqual(["a", "c"]);
+  });
+
+  test("loadLatestAssistant returns null when empty", () => {
+    expect(loadLatestAssistant()).toBeNull();
+  });
+
+  test("loadLatestAssistant returns most recently hatched entry", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("old", "http://localhost:7821", { hatchedAt: "2024-01-01T00:00:00Z" }),
+        makeEntry("new", "http://localhost:7822", { hatchedAt: "2025-06-15T00:00:00Z" }),
+        makeEntry("mid", "http://localhost:7823", { hatchedAt: "2024-06-15T00:00:00Z" }),
+      ],
+    });
+    const latest = loadLatestAssistant();
+    expect(latest).not.toBeNull();
+    expect(latest!.assistantId).toBe("new");
+  });
+
+  test("loadLatestAssistant handles entries without hatchedAt", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("no-date"),
+        makeEntry("with-date", "http://localhost:7822", { hatchedAt: "2025-01-01T00:00:00Z" }),
+      ],
+    });
+    const latest = loadLatestAssistant();
+    expect(latest!.assistantId).toBe("with-date");
+  });
+
+  test("loadAllAssistants filters out entries missing required fields", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("valid"),
+        { cloud: "local" }, // missing assistantId and runtimeUrl
+        { assistantId: "no-url", cloud: "local" }, // missing runtimeUrl
+      ],
+    });
+    const all = loadAllAssistants();
+    expect(all).toHaveLength(1);
+    expect(all[0].assistantId).toBe("valid");
+  });
+});

package/src/__tests__/constants.test.ts

@@ -0,0 +1,48 @@
+import { describe, test, expect } from "bun:test";
+import {
+  FIREWALL_TAG,
+  GATEWAY_PORT,
+  VALID_REMOTE_HOSTS,
+  VALID_SPECIES,
+  SPECIES_CONFIG,
+} from "../lib/constants.js";
+
+describe("constants", () => {
+  test("FIREWALL_TAG is a non-empty string", () => {
+    expect(typeof FIREWALL_TAG).toBe("string");
+    expect(FIREWALL_TAG.length).toBeGreaterThan(0);
+  });
+
+  test("GATEWAY_PORT is a valid port number", () => {
+    expect(typeof GATEWAY_PORT).toBe("number");
+    expect(GATEWAY_PORT).toBeGreaterThan(0);
+    expect(GATEWAY_PORT).toBeLessThan(65536);
+  });
+
+  test("VALID_REMOTE_HOSTS includes expected hosts", () => {
+    expect(VALID_REMOTE_HOSTS).toContain("local");
+    expect(VALID_REMOTE_HOSTS).toContain("gcp");
+    expect(VALID_REMOTE_HOSTS).toContain("aws");
+    expect(VALID_REMOTE_HOSTS).toContain("custom");
+  });
+
+  test("VALID_SPECIES includes expected species", () => {
+    expect(VALID_SPECIES).toContain("openclaw");
+    expect(VALID_SPECIES).toContain("vellum");
+  });
+
+  test("SPECIES_CONFIG has entries for all valid species", () => {
+    for (const species of VALID_SPECIES) {
+      const config = SPECIES_CONFIG[species];
+      expect(config).toBeDefined();
+      expect(typeof config.color).toBe("string");
+      expect(Array.isArray(config.art)).toBe(true);
+      expect(config.art.length).toBeGreaterThan(0);
+      expect(typeof config.hatchedEmoji).toBe("string");
+      expect(Array.isArray(config.waitingMessages)).toBe(true);
+      expect(config.waitingMessages.length).toBeGreaterThan(0);
+      expect(Array.isArray(config.runningMessages)).toBe(true);
+      expect(config.runningMessages.length).toBeGreaterThan(0);
+    }
+  });
+});

package/src/__tests__/health-check.test.ts

@@ -0,0 +1,64 @@
+import { describe, test, expect } from "bun:test";
+import { checkHealth, HEALTH_CHECK_TIMEOUT_MS } from "../lib/health-check.js";
+
+describe("checkHealth", () => {
+  test("HEALTH_CHECK_TIMEOUT_MS is a positive number", () => {
+    expect(typeof HEALTH_CHECK_TIMEOUT_MS).toBe("number");
+    expect(HEALTH_CHECK_TIMEOUT_MS).toBeGreaterThan(0);
+  });
+
+  test("returns unreachable for non-existent host", async () => {
+    const result = await checkHealth("http://127.0.0.1:1");
+    expect(["unreachable", "timeout"]).toContain(result.status);
+  });
+
+  test("returns healthy for a mock healthy endpoint", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch() {
+        return Response.json({ status: "healthy" });
+      },
+    });
+
+    try {
+      const result = await checkHealth(`http://localhost:${server.port}`);
+      expect(result.status).toBe("healthy");
+      expect(result.detail).toBeNull();
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("returns status with detail for non-healthy response", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch() {
+        return Response.json({ status: "degraded", message: "high latency" });
+      },
+    });
+
+    try {
+      const result = await checkHealth(`http://localhost:${server.port}`);
+      expect(result.status).toBe("degraded");
+      expect(result.detail).toBe("high latency");
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("returns error status for non-ok HTTP response", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch() {
+        return new Response("Internal Server Error", { status: 500 });
+      },
+    });
+
+    try {
+      const result = await checkHealth(`http://localhost:${server.port}`);
+      expect(result.status).toBe("error (500)");
+    } finally {
+      server.stop(true);
+    }
+  });
+});

package/src/__tests__/random-name.test.ts

@@ -0,0 +1,19 @@
+import { describe, test, expect } from "bun:test";
+import { generateRandomSuffix } from "../lib/random-name.js";
+
+describe("generateRandomSuffix", () => {
+  test("returns a string in adjective-noun format", () => {
+    const result = generateRandomSuffix();
+    expect(result).toMatch(/^[a-z]+-[a-z]+$/);
+  });
+
+  test("produces varying results across multiple calls", () => {
+    const results = new Set<string>();
+    for (let i = 0; i < 20; i++) {
+      results.add(generateRandomSuffix());
+    }
+    // With 62 adjectives * 62 nouns = 3844 combos, 20 calls should produce
+    // at least a few unique values
+    expect(results.size).toBeGreaterThan(1);
+  });
+});

package/src/__tests__/retire-archive.test.ts

@@ -0,0 +1,30 @@
+import { describe, test, expect } from "bun:test";
+import { validateAssistantName } from "../lib/retire-archive.js";
+
+describe("validateAssistantName", () => {
+  test("accepts valid names", () => {
+    expect(() => validateAssistantName("my-assistant")).not.toThrow();
+    expect(() => validateAssistantName("test123")).not.toThrow();
+    expect(() => validateAssistantName("a")).not.toThrow();
+  });
+
+  test("rejects empty string", () => {
+    expect(() => validateAssistantName("")).toThrow("Invalid assistant name");
+  });
+
+  test("rejects names with forward slashes", () => {
+    expect(() => validateAssistantName("foo/bar")).toThrow("Invalid assistant name");
+  });
+
+  test("rejects names with backslashes", () => {
+    expect(() => validateAssistantName("foo\\bar")).toThrow("Invalid assistant name");
+  });
+
+  test("rejects dot-dot traversal", () => {
+    expect(() => validateAssistantName("..")).toThrow("Invalid assistant name");
+  });
+
+  test("rejects single dot", () => {
+    expect(() => validateAssistantName(".")).toThrow("Invalid assistant name");
+  });
+});

package/src/__tests__/status-emoji.test.ts

@@ -0,0 +1,44 @@
+import { describe, test, expect } from "bun:test";
+import { statusEmoji, withStatusEmoji } from "../lib/status-emoji.js";
+
+describe("statusEmoji", () => {
+  test("returns green for running/healthy/ok statuses", () => {
+    expect(statusEmoji("running")).toBe("\u{1F7E2}");
+    expect(statusEmoji("healthy")).toBe("\u{1F7E2}");
+    expect(statusEmoji("ok")).toBe("\u{1F7E2}");
+  });
+
+  test("returns green for statuses starting with 'up '", () => {
+    expect(statusEmoji("up 5 minutes")).toBe("\u{1F7E2}");
+    expect(statusEmoji("up 1d")).toBe("\u{1F7E2}");
+  });
+
+  test("returns red for error/unreachable/exited statuses", () => {
+    expect(statusEmoji("error")).toBe("\u{1F534}");
+    expect(statusEmoji("error (500)")).toBe("\u{1F534}");
+    expect(statusEmoji("unreachable")).toBe("\u{1F534}");
+    expect(statusEmoji("exited")).toBe("\u{1F534}");
+    expect(statusEmoji("exited (1)")).toBe("\u{1F534}");
+  });
+
+  test("returns yellow for unknown statuses", () => {
+    expect(statusEmoji("starting")).toBe("\u{1F7E1}");
+    expect(statusEmoji("pending")).toBe("\u{1F7E1}");
+    expect(statusEmoji("unknown")).toBe("\u{1F7E1}");
+  });
+
+  test("is case-insensitive", () => {
+    expect(statusEmoji("Running")).toBe("\u{1F7E2}");
+    expect(statusEmoji("HEALTHY")).toBe("\u{1F7E2}");
+    expect(statusEmoji("ERROR")).toBe("\u{1F534}");
+    expect(statusEmoji("Unreachable")).toBe("\u{1F534}");
+  });
+});
+
+describe("withStatusEmoji", () => {
+  test("prepends emoji to status string", () => {
+    expect(withStatusEmoji("running")).toBe("\u{1F7E2} running");
+    expect(withStatusEmoji("error")).toBe("\u{1F534} error");
+    expect(withStatusEmoji("pending")).toBe("\u{1F7E1} pending");
+  });
+});