@vellumai/cli 0.10.4-staging.1 → 0.10.4

package/package.json

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

package/src/__tests__/flags.test.ts

@@ -83,10 +83,10 @@ describe("vellum flags --assistant routing", () => {
       fetchCalls.push({ url, method });
       if (method === "PATCH") {
         return jsonResponse({
-          key: "external-plugins",
+          key: "voice-mode",
           enabled: true,
           defaultEnabled: false,
-          label: "External Plugins",
+          label: "Voice Mode",
           description: "test",
         });
       }
@@ -133,7 +133,7 @@ describe("vellum flags --assistant routing", () => {
       "vellum",
       "flags",
       "set",
-      "external-plugins",
+      "voice-mode",
       "true",
       "--assistant",
       "Bob",
@@ -146,7 +146,7 @@ describe("vellum flags --assistant routing", () => {
     // bob-2 has assistantId.length === 5, so port = 7800 + 5 = 7805.
     expect(fetchCalls[0].url).toContain("http://127.0.0.1:7805");
     expect(fetchCalls[0].url).toContain(
-      "/v1/assistants/bob-2/feature-flags/external-plugins",
+      "/v1/assistants/bob-2/feature-flags/voice-mode",
     );
   });
 
@@ -166,7 +166,7 @@ describe("vellum flags --assistant routing", () => {
       "--assistant",
       "Bob",
       "set",
-      "external-plugins",
+      "voice-mode",
       "true",
     ];
 
@@ -174,7 +174,7 @@ describe("vellum flags --assistant routing", () => {
 
     expect(fetchCalls.length).toBe(1);
     expect(fetchCalls[0].url).toContain(
-      "/v1/assistants/bob-2/feature-flags/external-plugins",
+      "/v1/assistants/bob-2/feature-flags/voice-mode",
     );
   });
 
@@ -193,7 +193,7 @@ describe("vellum flags --assistant routing", () => {
       "vellum",
       "flags",
       "set",
-      "external-plugins",
+      "voice-mode",
       "true",
     ];
 
@@ -203,7 +203,7 @@ describe("vellum flags --assistant routing", () => {
     // alice-1 has assistantId.length === 7, so port = 7800 + 7 = 7807.
     expect(fetchCalls[0].url).toContain("http://127.0.0.1:7807");
     expect(fetchCalls[0].url).toContain(
-      "/v1/assistants/alice-1/feature-flags/external-plugins",
+      "/v1/assistants/alice-1/feature-flags/voice-mode",
     );
   });
 
@@ -214,7 +214,7 @@ describe("vellum flags --assistant routing", () => {
       "vellum",
       "flags",
       "set",
-      "external-plugins",
+      "voice-mode",
       "true",
       "--assistant",
       "Ghost",
@@ -234,7 +234,7 @@ describe("vellum flags --assistant routing", () => {
       "vellum",
       "flags",
       "set",
-      "external-plugins",
+      "voice-mode",
       "true",
       "--assistant",
     ];

package/src/__tests__/recover.test.ts

@@ -13,6 +13,7 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
+  renameSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
@@ -220,37 +221,43 @@ describe("recover error cases", () => {
 describe("recover extraction path — default instance (instanceDir === homedir())", () => {
   test("extracts to retiredDir and renames staging dir to instanceDir/.vellum", async () => {
     const name = "default-instance";
-    // Default instance: instanceDir is the real home directory
     const entry = makeEntry(name, homedir());
     const { archivePath, extractedPath } = writeArchiveFixtures(name, entry);
 
     const expectedTargetDir = join(homedir(), ".vellum");
-
-    process.argv = ["bun", "vellum", "recover", name];
-    await recover();
-
-    // exec must have been called with -C retiredDir, NOT -C homedir()
-    expect(execMock).toHaveBeenCalledTimes(1);
-    const [cmd, args] = execMock.mock.calls[0] as [string, string[]];
-    expect(cmd).toBe("tar");
-    expect(args).toContain("-C");
-    const cIndex = args.indexOf("-C");
-    expect(args[cIndex + 1]).toBe(retiredDir);
-    expect(args[cIndex + 1]).not.toBe(homedir());
-
-    // Staging dir was renamed to the correct target
-    expect(existsSync(extractedPath)).toBe(false);
-    expect(existsSync(expectedTargetDir)).toBe(true);
-
-    // Archive and metadata were cleaned up
-    expect(existsSync(archivePath)).toBe(false);
-
-    // Daemon and gateway were started
-    expect(startLocalDaemonMock).toHaveBeenCalledTimes(1);
-    expect(startGatewayMock).toHaveBeenCalledTimes(1);
-
-    // Clean up so we don't leave a .vellum dir in the real home dir
-    rmSync(expectedTargetDir, { recursive: true, force: true });
+    // If a real ~/.vellum exists (e.g. the machine runs a live assistant),
+    // temporarily move it aside so the collision guard doesn't fire.
+    const backupDir = join(homedir(), ".vellum-recover-test-bak");
+    const hadExisting = existsSync(expectedTargetDir);
+    if (hadExisting) renameSync(expectedTargetDir, backupDir);
+
+    try {
+      process.argv = ["bun", "vellum", "recover", name];
+      await recover();
+
+      // exec must have been called with -C retiredDir, NOT -C homedir()
+      expect(execMock).toHaveBeenCalledTimes(1);
+      const [cmd, args] = execMock.mock.calls[0] as [string, string[]];
+      expect(cmd).toBe("tar");
+      expect(args).toContain("-C");
+      const cIndex = args.indexOf("-C");
+      expect(args[cIndex + 1]).toBe(retiredDir);
+      expect(args[cIndex + 1]).not.toBe(homedir());
+
+      // Staging dir was renamed to the correct target
+      expect(existsSync(extractedPath)).toBe(false);
+      expect(existsSync(expectedTargetDir)).toBe(true);
+
+      // Archive and metadata were cleaned up
+      expect(existsSync(archivePath)).toBe(false);
+
+      // Daemon and gateway were started
+      expect(startLocalDaemonMock).toHaveBeenCalledTimes(1);
+      expect(startGatewayMock).toHaveBeenCalledTimes(1);
+    } finally {
+      rmSync(expectedTargetDir, { recursive: true, force: true });
+      if (hadExisting) renameSync(backupDir, expectedTargetDir);
+    }
   });
 });
 

package/src/__tests__/teleport.test.ts

@@ -259,12 +259,27 @@ const localRuntimePollJobStatusMock = mock<
   },
 }));
 
+const localRuntimePreflightFromGcsMock = mock<
+  typeof localRuntimeClient.localRuntimePreflightFromGcs
+>(async () => ({
+  can_import: true,
+  summary: {
+    files_to_create: 2,
+    files_to_overwrite: 1,
+    files_unchanged: 0,
+    total_files: 3,
+  },
+  files: [],
+  conflicts: [],
+}));
+
 mock.module("../lib/local-runtime-client.js", () => ({
   ...realLocalRuntimeClient,
   localRuntimeExportToGcs: localRuntimeExportToGcsMock,
   localRuntimeImportFromGcs: localRuntimeImportFromGcsMock,
   localRuntimeIdentity: localRuntimeIdentityMock,
   localRuntimePollJobStatus: localRuntimePollJobStatusMock,
+  localRuntimePreflightFromGcs: localRuntimePreflightFromGcsMock,
 }));
 
 const hatchLocalMock = mock(async () => {});
@@ -483,6 +498,18 @@ beforeEach(() => {
   localRuntimeImportFromGcsMock.mockResolvedValue({
     jobId: "local-import-job-1",
   });
+  localRuntimePreflightFromGcsMock.mockReset();
+  localRuntimePreflightFromGcsMock.mockResolvedValue({
+    can_import: true,
+    summary: {
+      files_to_create: 2,
+      files_to_overwrite: 1,
+      files_unchanged: 0,
+      total_files: 3,
+    },
+    files: [],
+    conflicts: [],
+  });
   localRuntimeIdentityMock.mockReset();
   localRuntimeIdentityMock.mockResolvedValue({ version: "0.6.5" });
   localRuntimePollJobStatusMock.mockReset();
@@ -1932,7 +1959,7 @@ describe("dry-run", () => {
     }
   });
 
-  test("dry-run against local target fails fast (no preflight-from-gcs runtime endpoint yet)", async () => {
+  test("dry-run with existing local target calls preflight-from-gcs on runtime", async () => {
     setArgv("--from", "my-platform", "--local", "my-local", "--dry-run");
 
     const platformEntry = makeEntry("my-platform", {
@@ -1947,26 +1974,24 @@ describe("dry-run", () => {
       return null;
     });
 
-    platformPollJobStatusMock.mockResolvedValue({
-      jobId: "platform-export-job-1",
-      type: "export",
-      status: "complete",
-      bundleKey: "bundle-key-from-platform",
-    });
-
     const restoreFetch = installTrackingFetch();
     try {
-      await expect(teleport()).rejects.toThrow("process.exit:1");
-      expect(consoleErrorSpy).toHaveBeenCalledWith(
-        expect.stringContaining(
-          "--dry-run is not yet supported for local or docker targets",
-        ),
+      await teleport();
+
+      // Preflight was run against the local runtime
+      expect(localRuntimePreflightFromGcsMock).toHaveBeenCalledTimes(1);
+      expect(localRuntimePreflightFromGcsMock).toHaveBeenCalledWith(
+        expect.objectContaining({ assistantId: "my-local" }),
+        expect.any(String),
+        { bundleUrl: "https://storage.googleapis.com/bucket/signed-download" },
       );
 
-      // Must fail BEFORE any export work — no signed URL request, no runtime
-      // export kickoff, nothing that costs time or bandwidth.
-      expect(platformRequestSignedUrlMock).not.toHaveBeenCalled();
-      expect(localRuntimeExportToGcsMock).not.toHaveBeenCalled();
+      // No actual import happened — dry-run only
+      expect(localRuntimeImportFromGcsMock).not.toHaveBeenCalled();
+
+      // Source was not retired
+      expect(retireLocalMock).not.toHaveBeenCalled();
+      expect(retireDockerMock).not.toHaveBeenCalled();
     } finally {
       restoreFetch();
     }

package/src/commands/flags.ts

@@ -98,7 +98,7 @@ function printHelp(): void {
     "  $ vellum flags set voice-mode true                           # enable a flag",
   );
   console.log(
-    "  $ vellum flags set external-plugins true --assistant eval-1  # target by name/id",
+    "  $ vellum flags set voice-mode true --assistant eval-1       # target by name/id",
   );
 }
 

package/src/commands/teleport.ts

@@ -33,6 +33,7 @@ import {
   localRuntimeExportToGcs,
   localRuntimeIdentity,
   localRuntimeImportFromGcs,
+  localRuntimePreflightFromGcs,
   localRuntimePollJobStatus,
   MigrationInProgressError,
 } from "../lib/local-runtime-client.js";
@@ -707,11 +708,46 @@ async function importToAssistant(
 
   if (cloud === "local" || cloud === "docker") {
     if (dryRun) {
-      // TODO(cli): support dry-run against local targets
-      console.error(
-        "Error: --dry-run is not yet supported for local or docker targets (no preflight-from-gcs endpoint on the runtime).",
+      console.log("Running preflight analysis...\n");
+
+      // Query the target runtime's version before requesting a signed
+      // download URL — the platform uses it for the bundle compatibility check.
+      let targetRuntimeVersion: string;
+      try {
+        const identity = await callRuntimeWithAuthRetry(entry, (token) =>
+          localRuntimeIdentity(entry, token),
+        );
+        targetRuntimeVersion = identity.version;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(
+          `Error: Could not read target runtime version from '${entry.assistantId}': ${msg}`,
+        );
+        console.error(`Try: vellum wake ${entry.assistantId}`);
+        process.exit(1);
+      }
+
+      let bundleUrl: string;
+      try {
+        const result = await platformRequestSignedUrl(
+          { operation: "download", bundleKey, targetRuntimeVersion },
+          platformToken,
+          bundlePlatformUrl,
+        );
+        bundleUrl = result.url;
+      } catch (err) {
+        if (err instanceof VersionMismatchError) {
+          console.error(`Error: ${err.message}`);
+          process.exit(1);
+        }
+        throw err;
+      }
+
+      const preflightData = await callRuntimeWithAuthRetry(entry, (token) =>
+        localRuntimePreflightFromGcs(entry, token, { bundleUrl }),
       );
-      process.exit(1);
+      printPreflightSummary(preflightData as unknown as PreflightResponse);
+      return;
     }
 
     // Ask the platform for a signed download URL and hand it to the local
@@ -1231,18 +1267,8 @@ export async function teleport(): Promise<void> {
         process.exit(1);
       }
 
-      // Dry-run feasibility check — reject local/docker targets BEFORE any
-      // export work. The local runtime has no preflight-from-gcs endpoint yet,
-      // so we can't actually run a dry-run against it; burning a GCS upload
-      // just to fail afterwards would be wasteful.
-      // TODO(cli): support dry-run against local targets (needs a
-      // preflight-from-gcs endpoint on the runtime).
-      if (toCloud === "local" || toCloud === "docker") {
-        console.error(
-          "Error: --dry-run is not yet supported for local or docker targets (no preflight-from-gcs endpoint on the runtime).",
-        );
-        process.exit(1);
-      }
+      // Nothing to reject — preflight-from-gcs is now implemented for all
+      // target topologies including local and docker.
 
       // Version guard: block platform→non-platform when target is behind
       if (fromCloud === "vellum" && toCloud !== "vellum") {

package/src/lib/local-runtime-client.ts

@@ -195,6 +195,44 @@ export async function localRuntimeImportFromGcs(
   return { jobId: json.job_id };
 }
 
+/**
+ * Run a dry-run preflight analysis on a .vbundle archive stored at a signed
+ * GCS download URL.
+ *
+ * For local/docker assistants this POSTs to
+ * `{runtimeUrl}/v1/migrations/preflight-from-gcs` with guardian-token bearer
+ * auth. The daemon fetches the bundle from GCS, validates it, and returns a
+ * report of what would change on import — without writing anything to disk.
+ *
+ * Returns the raw preflight response body. Callers should cast to their
+ * local `PreflightResponse` shape (mirrors the `/import-preflight` shape).
+ */
+export async function localRuntimePreflightFromGcs(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  token: string,
+  params: { bundleUrl: string },
+): Promise<Record<string, unknown>> {
+  const response = await fetch(
+    resolveRuntimeMigrationUrl(entry, "preflight-from-gcs"),
+    {
+      method: "POST",
+      headers: await migrationRequestHeaders(entry, token),
+      body: JSON.stringify({ bundle_url: params.bundleUrl }),
+    },
+  );
+
+  if (response.status !== 200) {
+    const errText = await response.text().catch(() => "");
+    throw new Error(
+      `Local runtime preflight-from-gcs failed (${response.status}): ${
+        errText || response.statusText
+      }`,
+    );
+  }
+
+  return (await response.json()) as Record<string, unknown>;
+}
+
 /**
  * Poll the runtime's unified job-status endpoint.
  *