@vellumai/cli 0.5.6 → 0.5.7

package/src/lib/local.ts

@@ -192,10 +192,15 @@ function resolveDaemonMainPath(assistantIndex: string): string {
   return join(dirname(assistantIndex), "daemon", "main.ts");
 }
 
+type DaemonStartOptions = {
+  foreground?: boolean;
+  defaultWorkspaceConfigPath?: string;
+};
+
 async function startDaemonFromSource(
   assistantIndex: string,
   resources: LocalInstanceResources,
-  options?: { foreground?: boolean },
+  options?: DaemonStartOptions,
 ): Promise<void> {
   const foreground = options?.foreground ?? false;
   const daemonMainPath = resolveDaemonMainPath(assistantIndex);
@@ -260,6 +265,7 @@ async function startDaemonFromSource(
   const env: Record<string, string | undefined> = {
     ...process.env,
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
+    VELLUM_CLOUD: "local",
   };
   if (resources) {
     env.BASE_DATA_DIR = resources.instanceDir;
@@ -268,6 +274,10 @@ async function startDaemonFromSource(
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
     delete env.QDRANT_URL;
   }
+  if (options?.defaultWorkspaceConfigPath) {
+    env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH =
+      options.defaultWorkspaceConfigPath;
+  }
 
   // Write a sentinel PID file before spawning so concurrent hatch() calls
   // detect the in-progress spawn and wait instead of racing.
@@ -306,6 +316,7 @@ async function startDaemonFromSource(
 async function startDaemonWatchFromSource(
   assistantIndex: string,
   resources: LocalInstanceResources,
+  options?: DaemonStartOptions,
 ): Promise<void> {
   const mainPath = resolveDaemonMainPath(assistantIndex);
   if (!existsSync(mainPath)) {
@@ -381,6 +392,10 @@ async function startDaemonWatchFromSource(
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
     delete env.QDRANT_URL;
   }
+  if (options?.defaultWorkspaceConfigPath) {
+    env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH =
+      options.defaultWorkspaceConfigPath;
+  }
 
   // Write a sentinel PID file before spawning so concurrent hatch() calls
   // detect the in-progress spawn and wait instead of racing.
@@ -819,7 +834,7 @@ export function isGatewayWatchModeAvailable(): boolean {
 export async function startLocalDaemon(
   watch: boolean = false,
   resources: LocalInstanceResources,
-  options?: { foreground?: boolean },
+  options?: DaemonStartOptions,
 ): Promise<void> {
   const foreground = options?.foreground ?? false;
   // Check for a compiled daemon binary adjacent to the CLI executable.
@@ -905,7 +920,7 @@ export async function startLocalDaemon(
 
       // Build a minimal environment for the daemon. When launched from the
       // macOS app the CLI inherits a huge environment (XPC_SERVICE_NAME,
-      // __CFBundleIdentifier, CLAUDE_CODE_ENTRYPOINT, etc.) that can cause
+      // __CFBundleIdentifier, etc.) that can cause
       // the daemon to take 50+ seconds to start instead of ~1s.
       const home = homedir();
       const bunBinDir = join(home, ".bun", "bin");
@@ -924,20 +939,25 @@ export async function startLocalDaemon(
         "ANTHROPIC_API_KEY",
         "APP_VERSION",
         "BASE_DATA_DIR",
-        "PLATFORM_BASE_URL",
+        "VELLUM_PLATFORM_URL",
         "QDRANT_HTTP_PORT",
         "QDRANT_URL",
         "RUNTIME_HTTP_PORT",
-        "SENTRY_DSN",
+        "SENTRY_DSN_ASSISTANT",
         "TMPDIR",
         "USER",
         "LANG",
         "VELLUM_DEBUG",
+        "VELLUM_DESKTOP_APP",
       ]) {
         if (process.env[key]) {
           daemonEnv[key] = process.env[key]!;
         }
       }
+      if (options?.defaultWorkspaceConfigPath) {
+        daemonEnv.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH =
+          options.defaultWorkspaceConfigPath;
+      }
       // When running a named instance, override env so the daemon resolves
       // all paths under the instance directory and listens on its own port.
       if (resources) {
@@ -1005,9 +1025,9 @@ export async function startLocalDaemon(
         // Kill the bundled daemon to avoid two processes competing for the same port
         await stopProcessByPidFile(pidFile, "bundled daemon");
         if (watch) {
-          await startDaemonWatchFromSource(assistantIndex, resources);
+          await startDaemonWatchFromSource(assistantIndex, resources, options);
         } else {
-          await startDaemonFromSource(assistantIndex, resources);
+          await startDaemonFromSource(assistantIndex, resources, options);
         }
         daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
       }
@@ -1031,7 +1051,7 @@ export async function startLocalDaemon(
       );
     }
     if (watch) {
-      await startDaemonWatchFromSource(assistantIndex, resources);
+      await startDaemonWatchFromSource(assistantIndex, resources, options);
 
       const daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
       if (daemonReady) {
@@ -1042,7 +1062,7 @@ export async function startLocalDaemon(
         );
       }
     } else {
-      await startDaemonFromSource(assistantIndex, resources, { foreground });
+      await startDaemonFromSource(assistantIndex, resources, options);
 
       const daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
       if (daemonReady) {

package/src/lib/platform-client.ts

@@ -9,7 +9,7 @@ import {
 import { homedir } from "os";
 import { join, dirname } from "path";
 
-const DEFAULT_PLATFORM_URL = "https://platform.vellum.ai";
+const DEFAULT_PLATFORM_URL = "";
 
 function getXdgConfigHome(): string {
   return process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
@@ -23,6 +23,20 @@ export function getPlatformUrl(): string {
   return process.env.VELLUM_PLATFORM_URL ?? DEFAULT_PLATFORM_URL;
 }
 
+/**
+ * Returns the platform URL, throwing a clear error if it is not configured.
+ * Use this in functions that need a valid URL to make HTTP requests.
+ */
+function requirePlatformUrl(): string {
+  const url = getPlatformUrl();
+  if (!url) {
+    throw new Error(
+      "VELLUM_PLATFORM_URL is not configured. Set it in your environment or .env file.",
+    );
+  }
+  return url;
+}
+
 export function readPlatformToken(): string | null {
   try {
     return readFileSync(getPlatformTokenPath(), "utf-8").trim();
@@ -60,7 +74,7 @@ interface OrganizationListResponse {
 }
 
 export async function fetchOrganizationId(token: string): Promise<string> {
-  const platformUrl = getPlatformUrl();
+  const platformUrl = requirePlatformUrl();
   const url = `${platformUrl}/v1/organizations/`;
   const response = await fetch(url, {
     headers: { "X-Session-Token": token },
@@ -92,7 +106,7 @@ interface AllauthSessionResponse {
 }
 
 export async function fetchCurrentUser(token: string): Promise<PlatformUser> {
-  const url = `${getPlatformUrl()}/_allauth/app/v1/auth/session`;
+  const url = `${requirePlatformUrl()}/_allauth/app/v1/auth/session`;
   const response = await fetch(url, {
     headers: { "X-Session-Token": token },
   });

package/src/lib/platform-releases.ts

@@ -0,0 +1,112 @@
+import { getPlatformUrl } from "./platform-client.js";
+import { DOCKERHUB_IMAGES } from "./docker.js";
+import type { ServiceName } from "./docker.js";
+
+export interface ResolvedImageRefs {
+  imageTags: Record<ServiceName, string>;
+  source: "platform" | "dockerhub";
+}
+
+/**
+ * Resolve image references for a given version.
+ *
+ * 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.
+ */
+export async function resolveImageRefs(
+  version: string,
+  log?: (msg: string) => void,
+): Promise<ResolvedImageRefs> {
+  log?.("Resolving image references...");
+
+  const platformRefs = await fetchPlatformImageRefs(version, log);
+  if (platformRefs) {
+    log?.("Resolved image refs from platform API");
+    return { imageTags: platformRefs, source: "platform" };
+  }
+
+  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}`,
+  };
+  return { imageTags, source: "dockerhub" };
+}
+
+/**
+ * Fetch image references from the platform releases API.
+ *
+ * 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.
+ */
+async function fetchPlatformImageRefs(
+  version: string,
+  log?: (msg: string) => void,
+): Promise<Record<ServiceName, string> | null> {
+  try {
+    const platformUrl = getPlatformUrl();
+    const url = `${platformUrl}/v1/releases/?stable=true`;
+
+    log?.(`Fetching releases from ${url}`);
+
+    const response = await fetch(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 {
+      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;
+  }
+}

package/src/lib/upgrade-lifecycle.ts

@@ -0,0 +1,237 @@
+import { DOCKER_READY_TIMEOUT_MS } from "./docker.js";
+import { loadGuardianToken } from "./guardian-token.js";
+import { execOutput } from "./step-runner.js";
+
+// ---------------------------------------------------------------------------
+// Shared constants & builders for upgrade / rollback lifecycle events
+// ---------------------------------------------------------------------------
+
+/** User-facing progress messages shared across upgrade and rollback flows. */
+export const UPGRADE_PROGRESS = {
+  DOWNLOADING: "Downloading the update…",
+  BACKING_UP: "Saving a backup of your data…",
+  INSTALLING: "Installing the update…",
+  REVERTING: "The update didn't work. Reverting to the previous version…",
+  REVERTING_MIGRATIONS: "Reverting database changes…",
+  RESTORING: "Restoring your data…",
+  SWITCHING: "Switching to the previous version…",
+} as const;
+
+export function buildStartingEvent(
+  targetVersion: string,
+  expectedDowntimeSeconds = 60,
+) {
+  return { type: "starting" as const, targetVersion, expectedDowntimeSeconds };
+}
+
+export function buildProgressEvent(statusMessage: string) {
+  return { type: "progress" as const, statusMessage };
+}
+
+export function buildCompleteEvent(
+  installedVersion: string,
+  success: boolean,
+  rolledBackToVersion?: string,
+) {
+  return {
+    type: "complete" as const,
+    installedVersion,
+    success,
+    ...(rolledBackToVersion ? { rolledBackToVersion } : {}),
+  };
+}
+
+export function buildUpgradeCommitMessage(options: {
+  action: "upgrade" | "rollback";
+  phase: "starting" | "complete";
+  from: string;
+  to: string;
+  topology: "docker" | "managed";
+  assistantId: string;
+  result?: "success" | "failure";
+}): string {
+  const { action, phase, from, to, topology, assistantId, result } = options;
+  const header =
+    phase === "starting"
+      ? `[${action}] Starting: ${from} → ${to}`
+      : `[${action}] Complete: ${from} → ${to}`;
+  const lines = [
+    header,
+    "",
+    `assistant: ${assistantId}`,
+    `from: ${from}`,
+    `to: ${to}`,
+  ];
+  if (result) lines.push(`result: ${result}`);
+  lines.push(`topology: ${topology}`);
+  return lines.join("\n");
+}
+
+/**
+ * Environment variable keys that are set by CLI run arguments and should
+ * not be replayed from a captured container environment during upgrades
+ * or rollbacks. Shared between upgrade.ts and rollback.ts.
+ */
+export const CONTAINER_ENV_EXCLUDE_KEYS: ReadonlySet<string> = new Set([
+  "CES_SERVICE_TOKEN",
+  "VELLUM_ASSISTANT_NAME",
+  "RUNTIME_HTTP_HOST",
+  "PATH",
+  "ACTOR_TOKEN_SIGNING_KEY",
+]);
+
+/**
+ * Capture environment variables from a running Docker container so they
+ * can be replayed onto the replacement container after upgrade.
+ */
+export async function captureContainerEnv(
+  containerName: string,
+): Promise<Record<string, string>> {
+  const captured: Record<string, string> = {};
+  try {
+    const raw = await execOutput("docker", [
+      "inspect",
+      "--format",
+      "{{json .Config.Env}}",
+      containerName,
+    ]);
+    const entries = JSON.parse(raw) as string[];
+    for (const entry of entries) {
+      const eqIdx = entry.indexOf("=");
+      if (eqIdx > 0) {
+        captured[entry.slice(0, eqIdx)] = entry.slice(eqIdx + 1);
+      }
+    }
+  } catch {
+    // Container may not exist or not be inspectable
+  }
+  return captured;
+}
+
+/**
+ * Poll the gateway `/readyz` endpoint until it returns 200 or the timeout
+ * elapses. Returns whether the assistant became ready.
+ */
+export async function waitForReady(runtimeUrl: string): Promise<boolean> {
+  const readyUrl = `${runtimeUrl}/readyz`;
+  const start = Date.now();
+
+  while (Date.now() - start < DOCKER_READY_TIMEOUT_MS) {
+    try {
+      const resp = await fetch(readyUrl, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (resp.ok) {
+        const elapsedSec = ((Date.now() - start) / 1000).toFixed(1);
+        console.log(`Assistant ready after ${elapsedSec}s`);
+        return true;
+      }
+      let detail = "";
+      try {
+        const body = await resp.text();
+        const json = JSON.parse(body);
+        const parts = [json.status];
+        if (json.upstream != null) parts.push(`upstream=${json.upstream}`);
+        detail = ` — ${parts.join(", ")}`;
+      } catch {
+        // ignore parse errors
+      }
+      console.log(`Readiness check: ${resp.status}${detail} (retrying...)`);
+    } catch {
+      // Connection refused / timeout — not up yet
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+
+  return false;
+}
+
+/**
+ * Best-effort broadcast of an upgrade lifecycle event to connected clients
+ * via the gateway's upgrade-broadcast proxy. Uses guardian token auth.
+ * Failures are logged but never block the upgrade flow.
+ */
+export async function broadcastUpgradeEvent(
+  gatewayUrl: string,
+  assistantId: string,
+  event: Record<string, unknown>,
+): Promise<void> {
+  try {
+    const token = loadGuardianToken(assistantId);
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (token?.accessToken) {
+      headers["Authorization"] = `Bearer ${token.accessToken}`;
+    }
+    await fetch(`${gatewayUrl}/v1/admin/upgrade-broadcast`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(event),
+      signal: AbortSignal.timeout(3000),
+    });
+  } catch {
+    // Best-effort — gateway/daemon may already be shutting down or not yet ready
+  }
+}
+
+/**
+ * Roll back DB and workspace migrations to a target state via the gateway.
+ * Best-effort — failures are logged but never block the rollback flow.
+ */
+export async function rollbackMigrations(
+  gatewayUrl: string,
+  assistantId: string,
+  targetDbVersion?: number,
+  targetWorkspaceMigrationId?: string,
+  rollbackToRegistryCeiling?: boolean,
+): Promise<boolean> {
+  if (
+    !rollbackToRegistryCeiling &&
+    targetDbVersion === undefined &&
+    targetWorkspaceMigrationId === undefined
+  ) {
+    return false;
+  }
+  try {
+    const token = loadGuardianToken(assistantId);
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (token?.accessToken) {
+      headers["Authorization"] = `Bearer ${token.accessToken}`;
+    }
+    const body: Record<string, unknown> = {};
+    if (targetDbVersion !== undefined) body.targetDbVersion = targetDbVersion;
+    if (targetWorkspaceMigrationId !== undefined)
+      body.targetWorkspaceMigrationId = targetWorkspaceMigrationId;
+    if (rollbackToRegistryCeiling) body.rollbackToRegistryCeiling = true;
+
+    const resp = await fetch(`${gatewayUrl}/v1/admin/rollback-migrations`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(120_000),
+    });
+    if (!resp.ok) {
+      const text = await resp.text();
+      console.warn(`⚠️  Migration rollback failed (${resp.status}): ${text}`);
+      return false;
+    }
+    const result = (await resp.json()) as {
+      rolledBack?: { db?: string[]; workspace?: string[] };
+    };
+    const dbCount = result.rolledBack?.db?.length ?? 0;
+    const wsCount = result.rolledBack?.workspace?.length ?? 0;
+    if (dbCount > 0 || wsCount > 0) {
+      console.log(
+        `   Rolled back ${dbCount} DB migration(s) and ${wsCount} workspace migration(s)`,
+      );
+    }
+    return true;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`⚠️  Migration rollback failed: ${msg}`);
+    return false;
+  }
+}

package/src/lib/workspace-git.ts

@@ -0,0 +1,39 @@
+import { exec } from "./step-runner";
+
+/**
+ * Best-effort git commit in a workspace directory.
+ *
+ * Stages all changes and creates an `--allow-empty` commit so the
+ * history records every upgrade/rollback even when no files changed.
+ *
+ * Safety measures (mirroring WorkspaceGitService in the assistant package):
+ * - Deterministic committer identity (`vellum-cli`)
+ * - Hooks disabled (`core.hooksPath=/dev/null`, `--no-verify`)
+ *
+ * Callers should wrap this in try/catch — failures must never block
+ * the upgrade or rollback flow.
+ */
+export async function commitWorkspaceState(
+  workspaceDir: string,
+  message: string,
+): Promise<void> {
+  const opts = { cwd: workspaceDir };
+  await exec("git", ["add", "-A"], opts);
+  await exec(
+    "git",
+    [
+      "-c",
+      `user.name=${process.env.CLI_GIT_USER_NAME || "vellum-cli"}`,
+      "-c",
+      `user.email=${process.env.CLI_GIT_USER_EMAIL || "cli@vellum.ai"}`,
+      "-c",
+      "core.hooksPath=/dev/null",
+      "commit",
+      "--no-verify",
+      "--allow-empty",
+      "-m",
+      message,
+    ],
+    opts,
+  );
+}