@vellumai/cli 0.5.9 → 0.5.11

package/package.json

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

package/src/commands/hatch.ts

@@ -55,6 +55,7 @@ import { generateInstanceName } from "../lib/random-name";
 import { validateAssistantName } from "../lib/retire-archive";
 import { leaseGuardianToken } from "../lib/guardian-token";
 import { archiveLogFile, resetLogFile } from "../lib/xdg-log";
+import { emitProgress } from "../lib/desktop-progress.js";
 
 export type { PollResult, WatchHatchingResult } from "../lib/gcp";
 
@@ -645,6 +646,8 @@ async function hatchLocal(
     name ?? process.env.VELLUM_ASSISTANT_NAME,
   );
 
+  emitProgress(1, 7, "Preparing workspace...");
+
   // Clean up stale local state: if daemon/gateway processes are running but
   // the lock file has no entries AND the daemon is not healthy, stop them
   // before starting fresh. A healthy daemon should be reused, not killed —
@@ -703,6 +706,8 @@ async function hatchLocal(
     }
   }
 
+  emitProgress(2, 7, "Allocating resources...");
+
   // Reuse existing resources if re-hatching with --name that matches a known
   // local assistant, otherwise allocate fresh per-instance ports and directories.
   let resources: LocalInstanceResources;
@@ -763,10 +768,13 @@ async function hatchLocal(
     process.env.APP_VERSION = cliPkg.version;
   }
 
+  emitProgress(3, 7, "Writing configuration...");
   const defaultWorkspaceConfigPath = writeInitialConfig(configValues);
 
+  emitProgress(4, 7, "Starting assistant...");
   await startLocalDaemon(watch, resources, { defaultWorkspaceConfigPath });
 
+  emitProgress(5, 7, "Starting gateway...");
   let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
   try {
     runtimeUrl = await startGateway(watch, resources);
@@ -782,6 +790,7 @@ async function hatchLocal(
 
   // Lease a guardian token so the desktop app can import it on first launch
   // instead of hitting /v1/guardian/init itself.
+  emitProgress(6, 7, "Securing connection...");
   try {
     await leaseGuardianToken(runtimeUrl, instanceName);
   } catch (err) {
@@ -813,6 +822,7 @@ async function hatchLocal(
     serviceGroupVersion: cliPkg.version ? `v${cliPkg.version}` : undefined,
     resources,
   };
+  emitProgress(7, 7, "Saving configuration...");
   if (!restart) {
     saveAssistantEntry(localEntry);
     setActiveAssistant(instanceName);

package/src/lib/assistant-config.ts

@@ -438,7 +438,7 @@ export async function allocateLocalResources(
 ): Promise<LocalInstanceResources> {
   // First local assistant gets the home directory with default ports.
   // Respect BASE_DATA_DIR when set (e.g. in e2e tests) so the daemon,
-  // gateway, and keychain broker all resolve paths under the same root.
+  // gateway, and credential store all resolve paths under the same root.
   const existingLocals = loadAllAssistants().filter((e) => e.cloud === "local");
   if (existingLocals.length === 0) {
     const baseDir = getBaseDir();

package/src/lib/aws.ts

@@ -11,6 +11,7 @@ import type { Species } from "./constants";
 import { leaseGuardianToken } from "./guardian-token";
 import { generateInstanceName } from "./random-name";
 import { exec, execOutput } from "./step-runner";
+import { emitProgress } from "./desktop-progress.js";
 
 const KEY_PAIR_NAME = "vellum-assistant";
 const DEFAULT_SSH_USER = "admin";
@@ -443,6 +444,7 @@ export async function hatchAws(
     console.log("\u{1F50D} Finding latest Debian AMI...");
     const amiId = await getLatestDebianAmi(region);
 
+    emitProgress(1, 5, "Preparing startup script...");
     const { script: startupScript, laptopBootstrapSecret } =
       await buildStartupScript(
         species,
@@ -455,6 +457,7 @@ export async function hatchAws(
     const startupScriptPath = join(tmpdir(), `${instanceName}-startup.sh`);
     writeFileSync(startupScriptPath, startupScript);
 
+    emitProgress(2, 5, "Launching instance...");
     console.log("\u{1F528} Launching instance...");
     let instanceId: string;
     try {
@@ -491,6 +494,7 @@ export async function hatchAws(
     const runtimeUrl = externalIp
       ? `http://${externalIp}:${GATEWAY_PORT}`
       : `http://${instanceName}:${GATEWAY_PORT}`;
+    emitProgress(3, 5, "Saving configuration...");
     const awsEntry: AssistantEntry = {
       assistantId: instanceName,
       runtimeUrl,
@@ -522,6 +526,7 @@ export async function hatchAws(
 
       if (externalIp) {
         const ip = externalIp;
+        emitProgress(4, 5, "Installing software...");
         const result = await watchHatching(
           () => pollAwsInstance(ip, keyPath),
           instanceName,
@@ -539,6 +544,7 @@ export async function hatchAws(
           process.exit(1);
         }
 
+        emitProgress(5, 5, "Finalizing...");
         try {
           await leaseGuardianToken(
             runtimeUrl,

package/src/lib/desktop-progress.ts

@@ -0,0 +1,22 @@
+/**
+ * Lightweight progress reporting for the desktop app.
+ *
+ * Writes structured `HATCH_PROGRESS:{...}` lines to stdout so the Electron
+ * wrapper can parse them and render a progress bar during hatch.
+ *
+ * This module intentionally has ZERO internal imports to avoid circular
+ * dependency issues — it is a leaf module.
+ */
+
+/**
+ * Emit a structured progress event to stdout.
+ *
+ * Only emits when `VELLUM_DESKTOP_APP` env var is set (desktop mode).
+ * The desktop app parses lines matching `HATCH_PROGRESS:{...}` to update
+ * its progress UI.
+ */
+export function emitProgress(step: number, total: number, label: string): void {
+  if (!process.env.VELLUM_DESKTOP_APP) return;
+  const payload = JSON.stringify({ step, total, label });
+  process.stdout.write(`HATCH_PROGRESS:${payload}\n`);
+}

package/src/lib/docker.ts

@@ -26,6 +26,7 @@ import {
   resetLogFile,
   writeToLogFile,
 } from "./xdg-log";
+import { emitProgress } from "./desktop-progress.js";
 
 export type ServiceName = "assistant" | "credential-executor" | "gateway";
 
@@ -831,10 +832,11 @@ export async function sleepContainers(
   }
 }
 
-/** Start existing stopped containers. */
+/** Start existing stopped containers, starting Colima first if it isn't running. */
 export async function wakeContainers(
   res: ReturnType<typeof dockerResourceNames>,
 ): Promise<void> {
+  await ensureColimaRunning();
   for (const container of [
     res.assistantContainer,
     res.gatewayContainer,
@@ -844,6 +846,20 @@ export async function wakeContainers(
   }
 }
 
+/**
+ * Checks whether Colima is running and starts it if not.
+ * Assumes the Docker/Colima toolchain is already installed (handled during hatch).
+ */
+async function ensureColimaRunning(): Promise<void> {
+  ensureLocalBinOnPath();
+  try {
+    await exec("colima", ["status"]);
+  } catch {
+    console.log("🚀 Colima is not running. Starting Colima...");
+    await exec("colima", ["start"]);
+  }
+}
+
 /**
  * Capture the current image references for running service containers.
  * Returns a complete record of service → immutable image ID (sha256 digest)
@@ -1061,6 +1077,7 @@ export async function hatchDocker(
   };
 
   try {
+    emitProgress(1, 6, "Checking Docker...");
     await ensureDockerInstalled();
 
     const instanceName = generateInstanceName(species, name);
@@ -1075,6 +1092,7 @@ export async function hatchDocker(
     let repoRoot: string | undefined;
 
     if (watch) {
+      emitProgress(2, 6, "Building images...");
       repoRoot = findRepoRoot();
       const localTag = `local-${instanceName}`;
       imageTags.assistant = `vellum-assistant:${localTag}`;
@@ -1095,6 +1113,7 @@ export async function hatchDocker(
       await buildAllImages(repoRoot, imageTags, log);
       log("✅ Docker images built");
     } else {
+      emitProgress(2, 6, "Pulling images...");
       const version = cliPkg.version;
       const versionTag = version ? `v${version}` : "latest";
       log("🔍 Resolving image references...");
@@ -1121,6 +1140,7 @@ export async function hatchDocker(
 
     const res = dockerResourceNames(instanceName);
 
+    emitProgress(3, 6, "Creating volumes...");
     log("📁 Creating network and volumes...");
     await exec("docker", ["network", "create", res.network]);
     await exec("docker", ["volume", "create", res.socketVolume]);
@@ -1158,6 +1178,7 @@ export async function hatchDocker(
       ? `${preExisting},${ownSecret}`
       : ownSecret;
 
+    emitProgress(4, 6, "Starting containers...");
     await startContainers(
       {
         signingKey,
@@ -1193,9 +1214,11 @@ export async function hatchDocker(
         networkName: res.network,
       },
     };
+    emitProgress(5, 6, "Saving configuration...");
     saveAssistantEntry(dockerEntry);
     setActiveAssistant(instanceName);
 
+    emitProgress(6, 6, "Waiting for services...");
     const { ready } = await waitForGatewayAndLease({
       bootstrapSecret: ownSecret,
       containerName: res.assistantContainer,

package/src/lib/gcp.ts

@@ -14,6 +14,7 @@ import { leaseGuardianToken } from "./guardian-token";
 import { getPlatformUrl } from "./platform-client";
 import { generateInstanceName } from "./random-name";
 import { exec, execOutput } from "./step-runner";
+import { emitProgress } from "./desktop-progress.js";
 
 export async function getActiveProject(): Promise<string> {
   const output = await execOutput("gcloud", ["config", "get-value", "project"]);
@@ -522,6 +523,7 @@ export async function hatchGcp(
       );
       process.exit(1);
     }
+    emitProgress(1, 5, "Preparing startup script...");
     const { script: startupScript, laptopBootstrapSecret } =
       await buildStartupScript(
         species,
@@ -534,6 +536,7 @@ export async function hatchGcp(
     const startupScriptPath = join(tmpdir(), `${instanceName}-startup.sh`);
     writeFileSync(startupScriptPath, startupScript);
 
+    emitProgress(2, 5, "Launching instance...");
     console.log("\ud83d\udd28 Creating instance with startup script...");
     try {
       const createArgs = [
@@ -595,6 +598,7 @@ export async function hatchGcp(
     const runtimeUrl = externalIp
       ? `http://${externalIp}:${GATEWAY_PORT}`
       : `http://${instanceName}:${GATEWAY_PORT}`;
+    emitProgress(3, 5, "Saving configuration...");
     const gcpEntry: AssistantEntry = {
       assistantId: instanceName,
       runtimeUrl,
@@ -624,6 +628,7 @@ export async function hatchGcp(
       console.log("   Press Ctrl+C to detach (instance will keep running)");
       console.log("");
 
+      emitProgress(4, 5, "Installing software...");
       const result = await watchHatching(
         () => pollInstance(instanceName, project, zone, account),
         instanceName,
@@ -662,6 +667,7 @@ export async function hatchGcp(
         }
       }
 
+      emitProgress(5, 5, "Finalizing...");
       try {
         await leaseGuardianToken(
           runtimeUrl,

package/src/lib/local.ts

@@ -266,6 +266,7 @@ async function startDaemonFromSource(
     ...process.env,
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
     VELLUM_CLOUD: "local",
+    VELLUM_DEV: "1",
   };
   if (resources) {
     env.BASE_DATA_DIR = resources.instanceDir;