@vellumai/cli 0.5.6 → 0.5.8

package/src/index.ts

@@ -68,16 +68,16 @@ function printHelp(): void {
     "  ps       List assistants (or processes for a specific assistant)",
   );
   console.log("  recover  Restore a previously retired local assistant");
-  console.log("  restore  Restore a .vbundle backup into a running assistant");
-  console.log("  retire   Delete an assistant instance");
   console.log(
-    "  rollback  Roll back a Docker assistant to the previous version",
+    "  restore  Restore data (and optionally version) from a .vbundle backup",
   );
+  console.log("  retire   Delete an assistant instance");
+  console.log("  rollback  Roll back an assistant to a previous version");
   console.log("  setup    Configure API keys interactively");
   console.log("  sleep    Stop the assistant process");
   console.log("  ssh      SSH into a remote assistant instance");
   console.log("  tunnel   Create a tunnel for a locally hosted assistant");
-  console.log("  upgrade  Upgrade an assistant to the latest version");
+  console.log("  upgrade  Upgrade an assistant to a newer version");
   console.log("  use      Set the active assistant for commands");
   console.log("  wake     Start the assistant and gateway");
   console.log("  whoami   Show current logged-in user");

package/src/lib/assistant-config.ts

@@ -1,4 +1,12 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { randomBytes } from "crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "fs";
 import { homedir } from "os";
 import { join } from "path";
 
@@ -82,6 +90,14 @@ export interface AssistantEntry {
   previousServiceGroupVersion?: string;
   /** Docker image metadata from before the last upgrade. Enables rollback to the prior version. */
   previousContainerInfo?: ContainerInfo;
+  /** Path to the .vbundle backup created for the most recent upgrade. Used by rollback to restore
+   *  only the backup from the specific upgrade being rolled back — never a stale backup from a
+   *  previous upgrade cycle. */
+  preUpgradeBackupPath?: string;
+  /** Pre-upgrade DB migration version — used by rollback to know how far back to revert. */
+  previousDbMigrationVersion?: number;
+  /** Pre-upgrade workspace migration ID — used by rollback to know how far back to revert. */
+  previousWorkspaceMigrationId?: string;
   [key: string]: unknown;
 }
 
@@ -92,7 +108,7 @@ interface LockfileData {
   [key: string]: unknown;
 }
 
-function getBaseDir(): string {
+export function getBaseDir(): string {
   return process.env.BASE_DATA_DIR?.trim() || homedir();
 }
 
@@ -124,7 +140,16 @@ function readLockfile(): LockfileData {
 
 function writeLockfile(data: LockfileData): void {
   const lockfilePath = join(getLockfileDir(), ".vellum.lock.json");
-  writeFileSync(lockfilePath, JSON.stringify(data, null, 2) + "\n");
+  const tmpPath = `${lockfilePath}.${randomBytes(4).toString("hex")}.tmp`;
+  try {
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n");
+    renameSync(tmpPath, lockfilePath);
+  } catch (err) {
+    try {
+      unlinkSync(tmpPath);
+    } catch {}
+    throw err;
+  }
 }
 
 /**
@@ -412,12 +437,14 @@ export async function allocateLocalResources(
   instanceName: string,
 ): 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.
   const existingLocals = loadAllAssistants().filter((e) => e.cloud === "local");
   if (existingLocals.length === 0) {
-    const home = homedir();
-    const vellumDir = join(home, ".vellum");
+    const baseDir = getBaseDir();
+    const vellumDir = join(baseDir, ".vellum");
     return {
-      instanceDir: home,
+      instanceDir: baseDir,
       daemonPort: DEFAULT_DAEMON_PORT,
       gatewayPort: DEFAULT_GATEWAY_PORT,
       qdrantPort: DEFAULT_QDRANT_PORT,

package/src/lib/aws.ts

@@ -374,6 +374,7 @@ export async function hatchAws(
   species: Species,
   detached: boolean,
   name: string | null,
+  configValues: Record<string, string> = {},
 ): Promise<void> {
   const startTime = Date.now();
   try {
@@ -442,13 +443,15 @@ export async function hatchAws(
     console.log("\u{1F50D} Finding latest Debian AMI...");
     const amiId = await getLatestDebianAmi(region);
 
-    const startupScript = await buildStartupScript(
-      species,
-      sshUser,
-      providerApiKeys,
-      instanceName,
-      "aws",
-    );
+    const { script: startupScript, laptopBootstrapSecret } =
+      await buildStartupScript(
+        species,
+        sshUser,
+        providerApiKeys,
+        instanceName,
+        "aws",
+        configValues,
+      );
     const startupScriptPath = join(tmpdir(), `${instanceName}-startup.sh`);
     writeFileSync(startupScriptPath, startupScript);
 
@@ -537,7 +540,11 @@ export async function hatchAws(
         }
 
         try {
-          await leaseGuardianToken(runtimeUrl, instanceName);
+          await leaseGuardianToken(
+            runtimeUrl,
+            instanceName,
+            laptopBootstrapSecret,
+          );
         } catch (err) {
           console.warn(
             `\u26a0\ufe0f  Could not lease guardian token: ${err instanceof Error ? err.message : err}`,

package/src/lib/backup-ops.ts

@@ -0,0 +1,213 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+import { loadGuardianToken, leaseGuardianToken } from "./guardian-token.js";
+
+/** Default backup directory following XDG convention */
+export function getBackupsDir(): string {
+  const dataHome =
+    process.env.XDG_DATA_HOME?.trim() || join(homedir(), ".local", "share");
+  return join(dataHome, "vellum", "backups");
+}
+
+/** Human-readable file size */
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** Obtain a valid guardian access token (cached or fresh lease) */
+async function getGuardianAccessToken(
+  runtimeUrl: string,
+  assistantId: string,
+  forceRefresh?: boolean,
+): Promise<string> {
+  if (!forceRefresh) {
+    const tokenData = loadGuardianToken(assistantId);
+    if (tokenData && new Date(tokenData.accessTokenExpiresAt) > new Date()) {
+      return tokenData.accessToken;
+    }
+  }
+  const freshToken = await leaseGuardianToken(runtimeUrl, assistantId);
+  return freshToken.accessToken;
+}
+
+/**
+ * Create a .vbundle backup of a running assistant.
+ * Returns the path to the saved backup, or null if backup failed.
+ * Never throws — failures are logged as warnings.
+ */
+export async function createBackup(
+  runtimeUrl: string,
+  assistantId: string,
+  options?: { prefix?: string; description?: string },
+): Promise<string | null> {
+  try {
+    let accessToken = await getGuardianAccessToken(runtimeUrl, assistantId);
+
+    let response = await fetch(`${runtimeUrl}/v1/migrations/export`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        description: options?.description ?? "CLI backup",
+      }),
+      signal: AbortSignal.timeout(120_000),
+    });
+
+    // Retry once with a fresh token on 401 — the cached token may be stale
+    // after a container restart that generated a new gateway signing key.
+    if (response.status === 401) {
+      accessToken = await getGuardianAccessToken(runtimeUrl, assistantId, true);
+      response = await fetch(`${runtimeUrl}/v1/migrations/export`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          description: options?.description ?? "CLI backup",
+        }),
+        signal: AbortSignal.timeout(120_000),
+      });
+    }
+
+    if (!response.ok) {
+      const body = await response.text();
+      console.warn(
+        `Warning: backup export failed (${response.status}): ${body}`,
+      );
+      return null;
+    }
+
+    const arrayBuffer = await response.arrayBuffer();
+    const data = new Uint8Array(arrayBuffer);
+
+    const isoTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const prefix = options?.prefix ?? assistantId;
+    const outputPath = join(
+      getBackupsDir(),
+      `${prefix}-${isoTimestamp}.vbundle`,
+    );
+
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, data);
+
+    return outputPath;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`Warning: backup failed: ${msg}`);
+    return null;
+  }
+}
+
+/**
+ * Restore a .vbundle backup into a running assistant.
+ * Returns true if restore succeeded, false otherwise.
+ * Never throws — failures are logged as warnings.
+ */
+export async function restoreBackup(
+  runtimeUrl: string,
+  assistantId: string,
+  backupPath: string,
+): Promise<boolean> {
+  try {
+    if (!existsSync(backupPath)) {
+      console.warn(`Warning: backup file not found: ${backupPath}`);
+      return false;
+    }
+
+    const bundleData = readFileSync(backupPath);
+    let accessToken = await getGuardianAccessToken(runtimeUrl, assistantId);
+
+    let response = await fetch(`${runtimeUrl}/v1/migrations/import`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/octet-stream",
+      },
+      body: bundleData,
+      signal: AbortSignal.timeout(120_000),
+    });
+
+    // Retry once with a fresh token on 401 — the cached token may be stale
+    // after a container restart that generated a new gateway signing key.
+    if (response.status === 401) {
+      accessToken = await getGuardianAccessToken(runtimeUrl, assistantId, true);
+      response = await fetch(`${runtimeUrl}/v1/migrations/import`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/octet-stream",
+        },
+        body: bundleData,
+        signal: AbortSignal.timeout(120_000),
+      });
+    }
+
+    if (!response.ok) {
+      const body = await response.text();
+      console.warn(`Warning: restore failed (${response.status}): ${body}`);
+      return false;
+    }
+
+    const result = (await response.json()) as {
+      success: boolean;
+      message?: string;
+      reason?: string;
+    };
+    if (!result.success) {
+      console.warn(
+        `Warning: restore failed — ${result.message ?? result.reason ?? "unknown reason"}`,
+      );
+      return false;
+    }
+
+    return true;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`Warning: restore failed: ${msg}`);
+    return false;
+  }
+}
+
+/**
+ * Keep only the N most recent pre-upgrade backups for an assistant,
+ * deleting older ones. Default: keep 3.
+ * Never throws — failures are silently ignored.
+ */
+export function pruneOldBackups(assistantId: string, keep: number = 3): void {
+  try {
+    const backupsDir = getBackupsDir();
+    if (!existsSync(backupsDir)) return;
+
+    const prefix = `${assistantId}-pre-upgrade-`;
+    const entries = readdirSync(backupsDir)
+      .filter((f) => f.startsWith(prefix) && f.endsWith(".vbundle"))
+      .sort();
+
+    if (entries.length <= keep) return;
+
+    const toDelete = entries.slice(0, entries.length - keep);
+    for (const file of toDelete) {
+      try {
+        unlinkSync(join(backupsDir, file));
+      } catch {
+        // Best-effort cleanup — ignore individual file errors
+      }
+    }
+  } catch {
+    // Best-effort cleanup — never block the upgrade
+  }
+}

package/src/lib/cli-error.ts

@@ -0,0 +1,93 @@
+/**
+ * Structured CLI error reporting for upgrade/rollback commands.
+ *
+ * When a CLI command fails, it can emit a machine-readable JSON object
+ * prefixed with `CLI_ERROR:` to stderr so that consumers (e.g. the
+ * desktop app) can parse it reliably. Modeled after the DAEMON_ERROR
+ * protocol in `assistant/src/daemon/startup-error.ts`.
+ */
+
+/** Known error categories emitted by CLI commands. */
+export type CliErrorCategory =
+  | "DOCKER_NOT_RUNNING"
+  | "IMAGE_PULL_FAILED"
+  | "MISSING_VERSION"
+  | "READINESS_TIMEOUT"
+  | "ROLLBACK_FAILED"
+  | "ROLLBACK_NO_STATE"
+  | "VERSION_DIRECTION"
+  | "AUTH_FAILED"
+  | "NETWORK_ERROR"
+  | "UNSUPPORTED_TOPOLOGY"
+  | "ASSISTANT_NOT_FOUND"
+  | "PLATFORM_API_ERROR"
+  | "UNKNOWN";
+
+interface CliErrorPayload {
+  error: CliErrorCategory;
+  message: string;
+  detail?: string;
+}
+
+const CLI_ERROR_PREFIX = "CLI_ERROR:";
+
+/**
+ * Write a structured error line to stderr. The line is prefixed with
+ * `CLI_ERROR:` followed by JSON, making it unambiguous even if other
+ * stderr output precedes it.
+ */
+export function emitCliError(
+  category: CliErrorCategory,
+  message: string,
+  detail?: string,
+): void {
+  const payload: CliErrorPayload = { error: category, message, detail };
+  const line = `${CLI_ERROR_PREFIX}${JSON.stringify(payload)}`;
+  process.stderr.write(line + "\n");
+}
+
+/**
+ * Inspect an error string and return the most appropriate
+ * {@link CliErrorCategory} for common upgrade/rollback failures.
+ */
+export function categorizeUpgradeError(err: unknown): CliErrorCategory {
+  const msg = String(err).toLowerCase();
+
+  if (
+    msg.includes("cannot connect to the docker") ||
+    msg.includes("is docker running")
+  ) {
+    return "DOCKER_NOT_RUNNING";
+  }
+
+  if (
+    msg.includes("manifest unknown") ||
+    msg.includes("manifest not found") ||
+    msg.includes("pull access denied") ||
+    msg.includes("repository does not exist")
+  ) {
+    return "IMAGE_PULL_FAILED";
+  }
+
+  if (msg.includes("timeout") || msg.includes("readyz")) {
+    return "READINESS_TIMEOUT";
+  }
+
+  if (
+    msg.includes("401") ||
+    msg.includes("403") ||
+    msg.includes("unauthorized")
+  ) {
+    return "AUTH_FAILED";
+  }
+
+  if (
+    msg.includes("enotfound") ||
+    msg.includes("econnrefused") ||
+    msg.includes("network")
+  ) {
+    return "NETWORK_ERROR";
+  }
+
+  return "UNKNOWN";
+}

package/src/lib/config-utils.ts

@@ -0,0 +1,59 @@
+import { writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+/**
+ * Convert flat dot-notation key=value pairs into a nested config object.
+ *
+ * e.g. {"services.inference.provider": "anthropic", "services.inference.model": "claude-opus-4-6"}
+ *   → {services: {inference: {provider: "anthropic", model: "claude-opus-4-6"}}}
+ */
+export function buildNestedConfig(
+  configValues: Record<string, string>,
+): Record<string, unknown> {
+  const config: Record<string, unknown> = {};
+  for (const [dotKey, value] of Object.entries(configValues)) {
+    const parts = dotKey.split(".");
+    let target: Record<string, unknown> = config;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      const existing = target[part];
+      if (
+        existing == null ||
+        typeof existing !== "object" ||
+        Array.isArray(existing)
+      ) {
+        target[part] = {};
+      }
+      target = target[part] as Record<string, unknown>;
+    }
+    target[parts[parts.length - 1]] = value;
+  }
+  return config;
+}
+
+/**
+ * Write arbitrary key-value pairs to a temporary JSON file and return its
+ * path. The caller passes this path to the daemon via the
+ * VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH env var so the daemon can merge the
+ * values into its workspace config on first boot.
+ *
+ * Keys use dot-notation to address nested fields. For example:
+ *   "services.inference.provider" → {services: {inference: {provider: ...}}}
+ *   "services.inference.model"    → {services: {inference: {model: ...}}}
+ *
+ * Returns undefined when configValues is empty (nothing to write).
+ */
+export function writeInitialConfig(
+  configValues: Record<string, string>,
+): string | undefined {
+  if (Object.keys(configValues).length === 0) return undefined;
+
+  const config = buildNestedConfig(configValues);
+  const tempPath = join(
+    tmpdir(),
+    `vellum-default-workspace-config-${process.pid}-${Date.now()}.json`,
+  );
+  writeFileSync(tempPath, JSON.stringify(config, null, 2) + "\n");
+  return tempPath;
+}