@vellumai/cli 0.4.43 → 0.4.45

package/CONTRIBUTING.md

@@ -0,0 +1,5 @@
+# CLI Package — Contributing Guidelines
+
+## Module Boundaries
+
+- **Commands must not import from other commands.** Shared logic belongs in `src/lib/`. If two commands need the same function, extract it into an appropriate lib module rather than importing across `src/commands/` files.

package/package.json

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

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

@@ -1,5 +1,5 @@
 import { describe, test, expect, beforeEach, afterAll } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -14,6 +14,7 @@ import {
   loadAllAssistants,
   saveAssistantEntry,
   getActiveAssistant,
+  migrateLegacyEntry,
   type AssistantEntry,
 } from "../lib/assistant-config.js";
 
@@ -180,3 +181,250 @@ describe("assistant-config", () => {
     expect(all[0].assistantId).toBe("valid");
   });
 });
+
+describe("migrateLegacyEntry", () => {
+  test("rewrites baseDataDir as resources.instanceDir", () => {
+    /**
+     * Tests that a legacy entry with top-level baseDataDir gets migrated
+     * to the current resources.instanceDir format.
+     */
+
+    // GIVEN a legacy entry with baseDataDir set at the top level
+    const entry: Record<string, unknown> = {
+      assistantId: "my-assistant",
+      runtimeUrl: "http://localhost:7830",
+      cloud: "local",
+      baseDataDir: "/home/user/.local/share/vellum/assistants/my-assistant",
+    };
+
+    // WHEN we migrate the entry
+    const changed = migrateLegacyEntry(entry);
+
+    // THEN the entry should be mutated
+    expect(changed).toBe(true);
+
+    // AND baseDataDir should be removed
+    expect(entry.baseDataDir).toBeUndefined();
+
+    // AND resources.instanceDir should contain the old baseDataDir value
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.instanceDir).toBe(
+      "/home/user/.local/share/vellum/assistants/my-assistant",
+    );
+  });
+
+  test("synthesises full resources when none exist", () => {
+    /**
+     * Tests that a legacy local entry with no resources object gets a
+     * complete resources object synthesised with default ports and pidFile.
+     */
+
+    // GIVEN a local entry with no resources
+    const entry: Record<string, unknown> = {
+      assistantId: "old-assistant",
+      runtimeUrl: "http://localhost:7830",
+      cloud: "local",
+    };
+
+    // WHEN we migrate the entry
+    const changed = migrateLegacyEntry(entry);
+
+    // THEN the entry should be mutated
+    expect(changed).toBe(true);
+
+    // AND resources should be fully populated
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.instanceDir).toContain("old-assistant");
+    expect(resources.daemonPort).toBe(7821);
+    expect(resources.gatewayPort).toBe(7830);
+    expect(resources.qdrantPort).toBe(6333);
+    expect(resources.pidFile).toContain("vellum.pid");
+  });
+
+  test("infers gateway port from runtimeUrl", () => {
+    /**
+     * Tests that the gateway port is extracted from the runtimeUrl when
+     * synthesising resources for a legacy entry.
+     */
+
+    // GIVEN a local entry with a non-default gateway port in the runtimeUrl
+    const entry: Record<string, unknown> = {
+      assistantId: "custom-port",
+      runtimeUrl: "http://localhost:9999",
+      cloud: "local",
+    };
+
+    // WHEN we migrate the entry
+    migrateLegacyEntry(entry);
+
+    // THEN the gateway port should match the runtimeUrl port
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.gatewayPort).toBe(9999);
+  });
+
+  test("skips non-local entries", () => {
+    /**
+     * Tests that remote (non-local) entries are left untouched.
+     */
+
+    // GIVEN a GCP entry without resources
+    const entry: Record<string, unknown> = {
+      assistantId: "gcp-assistant",
+      runtimeUrl: "https://example.com",
+      cloud: "gcp",
+    };
+
+    // WHEN we attempt to migrate it
+    const changed = migrateLegacyEntry(entry);
+
+    // THEN nothing should change
+    expect(changed).toBe(false);
+    expect(entry.resources).toBeUndefined();
+  });
+
+  test("backfills missing fields on partial resources", () => {
+    /**
+     * Tests that an entry with a partial resources object (e.g. only
+     * instanceDir) gets the remaining fields backfilled.
+     */
+
+    // GIVEN an entry with partial resources (only instanceDir)
+    const entry: Record<string, unknown> = {
+      assistantId: "partial",
+      runtimeUrl: "http://localhost:7830",
+      cloud: "local",
+      resources: {
+        instanceDir: "/custom/path",
+      },
+    };
+
+    // WHEN we migrate the entry
+    const changed = migrateLegacyEntry(entry);
+
+    // THEN the entry should be mutated
+    expect(changed).toBe(true);
+
+    // AND all missing resources fields should be filled in
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.instanceDir).toBe("/custom/path");
+    expect(resources.daemonPort).toBe(7821);
+    expect(resources.gatewayPort).toBe(7830);
+    expect(resources.qdrantPort).toBe(6333);
+    expect(resources.pidFile).toBe("/custom/path/.vellum/vellum.pid");
+  });
+
+  test("does not overwrite existing resources fields", () => {
+    /**
+     * Tests that an entry with a complete resources object is left untouched.
+     */
+
+    // GIVEN an entry with a complete resources object
+    const entry: Record<string, unknown> = {
+      assistantId: "complete",
+      runtimeUrl: "http://localhost:7830",
+      cloud: "local",
+      resources: {
+        instanceDir: "/my/path",
+        daemonPort: 8000,
+        gatewayPort: 8001,
+        qdrantPort: 8002,
+        pidFile: "/my/path/.vellum/vellum.pid",
+      },
+    };
+
+    // WHEN we migrate the entry
+    const changed = migrateLegacyEntry(entry);
+
+    // THEN nothing should change
+    expect(changed).toBe(false);
+
+    // AND existing values should be preserved
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.daemonPort).toBe(8000);
+    expect(resources.gatewayPort).toBe(8001);
+    expect(resources.qdrantPort).toBe(8002);
+  });
+
+  test("baseDataDir does not overwrite existing resources.instanceDir", () => {
+    /**
+     * Tests that when both baseDataDir and resources.instanceDir exist,
+     * the existing instanceDir is preserved and baseDataDir is removed.
+     */
+
+    // GIVEN an entry with both baseDataDir and resources.instanceDir
+    const entry: Record<string, unknown> = {
+      assistantId: "conflict",
+      runtimeUrl: "http://localhost:7830",
+      cloud: "local",
+      baseDataDir: "/old/path",
+      resources: {
+        instanceDir: "/new/path",
+        daemonPort: 7821,
+        gatewayPort: 7830,
+        qdrantPort: 6333,
+        pidFile: "/new/path/.vellum/vellum.pid",
+      },
+    };
+
+    // WHEN we migrate the entry
+    const changed = migrateLegacyEntry(entry);
+
+    // THEN baseDataDir should be removed
+    expect(changed).toBe(true);
+    expect(entry.baseDataDir).toBeUndefined();
+
+    // AND the existing instanceDir should be preserved
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.instanceDir).toBe("/new/path");
+  });
+});
+
+describe("legacy migration via loadAllAssistants", () => {
+  beforeEach(() => {
+    try {
+      rmSync(join(testDir, ".vellum.lock.json"));
+    } catch {
+      // file may not exist
+    }
+  });
+
+  test("migrates legacy entries and persists to disk on read", () => {
+    /**
+     * Tests that reading assistants from a lockfile with legacy entries
+     * triggers migration and persists the updated format to disk.
+     */
+
+    // GIVEN a lockfile with a legacy entry containing baseDataDir
+    writeLockfile({
+      assistants: [
+        {
+          assistantId: "legacy-bot",
+          runtimeUrl: "http://localhost:7830",
+          cloud: "local",
+          baseDataDir: "/home/user/.local/share/vellum/assistants/legacy-bot",
+        },
+      ],
+    });
+
+    // WHEN we load assistants
+    const all = loadAllAssistants();
+
+    // THEN the entry should have resources populated
+    expect(all).toHaveLength(1);
+    expect(all[0].resources).toBeDefined();
+    expect(all[0].resources!.instanceDir).toBe(
+      "/home/user/.local/share/vellum/assistants/legacy-bot",
+    );
+    expect(all[0].resources!.gatewayPort).toBe(7830);
+
+    // AND the lockfile on disk should reflect the migration
+    const rawDisk = JSON.parse(
+      readFileSync(join(testDir, ".vellum.lock.json"), "utf-8"),
+    );
+    const diskEntry = rawDisk.assistants[0];
+    expect(diskEntry.baseDataDir).toBeUndefined();
+    expect(diskEntry.resources.instanceDir).toBe(
+      "/home/user/.local/share/vellum/assistants/legacy-bot",
+    );
+  });
+});

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

@@ -94,21 +94,22 @@ describe("multi-local", () => {
   });
 
   describe("allocateLocalResources() produces non-conflicting ports", () => {
-    test("first instance gets XDG path and default ports", async () => {
+    test("first instance gets home directory and default ports", async () => {
       // GIVEN no local assistants exist in the lockfile
 
       // WHEN we allocate resources for the first instance
       const res = await allocateLocalResources("instance-a");
 
-      // THEN it gets an XDG instance directory under the home dir
-      expect(res.instanceDir).toBe(
-        join(testDir, ".local", "share", "vellum", "assistants", "instance-a"),
-      );
+      // THEN it gets the home directory as its instance root
+      expect(res.instanceDir).toBe(testDir);
 
       // AND it gets the default ports since no other instances exist
       expect(res.daemonPort).toBe(DEFAULT_DAEMON_PORT);
       expect(res.gatewayPort).toBe(DEFAULT_GATEWAY_PORT);
       expect(res.qdrantPort).toBe(DEFAULT_QDRANT_PORT);
+
+      // AND the PID file is under ~/.vellum/
+      expect(res.pidFile).toBe(join(testDir, ".vellum", "vellum.pid"));
     });
 
     test("second instance gets distinct ports and dir when first instance is saved", async () => {

package/src/commands/clean.ts

@@ -0,0 +1,34 @@
+import { detectOrphanedProcesses } from "../lib/orphan-detection";
+import { stopProcess } from "../lib/process";
+
+export async function clean(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum clean");
+    console.log("");
+    console.log("Kill all orphaned vellum processes that are not tracked by any assistant.");
+    process.exit(0);
+  }
+
+  const orphans = await detectOrphanedProcesses();
+
+  if (orphans.length === 0) {
+    console.log("No orphaned processes found.");
+    return;
+  }
+
+  console.log(`Found ${orphans.length} orphaned process${orphans.length === 1 ? "" : "es"}.\n`);
+
+  let killed = 0;
+  for (const orphan of orphans) {
+    const pid = parseInt(orphan.pid, 10);
+    const stopped = await stopProcess(pid, `${orphan.name} (PID ${orphan.pid})`);
+    if (stopped) {
+      killed++;
+    }
+  }
+
+  console.log(
+    `\nCleaned up ${killed} process${killed === 1 ? "" : "es"}.`,
+  );
+}

package/src/commands/hatch.ts

@@ -47,9 +47,11 @@ import {
   startGateway,
   stopLocalProcesses,
 } from "../lib/local";
+import { maybeStartNgrokTunnel } from "../lib/ngrok";
 import { isProcessAlive } from "../lib/process";
 import { generateRandomSuffix } from "../lib/random-name";
 import { validateAssistantName } from "../lib/retire-archive";
+import { archiveLogFile, resetLogFile } from "../lib/xdg-log";
 
 export type { PollResult, WatchHatchingResult } from "../lib/gcp";
 
@@ -265,7 +267,16 @@ function parseArgs(): HatchArgs {
     }
   }
 
-  return { species, detached, keepAlive, name, remote, daemonOnly, restart, watch };
+  return {
+    species,
+    detached,
+    keepAlive,
+    name,
+    remote,
+    daemonOnly,
+    restart,
+    watch,
+  };
 }
 
 function formatElapsed(ms: number): string {
@@ -730,6 +741,16 @@ async function hatchLocal(
     resources = await allocateLocalResources(instanceName);
   }
 
+  const logsDir = join(
+    resources.instanceDir,
+    ".vellum",
+    "workspace",
+    "data",
+    "logs",
+  );
+  archiveLogFile("hatch.log", logsDir);
+  resetLogFile("hatch.log");
+
   console.log(`🥚 Hatching local assistant: ${instanceName}`);
   console.log(`   Species: ${species}`);
   console.log("");
@@ -749,6 +770,21 @@ async function hatchLocal(
     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;
+  }
+
   // Read the bearer token (JWT) written by the daemon so the CLI can
   // with the gateway (which requires auth by default). The daemon writes under
   // getRootDir() which resolves to <instanceDir>/.vellum/.
@@ -826,9 +862,7 @@ async function hatchLocal(
         consecutiveFailures++;
       }
       if (consecutiveFailures >= MAX_FAILURES) {
-        console.log(
-          "\n⚠️  Gateway stopped responding — shutting down.",
-        );
+        console.log("\n⚠️  Gateway stopped responding — shutting down.");
         await stopLocalProcesses(resources);
         process.exit(1);
       }
@@ -844,8 +878,16 @@ export async function hatch(): Promise<void> {
   const cliVersion = getCliVersion();
   console.log(`@vellumai/cli v${cliVersion}`);
 
-  const { species, detached, keepAlive, name, remote, daemonOnly, restart, watch } =
-    parseArgs();
+  const {
+    species,
+    detached,
+    keepAlive,
+    name,
+    remote,
+    daemonOnly,
+    restart,
+    watch,
+  } = parseArgs();
 
   if (restart && remote !== "local") {
     console.error(

package/src/commands/ps.ts

@@ -1,5 +1,3 @@
-import { existsSync, readFileSync } from "fs";
-import { homedir } from "os";
 import { join } from "path";
 
 import {
@@ -9,6 +7,13 @@ import {
   type AssistantEntry,
 } from "../lib/assistant-config";
 import { checkHealth } from "../lib/health-check";
+import {
+  classifyProcess,
+  detectOrphanedProcesses,
+  isProcessAlive,
+  parseRemotePs,
+  readPidFile,
+} from "../lib/orphan-detection";
 import { pgrepExact } from "../lib/pgrep";
 import { probePort } from "../lib/port-probe";
 import { withStatusEmoji } from "../lib/status-emoji";
@@ -77,40 +82,6 @@ const REMOTE_PS_CMD = [
   "| grep -v grep",
 ].join(" ");
 
-interface RemoteProcess {
-  pid: string;
-  ppid: string;
-  command: string;
-}
-
-function classifyProcess(command: string): string {
-  if (/qdrant/.test(command)) return "qdrant";
-  if (/vellum-gateway/.test(command)) return "gateway";
-  if (/openclaw/.test(command)) return "openclaw-adapter";
-  if (/vellum-daemon/.test(command)) return "assistant";
-  if (/daemon\s+(start|restart)/.test(command)) return "assistant";
-  // Exclude macOS desktop app processes — their path contains .app/Contents/MacOS/
-  // but they are not background service processes.
-  if (/\.app\/Contents\/MacOS\//.test(command)) return "unknown";
-  if (/vellum/.test(command)) return "vellum";
-  return "unknown";
-}
-
-function parseRemotePs(output: string): RemoteProcess[] {
-  return output
-    .trim()
-    .split("\n")
-    .filter((line) => line.trim().length > 0)
-    .map((line) => {
-      const trimmed = line.trim();
-      const parts = trimmed.split(/\s+/);
-      const pid = parts[0];
-      const ppid = parts[1];
-      const command = parts.slice(2).join(" ");
-      return { pid, ppid, command };
-    });
-}
-
 function extractHostFromUrl(url: string): string {
   try {
     const parsed = new URL(url);
@@ -157,21 +128,6 @@ interface ProcessSpec {
   pidFile: string;
 }
 
-function readPidFile(pidFile: string): string | null {
-  if (!existsSync(pidFile)) return null;
-  const pid = readFileSync(pidFile, "utf-8").trim();
-  return pid || null;
-}
-
-function isProcessAlive(pid: string): boolean {
-  try {
-    process.kill(parseInt(pid, 10), 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 interface DetectedProcess {
   name: string;
   pid: string | null;
@@ -318,57 +274,6 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
   printTable(rows);
 }
 
-// ── Orphaned process detection ──────────────────────────────────
-
-interface OrphanedProcess {
-  name: string;
-  pid: string;
-  source: string;
-}
-
-async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
-  const results: OrphanedProcess[] = [];
-  const seenPids = new Set<string>();
-  const vellumDir = join(homedir(), ".vellum");
-
-  // Strategy 1: PID file scan
-  const pidFiles: Array<{ file: string; name: string }> = [
-    { file: join(vellumDir, "vellum.pid"), name: "assistant" },
-    { file: join(vellumDir, "gateway.pid"), name: "gateway" },
-    { file: join(vellumDir, "qdrant.pid"), name: "qdrant" },
-  ];
-
-  for (const { file, name } of pidFiles) {
-    const pid = readPidFile(file);
-    if (pid && isProcessAlive(pid)) {
-      results.push({ name, pid, source: "pid file" });
-      seenPids.add(pid);
-    }
-  }
-
-  // Strategy 2: Process table scan
-  try {
-    const output = await execOutput("sh", [
-      "-c",
-      "ps ax -o pid=,ppid=,args= | grep -E 'vellum|vellum-gateway|qdrant|openclaw' | grep -v grep",
-    ]);
-    const procs = parseRemotePs(output);
-    const ownPid = String(process.pid);
-
-    for (const p of procs) {
-      if (p.pid === ownPid || seenPids.has(p.pid)) continue;
-      const type = classifyProcess(p.command);
-      if (type === "unknown") continue;
-      results.push({ name: type, pid: p.pid, source: "process table" });
-      seenPids.add(p.pid);
-    }
-  } catch {
-    // grep exits 1 when no matches found — ignore
-  }
-
-  return results;
-}
-
 // ── List all assistants (no arg) ────────────────────────────────
 
 async function listAllAssistants(): Promise<void> {
@@ -387,9 +292,8 @@ async function listAllAssistants(): Promise<void> {
         info: `PID ${o.pid} (from ${o.source})`,
       }));
       printTable(rows);
-      const pids = orphans.map((o) => o.pid).join(" ");
       console.log(
-        `\nHint: Run \`kill ${pids}\` to clean up orphaned processes.`,
+        `\nHint: Run \`vellum clean\` to clean up orphaned processes.`,
       );
     }
 

package/src/commands/wake.ts

@@ -1,9 +1,10 @@
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
 
 import { resolveTargetAssistant } from "../lib/assistant-config.js";
 import { isProcessAlive, stopProcessByPidFile } from "../lib/process";
 import { startLocalDaemon, startGateway } from "../lib/local";
+import { maybeStartNgrokTunnel } from "../lib/ngrok";
 
 export async function wake(): Promise<void> {
   const args = process.argv.slice(3);
@@ -95,5 +96,20 @@ export async function wake(): Promise<void> {
     }
   }
 
+  // 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;
+  }
+
   console.log("Wake complete.");
 }