@vellumai/cli 0.8.11-staging.1 → 0.8.12-staging.1

package/src/lib/platform-releases.ts

@@ -2,142 +2,164 @@ import { getPlatformUrl } from "./platform-client.js";
 import { DOCKERHUB_IMAGES } from "./docker.js";
 import type { ServiceName } from "./docker.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
+import { stripVersionPrefix } from "./version-compat.js";
 
 export interface ResolvedImageRefs {
   imageTags: Record<ServiceName, string>;
   source: "platform" | "dockerhub";
 }
 
+export interface ReleaseListItem {
+  version: string;
+  is_stable?: boolean;
+  assistant_image_ref?: string | null;
+  gateway_image_ref?: string | null;
+  credential_executor_image_ref?: string | null;
+}
+
 /**
- * Fetch the latest stable release version from the platform API.
- * Returns the version string (e.g. "0.7.0") or null if unavailable.
- * The releases endpoint returns entries ordered newest-first.
+ * The endpoint defaults `limit` to 10, which is too few to validate an
+ * explicit --version against ("absent from the list" is treated as a hard
+ * error) — always request the documented maximum.
  */
-export async function fetchLatestStableVersion(): Promise<string | null> {
+const RELEASES_FETCH_LIMIT = 100;
+
+/**
+ * Fetch the releases list from the platform API, optionally filtered by
+ * channel (the `channel` param takes precedence over `stable` server-side).
+ * `platformUrl` overrides the lockfile/env-resolved default — pass the
+ * target assistant's platform URL when it may differ from the active one.
+ * Returns `null` when the platform is unreachable or responds non-OK —
+ * distinct from `[]` (platform answered, no releases).
+ */
+export async function fetchReleases(opts?: {
+  channel?: "stable" | "preview";
+  platformUrl?: string;
+}): Promise<ReleaseListItem[] | null> {
   try {
-    const platformUrl = getPlatformUrl();
-    const response = await loopbackSafeFetch(`${platformUrl}/v1/releases/?stable=true`, {
-      signal: AbortSignal.timeout(10_000),
-    });
+    const platformUrl = opts?.platformUrl || getPlatformUrl();
+    const filter = opts?.channel ? `channel=${opts.channel}` : "stable=true";
+    const response = await loopbackSafeFetch(
+      `${platformUrl}/v1/releases/?${filter}&limit=${RELEASES_FETCH_LIMIT}`,
+      { signal: AbortSignal.timeout(10_000) },
+    );
     if (!response.ok) return null;
-
-    const releases = (await response.json()) as Array<{
-      version?: string;
-    }>;
-    const first = releases[0];
-    return first?.version ?? null;
+    return (await response.json()) as ReleaseListItem[];
   } catch {
     return null;
   }
 }
 
 /**
- * Resolve image references for a given version.
+ * Fetch the latest stable release version from the platform API.
+ * Returns the version string (e.g. "0.7.0") or null if unavailable.
+ * The releases endpoint returns entries ordered newest-first.
+ */
+export async function fetchLatestStableVersion(): Promise<string | null> {
+  const releases = await fetchReleases();
+  return releases?.[0]?.version ?? null;
+}
+
+export type ImageRefResolution =
+  | { status: "platform"; imageTags: Record<ServiceName, string> }
+  | { status: "dockerhub-fallback"; imageTags: Record<ServiceName, string> }
+  | { status: "version-not-found" };
+
+function dockerhubImageTags(version: string): Record<ServiceName, string> {
+  return {
+    assistant: `${DOCKERHUB_IMAGES.assistant}:${version}`,
+    "credential-executor": `${DOCKERHUB_IMAGES["credential-executor"]}:${version}`,
+    gateway: `${DOCKERHUB_IMAGES.gateway}:${version}`,
+  };
+}
+
+/**
+ * Resolve image references for a given version, distinguishing why the
+ * platform refs were unavailable:
  *
- * Tries the platform API first (returns GCR digest-based refs when available),
- * then falls back to DockerHub tag-based refs when the platform is unreachable
- * or the version is not found.
+ *   - `platform` — release found; GCR digest-based refs (credential-executor
+ *     falls back to DockerHub per-service when its ref is null).
+ *   - `dockerhub-fallback` — platform unreachable or responded non-OK;
+ *     tag-based DockerHub refs.
+ *   - `version-not-found` — the platform answered but the version is absent
+ *     from the releases list (likely a typo'd --version).
  */
-export async function resolveImageRefs(
+export async function resolveImageRefsDetailed(
   version: string,
   log?: (msg: string) => void,
-): Promise<ResolvedImageRefs> {
+): Promise<ImageRefResolution> {
   log?.("Resolving image references...");
 
-  const platformRefs = await fetchPlatformImageRefs(version, log);
-  if (platformRefs) {
-    log?.("Resolved image refs from platform API");
+  const releases = await fetchReleases();
+  if (releases === null) {
+    log?.("Platform unreachable — falling back to DockerHub tags");
     return {
-      imageTags: platformRefs.imageTags,
-      source: "platform",
+      status: "dockerhub-fallback",
+      imageTags: dockerhubImageTags(version),
     };
   }
 
-  log?.("Falling back to DockerHub tags");
-  const imageTags: Record<ServiceName, string> = {
-    assistant: `${DOCKERHUB_IMAGES.assistant}:${version}`,
-    "credential-executor": `${DOCKERHUB_IMAGES["credential-executor"]}:${version}`,
-    gateway: `${DOCKERHUB_IMAGES.gateway}:${version}`,
+  const normalizedVersion = stripVersionPrefix(version);
+  const release = releases.find(
+    (r) => stripVersionPrefix(r.version ?? "") === normalizedVersion,
+  );
+
+  if (!release) {
+    log?.(`Version ${version} not found in platform releases`);
+    return { status: "version-not-found" };
+  }
+
+  const assistantImage = release.assistant_image_ref;
+  const gatewayImage = release.gateway_image_ref;
+  let credentialExecutorImage = release.credential_executor_image_ref;
+
+  // Assistant and gateway images are required; a release missing them is a
+  // platform data gap, not a user typo — fall back to DockerHub tags.
+  if (!assistantImage || !gatewayImage) {
+    log?.("Platform release missing required image refs");
+    return {
+      status: "dockerhub-fallback",
+      imageTags: dockerhubImageTags(version),
+    };
+  }
+
+  if (!credentialExecutorImage) {
+    credentialExecutorImage = `${DOCKERHUB_IMAGES["credential-executor"]}:${version}`;
+    log?.(
+      "credential-executor image not in platform release, using DockerHub fallback",
+    );
+  }
+
+  return {
+    status: "platform",
+    imageTags: {
+      assistant: assistantImage,
+      "credential-executor": credentialExecutorImage,
+      gateway: gatewayImage,
+    },
   };
-  return { imageTags, source: "dockerhub" };
 }
 
 /**
- * Fetch image references from the platform releases API.
+ * Resolve image references for a given version.
  *
- * Returns a record of service name to image ref (GCR digest-based) for the
- * given version, or null if the platform is unreachable, the version is not
- * found, or any error occurs.
+ * Lenient wrapper around {@link resolveImageRefsDetailed}: maps
+ * `version-not-found` to the DockerHub fallback so existing callers
+ * (start flows, docker rollback) keep their permissive behavior. The
+ * upgrade command uses the detailed variant to fail fast on typos.
  */
-async function fetchPlatformImageRefs(
+export async function resolveImageRefs(
   version: string,
   log?: (msg: string) => void,
-): Promise<{
-  imageTags: Record<ServiceName, string>;
-} | null> {
-  try {
-    const platformUrl = getPlatformUrl();
-    const url = `${platformUrl}/v1/releases/?stable=true`;
-
-    log?.(`Fetching releases from ${url}`);
-
-    const response = await loopbackSafeFetch(url, {
-      signal: AbortSignal.timeout(10_000),
-    });
-
-    if (!response.ok) {
-      log?.(`Platform API returned ${response.status}`);
-      return null;
-    }
-
-    const releases = (await response.json()) as Array<{
-      version?: string;
-      assistant_image_ref?: string | null;
-      gateway_image_ref?: string | null;
-      credential_executor_image_ref?: string | null;
-    }>;
-
-    // Strip leading "v" from the requested version for matching
-    const normalizedVersion = version.replace(/^v/, "");
-
-    const release = releases.find((r) => {
-      const releaseVersion = (r.version ?? "").replace(/^v/, "");
-      return releaseVersion === normalizedVersion;
-    });
-
-    if (!release) {
-      log?.(`Version ${version} not found in platform releases`);
-      return null;
-    }
-
-    const assistantImage = release.assistant_image_ref;
-    const gatewayImage = release.gateway_image_ref;
-    let credentialExecutorImage = release.credential_executor_image_ref;
-
-    // Assistant and gateway images are required; credential-executor falls back to DockerHub
-    if (!assistantImage || !gatewayImage) {
-      log?.("Platform release missing required image refs");
-      return null;
-    }
-
-    // Fall back to DockerHub for credential-executor if its image ref is null
-    if (!credentialExecutorImage) {
-      credentialExecutorImage = `${DOCKERHUB_IMAGES["credential-executor"]}:${version}`;
-      log?.(
-        "credential-executor image not in platform release, using DockerHub fallback",
-      );
-    }
-
-    return {
-      imageTags: {
-        assistant: assistantImage,
-        "credential-executor": credentialExecutorImage,
-        gateway: gatewayImage,
-      },
-    };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    log?.(`Platform image ref resolution failed: ${message}`);
-    return null;
+): Promise<ResolvedImageRefs> {
+  const resolution = await resolveImageRefsDetailed(version, log);
+  if (resolution.status === "platform") {
+    log?.("Resolved image refs from platform API");
+    return { imageTags: resolution.imageTags, source: "platform" };
+  }
+  if (resolution.status === "version-not-found") {
+    log?.("Falling back to DockerHub tags");
+    return { imageTags: dockerhubImageTags(version), source: "dockerhub" };
   }
+  return { imageTags: resolution.imageTags, source: "dockerhub" };
 }

package/src/lib/sync-cloud-assistants.ts

@@ -15,6 +15,7 @@
 
 import {
   loadAllAssistants,
+  normalizeVersion,
   removeAssistantEntry,
   saveAssistantEntry,
 } from "./assistant-config.js";
@@ -22,6 +23,7 @@ import {
   fetchCurrentUser,
   fetchPlatformAssistants,
   getPlatformUrl,
+  type HatchedAssistant,
 } from "./platform-client.js";
 
 export type SyncLogger = (message: string) => void;
@@ -82,7 +84,7 @@ export async function syncCloudAssistants(
     }
   }
 
-  let platformAssistants: { id: string; name: string; status: string }[];
+  let platformAssistants: HatchedAssistant[];
   try {
     log?.("Fetching platform assistants…");
     platformAssistants = await fetchPlatformAssistants(token);
@@ -126,22 +128,33 @@ export async function syncCloudAssistants(
     const existing = existingCloudById.get(pa.id);
     const assistantName = pa.name.trim();
     const nameFields = assistantName ? { name: assistantName } : {};
+    // undefined when the platform reports no release — written through on
+    // update so a stale cached version is cleared, not preserved.
+    const version =
+      pa.current_release_version != null
+        ? normalizeVersion(pa.current_release_version)
+        : undefined;
     if (!existing) {
       log?.(`Adding ${pa.name || pa.id} to lockfile`);
       saveAssistantEntry({
         assistantId: pa.id,
         ...nameFields,
+        ...(version && { version }),
         runtimeUrl: getPlatformUrl(),
         cloud: "vellum",
         species: "vellum",
         hatchedAt: new Date().toISOString(),
       });
       added++;
-    } else if (assistantName && existing.name !== assistantName) {
-      log?.(`Updating ${pa.id} name to ${assistantName}`);
+    } else if (
+      (assistantName && existing.name !== assistantName) ||
+      existing.version !== version
+    ) {
+      log?.(`Updating ${pa.id} from platform`);
       saveAssistantEntry({
         ...existing,
-        name: assistantName,
+        ...nameFields,
+        version,
       });
       updated++;
     }

package/src/lib/upgrade-lifecycle.ts

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
 
 import type { AssistantEntry } from "./assistant-config.js";
-import { saveAssistantEntry } from "./assistant-config.js";
+import { normalizeVersion, saveAssistantEntry } from "./assistant-config.js";
 import { createBackup, pruneOldBackups, restoreBackup } from "./backup-ops.js";
 import { emitCliError } from "./cli-error.js";
 import { getOrCreateHostDeviceId } from "./device-id.js";
@@ -19,14 +19,14 @@ import {
 import { getStateDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 import { loadGuardianToken } from "./guardian-token.js";
-import { resolveImageRefs } from "./platform-releases.js";
+import { fetchReleases, resolveImageRefs } from "./platform-releases.js";
 import {
   getBuilderManagedEnvKeys,
   type DockerStatefulSetSpec,
   type ServiceName,
 } from "./statefulset.js";
 import { exec, execOutput } from "./step-runner.js";
-import { compareVersions } from "./version-compat.js";
+import { compareVersions, stripVersionPrefix } from "./version-compat.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 // ---------------------------------------------------------------------------
@@ -339,27 +339,18 @@ export async function fetchPreviousVersion(
 
   // 2. Derive from releases list
   if (!currentVersion) return undefined;
-  try {
-    const { getPlatformUrl } = await import("./platform-client.js");
-    const platformUrl = getPlatformUrl();
-    const resp = await loopbackSafeFetch(`${platformUrl}/v1/releases/?stable=true`, {
-      signal: AbortSignal.timeout(10_000),
-    });
-    if (!resp.ok) return undefined;
+  const releases = await fetchReleases();
+  if (!releases) return undefined;
 
-    const releases = (await resp.json()) as Array<{ version?: string }>;
-    const normalizedCurrent = currentVersion.replace(/^v/, "");
+  const normalizedCurrent = stripVersionPrefix(currentVersion);
 
-    // Releases are ordered newest-first; find the entry right after the
-    // current version (i.e. the one that was running before the upgrade).
-    const idx = releases.findIndex(
-      (r) => (r.version ?? "").replace(/^v/, "") === normalizedCurrent,
-    );
-    if (idx >= 0 && idx + 1 < releases.length) {
-      return releases[idx + 1].version;
-    }
-  } catch {
-    // Best-effort
+  // Releases are ordered newest-first; find the entry right after the
+  // current version (i.e. the one that was running before the upgrade).
+  const idx = releases.findIndex(
+    (r) => stripVersionPrefix(r.version ?? "") === normalizedCurrent,
+  );
+  if (idx >= 0 && idx + 1 < releases.length) {
+    return releases[idx + 1].version;
   }
   return undefined;
 }
@@ -788,6 +779,7 @@ export async function performDockerRollback(
       previousContainerInfo: entry.containerInfo,
       previousDbMigrationVersion: preMigrationState.dbVersion,
       previousWorkspaceMigrationId: preMigrationState.lastWorkspaceMigrationId,
+      version: normalizeVersion(targetVersion),
       preUpgradeBackupPath: undefined,
     };
     saveAssistantEntry(updatedEntry);

package/src/lib/upgrade-preflight.ts

@@ -0,0 +1,127 @@
+import type { ReleaseListItem } from "./platform-releases.js";
+import { compareVersions, versionsEqual } from "./version-compat.js";
+
+export interface UpgradeTargetResolution {
+  kind: "ok" | "version-not-found" | "no-releases";
+  /** Resolved target version (kind "ok" only). */
+  target: string | null;
+  /** compareVersions(target, current); null when either side is unknown/unparseable. */
+  comparison: number | null;
+  isNoOp: boolean;
+  isDowngrade: boolean;
+}
+
+/**
+ * Resolve the upgrade target version from the releases list and compare it
+ * against the running version. Pure — callers fetch releases/current first.
+ *
+ * - An explicit version is validated against the releases list when one is
+ *   available (`releases !== null`); absent from the list → "version-not-found".
+ * - No explicit version → latest release, skipping non-stable heads
+ *   (mirrors the web UI: `releases.find(r => r.is_stable !== false) ?? releases[0]`).
+ * - `releases === null` (platform unreachable) with an explicit version
+ *   trusts the explicit version; without one → "no-releases".
+ */
+export function resolveUpgradeTarget(args: {
+  explicitVersion: string | null;
+  releases: ReleaseListItem[] | null;
+  currentVersion: string | undefined;
+}): UpgradeTargetResolution {
+  const { explicitVersion, releases, currentVersion } = args;
+
+  let target: string | null = null;
+  if (explicitVersion) {
+    if (releases !== null) {
+      const found = releases.find((r) =>
+        versionsEqual(r.version ?? "", explicitVersion),
+      );
+      if (!found) {
+        return {
+          kind: "version-not-found",
+          target: null,
+          comparison: null,
+          isNoOp: false,
+          isDowngrade: false,
+        };
+      }
+    }
+    target = explicitVersion;
+  } else {
+    if (releases === null || releases.length === 0) {
+      return {
+        kind: "no-releases",
+        target: null,
+        comparison: null,
+        isNoOp: false,
+        isDowngrade: false,
+      };
+    }
+    target =
+      (releases.find((r) => r.is_stable !== false) ?? releases[0]).version;
+  }
+
+  const comparison = currentVersion
+    ? compareVersions(target, currentVersion)
+    : null;
+  const isNoOp = currentVersion
+    ? versionsEqual(target, currentVersion)
+    : false;
+
+  return {
+    kind: "ok",
+    target,
+    comparison,
+    isNoOp,
+    isDowngrade: comparison !== null && comparison < 0,
+  };
+}
+
+export interface UpgradePollState {
+  /** Resolved target; null when the server resolved "latest" without reporting it. */
+  targetVersion: string | null;
+  /** Version observed before the upgrade was triggered. */
+  initialVersion: string | null;
+  /** Latest current_release_version from the assistant detail endpoint. */
+  observedVersion: string | null;
+  /** Latest upgrade-status in_progress; null when the endpoint is unavailable. */
+  inProgress: boolean | null;
+  /** Whether in_progress === true was ever observed during this poll. */
+  sawInProgress: boolean;
+}
+
+/**
+ * Completion predicate for the platform upgrade poll loop. Pure.
+ *
+ * The primary signal is the DB-backed `current_release_version` (works while
+ * the service group restarts or the assistant sleeps); the upgrade-status
+ * lock is secondary, used only when the target version is unknown.
+ */
+export function evaluateUpgradePoll(
+  state: UpgradePollState,
+): "pending" | "complete" {
+  const { targetVersion, initialVersion, observedVersion, inProgress, sawInProgress } =
+    state;
+
+  if (targetVersion) {
+    return observedVersion && versionsEqual(observedVersion, targetVersion)
+      ? "complete"
+      : "pending";
+  }
+
+  // Target unknown: a version change from the pre-upgrade value is
+  // definitive on its own — the upgrade can finish before the first poll,
+  // leaving in_progress false without sawInProgress ever being set.
+  if (
+    observedVersion &&
+    initialVersion &&
+    !versionsEqual(observedVersion, initialVersion)
+  ) {
+    return "complete";
+  }
+
+  // Otherwise rely on the in-progress lock releasing (e.g. when the
+  // pre-upgrade version was unknown).
+  if (sawInProgress && inProgress === false) return "complete";
+
+  return "pending";
+}

package/src/lib/version-compat.ts

@@ -86,6 +86,24 @@ export function compareVersions(a: string, b: string): number | null {
   return comparePreRelease(pa.pre!, pb.pre!);
 }
 
+/**
+ * Strip an optional leading `v`/`V` prefix: "v0.7.0" → "0.7.0".
+ */
+export function stripVersionPrefix(version: string): string {
+  return version.replace(/^[vV]/, "");
+}
+
+/**
+ * Check whether two version strings refer to the same version.
+ * Compares via semver when both parse; falls back to prefix-stripped
+ * string equality when either is unparseable.
+ */
+export function versionsEqual(a: string, b: string): boolean {
+  const cmp = compareVersions(a, b);
+  if (cmp !== null) return cmp === 0;
+  return stripVersionPrefix(a) === stripVersionPrefix(b);
+}
+
 /**
  * Check whether two version strings are compatible.
  * Compatibility requires matching major AND minor versions.