@vellumai/cli 0.5.7 → 0.5.9

package/src/commands/upgrade.ts

@@ -1,5 +1,4 @@
 import { randomBytes } from "crypto";
-import { join } from "node:path";
 
 import cliPkg from "../../package.json";
 
@@ -25,10 +24,6 @@ import {
   getPlatformUrl,
   readPlatformToken,
 } from "../lib/platform-client";
-import {
-  loadBootstrapSecret,
-  saveBootstrapSecret,
-} from "../lib/guardian-token";
 import {
   createBackup,
   pruneOldBackups,
@@ -43,30 +38,35 @@ import {
   buildStartingEvent,
   buildUpgradeCommitMessage,
   captureContainerEnv,
+  commitWorkspaceViaGateway,
   CONTAINER_ENV_EXCLUDE_KEYS,
   rollbackMigrations,
   UPGRADE_PROGRESS,
   waitForReady,
 } from "../lib/upgrade-lifecycle.js";
 import { parseVersion } from "../lib/version-compat.js";
-import { commitWorkspaceState } from "../lib/workspace-git.js";
 
 interface UpgradeArgs {
   name: string | null;
   version: string | null;
+  prepare: boolean;
+  finalize: boolean;
 }
 
 function parseArgs(): UpgradeArgs {
   const args = process.argv.slice(3);
   let name: string | null = null;
   let version: string | null = null;
+  let prepare = false;
+  let finalize = false;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--help" || arg === "-h") {
       console.log("Usage: vellum upgrade [<name>] [options]");
       console.log("");
-      console.log("Upgrade an assistant to the latest version.");
+      console.log("Upgrade an assistant to a newer version.");
+      console.log("To roll back to a previous version, use `vellum rollback`.");
       console.log("");
       console.log("Arguments:");
       console.log(
@@ -77,6 +77,12 @@ function parseArgs(): UpgradeArgs {
       console.log(
         "  --version <version>  Target version to upgrade to (default: latest)",
       );
+      console.log(
+        "  --prepare            Run pre-upgrade steps only (backup, notify) without swapping versions",
+      );
+      console.log(
+        "  --finalize           Run post-upgrade steps only (broadcast complete, workspace commit)",
+      );
       console.log("");
       console.log("Examples:");
       console.log(
@@ -98,6 +104,10 @@ function parseArgs(): UpgradeArgs {
       }
       version = next;
       i++;
+    } else if (arg === "--prepare") {
+      prepare = true;
+    } else if (arg === "--finalize") {
+      finalize = true;
     } else if (!arg.startsWith("-")) {
       name = arg;
     } else {
@@ -107,7 +117,13 @@ function parseArgs(): UpgradeArgs {
     }
   }
 
-  return { name, version };
+  if (prepare && finalize) {
+    console.error("Error: --prepare and --finalize are mutually exclusive.");
+    emitCliError("UNKNOWN", "--prepare and --finalize are mutually exclusive");
+    process.exit(1);
+  }
+
+  return { name, version, prepare, finalize };
 }
 
 function resolveCloud(entry: AssistantEntry): string {
@@ -171,12 +187,32 @@ async function upgradeDocker(
 ): Promise<void> {
   const instanceName = entry.assistantId;
   const res = dockerResourceNames(instanceName);
-  const workspaceDir = entry.resources
-    ? join(entry.resources.instanceDir, ".vellum", "workspace")
-    : null;
 
   const versionTag =
     version ?? (cliPkg.version ? `v${cliPkg.version}` : "latest");
+
+  // Reject downgrades — `vellum upgrade` only handles forward version changes.
+  // Users should use `vellum rollback --version <version>` for downgrades.
+  const currentVersion = entry.serviceGroupVersion;
+  if (currentVersion && versionTag) {
+    const current = parseVersion(currentVersion);
+    const target = parseVersion(versionTag);
+    if (current && target) {
+      const isOlder =
+        target.major < current.major ||
+        (target.major === current.major && target.minor < current.minor) ||
+        (target.major === current.major &&
+          target.minor === current.minor &&
+          target.patch < current.patch);
+      if (isOlder) {
+        const msg = `Cannot upgrade to an older version (${versionTag} < ${currentVersion}). Use \`vellum rollback --version ${versionTag}\` instead.`;
+        console.error(msg);
+        emitCliError("VERSION_DIRECTION", msg);
+        process.exit(1);
+      }
+    }
+  }
+
   console.log("🔍 Resolving image references...");
   const { imageTags } = await resolveImageRefs(versionTag);
 
@@ -223,63 +259,6 @@ async function upgradeDocker(
     // Best-effort — if we can't get migration state, rollback will skip migration reversal
   }
 
-  // Detect if this upgrade is actually a downgrade (user picked an older
-  // version via the version picker). Used after readiness succeeds to align
-  // the DB schema with the now-running old daemon.
-  const currentVersion = entry.serviceGroupVersion;
-  const isDowngrade =
-    currentVersion &&
-    versionTag &&
-    (() => {
-      const current = parseVersion(currentVersion);
-      const target = parseVersion(versionTag);
-      if (!current || !target) return false;
-      if (target.major !== current.major) return target.major < current.major;
-      if (target.minor !== current.minor) return target.minor < current.minor;
-      return target.patch < current.patch;
-    })();
-
-  // For downgrades, fetch the target version's migration ceiling from the
-  // releases API. This tells us exactly which DB migration version and
-  // workspace migration the target version expects, enabling a precise
-  // rollback on the CURRENT (newer) daemon before swapping containers.
-  let targetMigrationCeiling: {
-    dbVersion?: number;
-    workspaceMigrationId?: string;
-  } = {};
-  if (isDowngrade) {
-    try {
-      const platformUrl = getPlatformUrl();
-      const releasesResp = await fetch(
-        `${platformUrl}/v1/releases/?stable=true`,
-        { signal: AbortSignal.timeout(10000) },
-      );
-      if (releasesResp.ok) {
-        const releases = (await releasesResp.json()) as Array<{
-          version: string;
-          db_migration_version?: number | null;
-          last_workspace_migration_id?: string;
-        }>;
-        const normalizedTag = versionTag.replace(/^v/, "");
-        const targetRelease = releases.find(
-          (r) => r.version?.replace(/^v/, "") === normalizedTag,
-        );
-        if (
-          targetRelease?.db_migration_version != null ||
-          targetRelease?.last_workspace_migration_id
-        ) {
-          targetMigrationCeiling = {
-            dbVersion: targetRelease.db_migration_version ?? undefined,
-            workspaceMigrationId:
-              targetRelease.last_workspace_migration_id || undefined,
-          };
-        }
-      }
-    } catch {
-      // Best-effort — fall back to rollbackToRegistryCeiling post-swap
-    }
-  }
-
   // Persist rollback state to lockfile BEFORE any destructive changes.
   // This enables the `vellum rollback` command to restore the previous version.
   if (entry.serviceGroupVersion && entry.containerInfo) {
@@ -295,25 +274,18 @@ async function upgradeDocker(
   }
 
   // Record version transition start in workspace git history
-  if (workspaceDir) {
-    try {
-      await commitWorkspaceState(
-        workspaceDir,
-        buildUpgradeCommitMessage({
-          action: "upgrade",
-          phase: "starting",
-          from: entry.serviceGroupVersion ?? "unknown",
-          to: versionTag,
-          topology: "docker",
-          assistantId: entry.assistantId,
-        }),
-      );
-    } catch (err) {
-      console.warn(
-        `⚠️  Failed to create pre-upgrade workspace commit: ${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
-  }
+  await commitWorkspaceViaGateway(
+    entry.runtimeUrl,
+    entry.assistantId,
+    buildUpgradeCommitMessage({
+      action: "upgrade",
+      phase: "starting",
+      from: entry.serviceGroupVersion ?? "unknown",
+      to: versionTag,
+      topology: "docker",
+      assistantId: entry.assistantId,
+    }),
+  );
 
   console.log("💾 Capturing existing container environment...");
   const capturedEnv = await captureContainerEnv(res.assistantContainer);
@@ -381,16 +353,6 @@ async function upgradeDocker(
   const cesServiceToken =
     capturedEnv["CES_SERVICE_TOKEN"] || randomBytes(32).toString("hex");
 
-  // Retrieve or generate a bootstrap secret for the gateway. The secret was
-  // persisted to disk during hatch; older instances won't have one yet.
-  // This runs BEFORE stopping containers so a write failure (disk full,
-  // permissions) doesn't leave the assistant offline.
-  const loadedSecret = loadBootstrapSecret(instanceName);
-  const bootstrapSecret = loadedSecret || randomBytes(32).toString("hex");
-  if (!loadedSecret) {
-    saveBootstrapSecret(instanceName, bootstrapSecret);
-  }
-
   // Extract or generate the shared JWT signing key. Pre-env-var instances
   // won't have it in capturedEnv, so generate fresh in that case.
   const signingKey =
@@ -434,32 +396,6 @@ async function upgradeDocker(
     buildProgressEvent(UPGRADE_PROGRESS.INSTALLING),
   );
 
-  // If we have the target version's migration ceiling, run a PRECISE
-  // rollback on the CURRENT (newer) daemon before stopping it. The current
-  // daemon has the `down()` code for all migrations it applied, so it can
-  // cleanly revert to the target version's ceiling. This is critical for
-  // multi-version downgrades where the old daemon wouldn't know about
-  // migrations introduced after its release.
-  let preSwapRollbackOk = true;
-  if (
-    isDowngrade &&
-    (targetMigrationCeiling.dbVersion !== undefined ||
-      targetMigrationCeiling.workspaceMigrationId !== undefined)
-  ) {
-    console.log("🔄 Reverting database changes for downgrade...");
-    await broadcastUpgradeEvent(
-      entry.runtimeUrl,
-      entry.assistantId,
-      buildProgressEvent(UPGRADE_PROGRESS.REVERTING_MIGRATIONS),
-    );
-    preSwapRollbackOk = await rollbackMigrations(
-      entry.runtimeUrl,
-      entry.assistantId,
-      targetMigrationCeiling.dbVersion,
-      targetMigrationCeiling.workspaceMigrationId,
-    );
-  }
-
   console.log("🛑 Stopping existing containers...");
   await stopContainers(res);
   console.log("✅ Containers stopped\n");
@@ -491,7 +427,6 @@ async function upgradeDocker(
   await startContainers(
     {
       signingKey,
-      bootstrapSecret,
       cesServiceToken,
       extraAssistantEnv,
       gatewayPort,
@@ -529,27 +464,6 @@ async function upgradeDocker(
     };
     saveAssistantEntry(updatedEntry);
 
-    // After a downgrade, fall back to asking the now-running old daemon
-    // to roll back migrations above its own registry ceiling when either:
-    // (a) no release metadata was available for a precise pre-swap rollback, or
-    // (b) the precise pre-swap rollback failed (timeout, daemon crash, etc.).
-    // This is a no-op for multi-version jumps where the old daemon doesn't
-    // know about the newer migrations, but correct for single-step rollbacks.
-    if (
-      isDowngrade &&
-      (!preSwapRollbackOk ||
-        (targetMigrationCeiling.dbVersion === undefined &&
-          targetMigrationCeiling.workspaceMigrationId === undefined))
-    ) {
-      await rollbackMigrations(
-        entry.runtimeUrl,
-        entry.assistantId,
-        undefined,
-        undefined,
-        true,
-      );
-    }
-
     // Notify clients on the new service group that the upgrade succeeded.
     await broadcastUpgradeEvent(
       entry.runtimeUrl,
@@ -558,26 +472,19 @@ async function upgradeDocker(
     );
 
     // Record successful upgrade in workspace git history
-    if (workspaceDir) {
-      try {
-        await commitWorkspaceState(
-          workspaceDir,
-          buildUpgradeCommitMessage({
-            action: "upgrade",
-            phase: "complete",
-            from: entry.serviceGroupVersion ?? "unknown",
-            to: versionTag,
-            topology: "docker",
-            assistantId: entry.assistantId,
-            result: "success",
-          }),
-        );
-      } catch (err) {
-        console.warn(
-          `⚠️  Failed to create post-upgrade workspace commit: ${err instanceof Error ? err.message : String(err)}`,
-        );
-      }
-    }
+    await commitWorkspaceViaGateway(
+      entry.runtimeUrl,
+      entry.assistantId,
+      buildUpgradeCommitMessage({
+        action: "upgrade",
+        phase: "complete",
+        from: entry.serviceGroupVersion ?? "unknown",
+        to: versionTag,
+        topology: "docker",
+        assistantId: entry.assistantId,
+        result: "success",
+      }),
+    );
 
     console.log(
       `\n✅ Docker assistant '${instanceName}' upgraded to ${versionTag}.`,
@@ -621,7 +528,6 @@ async function upgradeDocker(
         await startContainers(
           {
             signingKey,
-            bootstrapSecret,
             cesServiceToken,
             extraAssistantEnv,
             gatewayPort,
@@ -785,28 +691,28 @@ async function upgradePlatform(
   entry: AssistantEntry,
   version: string | null,
 ): Promise<void> {
-  const workspaceDir = entry.resources
-    ? join(entry.resources.instanceDir, ".vellum", "workspace")
-    : null;
-
-  // Record version transition start in workspace git history
-  if (workspaceDir) {
-    try {
-      await commitWorkspaceState(
-        workspaceDir,
-        buildUpgradeCommitMessage({
-          action: "upgrade",
-          phase: "starting",
-          from: entry.serviceGroupVersion ?? "unknown",
-          to: version ?? "latest",
-          topology: "managed",
-          assistantId: entry.assistantId,
-        }),
-      );
-    } catch (err) {
-      console.warn(
-        `⚠️  Failed to create pre-upgrade workspace commit: ${err instanceof Error ? err.message : String(err)}`,
-      );
+  // Reject downgrades — `vellum upgrade` only handles forward version changes.
+  // Users should use `vellum rollback --version <version>` for downgrades.
+  // Only enforce this guard when the user explicitly passed `--version`.
+  // When version is null the platform API decides the actual target, so
+  // we must not block the request based on the local CLI version.
+  const currentVersion = entry.serviceGroupVersion;
+  if (version && currentVersion) {
+    const current = parseVersion(currentVersion);
+    const target = parseVersion(version);
+    if (current && target) {
+      const isOlder =
+        target.major < current.major ||
+        (target.major === current.major && target.minor < current.minor) ||
+        (target.major === current.major &&
+          target.minor === current.minor &&
+          target.patch < current.patch);
+      if (isOlder) {
+        const msg = `Cannot upgrade to an older version (${version} < ${currentVersion}). Use \`vellum rollback --version ${version}\` instead.`;
+        console.error(msg);
+        emitCliError("VERSION_DIRECTION", msg);
+        process.exit(1);
+      }
     }
   }
 
@@ -833,15 +739,6 @@ async function upgradePlatform(
     body.version = version;
   }
 
-  // Notify connected clients that an upgrade is about to begin.
-  const targetVersion = version ?? `v${cliPkg.version}`;
-  console.log("📢 Notifying connected clients...");
-  await broadcastUpgradeEvent(
-    entry.runtimeUrl,
-    entry.assistantId,
-    buildStartingEvent(targetVersion, 90),
-  );
-
   const response = await fetch(url, {
     method: "POST",
     headers: {
@@ -879,37 +776,124 @@ async function upgradePlatform(
   // version-change detection (DaemonConnection.swift) once the new
   // version actually appears after the platform restarts the service group.
 
-  // Record successful upgrade in workspace git history
-  if (workspaceDir) {
-    try {
-      await commitWorkspaceState(
-        workspaceDir,
-        buildUpgradeCommitMessage({
-          action: "upgrade",
-          phase: "complete",
-          from: entry.serviceGroupVersion ?? "unknown",
-          to: version ?? "latest",
-          topology: "managed",
-          assistantId: entry.assistantId,
-          result: "success",
-        }),
-      );
-    } catch (err) {
-      console.warn(
-        `⚠️  Failed to create post-upgrade workspace commit: ${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
-  }
-
   console.log(`✅ ${result.detail}`);
   if (result.version) {
     console.log(`   Version: ${result.version}`);
   }
 }
 
+/**
+ * Pre-upgrade steps for Sparkle (macOS app) lifecycle.
+ * Runs the pre-update orchestration without actually swapping containers:
+ * broadcasts SSE events, creates a workspace commit, creates a backup,
+ * prunes old backups, and outputs the backup path.
+ */
+async function upgradePrepare(
+  entry: AssistantEntry,
+  version: string | null,
+): Promise<void> {
+  const targetVersion = version ?? entry.serviceGroupVersion ?? "unknown";
+  const currentVersion = entry.serviceGroupVersion ?? "unknown";
+
+  // 1. Broadcast "starting" so the UI shows the progress spinner
+  await broadcastUpgradeEvent(
+    entry.runtimeUrl,
+    entry.assistantId,
+    buildStartingEvent(targetVersion, 30),
+  );
+
+  // 2. Workspace commit: record pre-update state
+  await commitWorkspaceViaGateway(
+    entry.runtimeUrl,
+    entry.assistantId,
+    `[sparkle-update] Starting: ${currentVersion} → ${targetVersion}`,
+  );
+
+  // 3. Progress: saving backup
+  await broadcastUpgradeEvent(
+    entry.runtimeUrl,
+    entry.assistantId,
+    buildProgressEvent("Saving a backup of your data…"),
+  );
+
+  // 4. Create backup
+  const backupPath = await createBackup(entry.runtimeUrl, entry.assistantId, {
+    prefix: `${entry.assistantId}-pre-upgrade`,
+    description: `Pre-upgrade snapshot before ${currentVersion} → ${targetVersion}`,
+  });
+
+  // 5. Prune old backups (keep 3)
+  if (backupPath) {
+    pruneOldBackups(entry.assistantId, 3);
+  }
+
+  // 6. Progress: installing update
+  await broadcastUpgradeEvent(
+    entry.runtimeUrl,
+    entry.assistantId,
+    buildProgressEvent(UPGRADE_PROGRESS.INSTALLING),
+  );
+
+  // 7. Output backup path to stdout for the macOS app to parse
+  if (backupPath) {
+    console.log(`BACKUP_PATH:${backupPath}`);
+  }
+}
+
+/**
+ * Post-upgrade steps for Sparkle (macOS app) lifecycle.
+ * Called after the app has been replaced and the daemon is back up.
+ * Broadcasts a "complete" SSE event and creates a workspace commit.
+ */
+async function upgradeFinalize(
+  entry: AssistantEntry,
+  version: string | null,
+): Promise<void> {
+  if (!version) {
+    console.error(
+      "Error: --finalize requires --version <from-version> to record the transition.",
+    );
+    emitCliError(
+      "UNKNOWN",
+      "--finalize requires --version <from-version> to record the transition",
+    );
+    process.exit(1);
+  }
+
+  const fromVersion = version;
+  const currentVersion = cliPkg.version
+    ? `v${cliPkg.version}`
+    : (entry.serviceGroupVersion ?? "unknown");
+
+  // 1. Broadcast "complete" so the UI clears the progress spinner
+  await broadcastUpgradeEvent(
+    entry.runtimeUrl,
+    entry.assistantId,
+    buildCompleteEvent(currentVersion, true),
+  );
+
+  // 2. Workspace commit: record successful update
+  await commitWorkspaceViaGateway(
+    entry.runtimeUrl,
+    entry.assistantId,
+    `[sparkle-update] Complete: ${fromVersion} → ${currentVersion}\n\nresult: success`,
+  );
+}
+
 export async function upgrade(): Promise<void> {
-  const { name, version } = parseArgs();
+  const { name, version, prepare, finalize } = parseArgs();
   const entry = resolveTargetAssistant(name);
+
+  if (prepare) {
+    await upgradePrepare(entry, version);
+    return;
+  }
+
+  if (finalize) {
+    await upgradeFinalize(entry, version);
+    return;
+  }
+
   const cloud = resolveCloud(entry);
 
   try {

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/aws.ts

@@ -443,14 +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",
-      configValues,
-    );
+    const { script: startupScript, laptopBootstrapSecret } =
+      await buildStartupScript(
+        species,
+        sshUser,
+        providerApiKeys,
+        instanceName,
+        "aws",
+        configValues,
+      );
     const startupScriptPath = join(tmpdir(), `${instanceName}-startup.sh`);
     writeFileSync(startupScriptPath, startupScript);
 
@@ -539,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/cli-error.ts

@@ -11,9 +11,11 @@
 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"