@vellumai/cli 0.4.36 → 0.4.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.4.36",
+  "version": "0.4.40",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {
@@ -11,7 +11,7 @@
     "./src/commands/*": "./src/commands/*.ts"
   },
   "bin": {
-    "vellum": "./src/index.ts"
+    "assistant": "./src/index.ts"
   },
   "scripts": {
     "format": "prettier --write .",

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

@@ -0,0 +1,275 @@
+import { describe, test, expect, beforeEach, afterAll, mock } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Create a temp directory that acts as a fake home, so allocateLocalResources()
+// and defaultLocalResources() never touch the real ~/.vellum directory.
+const testDir = mkdtempSync(join(tmpdir(), "cli-multi-local-test-"));
+process.env.BASE_DATA_DIR = testDir;
+
+// Mock homedir() to return testDir — this isolates allocateLocalResources()
+// which uses homedir() directly for instance directory creation.
+const realOs = await import("node:os");
+mock.module("node:os", () => ({
+  ...realOs,
+  homedir: () => testDir,
+}));
+// Also mock the bare "os" specifier since assistant-config.ts uses `from "os"`
+mock.module("os", () => ({
+  ...realOs,
+  homedir: () => testDir,
+}));
+
+// Mock probePort so we control which ports appear in-use without touching the network
+const probePortMock = mock<(port: number, host?: string) => Promise<boolean>>(
+  () => Promise.resolve(false),
+);
+mock.module("../lib/port-probe.js", () => ({
+  probePort: probePortMock,
+}));
+
+import {
+  allocateLocalResources,
+  defaultLocalResources,
+  resolveTargetAssistant,
+  setActiveAssistant,
+  getActiveAssistant,
+  removeAssistantEntry,
+  saveAssistantEntry,
+  type AssistantEntry,
+} from "../lib/assistant-config.js";
+import { DEFAULT_DAEMON_PORT } from "../lib/constants.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),
+  );
+}
+
+function readLockfileRaw(): Record<string, unknown> {
+  return JSON.parse(
+    readFileSync(join(testDir, ".vellum.lock.json"), "utf-8"),
+  ) as Record<string, unknown>;
+}
+
+const makeEntry = (
+  id: string,
+  cloud = "local",
+  extra?: Partial<AssistantEntry>,
+): AssistantEntry => ({
+  assistantId: id,
+  runtimeUrl: `http://localhost:${DEFAULT_DAEMON_PORT}`,
+  cloud,
+  ...extra,
+});
+
+function resetLockfile(): void {
+  try {
+    rmSync(join(testDir, ".vellum.lock.json"));
+  } catch {
+    // file may not exist
+  }
+  try {
+    rmSync(join(testDir, ".vellum.lockfile.json"));
+  } catch {
+    // file may not exist
+  }
+}
+
+describe("multi-local", () => {
+  beforeEach(() => {
+    resetLockfile();
+    probePortMock.mockReset();
+    probePortMock.mockImplementation(() => Promise.resolve(false));
+  });
+
+  describe("allocateLocalResources() produces non-conflicting ports", () => {
+    test("two instances get distinct ports and dirs when first instance ports are occupied", async () => {
+      // After the first allocation grabs its ports, simulate those ports
+      // being in-use so the second allocation must pick different ones.
+      const a = await allocateLocalResources("instance-a");
+      const occupiedPorts = new Set([
+        a.daemonPort,
+        a.gatewayPort,
+        a.qdrantPort,
+      ]);
+      probePortMock.mockImplementation((port: number) =>
+        Promise.resolve(occupiedPorts.has(port)),
+      );
+
+      const b = await allocateLocalResources("instance-b");
+
+      // All six ports must be unique across both instances
+      const allPorts = [
+        a.daemonPort,
+        a.gatewayPort,
+        a.qdrantPort,
+        b.daemonPort,
+        b.gatewayPort,
+        b.qdrantPort,
+      ];
+      expect(new Set(allPorts).size).toBe(6);
+
+      // Instance dirs must be distinct
+      expect(a.instanceDir).not.toBe(b.instanceDir);
+      expect(a.instanceDir).toContain("instance-a");
+      expect(b.instanceDir).toContain("instance-b");
+    });
+
+    test("skips ports that probePort reports as in-use", async () => {
+      // Simulate the default ports being occupied
+      const portsInUse = new Set([
+        DEFAULT_DAEMON_PORT,
+        DEFAULT_DAEMON_PORT + 1,
+      ]);
+      probePortMock.mockImplementation((port: number) =>
+        Promise.resolve(portsInUse.has(port)),
+      );
+
+      const res = await allocateLocalResources("probe-test");
+      expect(res.daemonPort).toBeGreaterThan(DEFAULT_DAEMON_PORT + 1);
+      expect(portsInUse.has(res.daemonPort)).toBe(false);
+    });
+  });
+
+  describe("defaultLocalResources() returns legacy paths", () => {
+    test("instanceDir is homedir", () => {
+      const res = defaultLocalResources();
+      expect(res.instanceDir).toBe(testDir);
+    });
+
+    test("daemonPort is DEFAULT_DAEMON_PORT", () => {
+      const res = defaultLocalResources();
+      expect(res.daemonPort).toBe(DEFAULT_DAEMON_PORT);
+    });
+  });
+
+  describe("resolveTargetAssistant() priority chain", () => {
+    test("explicit name returns that entry", () => {
+      writeLockfile({
+        assistants: [makeEntry("alpha"), makeEntry("beta")],
+      });
+      const result = resolveTargetAssistant("beta");
+      expect(result.assistantId).toBe("beta");
+    });
+
+    test("active assistant set returns the active entry", () => {
+      writeLockfile({
+        assistants: [makeEntry("alpha"), makeEntry("beta")],
+        activeAssistant: "alpha",
+      });
+      const result = resolveTargetAssistant();
+      expect(result.assistantId).toBe("alpha");
+    });
+
+    test("sole local assistant returns it", () => {
+      writeLockfile({
+        assistants: [makeEntry("only-one")],
+      });
+      const result = resolveTargetAssistant();
+      expect(result.assistantId).toBe("only-one");
+    });
+
+    test("multiple local assistants and no active throws with guidance", () => {
+      writeLockfile({
+        assistants: [makeEntry("x"), makeEntry("y")],
+      });
+      // resolveTargetAssistant calls process.exit(1) on ambiguity
+      const mockExit = mock(() => {
+        throw new Error("process.exit called");
+      });
+      const origExit = process.exit;
+      process.exit = mockExit as unknown as typeof process.exit;
+      try {
+        expect(() => resolveTargetAssistant()).toThrow("process.exit called");
+        expect(mockExit).toHaveBeenCalledWith(1);
+      } finally {
+        process.exit = origExit;
+      }
+    });
+
+    test("no local assistants throws", () => {
+      writeLockfile({ assistants: [] });
+      const mockExit = mock(() => {
+        throw new Error("process.exit called");
+      });
+      const origExit = process.exit;
+      process.exit = mockExit as unknown as typeof process.exit;
+      try {
+        expect(() => resolveTargetAssistant()).toThrow("process.exit called");
+        expect(mockExit).toHaveBeenCalledWith(1);
+      } finally {
+        process.exit = origExit;
+      }
+    });
+  });
+
+  describe("setActiveAssistant() / getActiveAssistant() round-trip", () => {
+    test("set active, read it back", () => {
+      writeLockfile({ assistants: [makeEntry("my-assistant")] });
+      setActiveAssistant("my-assistant");
+      expect(getActiveAssistant()).toBe("my-assistant");
+    });
+
+    test("lockfile is updated on disk", () => {
+      writeLockfile({ assistants: [makeEntry("disk-check")] });
+      setActiveAssistant("disk-check");
+      const raw = readLockfileRaw();
+      expect(raw.activeAssistant).toBe("disk-check");
+    });
+  });
+
+  describe("removeAssistantEntry() clears matching activeAssistant", () => {
+    test("set active to foo, remove foo, verify active is null", () => {
+      writeLockfile({
+        assistants: [makeEntry("foo"), makeEntry("bar")],
+        activeAssistant: "foo",
+      });
+      removeAssistantEntry("foo");
+      expect(getActiveAssistant()).toBeNull();
+    });
+
+    test("set active to foo, remove bar, verify active is still foo", () => {
+      writeLockfile({
+        assistants: [makeEntry("foo"), makeEntry("bar")],
+        activeAssistant: "foo",
+      });
+      removeAssistantEntry("bar");
+      expect(getActiveAssistant()).toBe("foo");
+    });
+  });
+
+  describe("remote non-regression", () => {
+    test("resolveTargetAssistant works with remote entries", () => {
+      writeLockfile({
+        assistants: [
+          makeEntry("my-remote", "gcp", {
+            runtimeUrl: "http://10.0.0.1:7821",
+          }),
+        ],
+        activeAssistant: "my-remote",
+      });
+      const result = resolveTargetAssistant();
+      expect(result.assistantId).toBe("my-remote");
+      expect(result.cloud).toBe("gcp");
+    });
+
+    test("remote entries don't get resources applied", () => {
+      const remoteEntry = makeEntry("cloud-box", "aws", {
+        runtimeUrl: "http://10.0.0.2:7821",
+      });
+      writeLockfile({ assistants: [remoteEntry] });
+      // Save and reload to verify resources are not injected
+      saveAssistantEntry(remoteEntry);
+      const result = resolveTargetAssistant("cloud-box");
+      expect(result.resources).toBeUndefined();
+    });
+  });
+});

package/src/__tests__/skills-uninstall.test.ts

@@ -0,0 +1,203 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { skills } from "../commands/skills.js";
+
+let tempDir: string;
+let originalArgv: string[];
+let originalBaseDataDir: string | undefined;
+let originalExitCode: number | string | null | undefined;
+
+function getSkillsDir(): string {
+  return join(tempDir, ".vellum", "workspace", "skills");
+}
+
+function getSkillsIndexPath(): string {
+  return join(getSkillsDir(), "SKILLS.md");
+}
+
+function installFakeSkill(skillId: string): void {
+  const skillDir = join(getSkillsDir(), skillId);
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(join(skillDir, "SKILL.md"), `# ${skillId}\nA test skill.\n`);
+}
+
+function writeSkillsIndex(content: string): void {
+  mkdirSync(getSkillsDir(), { recursive: true });
+  writeFileSync(getSkillsIndexPath(), content);
+}
+
+beforeEach(() => {
+  tempDir = join(tmpdir(), `skills-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tempDir, ".vellum", "workspace", "skills"), {
+    recursive: true,
+  });
+  originalArgv = process.argv;
+  originalBaseDataDir = process.env.BASE_DATA_DIR;
+  originalExitCode = process.exitCode;
+  process.env.BASE_DATA_DIR = tempDir;
+});
+
+afterEach(() => {
+  process.argv = originalArgv;
+  process.env.BASE_DATA_DIR = originalBaseDataDir;
+  // Bun treats `process.exitCode = undefined` as a no-op, so explicitly
+  // reset to 0 when the original value was not set.
+  process.exitCode = originalExitCode ?? 0;
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("vellum skills uninstall", () => {
+  test("removes skill directory and SKILLS.md entry", async () => {
+    /**
+     * Tests the happy path for uninstalling a skill.
+     */
+
+    // GIVEN a skill is installed locally
+    installFakeSkill("weather");
+    writeSkillsIndex("- weather\n- google-oauth-setup\n");
+
+    // WHEN we run `vellum skills uninstall weather`
+    process.argv = ["bun", "run", "skills", "uninstall", "weather"];
+    await skills();
+
+    // THEN the skill directory should be removed
+    expect(existsSync(join(getSkillsDir(), "weather"))).toBe(false);
+
+    // AND the SKILLS.md entry should be removed
+    const index = readFileSync(getSkillsIndexPath(), "utf-8");
+    expect(index).not.toContain("weather");
+
+    // AND other skills should remain in the index
+    expect(index).toContain("google-oauth-setup");
+  });
+
+  test("outputs JSON on success when --json flag is passed", async () => {
+    /**
+     * Tests that --json flag produces machine-readable output.
+     */
+
+    // GIVEN a skill is installed locally
+    installFakeSkill("weather");
+    writeSkillsIndex("- weather\n");
+
+    // WHEN we run `vellum skills uninstall weather --json`
+    process.argv = ["bun", "run", "skills", "uninstall", "weather", "--json"];
+    const logs: string[] = [];
+    const origLog = console.log;
+    console.log = (...args: unknown[]) => logs.push(args.join(" "));
+    try {
+      await skills();
+    } finally {
+      console.log = origLog;
+    }
+
+    // THEN JSON output should indicate success
+    const output = JSON.parse(logs[0]);
+    expect(output).toEqual({ ok: true, skillId: "weather" });
+  });
+
+  test("errors when skill is not installed", async () => {
+    /**
+     * Tests that uninstalling a non-existent skill produces an error.
+     */
+
+    // GIVEN no skills are installed
+    // WHEN we run `vellum skills uninstall nonexistent`
+    process.argv = ["bun", "run", "skills", "uninstall", "nonexistent"];
+    const errors: string[] = [];
+    const origError = console.error;
+    console.error = (...args: unknown[]) => errors.push(args.join(" "));
+    try {
+      await skills();
+    } finally {
+      console.error = origError;
+    }
+
+    // THEN an error message should be displayed
+    expect(errors[0]).toContain('Skill "nonexistent" is not installed.');
+    expect(process.exitCode).toBe(1);
+  });
+
+  test("errors with JSON output when skill is not installed and --json is passed", async () => {
+    /**
+     * Tests that --json flag produces machine-readable error output.
+     */
+
+    // GIVEN no skills are installed
+    // WHEN we run `vellum skills uninstall nonexistent --json`
+    process.argv = [
+      "bun",
+      "run",
+      "skills",
+      "uninstall",
+      "nonexistent",
+      "--json",
+    ];
+    const logs: string[] = [];
+    const origLog = console.log;
+    console.log = (...args: unknown[]) => logs.push(args.join(" "));
+    try {
+      await skills();
+    } finally {
+      console.log = origLog;
+    }
+
+    // THEN JSON output should indicate failure
+    const output = JSON.parse(logs[0]);
+    expect(output.ok).toBe(false);
+    expect(output.error).toContain('Skill "nonexistent" is not installed.');
+  });
+
+  test("works when SKILLS.md does not exist", async () => {
+    /**
+     * Tests that uninstall works even if the SKILLS.md index file is missing.
+     */
+
+    // GIVEN a skill directory exists but no SKILLS.md
+    installFakeSkill("weather");
+
+    // WHEN we run `vellum skills uninstall weather`
+    process.argv = ["bun", "run", "skills", "uninstall", "weather"];
+    await skills();
+
+    // THEN the skill directory should be removed
+    expect(existsSync(join(getSkillsDir(), "weather"))).toBe(false);
+
+    // AND no SKILLS.md should have been created
+    expect(existsSync(getSkillsIndexPath())).toBe(false);
+  });
+
+  test("removes skill with nested files", async () => {
+    /**
+     * Tests that uninstall recursively removes skills with nested directories.
+     */
+
+    // GIVEN a skill with nested files is installed
+    const skillDir = join(getSkillsDir(), "weather");
+    mkdirSync(join(skillDir, "scripts", "lib"), { recursive: true });
+    writeFileSync(join(skillDir, "SKILL.md"), "# weather\n");
+    writeFileSync(join(skillDir, "scripts", "fetch.sh"), "#!/bin/bash\n");
+    writeFileSync(join(skillDir, "scripts", "lib", "utils.sh"), "# utils\n");
+    writeSkillsIndex("- weather\n");
+
+    // WHEN we run `vellum skills uninstall weather`
+    process.argv = ["bun", "run", "skills", "uninstall", "weather"];
+    await skills();
+
+    // THEN the entire skill directory tree should be removed
+    expect(existsSync(skillDir)).toBe(false);
+
+    // AND the SKILLS.md entry should be removed
+    const index = readFileSync(getSkillsIndexPath(), "utf-8");
+    expect(index).not.toContain("weather");
+  });
+});

package/src/commands/client.ts

@@ -1,5 +1,6 @@
 import {
   findAssistantByName,
+  getActiveAssistant,
   loadLatestAssistant,
 } from "../lib/assistant-config";
 import { GATEWAY_PORT, type Species } from "../lib/constants";
@@ -45,16 +46,31 @@ function parseArgs(): ParsedArgs {
     }
   }
 
-  const entry = positionalName
-    ? findAssistantByName(positionalName)
-    : loadLatestAssistant();
-  if (positionalName && !entry) {
-    console.error(`No assistant instance found with name '${positionalName}'.`);
-    process.exit(1);
+  let entry: ReturnType<typeof findAssistantByName>;
+  if (positionalName) {
+    entry = findAssistantByName(positionalName);
+    if (!entry) {
+      console.error(
+        `No assistant instance found with name '${positionalName}'.`,
+      );
+      process.exit(1);
+    }
+  } else if (process.env.RUNTIME_URL) {
+    // Explicit env var — skip assistant resolution, will use env values below
+    entry = loadLatestAssistant();
+  } else {
+    // Respect active assistant when set, otherwise fall back to latest
+    // for backward compatibility with remote-only setups.
+    const active = getActiveAssistant();
+    const activeEntry = active ? findAssistantByName(active) : null;
+    entry = activeEntry ?? loadLatestAssistant();
   }
 
   let runtimeUrl =
-    process.env.RUNTIME_URL || entry?.runtimeUrl || FALLBACK_RUNTIME_URL;
+    process.env.RUNTIME_URL ||
+    entry?.localUrl ||
+    entry?.runtimeUrl ||
+    FALLBACK_RUNTIME_URL;
   let assistantId =
     process.env.ASSISTANT_ID || entry?.assistantId || FALLBACK_ASSISTANT_ID;
   const bearerToken =