@vellumai/cli 0.5.4 → 0.5.6

package/src/commands/restore.ts

@@ -0,0 +1,330 @@
+import { existsSync, readFileSync } from "fs";
+
+import { findAssistantByName } from "../lib/assistant-config.js";
+import {
+  loadGuardianToken,
+  leaseGuardianToken,
+} from "../lib/guardian-token.js";
+
+function printUsage(): void {
+  console.log("Usage: vellum restore <name> --from <path> [--dry-run]");
+  console.log("");
+  console.log("Restore a .vbundle backup into a running assistant.");
+  console.log("");
+  console.log("Arguments:");
+  console.log("  <name>              Name of the assistant to restore into");
+  console.log("");
+  console.log("Options:");
+  console.log(
+    "  --from <path>       Path to the .vbundle file to restore (required)",
+  );
+  console.log("  --dry-run           Show what would change without applying");
+  console.log("");
+  console.log("Examples:");
+  console.log("  vellum restore my-assistant --from ~/Desktop/backup.vbundle");
+  console.log(
+    "  vellum restore my-assistant --from ~/Desktop/backup.vbundle --dry-run",
+  );
+}
+
+function parseArgs(argv: string[]): {
+  name: string | undefined;
+  fromPath: string | undefined;
+  dryRun: boolean;
+  help: boolean;
+} {
+  const args = argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    return { name: undefined, fromPath: undefined, dryRun: false, help: true };
+  }
+
+  let fromPath: string | undefined;
+  const dryRun = args.includes("--dry-run");
+  const positionals: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--from" && args[i + 1]) {
+      fromPath = args[i + 1];
+      i++; // skip the value
+    } else if (args[i] === "--dry-run") {
+      // already handled above
+    } else if (!args[i].startsWith("-")) {
+      positionals.push(args[i]);
+    }
+  }
+
+  return { name: positionals[0], fromPath, dryRun, help: false };
+}
+
+async function getAccessToken(
+  runtimeUrl: string,
+  assistantId: string,
+  displayName: string,
+): Promise<string> {
+  const tokenData = loadGuardianToken(assistantId);
+
+  if (tokenData && new Date(tokenData.accessTokenExpiresAt) > new Date()) {
+    return tokenData.accessToken;
+  }
+
+  try {
+    const freshToken = await leaseGuardianToken(runtimeUrl, assistantId);
+    return freshToken.accessToken;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+      console.error(
+        `Error: Could not connect to assistant '${displayName}'. Is it running?`,
+      );
+      console.error(`Try: vellum wake ${displayName}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
+interface PreflightFileEntry {
+  path: string;
+  action: string;
+}
+
+interface StructuredError {
+  code: string;
+  message: string;
+  path?: string;
+}
+
+interface PreflightResponse {
+  can_import: boolean;
+  validation?: {
+    is_valid: false;
+    errors: StructuredError[];
+  };
+  files?: PreflightFileEntry[];
+  summary?: {
+    files_to_create: number;
+    files_to_overwrite: number;
+    files_unchanged: number;
+    total_files: number;
+  };
+  conflicts?: StructuredError[];
+}
+
+interface ImportResponse {
+  success: boolean;
+  reason?: string;
+  errors?: StructuredError[];
+  message?: string;
+  warnings?: string[];
+  summary?: {
+    total_files: number;
+    files_created: number;
+    files_overwritten: number;
+    files_skipped: number;
+    backups_created: number;
+  };
+}
+
+export async function restore(): Promise<void> {
+  const { name, fromPath, dryRun, help } = parseArgs(process.argv);
+
+  if (help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!name || !fromPath) {
+    console.error("Error: Both <name> and --from <path> are required.");
+    console.error("");
+    printUsage();
+    process.exit(1);
+  }
+
+  // Look up the instance
+  const entry = findAssistantByName(name);
+  if (!entry) {
+    console.error(`Error: No assistant found with name '${name}'.`);
+    console.error("Run 'vellum ps' to see available assistants.");
+    process.exit(1);
+  }
+
+  // Verify .vbundle file exists
+  if (!existsSync(fromPath)) {
+    console.error(`Error: File not found: ${fromPath}`);
+    process.exit(1);
+  }
+
+  // Read the .vbundle file
+  const bundleData = readFileSync(fromPath);
+  const sizeMB = (bundleData.byteLength / (1024 * 1024)).toFixed(2);
+  console.log(`Reading ${fromPath} (${sizeMB} MB)...`);
+
+  // Obtain auth token
+  const accessToken = await getAccessToken(
+    entry.runtimeUrl,
+    entry.assistantId,
+    name,
+  );
+
+  if (dryRun) {
+    // Preflight check
+    console.log("Running preflight analysis...\n");
+
+    let response: Response;
+    try {
+      response = await fetch(
+        `${entry.runtimeUrl}/v1/migrations/import-preflight`,
+        {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/octet-stream",
+          },
+          body: bundleData,
+          signal: AbortSignal.timeout(120_000),
+        },
+      );
+    } catch (err) {
+      if (err instanceof Error && err.name === "TimeoutError") {
+        console.error("Error: Preflight request timed out after 2 minutes.");
+        process.exit(1);
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+        console.error(
+          `Error: Could not connect to assistant '${name}'. Is it running?`,
+        );
+        console.error(`Try: vellum wake ${name}`);
+        process.exit(1);
+      }
+      throw err;
+    }
+
+    if (!response.ok) {
+      const body = await response.text();
+      console.error(
+        `Error: Preflight check failed (${response.status}): ${body}`,
+      );
+      process.exit(1);
+    }
+
+    const result = (await response.json()) as PreflightResponse;
+
+    if (!result.can_import) {
+      if (result.validation?.errors?.length) {
+        console.error("Import blocked by validation errors:");
+        for (const err of result.validation.errors) {
+          console.error(`  - ${err.message}${err.path ? ` (${err.path})` : ""}`);
+        }
+      }
+      if (result.conflicts?.length) {
+        console.error("Import blocked by conflicts:");
+        for (const conflict of result.conflicts) {
+          console.error(`  - ${conflict.message}${conflict.path ? ` (${conflict.path})` : ""}`);
+        }
+      }
+      process.exit(1);
+    }
+
+    // Print summary table
+    const summary = result.summary ?? {
+      files_to_create: 0,
+      files_to_overwrite: 0,
+      files_unchanged: 0,
+      total_files: 0,
+    };
+    console.log("Preflight analysis:");
+    console.log(`  Files to create:    ${summary.files_to_create}`);
+    console.log(`  Files to overwrite: ${summary.files_to_overwrite}`);
+    console.log(`  Files unchanged:    ${summary.files_unchanged}`);
+    console.log(`  Total:              ${summary.total_files}`);
+    console.log("");
+
+    const conflicts = result.conflicts ?? [];
+    console.log(
+      `Conflicts: ${conflicts.length > 0 ? conflicts.map((c) => c.message).join(", ") : "none"}`,
+    );
+
+    // List individual files with their action
+    if (result.files && result.files.length > 0) {
+      console.log("");
+      console.log("Files:");
+      for (const file of result.files) {
+        console.log(`  [${file.action}] ${file.path}`);
+      }
+    }
+  } else {
+    // Full import
+    console.log("Importing backup...\n");
+
+    let response: Response;
+    try {
+      response = await fetch(`${entry.runtimeUrl}/v1/migrations/import`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/octet-stream",
+        },
+        body: bundleData,
+        signal: AbortSignal.timeout(120_000),
+      });
+    } catch (err) {
+      if (err instanceof Error && err.name === "TimeoutError") {
+        console.error("Error: Import request timed out after 2 minutes.");
+        process.exit(1);
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+        console.error(
+          `Error: Could not connect to assistant '${name}'. Is it running?`,
+        );
+        console.error(`Try: vellum wake ${name}`);
+        process.exit(1);
+      }
+      throw err;
+    }
+
+    if (!response.ok) {
+      const body = await response.text();
+      console.error(`Error: Import failed (${response.status}): ${body}`);
+      process.exit(1);
+    }
+
+    const result = (await response.json()) as ImportResponse;
+
+    if (!result.success) {
+      console.error(
+        `Error: Import failed — ${result.message ?? result.reason ?? "unknown reason"}`,
+      );
+      for (const err of result.errors ?? []) {
+        console.error(`  - ${err.message}${err.path ? ` (${err.path})` : ""}`);
+      }
+      process.exit(1);
+    }
+
+    // Print import report
+    const summary = result.summary ?? {
+      total_files: 0,
+      files_created: 0,
+      files_overwritten: 0,
+      files_skipped: 0,
+      backups_created: 0,
+    };
+    console.log("✅ Restore complete.");
+    console.log(`  Files created:     ${summary.files_created}`);
+    console.log(`  Files overwritten: ${summary.files_overwritten}`);
+    console.log(`  Files skipped:     ${summary.files_skipped}`);
+    console.log(`  Backups created:   ${summary.backups_created}`);
+
+    // Print warnings if any
+    const warnings = result.warnings ?? [];
+    if (warnings.length > 0) {
+      console.log("");
+      console.log("Warnings:");
+      for (const warning of warnings) {
+        console.log(`  ⚠️  ${warning}`);
+      }
+    }
+  }
+}

package/src/commands/rollback.ts

@@ -0,0 +1,280 @@
+import { randomBytes } from "crypto";
+
+import {
+  findAssistantByName,
+  getActiveAssistant,
+  loadAllAssistants,
+  saveAssistantEntry,
+} from "../lib/assistant-config";
+import type { AssistantEntry } from "../lib/assistant-config";
+import {
+  captureImageRefs,
+  clearSigningKeyBootstrapLock,
+  GATEWAY_INTERNAL_PORT,
+  dockerResourceNames,
+  migrateCesSecurityFiles,
+  migrateGatewaySecurityFiles,
+  startContainers,
+  stopContainers,
+} from "../lib/docker";
+import type { ServiceName } from "../lib/docker";
+import { loadBootstrapSecret } from "../lib/guardian-token";
+import {
+  broadcastUpgradeEvent,
+  captureContainerEnv,
+  waitForReady,
+} from "./upgrade";
+
+function parseArgs(): { name: string | null } {
+  const args = process.argv.slice(3);
+  let name: string | null = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      console.log("Usage: vellum rollback [<name>]");
+      console.log("");
+      console.log("Roll back a Docker assistant to the previous version.");
+      console.log("");
+      console.log("Arguments:");
+      console.log(
+        "  <name>  Name of the assistant to roll back (default: active or only assistant)",
+      );
+      console.log("");
+      console.log("Examples:");
+      console.log(
+        "  vellum rollback                # Roll back the active assistant",
+      );
+      console.log(
+        "  vellum rollback my-assistant   # Roll back a specific assistant by name",
+      );
+      process.exit(0);
+    } else if (!arg.startsWith("-")) {
+      name = arg;
+    } else {
+      console.error(`Error: Unknown option '${arg}'.`);
+      process.exit(1);
+    }
+  }
+
+  return { name };
+}
+
+function resolveCloud(entry: AssistantEntry): string {
+  if (entry.cloud) {
+    return entry.cloud;
+  }
+  if (entry.project) {
+    return "gcp";
+  }
+  if (entry.sshUser) {
+    return "custom";
+  }
+  return "local";
+}
+
+/**
+ * Resolve which assistant to target for the rollback command. Priority:
+ * 1. Explicit name argument
+ * 2. Active assistant set via `vellum use`
+ * 3. Sole assistant (when exactly one exists)
+ */
+function resolveTargetAssistant(nameArg: string | null): AssistantEntry {
+  if (nameArg) {
+    const entry = findAssistantByName(nameArg);
+    if (!entry) {
+      console.error(`No assistant found with name '${nameArg}'.`);
+      process.exit(1);
+    }
+    return entry;
+  }
+
+  const active = getActiveAssistant();
+  if (active) {
+    const entry = findAssistantByName(active);
+    if (entry) return entry;
+  }
+
+  const all = loadAllAssistants();
+  if (all.length === 1) return all[0];
+
+  if (all.length === 0) {
+    console.error("No assistants found. Run 'vellum hatch' first.");
+  } else {
+    console.error(
+      "Multiple assistants found. Specify a name or set an active assistant with 'vellum use <name>'.",
+    );
+  }
+  process.exit(1);
+}
+
+export async function rollback(): Promise<void> {
+  const { name } = parseArgs();
+  const entry = resolveTargetAssistant(name);
+  const cloud = resolveCloud(entry);
+
+  // Only Docker assistants support rollback
+  if (cloud !== "docker") {
+    console.error(
+      "Rollback is only supported for Docker assistants. For managed assistants, use the version picker to upgrade to the previous version.",
+    );
+    process.exit(1);
+  }
+
+  // Verify rollback state exists
+  if (!entry.previousServiceGroupVersion || !entry.previousContainerInfo) {
+    console.error(
+      "No rollback state available. Run `vellum upgrade` first to create a rollback point.",
+    );
+    process.exit(1);
+  }
+
+  // Verify all three digest fields are present
+  const prev = entry.previousContainerInfo;
+  if (!prev.assistantDigest || !prev.gatewayDigest || !prev.cesDigest) {
+    console.error(
+      "Incomplete rollback state. Previous container digests are missing.",
+    );
+    process.exit(1);
+  }
+
+  // Build image refs from the previous digests
+  const previousImageRefs: Record<ServiceName, string> = {
+    assistant: prev.assistantDigest,
+    "credential-executor": prev.cesDigest,
+    gateway: prev.gatewayDigest,
+  };
+
+  const instanceName = entry.assistantId;
+  const res = dockerResourceNames(instanceName);
+
+  console.log(
+    `🔄 Rolling back Docker assistant '${instanceName}' to ${entry.previousServiceGroupVersion}...\n`,
+  );
+
+  // Capture current container env
+  console.log("💾 Capturing existing container environment...");
+  const capturedEnv = await captureContainerEnv(res.assistantContainer);
+  console.log(
+    `   Captured ${Object.keys(capturedEnv).length} env var(s) from ${res.assistantContainer}\n`,
+  );
+
+  // Extract CES_SERVICE_TOKEN from captured env, or generate fresh one
+  const cesServiceToken =
+    capturedEnv["CES_SERVICE_TOKEN"] || randomBytes(32).toString("hex");
+
+  // Retrieve or generate a bootstrap secret for the gateway.
+  const bootstrapSecret =
+    loadBootstrapSecret(instanceName) || randomBytes(32).toString("hex");
+
+  // Build extra env vars, excluding keys managed by serviceDockerRunArgs
+  const envKeysSetByRunArgs = new Set([
+    "CES_SERVICE_TOKEN",
+    "VELLUM_ASSISTANT_NAME",
+    "RUNTIME_HTTP_HOST",
+    "PATH",
+  ]);
+  for (const envVar of ["ANTHROPIC_API_KEY", "VELLUM_PLATFORM_URL"]) {
+    if (process.env[envVar]) {
+      envKeysSetByRunArgs.add(envVar);
+    }
+  }
+  const extraAssistantEnv: Record<string, string> = {};
+  for (const [key, value] of Object.entries(capturedEnv)) {
+    if (!envKeysSetByRunArgs.has(key)) {
+      extraAssistantEnv[key] = value;
+    }
+  }
+
+  // Parse gateway port from entry's runtimeUrl, fall back to default
+  let gatewayPort = GATEWAY_INTERNAL_PORT;
+  try {
+    const parsed = new URL(entry.runtimeUrl);
+    const port = parseInt(parsed.port, 10);
+    if (!isNaN(port)) {
+      gatewayPort = port;
+    }
+  } catch {
+    // use default
+  }
+
+  // Notify connected clients that a rollback is about to begin (best-effort)
+  console.log("📢 Notifying connected clients...");
+  await broadcastUpgradeEvent(entry.runtimeUrl, entry.assistantId, {
+    type: "starting",
+    targetVersion: entry.previousServiceGroupVersion,
+    expectedDowntimeSeconds: 60,
+  });
+  // Brief pause to allow SSE delivery before containers stop.
+  await new Promise((r) => setTimeout(r, 500));
+
+  console.log("🛑 Stopping existing containers...");
+  await stopContainers(res);
+  console.log("✅ Containers stopped\n");
+
+  // Run security file migrations and signing key cleanup
+  console.log("🔄 Migrating security files to gateway volume...");
+  await migrateGatewaySecurityFiles(res, (msg) => console.log(msg));
+
+  console.log("🔄 Migrating credential files to CES security volume...");
+  await migrateCesSecurityFiles(res, (msg) => console.log(msg));
+
+  console.log("🔑 Clearing signing key bootstrap lock...");
+  await clearSigningKeyBootstrapLock(res);
+
+  console.log("🚀 Starting containers with previous version...");
+  await startContainers(
+    {
+      bootstrapSecret,
+      cesServiceToken,
+      extraAssistantEnv,
+      gatewayPort,
+      imageTags: previousImageRefs,
+      instanceName,
+      res,
+    },
+    (msg) => console.log(msg),
+  );
+  console.log("✅ Containers started\n");
+
+  console.log("Waiting for assistant to become ready...");
+  const ready = await waitForReady(entry.runtimeUrl);
+
+  if (ready) {
+    // Capture new digests from the rolled-back containers
+    const newDigests = await captureImageRefs(res);
+
+    // Swap current/previous state to enable "rollback the rollback"
+    const updatedEntry: AssistantEntry = {
+      ...entry,
+      serviceGroupVersion: entry.previousServiceGroupVersion,
+      containerInfo: {
+        assistantImage: prev.assistantImage ?? previousImageRefs.assistant,
+        gatewayImage: prev.gatewayImage ?? previousImageRefs.gateway,
+        cesImage: prev.cesImage ?? previousImageRefs["credential-executor"],
+        assistantDigest: newDigests?.assistant,
+        gatewayDigest: newDigests?.gateway,
+        cesDigest: newDigests?.["credential-executor"],
+        networkName: res.network,
+      },
+      previousServiceGroupVersion: entry.serviceGroupVersion,
+      previousContainerInfo: entry.containerInfo,
+    };
+    saveAssistantEntry(updatedEntry);
+
+    // Notify clients that the rollback succeeded
+    await broadcastUpgradeEvent(entry.runtimeUrl, entry.assistantId, {
+      type: "complete",
+      installedVersion: entry.previousServiceGroupVersion,
+      success: true,
+    });
+
+    console.log(
+      `\n✅ Docker assistant '${instanceName}' rolled back to ${entry.previousServiceGroupVersion}.`,
+    );
+  } else {
+    console.error(`\n❌ Containers failed to become ready within the timeout.`);
+    console.log(`   Check logs with: docker logs -f ${res.assistantContainer}`);
+    process.exit(1);
+  }
+}