@vellumai/cli 0.8.11 → 0.8.12-dev.202606122337.5897832

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/upgrade-lifecycle.ts

@@ -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;
 }

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.

package/src/lib/workos-pkce.ts

@@ -0,0 +1,160 @@
+/**
+ * App-held PKCE login against WorkOS User Management (RFC 8252 loopback).
+ */
+
+import crypto from "node:crypto";
+
+import { loopbackSafeFetch } from "./loopback-fetch.js";
+
+const WORKOS_API_BASE_URL = "https://api.workos.com";
+const PROVIDER_ID = "workos";
+const SCOPE = "openid profile email";
+
+// Use a loopback callback: `http://127.0.0.1:*/auth/callback`
+export const CALLBACK_PATH = "/auth/callback";
+
+export interface PkcePair {
+  verifier: string;
+  challenge: string;
+}
+
+export function generatePkcePair(): PkcePair {
+  const verifier = crypto.randomBytes(32).toString("base64url");
+  const challenge = crypto
+    .createHash("sha256")
+    .update(verifier)
+    .digest("base64url");
+  return { verifier, challenge };
+}
+
+export interface AuthorizeUrlOptions {
+  clientId: string;
+  redirectUri: string;
+  challenge: string;
+  state: string;
+  loginHint?: string;
+  providerHint?: string;
+}
+
+export function buildAuthorizeUrl(options: AuthorizeUrlOptions): string {
+  const url = new URL("/user_management/authorize", WORKOS_API_BASE_URL);
+  url.searchParams.set("client_id", options.clientId);
+  url.searchParams.set("redirect_uri", options.redirectUri);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("scope", SCOPE);
+  url.searchParams.set("code_challenge", options.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", options.state);
+  // No `prompt`: lets the browser's existing IdP session be reused.
+  url.searchParams.set("provider", options.providerHint || "authkit");
+  if (options.loginHint) url.searchParams.set("login_hint", options.loginHint);
+  return url.toString();
+}
+
+interface HeadlessProviderEntry {
+  id: string;
+  name?: string;
+  client_id?: string;
+  flows?: string[];
+  openid_configuration_url?: string;
+}
+
+/**
+ * Pick the OAuth2 WorkOS provider from the headless config. During the
+ * coexistence window two entries share the "workos-oidc" id; the usable one
+ * has token auth and no OIDC discovery URL. Null if none.
+ */
+export function selectWorkosClientId(
+  providers: HeadlessProviderEntry[],
+): string | null {
+  const entry = providers.find(
+    (p) =>
+      !p.openid_configuration_url &&
+      (p.flows ?? []).includes("provider_token") &&
+      typeof p.client_id === "string",
+  );
+  return entry?.client_id ?? null;
+}
+
+export async function fetchWorkosClientId(
+  platformUrl: string,
+): Promise<string> {
+  const url = `${new URL(platformUrl).origin}/_allauth/app/v1/config`;
+  const response = await loopbackSafeFetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch auth config (${response.status})`);
+  }
+  const body = (await response.json()) as {
+    data?: { socialaccount?: { providers?: HeadlessProviderEntry[] } };
+  };
+  const clientId = selectWorkosClientId(
+    body.data?.socialaccount?.providers ?? [],
+  );
+  if (!clientId) {
+    throw new Error(
+      "Platform does not advertise a token-auth WorkOS provider; cannot start PKCE login.",
+    );
+  }
+  return clientId;
+}
+
+/** Exchange the authorization code at WorkOS as a public client. */
+export async function exchangeCodeWithWorkos(options: {
+  clientId: string;
+  code: string;
+  verifier: string;
+}): Promise<string> {
+  const response = await loopbackSafeFetch(
+    `${WORKOS_API_BASE_URL}/user_management/authenticate`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        client_id: options.clientId,
+        grant_type: "authorization_code",
+        code: options.code,
+        code_verifier: options.verifier,
+      }),
+    },
+  );
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(
+      `WorkOS code exchange failed (${response.status}): ${body}`,
+    );
+  }
+  const data = (await response.json()) as { access_token?: string };
+  if (!data.access_token) {
+    throw new Error("WorkOS code exchange returned no access token.");
+  }
+  return data.access_token;
+}
+
+/** Exchange the WorkOS access token for a platform session token. */
+export async function exchangeAccessTokenForSession(
+  platformUrl: string,
+  clientId: string,
+  accessToken: string,
+): Promise<string> {
+  const url = `${new URL(platformUrl).origin}/_allauth/app/v1/auth/provider/token`;
+  const response = await loopbackSafeFetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      provider: PROVIDER_ID,
+      process: "login",
+      token: { client_id: clientId, access_token: accessToken },
+    }),
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Session exchange failed (${response.status}): ${body}`);
+  }
+  const data = (await response.json()) as {
+    meta?: { session_token?: string };
+  };
+  if (!data.meta?.session_token) {
+    throw new Error("Session exchange returned no session token.");
+  }
+  return data.meta.session_token;
+}