@vellumai/cli 0.5.6 → 0.5.8

package/src/commands/restore.ts

@@ -1,45 +1,71 @@
 import { existsSync, readFileSync } from "fs";
 
 import { findAssistantByName } from "../lib/assistant-config.js";
+import type { AssistantEntry } from "../lib/assistant-config.js";
 import {
   loadGuardianToken,
   leaseGuardianToken,
 } from "../lib/guardian-token.js";
+import {
+  readPlatformToken,
+  fetchOrganizationId,
+  rollbackPlatformAssistant,
+  platformImportPreflight,
+  platformImportBundle,
+} from "../lib/platform-client.js";
+import { performDockerRollback } from "../lib/upgrade-lifecycle.js";
 
 function printUsage(): void {
-  console.log("Usage: vellum restore <name> --from <path> [--dry-run]");
+  console.log(
+    "Usage: vellum restore <name> --from <path> [--version <version>] [--dry-run]",
+  );
   console.log("");
-  console.log("Restore a .vbundle backup into a running assistant.");
+  console.log("Restore data from a .vbundle backup into an assistant.");
+  console.log(
+    "With --version, also rolls back to the specified version first.",
+  );
   console.log("");
   console.log("Arguments:");
-  console.log("  <name>              Name of the assistant to restore into");
+  console.log("  <name>               Name of the assistant to restore into");
   console.log("");
   console.log("Options:");
+  console.log("  --from <path>        Path to the .vbundle file (required)");
+  console.log(
+    "  --version <version>  Roll back to this version before importing data",
+  );
   console.log(
-    "  --from <path>       Path to the .vbundle file to restore (required)",
+    "  --dry-run            Show what would change without applying (data-only)",
   );
-  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 backup.vbundle");
   console.log(
-    "  vellum restore my-assistant --from ~/Desktop/backup.vbundle --dry-run",
+    "  vellum restore my-assistant --from backup.vbundle --version v1.2.3",
   );
+  console.log("  vellum restore my-assistant --from backup.vbundle --dry-run");
 }
 
 function parseArgs(argv: string[]): {
   name: string | undefined;
   fromPath: string | undefined;
+  version: 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 };
+    return {
+      name: undefined,
+      fromPath: undefined,
+      version: undefined,
+      dryRun: false,
+      help: true,
+    };
   }
 
   let fromPath: string | undefined;
+  let version: string | undefined;
   const dryRun = args.includes("--dry-run");
   const positionals: string[] = [];
 
@@ -47,6 +73,14 @@ function parseArgs(argv: string[]): {
     if (args[i] === "--from" && args[i + 1]) {
       fromPath = args[i + 1];
       i++; // skip the value
+    } else if (args[i] === "--version") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.error("Error: --version requires a value");
+        process.exit(1);
+      }
+      version = next;
+      i++; // skip the value
     } else if (args[i] === "--dry-run") {
       // already handled above
     } else if (!args[i].startsWith("-")) {
@@ -54,7 +88,7 @@ function parseArgs(argv: string[]): {
     }
   }
 
-  return { name: positionals[0], fromPath, dryRun, help: false };
+  return { name: positionals[0], fromPath, version, dryRun, help: false };
 }
 
 async function getAccessToken(
@@ -126,14 +160,289 @@ interface ImportResponse {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Platform (Vellum-hosted) restore via Django migration import
+// ---------------------------------------------------------------------------
+
+async function restorePlatform(
+  entry: AssistantEntry,
+  name: string,
+  bundleData: Buffer,
+  opts: { version?: string; dryRun: boolean },
+): Promise<void> {
+  // Step 1 — Authenticate
+  const token = readPlatformToken();
+  if (!token) {
+    console.error("Not logged in. Run 'vellum login' first.");
+    process.exit(1);
+  }
+
+  let orgId: string;
+  try {
+    orgId = await fetchOrganizationId(token);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("401") || msg.includes("403")) {
+      console.error("Authentication failed. Run 'vellum login' to refresh.");
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // Step 2 — Dry-run path
+  if (opts.dryRun) {
+    if (opts.version) {
+      console.error(
+        "Dry-run is not supported with --version. Use `vellum restore --from <path> --dry-run` for data-only preflight.",
+      );
+      process.exit(1);
+    }
+
+    console.log("Running preflight analysis...\n");
+
+    let preflightResult: { statusCode: number; body: Record<string, unknown> };
+    try {
+      preflightResult = await platformImportPreflight(
+        new Uint8Array(bundleData),
+        token,
+        orgId,
+      );
+    } catch (err) {
+      if (err instanceof Error && err.name === "TimeoutError") {
+        console.error("Error: Preflight request timed out after 2 minutes.");
+        process.exit(1);
+      }
+      throw err;
+    }
+
+    if (
+      preflightResult.statusCode === 401 ||
+      preflightResult.statusCode === 403
+    ) {
+      console.error("Authentication failed. Run 'vellum login' to refresh.");
+      process.exit(1);
+    }
+
+    if (preflightResult.statusCode === 404) {
+      console.error(
+        "No managed assistant found. Ensure your assistant is running.",
+      );
+      process.exit(1);
+    }
+
+    if (preflightResult.statusCode === 409) {
+      console.error(
+        "Multiple assistants found. This is a platform configuration issue.",
+      );
+      process.exit(1);
+    }
+
+    if (
+      preflightResult.statusCode === 502 ||
+      preflightResult.statusCode === 503 ||
+      preflightResult.statusCode === 504
+    ) {
+      console.error(
+        `Assistant is unreachable. Try 'vellum wake ${name}' first.`,
+      );
+      process.exit(1);
+    }
+
+    if (preflightResult.statusCode !== 200) {
+      console.error(
+        `Error: Preflight check failed (${preflightResult.statusCode}): ${JSON.stringify(preflightResult.body)}`,
+      );
+      process.exit(1);
+    }
+
+    const result = preflightResult.body as unknown 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}`);
+      }
+    }
+
+    return;
+  }
+
+  // Step 3 — Version rollback (if --version set)
+  if (opts.version) {
+    console.log(
+      `Rolling back to version ${opts.version} before restoring data...`,
+    );
+
+    try {
+      await rollbackPlatformAssistant(token, orgId, opts.version);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("401") || msg.includes("403")) {
+        console.error("Authentication failed. Run 'vellum login' to refresh.");
+        process.exit(1);
+      }
+      console.error(`Error: Rollback failed — ${msg}`);
+      process.exit(1);
+    }
+
+    console.log(
+      `Rolled back to ${opts.version}. Proceeding with data restore...`,
+    );
+  }
+
+  // Step 4 — Data import
+  console.log("Importing backup data...");
+
+  let importResult: { statusCode: number; body: Record<string, unknown> };
+  try {
+    importResult = await platformImportBundle(
+      new Uint8Array(bundleData),
+      token,
+      orgId,
+    );
+  } catch (err) {
+    if (err instanceof Error && err.name === "TimeoutError") {
+      console.error("Error: Import request timed out after 2 minutes.");
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  if (importResult.statusCode === 401 || importResult.statusCode === 403) {
+    console.error("Authentication failed. Run 'vellum login' to refresh.");
+    process.exit(1);
+  }
+
+  if (importResult.statusCode === 404) {
+    console.error(
+      "No managed assistant found. Ensure your assistant is running.",
+    );
+    process.exit(1);
+  }
+
+  if (importResult.statusCode === 409) {
+    console.error(
+      "Multiple assistants found. This is a platform configuration issue.",
+    );
+    process.exit(1);
+  }
+
+  if (
+    importResult.statusCode === 502 ||
+    importResult.statusCode === 503 ||
+    importResult.statusCode === 504
+  ) {
+    console.error(`Assistant is unreachable. Try 'vellum wake ${name}' first.`);
+    process.exit(1);
+  }
+
+  if (importResult.statusCode < 200 || importResult.statusCode >= 300) {
+    console.error(`Error: Import failed (${importResult.statusCode})`);
+    process.exit(1);
+  }
+
+  const result = importResult.body as unknown 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}`);
+    }
+  }
+}
+
 export async function restore(): Promise<void> {
-  const { name, fromPath, dryRun, help } = parseArgs(process.argv);
+  const { name, fromPath, version, dryRun, help } = parseArgs(process.argv);
 
   if (help) {
     printUsage();
     process.exit(0);
   }
 
+  // --version requires --from
+  if (version && !fromPath) {
+    console.error(
+      "A backup file is required for restore. Use --from <path> to specify the .vbundle file.",
+    );
+    process.exit(1);
+  }
+
+  // --dry-run is not supported with --version
+  if (version && dryRun) {
+    console.error(
+      "Dry-run is not supported with --version. Use `vellum restore --from <path> --dry-run` for data-only preflight.",
+    );
+    process.exit(1);
+  }
+
   if (!name || !fromPath) {
     console.error("Error: Both <name> and --from <path> are required.");
     console.error("");
@@ -160,8 +469,24 @@ export async function restore(): Promise<void> {
   const sizeMB = (bundleData.byteLength / (1024 * 1024)).toFixed(2);
   console.log(`Reading ${fromPath} (${sizeMB} MB)...`);
 
-  // Obtain auth token
-  const accessToken = await getAccessToken(
+  // Detect topology and route platform assistants through Django import
+  const cloud =
+    entry.cloud || (entry.project ? "gcp" : entry.sshUser ? "custom" : "local");
+  if (cloud === "vellum") {
+    await restorePlatform(entry, name, bundleData, { version, dryRun });
+    return;
+  }
+
+  if (version && cloud !== "docker") {
+    console.error(
+      "Restore with --version is only supported for Docker and managed assistants.",
+    );
+    process.exit(1);
+  }
+
+  // Obtain auth token (acquired before dry-run or before data import;
+  // re-acquired after version rollback since containers restart).
+  let accessToken = await getAccessToken(
     entry.runtimeUrl,
     entry.assistantId,
     name,
@@ -215,13 +540,17 @@ export async function restore(): Promise<void> {
       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})` : ""}`);
+          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})` : ""}`);
+          console.error(
+            `  - ${conflict.message}${conflict.path ? ` (${conflict.path})` : ""}`,
+          );
         }
       }
       process.exit(1);
@@ -255,8 +584,22 @@ export async function restore(): Promise<void> {
       }
     }
   } else {
-    // Full import
-    console.log("Importing backup...\n");
+    // Version rollback (when --version is specified)
+    if (version) {
+      console.log(`Rolling back to version ${version}...`);
+      await performDockerRollback(entry, { targetVersion: version });
+      console.log("");
+
+      // Re-acquire auth token since containers were restarted during rollback
+      accessToken = await getAccessToken(
+        entry.runtimeUrl,
+        entry.assistantId,
+        name,
+      );
+    }
+
+    // Data import
+    console.log("Importing backup data...\n");
 
     let response: Response;
     try {

package/src/commands/retire.ts

@@ -1,10 +1,10 @@
 import { spawn } from "child_process";
 import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
-import { homedir } from "os";
 import { basename, dirname, join } from "path";
 
 import {
   findAssistantByName,
+  getBaseDir,
   loadAllAssistants,
   removeAssistantEntry,
 } from "../lib/assistant-config";
@@ -109,10 +109,10 @@ async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
     await stopOrphanedDaemonProcesses();
   }
 
-  // For named instances (instanceDir differs from homedir), archive and
-  // remove the entire instance directory. For the default instance
-  // (instanceDir is homedir), archive only the .vellum subdirectory.
-  const isNamedInstance = resources.instanceDir !== homedir();
+  // For named instances (instanceDir differs from the base directory),
+  // archive and remove the entire instance directory. For the default
+  // instance, archive only the .vellum subdirectory.
+  const isNamedInstance = resources.instanceDir !== getBaseDir();
   const dirToArchive = isNamedInstance ? resources.instanceDir : vellumDir;
 
   // Move the data directory out of the way so the path is immediately available