@vellumai/cli 0.4.22 → 0.4.25

package/package.json

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

package/src/commands/hatch.ts

@@ -147,6 +147,7 @@ interface HatchArgs {
   remote: RemoteHost;
   daemonOnly: boolean;
   restart: boolean;
+  watch: boolean;
 }
 
 function parseArgs(): HatchArgs {
@@ -157,6 +158,7 @@ function parseArgs(): HatchArgs {
   let remote: RemoteHost = DEFAULT_REMOTE;
   let daemonOnly = false;
   let restart = false;
+  let watch = false;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -175,6 +177,7 @@ function parseArgs(): HatchArgs {
       console.log("  --remote <host>           Remote host (local, gcp, aws, custom)");
       console.log("  --daemon-only             Start daemon only, skip gateway");
       console.log("  --restart                 Restart processes without onboarding side effects");
+      console.log("  --watch                   Run daemon and gateway in watch mode (hot reload on source changes)");
       process.exit(0);
     } else if (arg === "-d") {
       detached = true;
@@ -182,6 +185,8 @@ function parseArgs(): HatchArgs {
       daemonOnly = true;
     } else if (arg === "--restart") {
       restart = true;
+    } else if (arg === "--watch") {
+      watch = true;
     } else if (arg === "--name") {
       const next = args[i + 1];
       if (!next || next.startsWith("-")) {
@@ -210,13 +215,13 @@ function parseArgs(): HatchArgs {
       species = arg as Species;
     } else {
       console.error(
-        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --daemon-only, --restart, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>`,
+        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --daemon-only, --restart, --watch, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>`,
       );
       process.exit(1);
     }
   }
 
-  return { species, detached, name, remote, daemonOnly, restart };
+  return { species, detached, name, remote, daemonOnly, restart, watch };
 }
 
 function formatElapsed(ms: number): string {
@@ -594,7 +599,7 @@ async function displayPairingQRCode(runtimeUrl: string, bearerToken: string | un
   }
 }
 
-async function hatchLocal(species: Species, name: string | null, daemonOnly: boolean = false, restart: boolean = false): Promise<void> {
+async function hatchLocal(species: Species, name: string | null, daemonOnly: boolean = false, restart: boolean = false, watch: boolean = false): Promise<void> {
   if (restart && !name && !process.env.VELLUM_ASSISTANT_NAME) {
     console.error("Error: Cannot restart without a known assistant ID. Provide --name or ensure VELLUM_ASSISTANT_NAME is set.");
     process.exit(1);
@@ -649,11 +654,11 @@ async function hatchLocal(species: Species, name: string | null, daemonOnly: boo
   console.log(`   Species: ${species}`);
   console.log("");
 
-  await startLocalDaemon();
+  await startLocalDaemon(watch);
 
   let runtimeUrl: string;
   try {
-    runtimeUrl = await startGateway(instanceName);
+    runtimeUrl = await startGateway(instanceName, watch);
   } catch (error) {
     // Gateway failed — stop the daemon we just started so we don't leave
     // orphaned processes with no lock file entry.
@@ -710,15 +715,20 @@ export async function hatch(): Promise<void> {
   const cliVersion = getCliVersion();
   console.log(`@vellumai/cli v${cliVersion}`);
 
-  const { species, detached, name, remote, daemonOnly, restart } = parseArgs();
+  const { species, detached, name, remote, daemonOnly, restart, watch } = parseArgs();
 
   if (restart && remote !== "local") {
     console.error("Error: --restart is only supported for local hatch targets.");
     process.exit(1);
   }
 
+  if (watch && remote !== "local") {
+    console.error("Error: --watch is only supported for local hatch targets.");
+    process.exit(1);
+  }
+
   if (remote === "local") {
-    await hatchLocal(species, name, daemonOnly, restart);
+    await hatchLocal(species, name, daemonOnly, restart, watch);
     return;
   }
 

package/src/lib/local.ts

@@ -148,6 +148,10 @@ async function waitForSocketFile(
   return existsSync(socketPath);
 }
 
+function resolveDaemonMainPath(assistantIndex: string): string {
+  return join(dirname(assistantIndex), "daemon", "main.ts");
+}
+
 async function startDaemonFromSource(assistantIndex: string): Promise<void> {
   const env: Record<string, string | undefined> = {
     ...process.env,
@@ -176,6 +180,80 @@ async function startDaemonFromSource(assistantIndex: string): Promise<void> {
   });
 }
 
+// NOTE: startDaemonWatchFromSource() is the CLI-side watch-mode daemon
+// launcher. Its lifecycle guards should eventually converge with
+// assistant/src/daemon/daemon-control.ts::startDaemon which is the
+// assistant-side equivalent.
+async function startDaemonWatchFromSource(assistantIndex: string): Promise<void> {
+  const mainPath = resolveDaemonMainPath(assistantIndex);
+  if (!existsSync(mainPath)) {
+    throw new Error(`Daemon main.ts not found at ${mainPath}`);
+  }
+
+  const vellumDir = join(homedir(), ".vellum");
+  mkdirSync(vellumDir, { recursive: true });
+
+  const pidFile = join(vellumDir, "vellum.pid");
+  const socketFile = join(vellumDir, "vellum.sock");
+
+  // --- Lifecycle guard: prevent split-brain daemon state ---
+  // If a daemon is already running, skip spawning a new one.
+  if (existsSync(pidFile)) {
+    try {
+      const pid = parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
+      if (!isNaN(pid)) {
+        try {
+          process.kill(pid, 0); // Check if alive
+          console.log(`   Daemon already running (pid ${pid})\n`);
+          return;
+        } catch {
+          // Process doesn't exist, clean up stale PID file
+          try { unlinkSync(pidFile); } catch {}
+        }
+      }
+    } catch {}
+  }
+
+  // PID file was stale or missing, but a daemon with a different PID may
+  // still be listening on the socket. Check before starting a new one.
+  if (await isSocketResponsive(socketFile)) {
+    const ownerPid = findSocketOwnerPid(socketFile);
+    if (ownerPid) {
+      writeFileSync(pidFile, String(ownerPid), "utf-8");
+      console.log(
+        `   Daemon socket is responsive (pid ${ownerPid}) — skipping restart\n`,
+      );
+    } else {
+      console.log("   Daemon socket is responsive — skipping restart\n");
+    }
+    return;
+  }
+
+  // Socket is unresponsive or missing — safe to clean up and start fresh.
+  try { unlinkSync(socketFile); } catch {}
+
+  const env: Record<string, string | undefined> = {
+    ...process.env,
+    RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
+  };
+
+  const daemonLogFd = openLogFile("hatch.log");
+  const child = spawn("bun", ["--watch", "run", mainPath], {
+    detached: true,
+    stdio: ["ignore", "pipe", "pipe"],
+    env,
+  });
+  pipeToLogFile(child, daemonLogFd, "daemon");
+  child.unref();
+  const daemonPid = child.pid;
+
+  if (daemonPid) {
+    writeFileSync(pidFile, String(daemonPid), "utf-8");
+  }
+
+  console.log("   Daemon started in watch mode (bun --watch)");
+}
+
 function resolveGatewayDir(): string {
   const override = process.env.VELLUM_GATEWAY_DIR?.trim();
   if (override) {
@@ -417,10 +495,16 @@ function getLocalLanIPv4(): string | undefined {
   return undefined;
 }
 
-export async function startLocalDaemon(): Promise<void> {
-  if (process.env.VELLUM_DESKTOP_APP) {
+// NOTE: startLocalDaemon() is the CLI-side daemon lifecycle manager.
+// It should eventually converge with
+// assistant/src/daemon/daemon-control.ts::startDaemon which is the
+// assistant-side equivalent.
+export async function startLocalDaemon(watch: boolean = false): Promise<void> {
+  if (process.env.VELLUM_DESKTOP_APP && !watch) {
     // When running inside the desktop app, the CLI owns the daemon lifecycle.
     // Find the vellum-daemon binary adjacent to the CLI binary.
+    // In watch mode, skip the bundled binary and use source (bun --watch
+    // only works with source files, not compiled binaries).
     const daemonBinary = join(dirname(process.execPath), "vellum-daemon");
     if (!existsSync(daemonBinary)) {
       throw new Error(
@@ -545,7 +629,11 @@ export async function startLocalDaemon(): Promise<void> {
         );
         // Kill the bundled daemon to avoid two processes competing for the same socket/port
         await stopProcessByPidFile(pidFile, "bundled daemon", [socketFile]);
-        await startDaemonFromSource(assistantIndex);
+        if (watch) {
+          await startDaemonWatchFromSource(assistantIndex);
+        } else {
+          await startDaemonFromSource(assistantIndex);
+        }
         socketReady = await waitForSocketFile(socketFile, 60000);
       }
     }
@@ -567,11 +655,24 @@ export async function startLocalDaemon(): Promise<void> {
           "  Ensure the daemon binary is bundled alongside the CLI, or run from the source tree.",
       );
     }
-    await startDaemonFromSource(assistantIndex);
+    if (watch) {
+      await startDaemonWatchFromSource(assistantIndex);
+
+      const vellumDir = join(homedir(), ".vellum");
+      const socketFile = join(vellumDir, "vellum.sock");
+      const socketReady = await waitForSocketFile(socketFile, 60000);
+      if (socketReady) {
+        console.log("   Daemon socket ready\n");
+      } else {
+        console.log("   ⚠️  Daemon socket did not appear within 60s — continuing anyway\n");
+      }
+    } else {
+      await startDaemonFromSource(assistantIndex);
+    }
   }
 }
 
-export async function startGateway(assistantId?: string): Promise<string> {
+export async function startGateway(assistantId?: string, watch: boolean = false): Promise<string> {
   const publicUrl = await discoverPublicUrl();
   if (publicUrl) {
     console.log(`   Public URL: ${publicUrl}`);
@@ -677,8 +778,10 @@ export async function startGateway(assistantId?: string): Promise<string> {
 
   let gateway;
 
-  if (process.env.VELLUM_DESKTOP_APP) {
+  if (process.env.VELLUM_DESKTOP_APP && !watch) {
     // Desktop app: spawn the compiled gateway binary directly (mirrors daemon pattern).
+    // In watch mode, skip the bundled binary and use source (bun --watch
+    // only works with source files, not compiled binaries).
     const gatewayBinary = join(dirname(process.execPath), "vellum-gateway");
     if (!existsSync(gatewayBinary)) {
       throw new Error(
@@ -697,14 +800,20 @@ export async function startGateway(assistantId?: string): Promise<string> {
   } else {
     // Source tree / bunx: resolve the gateway source directory and run via bun.
     const gatewayDir = resolveGatewayDir();
+    const bunArgs = watch
+      ? ["--watch", "run", "src/index.ts", "--vellum-gateway"]
+      : ["run", "src/index.ts", "--vellum-gateway"];
     const gwLogFd = openLogFile("hatch.log");
-    gateway = spawn("bun", ["run", "src/index.ts", "--vellum-gateway"], {
+    gateway = spawn("bun", bunArgs, {
       cwd: gatewayDir,
       detached: true,
       stdio: ["ignore", "pipe", "pipe"],
       env: gatewayEnv,
     });
     pipeToLogFile(gateway, gwLogFd, "gateway");
+    if (watch) {
+      console.log("   Gateway started in watch mode (bun --watch)");
+    }
   }
 
   gateway.unref();