@vellumai/cli 0.6.3 → 0.6.5

package/src/lib/docker.ts

@@ -6,6 +6,13 @@ import { dirname, join } from "path";
 // Direct import — bun embeds this at compile time so it works in compiled binaries.
 import cliPkg from "../../package.json";
 
+// Pulled from skills/ — the Meet avatar device-path default is owned by the
+// meet-join skill; importing here keeps the CLI's Docker wiring locked to the
+// same value the bot and config schema use. The shared module is deliberately
+// zero-dep so this import cannot drag unrelated surface into the compiled CLI
+// binary.
+import { AVATAR_DEVICE_PATH_DEFAULT } from "../../../skills/meet-join/shared/avatar-device-path.js";
+
 import {
   findAssistantByName,
   saveAssistantEntry,
@@ -13,9 +20,10 @@ import {
 } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
 import { writeInitialConfig } from "./config-utils";
-import { DEFAULT_GATEWAY_PORT } from "./constants";
 import { PROVIDER_ENV_VAR_NAMES } from "../shared/provider-env-vars.js";
 import type { Species } from "./constants";
+import { getDefaultPorts } from "./environments/paths.js";
+import { getCurrentEnvironment } from "./environments/resolve.js";
 import { leaseGuardianToken } from "./guardian-token";
 import { isVellumProcess, stopProcess } from "./process";
 import { generateInstanceName } from "./random-name";
@@ -39,13 +47,75 @@ export const DOCKERHUB_IMAGES: Record<ServiceName, string> = {
 };
 
 /** Internal ports exposed by each service's Dockerfile. */
-export const ASSISTANT_INTERNAL_PORT = 3001;
+export const ASSISTANT_INTERNAL_PORT = 7821;
 export const GATEWAY_INTERNAL_PORT = 7830;
 
 /** Max time to wait for the assistant container to emit the readiness sentinel. */
 export const DOCKER_READY_TIMEOUT_MS = 3 * 60 * 1000;
 
+/**
+ * Default virtual-camera device path when the Meet avatar feature is
+ * enabled. Re-exports the shared
+ * {@link ../../../skills/meet-join/shared/avatar-device-path.js AVATAR_DEVICE_PATH_DEFAULT}
+ * so the CLI's device-passthrough wiring cannot drift from the bot's
+ * Chrome-flag wiring or the workspace config default. Matches the
+ * `video_nr=10` value in the README's host-setup section
+ * (`skills/meet-join/bot/README.md`). Operators can override the path by
+ * setting `VELLUM_MEET_AVATAR_DEVICE` to something other than the default
+ * (e.g. `/dev/video11` if a different `video_nr` was used).
+ */
+export const DEFAULT_MEET_AVATAR_DEVICE_PATH = AVATAR_DEVICE_PATH_DEFAULT;
+
+/**
+ * Env-var opt-in for bind-mounting the v4l2loopback virtual-camera device
+ * into the assistant container. Set to a truthy value (`1`, `true`, `yes`)
+ * to enable; unset or falsy disables the passthrough entirely.
+ *
+ * Kept as an env-var rather than a config-schema field because the Meet
+ * avatar config schema lands in a later PR (PR 5 of the phase-4 plan) —
+ * threading the config through the CLI's boot flow now would force a
+ * forward dependency. Once the schema lands, the CLI can either keep this
+ * env-var as a pre-config override or move the opt-in into the workspace
+ * config.
+ */
+export const MEET_AVATAR_ENV_VAR = "VELLUM_MEET_AVATAR";
+
+/**
+ * Override for the virtual-camera device path. Defaults to
+ * {@link DEFAULT_MEET_AVATAR_DEVICE_PATH}.
+ */
+export const MEET_AVATAR_DEVICE_ENV_VAR = "VELLUM_MEET_AVATAR_DEVICE";
+
+/**
+ * Resolve the Meet avatar device path to pass through to the assistant
+ * container, or `null` if the feature is not opted into. Exported so tests
+ * can assert against the env-var parsing without reaching into the shell.
+ */
+export function resolveMeetAvatarDevicePath(
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  const flag = env[MEET_AVATAR_ENV_VAR];
+  if (!flag) return null;
+  const normalized = flag.trim().toLowerCase();
+  if (
+    normalized === "" ||
+    normalized === "0" ||
+    normalized === "false" ||
+    normalized === "no"
+  ) {
+    return null;
+  }
+  const override = env[MEET_AVATAR_DEVICE_ENV_VAR];
+  return override && override.length > 0
+    ? override
+    : DEFAULT_MEET_AVATAR_DEVICE_PATH;
+}
+
+/** Default memory (GiB) allocated to the Colima VM. */
+const COLIMA_DEFAULT_MEMORY_GIB = 8;
+
 /** Directory for user-local binary installs (no sudo required). */
+
 const LOCAL_BIN_DIR = join(
   process.env.HOME || process.env.USERPROFILE || ".",
   ".local",
@@ -294,7 +364,11 @@ async function ensureDockerInstalled(): Promise<void> {
 
     console.log("🚀 Docker daemon not running. Starting Colima...");
     try {
-      await exec("colima", ["start"]);
+      await exec("colima", [
+        "start",
+        "--memory",
+        String(COLIMA_DEFAULT_MEMORY_GIB),
+      ]);
     } catch {
       // Colima may fail if a previous VM instance is in a corrupt state.
       // Attempt to delete the stale instance and retry once.
@@ -311,7 +385,11 @@ async function ensureDockerInstalled(): Promise<void> {
 
       try {
         console.log("🔄 Retrying colima start...");
-        await exec("colima", ["start"]);
+        await exec("colima", [
+          "start",
+          "--memory",
+          String(COLIMA_DEFAULT_MEMORY_GIB),
+        ]);
       } catch (retryErr) {
         const message =
           retryErr instanceof Error ? retryErr.message : String(retryErr);
@@ -329,6 +407,7 @@ export function dockerResourceNames(instanceName: string) {
     assistantContainer: `${instanceName}-assistant`,
     cesContainer: `${instanceName}-credential-executor`,
     cesSecurityVolume: `${instanceName}-ces-sec`,
+    dockerdDataVolume: `${instanceName}-dockerd-data`,
     gatewayContainer: `${instanceName}-gateway`,
     gatewaySecurityVolume: `${instanceName}-gateway-sec`,
     network: `${instanceName}-net`,
@@ -388,6 +467,7 @@ export async function retireDocker(name: string): Promise<void> {
     res.workspaceVolume,
     res.cesSecurityVolume,
     res.gatewaySecurityVolume,
+    res.dockerdDataVolume,
   ]) {
     try {
       await exec("docker", ["volume", "rm", vol]);
@@ -501,8 +581,8 @@ function serviceImageConfigs(
       tag: imageTags["credential-executor"],
     },
     gateway: {
-      context: join(repoRoot, "gateway"),
-      dockerfile: "Dockerfile",
+      context: repoRoot,
+      dockerfile: "gateway/Dockerfile",
       tag: imageTags.gateway,
     },
   };
@@ -551,19 +631,53 @@ export function serviceDockerRunArgs(opts: {
   } = opts;
   return {
     assistant: () => {
+      // Run the assistant container in Docker-in-Docker (DinD) mode: the
+      // container runs its own `dockerd` so the Meet subsystem can spawn
+      // sibling meet-bot containers without needing access to the host's
+      // Docker engine. This requires:
+      //   - `--privileged` so the inner dockerd can manage cgroups, iptables,
+      //     overlayfs mounts, etc.
+      //   - A dedicated named volume mounted at `/var/lib/docker` so the
+      //     inner Docker image cache and container state survive restarts of
+      //     the assistant container.
+      // The host's `/var/run/docker.sock` is intentionally NOT mounted — all
+      // Meet-bot spawning happens against the inner dockerd.
       const args: string[] = [
         "run",
         "--init",
         "-d",
+        "--privileged",
         "--name",
         res.assistantContainer,
         `--network=${res.network}`,
         "-p",
         `${gatewayPort}:${GATEWAY_INTERNAL_PORT}`,
+        // Published so the Meet subsystem's sibling bot containers can reach
+        // the daemon's internal HTTP API at host.docker.internal:<port>.
+        //
+        // Published on all host interfaces (no `127.0.0.1:` prefix) because on
+        // vanilla Linux Docker, `host.docker.internal:host-gateway` resolves
+        // to the Docker bridge gateway IP (e.g. 172.17.0.1), not loopback.
+        // Packets from sibling containers arrive at the host's bridge
+        // interface, and an iptables DNAT rule keyed on dest=127.0.0.1 would
+        // not match — causing connection refused. Docker Desktop (macOS/
+        // Windows) still works because its VM proxy forwards to the same
+        // published port regardless of the binding address.
+        //
+        // Security tradeoff: the daemon HTTP API is now reachable from the
+        // host's LAN (any device that can hit the host IP on this port).
+        // This matches the gateway port's existing posture and is acceptable
+        // for single-user self-hosted Docker mode per the Phase 1.8 security
+        // note. Managed/multi-tenant deployments are out of scope and would
+        // require a different design.
+        "-p",
+        `${ASSISTANT_INTERNAL_PORT}:${ASSISTANT_INTERNAL_PORT}`,
         "-v",
         `${res.workspaceVolume}:/workspace`,
         "-v",
         `${res.socketVolume}:/run/ces-bootstrap`,
+        "-v",
+        `${res.dockerdDataVolume}:/var/lib/docker`,
         "-e",
         "IS_CONTAINERIZED=true",
         "-e",
@@ -575,6 +689,10 @@ export function serviceDockerRunArgs(opts: {
         "-e",
         "VELLUM_WORKSPACE_DIR=/workspace",
         "-e",
+        "VELLUM_BACKUP_DIR=/workspace/.backups",
+        "-e",
+        "VELLUM_BACKUP_KEY_PATH=/workspace/.backup.key",
+        "-e",
         "CES_CREDENTIAL_URL=http://localhost:8090",
         "-e",
         `GATEWAY_INTERNAL_URL=http://localhost:${GATEWAY_INTERNAL_PORT}`,
@@ -596,6 +714,7 @@ export function serviceDockerRunArgs(opts: {
       }
       for (const envVar of [
         ...Object.values(PROVIDER_ENV_VAR_NAMES),
+        "VELLUM_ENVIRONMENT",
         "VELLUM_PLATFORM_URL",
       ]) {
         if (process.env[envVar]) {
@@ -607,6 +726,24 @@ export function serviceDockerRunArgs(opts: {
           args.push("-e", `${key}=${value}`);
         }
       }
+      // Optional Meet avatar (v4l2loopback) passthrough. When
+      // `VELLUM_MEET_AVATAR=1` is set in the caller's environment, bind the
+      // virtual-camera device node (default `/dev/video10`) into the
+      // assistant container so the nested `dockerd` can in turn pass it
+      // through to the Meet-bot container. The daemon-side equivalent of
+      // this opt-in lives on `DockerRunner.run()`'s `avatarDevicePath`
+      // option (see `skills/meet-join/daemon/docker-runner.ts`).
+      const avatarDevice = resolveMeetAvatarDevicePath();
+      if (avatarDevice) {
+        args.push(
+          "--device",
+          `${avatarDevice}:${avatarDevice}`,
+          "-e",
+          `${MEET_AVATAR_ENV_VAR}=1`,
+          "-e",
+          `${MEET_AVATAR_DEVICE_ENV_VAR}=${avatarDevice}`,
+        );
+      }
       args.push(imageTags.assistant);
       return args;
     },
@@ -644,6 +781,9 @@ export function serviceDockerRunArgs(opts: {
       ...(opts.bootstrapSecret
         ? ["-e", `GUARDIAN_BOOTSTRAP_SECRET=${opts.bootstrapSecret}`]
         : []),
+      ...(process.env.VELLUM_ENVIRONMENT
+        ? ["-e", `VELLUM_ENVIRONMENT=${process.env.VELLUM_ENVIRONMENT}`]
+        : []),
       ...(process.env.VELLUM_PLATFORM_URL
         ? ["-e", `VELLUM_PLATFORM_URL=${process.env.VELLUM_PLATFORM_URL}`]
         : []),
@@ -700,6 +840,16 @@ export async function startContainers(
   },
   log: (msg: string) => void,
 ): Promise<void> {
+  // Ensure the inner dockerd's data volume exists before mounting it.
+  // For instances hatched on Phase 1.10+, this is created in hatchDocker and
+  // is a no-op here. For instances that pre-date Phase 1.10 (DinD) and are
+  // upgrading in place, Docker would otherwise auto-create the volume on
+  // first `-v` mount without our standard ownership/labeling. Creating it
+  // explicitly keeps volume provenance consistent across fresh and upgraded
+  // instances. `docker volume create` is idempotent for an existing volume
+  // of the same name, so this is safe to run on every start.
+  await exec("docker", ["volume", "create", opts.res.dockerdDataVolume]);
+
   const runArgs = serviceDockerRunArgs(opts);
   for (const service of SERVICE_START_ORDER) {
     log(`🚀 Starting ${service} container...`);
@@ -1008,7 +1158,7 @@ export async function hatchDocker(
     await ensureDockerInstalled();
 
     const instanceName = generateInstanceName(species, name);
-    const gatewayPort = DEFAULT_GATEWAY_PORT;
+    const gatewayPort = getDefaultPorts(getCurrentEnvironment()).gateway;
 
     const imageTags: Record<ServiceName, string> = {
       assistant: "",
@@ -1110,6 +1260,7 @@ export async function hatchDocker(
     await exec("docker", ["volume", "create", res.workspaceVolume]);
     await exec("docker", ["volume", "create", res.cesSecurityVolume]);
     await exec("docker", ["volume", "create", res.gatewaySecurityVolume]);
+    await exec("docker", ["volume", "create", res.dockerdDataVolume]);
 
     // Set workspace volume ownership so non-root containers (UID 1001) can write.
     await exec("docker", [
@@ -1165,7 +1316,6 @@ export async function hatchDocker(
       cloud: "docker",
       species,
       hatchedAt: new Date().toISOString(),
-      serviceGroupVersion: cliPkg.version ? `v${cliPkg.version}` : undefined,
       containerInfo: {
         assistantImage: imageTags.assistant,
         gatewayImage: imageTags.gateway,

package/src/lib/environments/__tests__/paths.test.ts

@@ -0,0 +1,228 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { join } from "path";
+
+const TEST_HOME = "/test/home";
+
+// Mock homedir() so the helpers return predictable paths regardless of who
+// is running the test. `os.homedir()` is read once per process on Bun/Node
+// and does not reflect later $HOME changes, so setting process.env.HOME at
+// test time does not work — module mocking is the recommended pattern (see
+// cli/src/__tests__/multi-local.test.ts).
+const realOs = await import("node:os");
+mock.module("node:os", () => ({
+  ...realOs,
+  homedir: () => TEST_HOME,
+}));
+mock.module("os", () => ({
+  ...realOs,
+  homedir: () => TEST_HOME,
+}));
+
+// Imports that depend on the mocked `os` module must come after the
+// mock.module() calls above.
+const {
+  getConfigDir,
+  getDefaultPorts,
+  getLockfilePath,
+  getLockfilePaths,
+  getMultiInstanceDir,
+} = await import("../paths.js");
+type EnvironmentDefinition = import("../types.js").EnvironmentDefinition;
+
+const prod: EnvironmentDefinition = {
+  name: "production",
+  platformUrl: "https://platform.vellum.ai",
+};
+
+const dev: EnvironmentDefinition = {
+  name: "dev",
+  platformUrl: "https://dev-platform.vellum.ai",
+};
+
+const XDG_ENV_VARS = ["XDG_DATA_HOME", "XDG_CONFIG_HOME"] as const;
+
+describe("path helpers", () => {
+  let savedEnv: Record<string, string | undefined>;
+
+  beforeEach(() => {
+    savedEnv = {};
+    for (const key of XDG_ENV_VARS) {
+      savedEnv[key] = process.env[key];
+      delete process.env[key];
+    }
+  });
+
+  afterEach(() => {
+    for (const [key, value] of Object.entries(savedEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  describe("getConfigDir", () => {
+    test("production returns ~/.config/vellum/", () => {
+      expect(getConfigDir(prod)).toBe(join(TEST_HOME, ".config", "vellum"));
+    });
+
+    test("dev returns ~/.config/vellum-dev/", () => {
+      expect(getConfigDir(dev)).toBe(join(TEST_HOME, ".config", "vellum-dev"));
+    });
+
+    test("respects XDG_CONFIG_HOME for non-prod envs", () => {
+      process.env.XDG_CONFIG_HOME = "/custom/config";
+      expect(getConfigDir(dev)).toBe("/custom/config/vellum-dev");
+    });
+
+    test("respects XDG_CONFIG_HOME for production too", () => {
+      // Production's XDG config dir already follows XDG conventions, so the
+      // standard XDG override applies.
+      process.env.XDG_CONFIG_HOME = "/custom/config";
+      expect(getConfigDir(prod)).toBe("/custom/config/vellum");
+    });
+
+    test("respects env.configDirOverride", () => {
+      const env: EnvironmentDefinition = {
+        ...dev,
+        configDirOverride: "/tmp/cfg",
+      };
+      expect(getConfigDir(env)).toBe("/tmp/cfg");
+    });
+  });
+
+  describe("getLockfilePath", () => {
+    test("production returns ~/.vellum.lock.json", () => {
+      expect(getLockfilePath(prod)).toBe(join(TEST_HOME, ".vellum.lock.json"));
+    });
+
+    test("dev returns ~/.config/vellum-dev/lockfile.json", () => {
+      expect(getLockfilePath(dev)).toBe(
+        join(TEST_HOME, ".config", "vellum-dev", "lockfile.json"),
+      );
+    });
+
+    test("non-prod respects configDirOverride", () => {
+      const env: EnvironmentDefinition = {
+        ...dev,
+        configDirOverride: "/tmp/cfg",
+      };
+      expect(getLockfilePath(env)).toBe("/tmp/cfg/lockfile.json");
+    });
+
+    test("production respects lockfileDirOverride", () => {
+      const env: EnvironmentDefinition = {
+        ...prod,
+        lockfileDirOverride: "/tmp/lock",
+      };
+      expect(getLockfilePath(env)).toBe("/tmp/lock/.vellum.lock.json");
+    });
+
+    test("non-prod respects lockfileDirOverride (overrides configDir)", () => {
+      const env: EnvironmentDefinition = {
+        ...dev,
+        configDirOverride: "/tmp/cfg",
+        lockfileDirOverride: "/tmp/lock",
+      };
+      expect(getLockfilePath(env)).toBe("/tmp/lock/lockfile.json");
+    });
+  });
+
+  describe("getLockfilePaths", () => {
+    test("production returns both current and legacy filenames in priority order", () => {
+      expect(getLockfilePaths(prod)).toEqual([
+        join(TEST_HOME, ".vellum.lock.json"),
+        join(TEST_HOME, ".vellum.lockfile.json"),
+      ]);
+    });
+
+    test("non-prod returns a single canonical path", () => {
+      expect(getLockfilePaths(dev)).toEqual([
+        join(TEST_HOME, ".config", "vellum-dev", "lockfile.json"),
+      ]);
+    });
+
+    test("production with lockfileDirOverride applies to both candidates", () => {
+      const env: EnvironmentDefinition = {
+        ...prod,
+        lockfileDirOverride: "/tmp/lock",
+      };
+      expect(getLockfilePaths(env)).toEqual([
+        "/tmp/lock/.vellum.lock.json",
+        "/tmp/lock/.vellum.lockfile.json",
+      ]);
+    });
+
+    test("non-prod with lockfileDirOverride overrides the config dir", () => {
+      const env: EnvironmentDefinition = {
+        ...dev,
+        lockfileDirOverride: "/tmp/lock",
+      };
+      expect(getLockfilePaths(env)).toEqual(["/tmp/lock/lockfile.json"]);
+    });
+
+    test("getLockfilePath returns the first entry from getLockfilePaths", () => {
+      expect(getLockfilePath(prod)).toBe(getLockfilePaths(prod)[0]);
+      expect(getLockfilePath(dev)).toBe(getLockfilePaths(dev)[0]);
+    });
+  });
+
+  describe("getMultiInstanceDir", () => {
+    test("production returns ~/.local/share/vellum/assistants", () => {
+      expect(getMultiInstanceDir(prod)).toBe(
+        join(TEST_HOME, ".local", "share", "vellum", "assistants"),
+      );
+    });
+
+    test("dev returns ~/.local/share/vellum-dev/assistants", () => {
+      expect(getMultiInstanceDir(dev)).toBe(
+        join(TEST_HOME, ".local", "share", "vellum-dev", "assistants"),
+      );
+    });
+
+    test("respects XDG_DATA_HOME", () => {
+      process.env.XDG_DATA_HOME = "/custom/data";
+      expect(getMultiInstanceDir(dev)).toBe(
+        "/custom/data/vellum-dev/assistants",
+      );
+    });
+  });
+
+  describe("getDefaultPorts", () => {
+    test("returns production defaults for production", () => {
+      const ports = getDefaultPorts(prod);
+      expect(ports.daemon).toBe(7821);
+      expect(ports.gateway).toBe(7830);
+      expect(ports.qdrant).toBe(6333);
+      expect(ports.ces).toBe(8090);
+      expect(ports.outboundProxy).toBe(8080);
+      expect(ports.tcp).toBe(8765);
+    });
+
+    test("returns base defaults for a bare env with no portsOverride", () => {
+      // Bare env literal (no portsOverride) falls through to DEFAULT_PORTS.
+      // Real non-prod seeds populate portsOverride — see seeds.test cases.
+      expect(getDefaultPorts(dev)).toEqual(getDefaultPorts(prod));
+    });
+
+    test("merges env.portsOverride on top of defaults", () => {
+      const env: EnvironmentDefinition = {
+        ...dev,
+        portsOverride: { daemon: 9999, gateway: 9998 },
+      };
+      const ports = getDefaultPorts(env);
+      expect(ports.daemon).toBe(9999);
+      expect(ports.gateway).toBe(9998);
+      expect(ports.qdrant).toBe(6333);
+      expect(ports.ces).toBe(8090);
+    });
+
+    test("returns a fresh object — mutations do not affect future calls", () => {
+      const first = getDefaultPorts(prod);
+      first.daemon = 1;
+      const second = getDefaultPorts(prod);
+      expect(second.daemon).toBe(7821);
+    });
+  });
+});