@vellumai/cli 0.4.57 → 0.5.1

package/package.json

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

package/src/__tests__/coverage.test.ts

@@ -5,6 +5,11 @@ import { resolve } from "node:path";
 import { expect, test } from "bun:test";
 
 const EXCLUDE_PATTERNS = [".test.ts", ".d.ts"];
+const EXCLUDE_DIRS = [
+  // Ink components import yoga-layout whose WASM binary crashes
+  // intermittently during headless import (null reference in za()).
+  "components/",
+];
 const EXCLUDE_FILES = [
   // index.ts calls main() at module level, causing side effects on import
   "index.ts",
@@ -15,6 +20,7 @@ async function importAllModules(dir: string): Promise<string[]> {
   const files = [...glob.scanSync(dir)].filter(
     (f) =>
       !EXCLUDE_PATTERNS.some((pattern) => f.endsWith(pattern)) &&
+      !EXCLUDE_DIRS.some((dir) => f.startsWith(dir)) &&
       !EXCLUDE_FILES.some((excluded) => f === excluded) &&
       !f.includes("__tests__"),
   );

package/src/commands/hatch.ts

@@ -701,32 +701,36 @@ async function hatchLocal(
 
   await startLocalDaemon(watch, resources);
 
-  let runtimeUrl: string;
-  try {
-    runtimeUrl = await startGateway(watch, resources);
-  } catch (error) {
-    // Gateway failed — stop the daemon we just started so we don't leave
-    // orphaned processes with no lock file entry.
-    console.error(
-      `\n❌ Gateway startup failed — stopping assistant to avoid orphaned processes.`,
-    );
-    await stopLocalProcesses(resources);
-    throw error;
-  }
+  // When daemonOnly is set, skip gateway and ngrok — the caller only wants
+  // the daemon restarted (e.g. macOS app bootstrap retry).
+  let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
+  if (!daemonOnly) {
+    try {
+      runtimeUrl = await startGateway(watch, resources);
+    } catch (error) {
+      // Gateway failed — stop the daemon we just started so we don't leave
+      // orphaned processes with no lock file entry.
+      console.error(
+        `\n❌ Gateway startup failed — stopping assistant to avoid orphaned processes.`,
+      );
+      await stopLocalProcesses(resources);
+      throw error;
+    }
 
-  // Auto-start ngrok if webhook integrations (e.g. Telegram) are configured.
-  // Set BASE_DATA_DIR so ngrok reads the correct instance config.
-  const prevBaseDataDir = process.env.BASE_DATA_DIR;
-  process.env.BASE_DATA_DIR = resources.instanceDir;
-  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
-  if (ngrokChild?.pid) {
-    const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
-    writeFileSync(ngrokPidFile, String(ngrokChild.pid));
-  }
-  if (prevBaseDataDir !== undefined) {
-    process.env.BASE_DATA_DIR = prevBaseDataDir;
-  } else {
-    delete process.env.BASE_DATA_DIR;
+    // Auto-start ngrok if webhook integrations (e.g. Telegram, Twilio) are configured.
+    // Set BASE_DATA_DIR so ngrok reads the correct instance config.
+    const prevBaseDataDir = process.env.BASE_DATA_DIR;
+    process.env.BASE_DATA_DIR = resources.instanceDir;
+    const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
+    if (ngrokChild?.pid) {
+      const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
+      writeFileSync(ngrokPidFile, String(ngrokChild.pid));
+    }
+    if (prevBaseDataDir !== undefined) {
+      process.env.BASE_DATA_DIR = prevBaseDataDir;
+    } else {
+      delete process.env.BASE_DATA_DIR;
+    }
   }
 
   const localEntry: AssistantEntry = {
@@ -757,7 +761,12 @@ async function hatchLocal(
   }
 
   if (keepAlive) {
-    const gatewayHealthUrl = `http://127.0.0.1:${resources.gatewayPort}/healthz`;
+    // When --daemon-only is set, no gateway is running — poll the daemon
+    // health endpoint instead of the gateway to avoid self-termination.
+    const healthUrl = daemonOnly
+      ? `http://127.0.0.1:${resources.daemonPort}/healthz`
+      : `http://127.0.0.1:${resources.gatewayPort}/healthz`;
+    const healthTarget = daemonOnly ? "Assistant" : "Gateway";
     const POLL_INTERVAL_MS = 5000;
     const MAX_FAILURES = 3;
     let consecutiveFailures = 0;
@@ -771,11 +780,11 @@ async function hatchLocal(
     process.on("SIGTERM", () => void shutdown());
     process.on("SIGINT", () => void shutdown());
 
-    // Poll the gateway health endpoint until it stops responding.
+    // Poll the health endpoint until it stops responding.
     while (true) {
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
       try {
-        const res = await fetch(gatewayHealthUrl, {
+        const res = await fetch(healthUrl, {
           signal: AbortSignal.timeout(3000),
         });
         if (res.ok) {
@@ -787,7 +796,9 @@ async function hatchLocal(
         consecutiveFailures++;
       }
       if (consecutiveFailures >= MAX_FAILURES) {
-        console.log("\n⚠️  Gateway stopped responding — shutting down.");
+        console.log(
+          `\n⚠️  ${healthTarget} stopped responding — shutting down.`,
+        );
         await stopLocalProcesses(resources);
         process.exit(1);
       }

package/src/lib/docker.ts

@@ -1,4 +1,5 @@
-import { existsSync, watch as fsWatch } from "fs";
+import { chmodSync, existsSync, mkdirSync, watch as fsWatch } from "fs";
+import { arch, platform } from "os";
 import { dirname, join } from "path";
 
 // Direct import — bun embeds this at compile time so it works in compiled binaries.
@@ -39,60 +40,201 @@ 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;
 
+/** Directory for user-local binary installs (no sudo required). */
+const LOCAL_BIN_DIR = join(
+  process.env.HOME || process.env.USERPROFILE || ".",
+  ".local",
+  "bin",
+);
+
 /**
- * Checks whether the `docker` CLI and daemon are available on the system.
- * Installs Colima and Docker via Homebrew if the CLI is missing, and starts
- * Colima if the Docker daemon is not reachable.
+ * Returns the macOS architecture suffix used by GitHub release artifacts.
+ * Maps Node's `arch()` values to the names used in release URLs.
  */
-async function ensureDockerInstalled(): Promise<void> {
-  let installed = false;
+function releaseArch(): string {
+  const a = arch();
+  if (a === "arm64") return "aarch64";
+  if (a === "x64") return "x86_64";
+  return a;
+}
+
+/**
+ * Downloads a file from `url` to `destPath`, makes it executable, and returns
+ * the destination path. Throws on failure.
+ */
+async function downloadBinary(
+  url: string,
+  destPath: string,
+  label: string,
+): Promise<void> {
+  console.log(`  ⬇ Downloading ${label}...`);
+  await exec("bash", [
+    "-c",
+    `curl -fsSL -o "${destPath}" "${url}" && chmod +x "${destPath}"`,
+  ]);
+}
+
+/**
+ * Downloads and extracts a `.tar.gz` archive into `destDir`.
+ */
+async function downloadAndExtract(
+  url: string,
+  destDir: string,
+  label: string,
+): Promise<void> {
+  console.log(`  ⬇ Downloading ${label}...`);
+  await exec("bash", ["-c", `curl -fsSL "${url}" | tar xz -C "${destDir}"`]);
+}
+
+/**
+ * Installs Docker CLI, Colima, and Lima by downloading pre-built binaries
+ * directly into ~/.vellum/bin/. No Homebrew or sudo required.
+ *
+ * Falls back to Homebrew if available (e.g. admin users who prefer it).
+ */
+async function installDockerToolchain(): Promise<void> {
+  // Try Homebrew first if available — it handles updates and dependencies.
+  let hasBrew = false;
   try {
-    await execOutput("docker", ["--version"]);
-    installed = true;
+    await execOutput("brew", ["--version"]);
+    hasBrew = true;
   } catch {
-    // docker CLI not found — install it
+    // brew not found
   }
 
-  if (!installed) {
-    // Check whether Homebrew is available before attempting to use it.
-    let hasBrew = false;
+  if (hasBrew) {
+    console.log("🐳 Docker not found. Installing via Homebrew...");
     try {
-      await execOutput("brew", ["--version"]);
-      hasBrew = true;
+      await exec("brew", ["install", "colima", "docker"]);
+      return;
     } catch {
-      // brew not found
+      console.log(
+        "  ⚠ Homebrew install failed, falling back to direct binary download...",
+      );
     }
+  }
 
-    if (!hasBrew) {
-      console.log("🍺 Homebrew not found. Installing Homebrew...");
-      try {
-        await exec("bash", [
-          "-c",
-          'NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
-        ]);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new Error(
-          `Failed to install Homebrew. Please install Docker manually from https://www.docker.com/products/docker-desktop/\n${message}`,
-        );
-      }
+  // Direct binary install — no sudo required.
+  console.log(
+    "🐳 Docker not found. Installing Docker, Colima, and Lima to ~/.local/bin/...",
+  );
 
-      // Homebrew on Apple Silicon installs to /opt/homebrew; add it to PATH
-      // so subsequent brew/colima/docker invocations work in this session.
-      if (!process.env.PATH?.includes("/opt/homebrew")) {
-        process.env.PATH = `/opt/homebrew/bin:/opt/homebrew/sbin:${process.env.PATH}`;
-      }
-    }
+  mkdirSync(LOCAL_BIN_DIR, { recursive: true });
 
-    console.log("🐳 Docker not found. Installing via Homebrew...");
-    try {
-      await exec("brew", ["install", "colima", "docker"]);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+  const cpuArch = releaseArch();
+  const isMac = platform() === "darwin";
+
+  if (!isMac) {
+    throw new Error(
+      "Automatic Docker installation is only supported on macOS. " +
+        "Please install Docker manually: https://docs.docker.com/engine/install/",
+    );
+  }
+
+  // --- Docker CLI ---
+  // Docker publishes static binaries at download.docker.com.
+  const dockerArch = cpuArch === "aarch64" ? "aarch64" : "x86_64";
+  const dockerTarUrl = `https://download.docker.com/mac/static/stable/${dockerArch}/docker-27.5.1.tgz`;
+  const dockerTmpDir = join(LOCAL_BIN_DIR, ".docker-tmp");
+  mkdirSync(dockerTmpDir, { recursive: true });
+  try {
+    await downloadAndExtract(dockerTarUrl, dockerTmpDir, "Docker CLI");
+    // The archive extracts to docker/docker — move it to our bin dir.
+    await exec("mv", [
+      join(dockerTmpDir, "docker", "docker"),
+      join(LOCAL_BIN_DIR, "docker"),
+    ]);
+    chmodSync(join(LOCAL_BIN_DIR, "docker"), 0o755);
+  } finally {
+    await exec("rm", ["-rf", dockerTmpDir]).catch(() => {});
+  }
+
+  // --- Colima ---
+  const colimaArch = cpuArch === "aarch64" ? "arm64" : "x86_64";
+  const colimaUrl = `https://github.com/abiosoft/colima/releases/latest/download/colima-Darwin-${colimaArch}`;
+  await downloadBinary(colimaUrl, join(LOCAL_BIN_DIR, "colima"), "Colima");
+
+  // --- Lima ---
+  // Lima publishes tar.gz archives with bin/limactl and other tools.
+  const limaArch = cpuArch === "aarch64" ? "arm64" : "x86_64";
+  const limaVersionUrl =
+    "https://api.github.com/repos/lima-vm/lima/releases/latest";
+  let limaVersion: string;
+  try {
+    const resp = await fetch(limaVersionUrl);
+    if (!resp.ok) {
       throw new Error(
-        `Failed to install Docker via Homebrew. Please install Docker manually.\n${message}`,
+        `GitHub API returned ${resp.status}` +
+          (resp.status === 403
+            ? " (rate-limited) — try again later."
+            : `. Check your network connection.`),
       );
     }
+    const data = (await resp.json()) as { tag_name?: string };
+    if (!data.tag_name) {
+      throw new Error("GitHub API response missing tag_name.");
+    }
+    limaVersion = data.tag_name; // e.g. "v1.0.3"
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to fetch latest Lima version: ${message}`);
+  }
+  const limaVersionNum = limaVersion.replace(/^v/, ""); // "1.0.3"
+  const limaTarUrl = `https://github.com/lima-vm/lima/releases/download/${limaVersion}/lima-${limaVersionNum}-Darwin-${limaArch}.tar.gz`;
+  // Lima archives contain bin/limactl, bin/lima, share/lima/..., so extract
+  // into the parent (~/.local/) so that limactl lands in ~/.local/bin/.
+  const localDir = dirname(LOCAL_BIN_DIR);
+  await downloadAndExtract(limaTarUrl, localDir, "Lima");
+
+  // Verify all binaries are in place.
+  for (const bin of ["docker", "colima", "limactl"]) {
+    if (!existsSync(join(LOCAL_BIN_DIR, bin))) {
+      throw new Error(
+        `${bin} binary not found after installation. Please install Docker manually.`,
+      );
+    }
+  }
+
+  console.log("  ✅ Docker toolchain installed to ~/.local/bin/");
+}
+
+/**
+ * Ensures ~/.local/bin/ is on PATH for this process so that docker, colima,
+ * and limactl are discoverable.
+ */
+function ensureLocalBinOnPath(): void {
+  const currentPath = process.env.PATH || "";
+  if (!currentPath.includes(LOCAL_BIN_DIR)) {
+    process.env.PATH = `${LOCAL_BIN_DIR}:${currentPath}`;
+  }
+}
+
+/**
+ * Checks whether the `docker` CLI and daemon are available on the system.
+ * Installs Colima and Docker via direct binary download if missing (no sudo
+ * required), and starts Colima if the Docker daemon is not reachable.
+ */
+async function ensureDockerInstalled(): Promise<void> {
+  // Always add ~/.local/bin to PATH so previously installed binaries are found.
+  ensureLocalBinOnPath();
+
+  // Check that docker, colima, and limactl are all available. If any is
+  // missing (e.g. partial install from a previous failure), re-run install.
+  const toolchainComplete = await (async () => {
+    try {
+      await execOutput("docker", ["--version"]);
+      await execOutput("colima", ["version"]);
+      await execOutput("limactl", ["--version"]);
+      return true;
+    } catch {
+      return false;
+    }
+  })();
+
+  if (!toolchainComplete) {
+    await installDockerToolchain();
+    // Re-check PATH after install.
+    ensureLocalBinOnPath();
 
     try {
       await execOutput("docker", ["--version"]);
@@ -104,7 +246,7 @@ async function ensureDockerInstalled(): Promise<void> {
     }
   }
 
-  // Verify the Docker daemon is reachable; start Colima if it isn't
+  // Verify the Docker daemon is reachable; start Colima if it isn't.
   try {
     await exec("docker", ["info"]);
   } catch {
@@ -140,10 +282,10 @@ export function dockerResourceNames(instanceName: string) {
   return {
     assistantContainer: `${instanceName}-assistant`,
     cesContainer: `${instanceName}-credential-executor`,
-    dataVolume: `vellum-data-${instanceName}`,
+    dataVolume: `${instanceName}-data`,
     gatewayContainer: `${instanceName}-gateway`,
-    network: `vellum-net-${instanceName}`,
-    socketVolume: `vellum-ces-bootstrap-${instanceName}`,
+    network: `${instanceName}-net`,
+    socketVolume: `${instanceName}-socket`,
   };
 }
 
@@ -187,7 +329,7 @@ export async function retireDocker(name: string): Promise<void> {
   // Also clean up a legacy single-container instance if it exists
   await removeContainer(name);
 
-  // Remove shared network and volumes
+  // Remove network and volumes
   try {
     await exec("docker", ["network", "rm", res.network]);
   } catch {
@@ -378,7 +520,6 @@ export function serviceDockerRunArgs(opts: {
       "-d",
       "--name",
       res.cesContainer,
-      `--network=${res.network}`,
       "-v",
       `${res.socketVolume}:/run/ces-bootstrap`,
       "-v",
@@ -654,7 +795,7 @@ export async function hatchDocker(
 
     const res = dockerResourceNames(instanceName);
 
-    log("📁 Creating shared network and volumes...");
+    log("📁 Creating network and volumes...");
     await exec("docker", ["network", "create", res.network]);
     await exec("docker", ["volume", "create", res.dataVolume]);
     await exec("docker", ["volume", "create", res.socketVolume]);

package/src/lib/ngrok.ts

@@ -1,5 +1,11 @@
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -111,12 +117,29 @@ export async function findExistingTunnel(
 
 /**
  * Start an ngrok process tunneling HTTP traffic to the given local port.
+ *
+ * When `logFilePath` is provided, stdout/stderr are redirected to that file
+ * instead of being piped. This avoids keeping pipe handles open in the
+ * parent process — which would either prevent the CLI from exiting (if
+ * handles are left open) or send SIGPIPE to ngrok (if destroyed).
+ *
  * Returns the spawned child process.
  */
-export function startNgrokProcess(targetPort: number): ChildProcess {
+export function startNgrokProcess(
+  targetPort: number,
+  logFilePath?: string,
+): ChildProcess {
+  let stdio: ("ignore" | "pipe" | number)[] = ["ignore", "pipe", "pipe"];
+  if (logFilePath) {
+    const dir = dirname(logFilePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const fd = openSync(logFilePath, "a");
+    stdio = ["ignore", fd, fd];
+  }
+
   const child = spawn("ngrok", ["http", String(targetPort), "--log=stdout"], {
     detached: true,
-    stdio: ["ignore", "pipe", "pipe"],
+    stdio,
   });
   return child;
 }
@@ -170,14 +193,16 @@ function clearIngressUrl(): void {
 }
 
 /**
- * Check whether any webhook-based integrations (e.g. Telegram) are configured
- * that require a public ingress URL.
+ * Check whether any webhook-based integrations (e.g. Telegram, Twilio) are
+ * configured that require a public ingress URL.
  */
 function hasWebhookIntegrationsConfigured(): boolean {
   try {
     const config = loadRawConfig();
     const telegram = config.telegram as Record<string, unknown> | undefined;
     if (telegram?.botUsername) return true;
+    const twilio = config.twilio as Record<string, unknown> | undefined;
+    if (twilio?.accountSid || twilio?.phoneNumber) return true;
     return false;
   } catch {
     return false;
@@ -225,31 +250,23 @@ export async function maybeStartNgrokTunnel(
   }
 
   console.log(`   Starting ngrok tunnel for webhook integrations...`);
-  const ngrokProcess = startNgrokProcess(targetPort);
 
-  // Pipe output for debugging but don't block on it
-  ngrokProcess.stdout?.on("data", (data: Buffer) => {
-    const line = data.toString().trim();
-    if (line) console.log(`[ngrok] ${line}`);
-  });
-  ngrokProcess.stderr?.on("data", (data: Buffer) => {
-    const line = data.toString().trim();
-    if (line) console.error(`[ngrok] ${line}`);
-  });
+  // Spawn ngrok with stdout/stderr redirected to a log file instead of pipes.
+  // This avoids two problems that occur with piped stdio:
+  //   1. If pipe handles are left open, the CLI process hangs after hatch/wake.
+  //   2. If pipe handles are destroyed, SIGPIPE kills ngrok on its next write.
+  // Writing to a log file sidesteps both issues — the file descriptor is
+  // inherited by the detached ngrok process and remains valid after CLI exit.
+  const root = join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
+  const ngrokLogPath = join(root, "workspace", "data", "logs", "ngrok.log");
+  const ngrokProcess = startNgrokProcess(targetPort, ngrokLogPath);
+  ngrokProcess.unref();
 
   try {
     const publicUrl = await waitForNgrokUrl();
     saveIngressUrl(publicUrl);
     console.log(`   Tunnel established: ${publicUrl}`);
 
-    // Detach the ngrok process so the CLI (hatch/wake) can exit without
-    // keeping it alive. Remove stdout/stderr listeners and unref all handles.
-    ngrokProcess.stdout?.removeAllListeners("data");
-    ngrokProcess.stderr?.removeAllListeners("data");
-    ngrokProcess.stdout?.destroy();
-    ngrokProcess.stderr?.destroy();
-    ngrokProcess.unref();
-
     return ngrokProcess;
   } catch {
     console.warn(