@vellumai/cli 0.9.0-staging.2 → 0.9.1-staging.1

package/AGENTS.md

@@ -63,7 +63,7 @@ The CLI must **never** read from or write to the `.vellum/` directory (e.g. `~/.
 
 For example, the signing key used for JWT auth between the daemon and gateway is persisted in the lockfile (`resources.signingKey`) so that client actor tokens survive daemon/gateway restarts. On first start (or when the key is missing), the CLI generates a new key via `generateLocalSigningKey()` in `lib/local.ts`, saves it to the lockfile entry, and passes it to both `startLocalDaemon` and `startGateway` as the `ACTOR_TOKEN_SIGNING_KEY` env var. The CLI does **not** read or write to the `.vellum/` directory for signing keys — it uses the lockfile instead.
 
-**Exception: `~/.vellum/device.json`.** That file is the machine-wide shared device-identity file, co-owned by the Swift clients, the Electron main process, the host-mode assistant, and the CLI (see `clients/shared/App/Auth/DeviceIdStore.swift` and `apps/macos/src/main/device-id.ts`). The boundary rule covers daemon/gateway-internal state (e.g. `~/.vellum/protected/`, instance dirs), not this file.
+**Exception: `~/.vellum/device.json`.** That file is the machine-wide shared device-identity file, co-owned by the Electron main process, the host-mode assistant, and the CLI (see `clients/macos/src/main/device-id.ts`). The boundary rule covers daemon/gateway-internal state (e.g. `~/.vellum/protected/`, instance dirs), not this file.
 
 ## Process liveness
 

package/README.md

@@ -4,7 +4,7 @@ CLI tools for provisioning and managing Vellum assistant instances.
 
 ## Installation
 
-This package is used internally by the [`vel`](https://github.com/vellum-ai/vellum-assistant-platform/tree/main/vel) CLI. You typically don't need to install it directly.
+This package is used internally by the `vel` CLI. You typically don't need to install it directly.
 
 To run it standalone with [Bun](https://bun.sh):
 

package/node_modules/@vellumai/environments/src/seeds.ts

@@ -25,11 +25,8 @@ function portBlock(base: number): PortMap {
 }
 
 /**
- * Built-in environment definitions and the TS-side source of truth for the
- * set of known environment names. The Swift client mirrors this list in
- * `clients/macos/vellum-assistant/App/VellumEnvironment.swift`; since Swift
- * can't import TypeScript, drift between the two is caught at test time by
- * `cli/src/__tests__/env-drift.test.ts`.
+ * Built-in environment definitions and the source of truth for the
+ * set of known environment names.
  *
  * Custom environments via a user config file are a future phase — see the
  * "Coexisting environments" design doc. Until then, a call site that needs a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.9.0-staging.2",
+  "version": "0.9.1-staging.1",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/backup.test.ts

@@ -245,6 +245,69 @@ describe("vellum backup <local>: guardian bootstrap secret", () => {
   });
 });
 
+describe("vellum backup: --export-timeout flag", () => {
+  test("rejects a non-numeric value before any lookup", async () => {
+    setArgv("my-local", "--export-timeout", "soon");
+
+    const consoleErrorSpy = spyOn(console, "error").mockImplementation(
+      () => undefined,
+    );
+    try {
+      await expect(backup()).rejects.toThrow("process.exit:1");
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("--export-timeout must be a positive number"),
+      );
+      expect(findAssistantByNameMock).not.toHaveBeenCalled();
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  test("rejects a non-positive value", async () => {
+    setArgv("my-local", "--export-timeout", "0");
+
+    const consoleErrorSpy = spyOn(console, "error").mockImplementation(
+      () => undefined,
+    );
+    try {
+      await expect(backup()).rejects.toThrow("process.exit:1");
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("--export-timeout must be a positive number"),
+      );
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  test("accepts a valid override and completes the local export", async () => {
+    const localEntry = {
+      assistantId: "local-assistant",
+      runtimeUrl: "http://127.0.0.1:7830",
+      cloud: "local",
+      guardianBootstrapSecret: "bootstrap-secret-value",
+    } satisfies assistantConfig.AssistantEntry;
+    findAssistantByNameMock.mockReturnValue(localEntry);
+    setArgv(
+      "my-local",
+      "--export-timeout",
+      "600",
+      "--output",
+      "/tmp/local-backup.vbundle",
+    );
+
+    globalThis.fetch = mock(async () => {
+      return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
+    }) as unknown as typeof globalThis.fetch;
+
+    await backup();
+
+    expect(writeFileSyncMock).toHaveBeenCalledTimes(1);
+    expect(writeFileSyncMock.mock.calls[0]![0]).toBe(
+      "/tmp/local-backup.vbundle",
+    );
+  });
+});
+
 describe("vellum backup <platform-managed>: GCS happy path", () => {
   test("requests upload URL → kicks off runtime export → polls → downloads from GCS → writes file", async () => {
     findAssistantByNameMock.mockReturnValue(VELLUM_ENTRY);

package/src/__tests__/workos-pkce.test.ts

@@ -84,10 +84,10 @@ describe("buildAuthorizeUrl", () => {
   });
 
   test("login hint is forwarded", () => {
-    // generic-examples:ignore-next-line — reason: test fixture for URL encoding, not a real email
-    const url = new URL(buildAuthorizeUrl({ ...base, loginHint: "a@b.co" }));
-    // generic-examples:ignore-next-line — reason: test fixture for URL encoding, not a real email
-    expect(url.searchParams.get("login_hint")).toBe("a@b.co");
+    const url = new URL(
+      buildAuthorizeUrl({ ...base, loginHint: "user@example.com" }),
+    );
+    expect(url.searchParams.get("login_hint")).toBe("user@example.com");
 
     const noHint = new URL(buildAuthorizeUrl(base));
     expect(noHint.searchParams.has("login_hint")).toBe(false);

package/src/commands/backup.ts

@@ -18,23 +18,32 @@ import {
 } from "../lib/platform-client.js";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
+// Default timeout for the runtime-direct export request. Overridable via
+// --export-timeout.
+const DEFAULT_EXPORT_TIMEOUT_MS = 300_000;
+
 export async function backup(): Promise<void> {
   const args = process.argv.slice(3);
 
   if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum backup <name> [--output <path>]");
+    console.log(
+      "Usage: vellum backup <name> [--output <path>] [--export-timeout <seconds>]",
+    );
     console.log("");
     console.log(
       "Export a backup of a running assistant as a .vbundle archive.",
     );
     console.log("");
     console.log("Arguments:");
-    console.log("  <name>              Name of the assistant to back up");
+    console.log("  <name>                   Name of the assistant to back up");
     console.log("");
     console.log("Options:");
-    console.log("  --output <path>     Path to save the .vbundle file");
+    console.log("  --output <path>          Path to save the .vbundle file");
     console.log(
-      "                      (default: ~/.local/share/vellum/backups/<name>-<timestamp>.vbundle)",
+      "                           (default: ~/.local/share/vellum/backups/<name>-<timestamp>.vbundle)",
+    );
+    console.log(
+      `  --export-timeout <secs>  Export request timeout in seconds (default: ${DEFAULT_EXPORT_TIMEOUT_MS / 1000})`,
     );
     console.log("");
     console.log("Examples:");
@@ -42,21 +51,33 @@ export async function backup(): Promise<void> {
     console.log(
       "  vellum backup my-assistant --output ~/Desktop/backup.vbundle",
     );
+    console.log("  vellum backup my-assistant --export-timeout 600");
     process.exit(0);
   }
 
   const name = args[0];
   if (!name || name.startsWith("-")) {
-    console.error("Usage: vellum backup <name> [--output <path>]");
+    console.error(
+      "Usage: vellum backup <name> [--output <path>] [--export-timeout <seconds>]",
+    );
     process.exit(1);
   }
 
-  // Parse --output flag
+  // Parse flags
   let outputArg: string | undefined;
+  let exportTimeoutMs = DEFAULT_EXPORT_TIMEOUT_MS;
   for (let i = 1; i < args.length; i++) {
     if (args[i] === "--output" && args[i + 1]) {
       outputArg = args[i + 1];
-      break;
+    } else if (args[i] === "--export-timeout" && args[i + 1]) {
+      const seconds = Number(args[i + 1]);
+      if (!Number.isFinite(seconds) || seconds <= 0) {
+        console.error(
+          `Error: --export-timeout must be a positive number of seconds (got '${args[i + 1]}').`,
+        );
+        process.exit(1);
+      }
+      exportTimeoutMs = seconds * 1000;
     }
   }
 
@@ -120,7 +141,7 @@ export async function backup(): Promise<void> {
         "Content-Type": "application/json",
       },
       body: JSON.stringify({ description: "CLI backup" }),
-      signal: AbortSignal.timeout(120_000),
+      signal: AbortSignal.timeout(exportTimeoutMs),
     });
 
     // Retry once with a fresh token on 401 — the cached token may be stale
@@ -146,13 +167,15 @@ export async function backup(): Promise<void> {
             "Content-Type": "application/json",
           },
           body: JSON.stringify({ description: "CLI backup" }),
-          signal: AbortSignal.timeout(120_000),
+          signal: AbortSignal.timeout(exportTimeoutMs),
         });
       }
     }
   } catch (err) {
     if (err instanceof Error && err.name === "TimeoutError") {
-      console.error("Error: Export request timed out after 2 minutes.");
+      console.error(
+        `Error: Export request timed out after ${exportTimeoutMs / 1000} seconds.`,
+      );
       process.exit(1);
     }
     const msg = err instanceof Error ? err.message : String(err);

package/src/commands/client.ts

@@ -340,7 +340,7 @@ const SPA_BASE = "/assistant/";
  *
  * Resolution order:
  *   1. npm-installed package — require.resolve('@vellumai/web/package.json')
- *   2. Source checkout — walk up from cli/ to find apps/web/dist/
+ *   2. Source checkout — walk up from cli/ to find clients/web/dist/
  */
 function findWebDistDir(): string | null {
   try {
@@ -355,7 +355,7 @@ function findWebDistDir(): string | null {
 
   let dir = import.meta.dir;
   for (let depth = 0; depth < 8; depth++) {
-    const candidate = path.join(dir, "apps", "web", "dist", "index.html");
+    const candidate = path.join(dir, "clients", "web", "dist", "index.html");
     if (existsSync(candidate)) {
       return path.dirname(candidate);
     }
@@ -367,13 +367,13 @@ function findWebDistDir(): string | null {
 }
 
 /**
- * Locate the apps/web source directory for running the Vite dev server.
+ * Locate the clients/web source directory for running the Vite dev server.
  * Only works from a source checkout (not npm-installed).
  */
 function findWebSourceDir(): string | null {
   let dir = import.meta.dir;
   for (let depth = 0; depth < 8; depth++) {
-    const candidate = path.join(dir, "apps", "web", "vite.config.ts");
+    const candidate = path.join(dir, "clients", "web", "vite.config.ts");
     if (existsSync(candidate)) {
       return path.dirname(candidate);
     }
@@ -679,7 +679,7 @@ async function runWebInterface(
       `${ANSI.bold}--interface web${ANSI.reset}: unable to locate ` +
         `@vellumai/web assets.\n\n` +
         `  npm/bunx install:   npm install @vellumai/web\n` +
-        `  source checkout:    cd apps/web && VITE_PLATFORM_MODE=false bun run build`,
+        `  source checkout:    cd clients/web && VITE_PLATFORM_MODE=false bun run build`,
     );
     process.exit(1);
   }

package/src/commands/nginx-ingress.ts

@@ -195,7 +195,7 @@ async function up(target: NginxIngressTarget): Promise<void> {
     );
     console.error("");
     console.error("Build the SPA first:");
-    console.error("  cd apps/web && VITE_PLATFORM_MODE=false bun run build");
+    console.error("  cd clients/web && VITE_PLATFORM_MODE=false bun run build");
     console.error("");
     console.error(
       "Or install @vellumai/web so its packaged dist directory is available.",

package/src/commands/retire.ts

@@ -318,7 +318,7 @@ async function retireInner(): Promise<void> {
   console.log(`Removed ${formatAssistantReference(entry)} from config.`);
 
   // When no assistants remain, remove the dock-display-name sentinel so
-  // the next build.sh run falls back to "Vellum" instead of using the
+  // the dock label falls back to "Vellum" instead of using the
   // retired assistant's name.
   if (loadAllAssistants().length === 0) {
     const dockLabelFile = join(

package/src/commands/upgrade.ts

@@ -1012,7 +1012,7 @@ async function upgradePlatform(
 }
 
 /**
- * Pre-upgrade steps for Sparkle (macOS app) lifecycle.
+ * Pre-upgrade steps for the macOS app upgrade 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.
@@ -1035,7 +1035,7 @@ async function upgradePrepare(
   await commitWorkspaceViaGateway(
     entry.runtimeUrl,
     entry.assistantId,
-    `[sparkle-update] Starting: ${currentVersion} → ${targetVersion}`,
+    `[assistant-upgrade] Starting: ${currentVersion} → ${targetVersion}`,
   );
 
   // 3. Progress: saving backup
@@ -1070,7 +1070,7 @@ async function upgradePrepare(
 }
 
 /**
- * Post-upgrade steps for Sparkle (macOS app) lifecycle.
+ * Post-upgrade steps for the macOS app upgrade lifecycle.
  * Called after the app has been replaced and the daemon is back up.
  * Broadcasts a "complete" SSE event and creates a workspace commit.
  */
@@ -1103,7 +1103,7 @@ async function upgradeFinalize(
   await commitWorkspaceViaGateway(
     entry.runtimeUrl,
     entry.assistantId,
-    `[sparkle-update] Complete: ${fromVersion} → ${currentVersion}\n\nresult: success`,
+    `[assistant-upgrade] Complete: ${fromVersion} → ${currentVersion}\n\nresult: success`,
   );
 }
 

package/src/lib/device-id.ts

@@ -1,7 +1,7 @@
 /**
  * Host device ID resolver. Resolution order: `VELLUM_DEVICE_ID` env var,
  * then `device.json`. Production uses the machine-wide shared
- * `~/.vellum/device.json`, matching Electron (`apps/macos/src/main/device-id.ts`)
+ * `~/.vellum/device.json`, matching Electron (`clients/macos/src/main/device-id.ts`)
  * and Swift (`VellumPaths.deviceIdFile`); non-production uses
  * `<configDir>/device.json`.
  *

package/src/lib/environments/resolve.ts

@@ -87,10 +87,9 @@ export function getCurrentEnvironment(
   if (!seed) {
     if (name !== DEFAULT_ENVIRONMENT_NAME) {
       // Warn on stderr instead of throwing, to match the silent-fallback
-      // behavior in assistant/src/util/platform.ts:getXdgVellumConfigDirName
-      // and clients/shared/App/VellumEnvironment.swift:current. Those two
-      // silently fall back to production; the CLI should agree so all three
-      // writers don't end up in disjoint states on a typo.
+      // behavior in assistant/src/util/platform.ts:getXdgVellumConfigDirName,
+      // which silently falls back to production; the CLI agrees so neither
+      // writer ends up in a disjoint state on a typo.
       process.stderr.write(
         `warning: unknown environment "${name}"; falling back to "${DEFAULT_ENVIRONMENT_NAME}". ` +
           `Add it to packages/environments/src/seeds.ts and rebuild if this was intentional.\n`,

package/src/lib/local.ts

@@ -1018,7 +1018,7 @@ export async function startLocalDaemon(
     let daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
 
     // Dev fallback: if the bundled daemon did not become ready in time,
-    // fall back to source daemon startup so local `./build.sh run` still works.
+    // fall back to source daemon startup so local source runs still work.
     if (!daemonReady) {
       const assistantIndex = resolveAssistantIndexPath();
       if (assistantIndex) {

package/src/lib/nginx-ingress.ts

@@ -85,7 +85,7 @@ function saveRawConfig(
  *
  * Resolution order:
  *   1. npm-installed package — require.resolve('@vellumai/web/package.json')
- *   2. Source checkout — walk up from cli/ to find apps/web/dist/
+ *   2. Source checkout — walk up from cli/ to find clients/web/dist/
  */
 export function findWebDistDir(): string | null {
   try {
@@ -100,7 +100,7 @@ export function findWebDistDir(): string | null {
 
   let dir = import.meta.dir;
   for (let depth = 0; depth < 8; depth++) {
-    const candidate = join(dir, "apps", "web", "dist", "index.html");
+    const candidate = join(dir, "clients", "web", "dist", "index.html");
     if (existsSync(candidate)) {
       return dirname(candidate);
     }

package/src/__tests__/env-drift.test.ts

@@ -1,53 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-import { SEEDS } from "@vellumai/environments";
-
-// Drift guard between the two language-level sources of truth for the set of
-// known environment names:
-//
-//   1. packages/environments/src/seeds.ts       — SEEDS record (TS source of truth)
-//   2. clients/shared/App/VellumEnvironment.swift — Swift `VellumEnvironment` enum
-//
-// The Swift client can't import the TypeScript package, so the two lists are
-// maintained independently and must be kept in lockstep by hand. This test
-// parses the enum cases out of the Swift source and asserts they agree with
-// SEEDS. Adding an environment means updating both sites.
-
-const REPO_ROOT = join(import.meta.dir, "..", "..", "..");
-const SWIFT_ENVIRONMENT = join(
-  REPO_ROOT,
-  "clients",
-  "shared",
-  "App",
-  "VellumEnvironment.swift",
-);
-
-/**
- * Extract the case names declared in the `VellumEnvironment` enum. Matches
- * standalone `case <name>` declaration lines (one identifier, nothing else),
- * which is the enum's own declaration syntax. Switch-statement arms like
- * `case .local:` carry a leading dot and a trailing colon, so they're
- * excluded — the match is anchored to a bare identifier at end of line.
- */
-function extractSwiftEnumCases(source: string): string[] {
-  const names: string[] = [];
-  for (const line of source.split("\n")) {
-    const match = line.match(/^\s*case\s+([a-zA-Z][a-zA-Z0-9]*)\s*$/);
-    if (match) names.push(match[1]!);
-  }
-  return names;
-}
-
-describe("environment name drift guard (TS ↔ Swift)", () => {
-  const seedNames = new Set(Object.keys(SEEDS));
-
-  test("clients/shared/App/VellumEnvironment.swift matches SEEDS", () => {
-    const source = readFileSync(SWIFT_ENVIRONMENT, "utf8");
-    const swiftNames = new Set(extractSwiftEnumCases(source));
-
-    expect(swiftNames.size).toBeGreaterThan(0);
-    expect([...swiftNames].sort()).toEqual([...seedNames].sort());
-  });
-});