feat: versioned deployments — rollback CLI, manifest v3, worker-side migrations

- Add `void project rollback [deployId]` command with interactive selection
- Add migration handler runtime for worker-side D1 migrations (v3 flow)
- Update deploy manifest: migrations as `{ dialect, pending }`, hyperdrive as `string[]`
- Add `--deployment` filter to `void project logs`
- Show live/retained/evicted status in `void project status`
- Inject `__void/migrate` route into compiled worker entry

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: yyx990803

docs/reference/cli.md

@@ -22,6 +22,7 @@ outline: deep
 | `void auth login`                 | Authenticate with Void                  |
 | `void project link`               | Link directory to a project             |
 | `void project logs`               | Show runtime logs from deployed project |
+| `void project rollback`           | Roll back to a previous deployment      |
 | `void init`                       | Setup wizard (tsconfig, agents, CI)     |
 
 ## Binary Invocation
@@ -101,7 +102,7 @@ List all your projects (slug, mode, URL).
 ### `void project logs`
 
 ```
-void project logs [--filter <text>] [--range <duration>]
+void project logs [--filter <text>] [--range <duration>] [--deployment <id>]
 ```
 
 Show runtime logs from the deployed project. Uses the linked project from `.void/project.json`.
@@ -110,9 +111,23 @@ Show runtime logs from the deployed project. Uses the linked project from `.void
 | -------------------- | --------------------------------------------------------------------------------------------------------------- | ------- |
 | `--range <duration>` | How far back to look. Format: `<number><unit>` (m/h/d). Max 7d.                                                 | `1h`    |
 | `--filter <text>`    | Case-insensitive text match against log/exception messages. Shows full request entry when any log line matches. | —       |
+| `--deployment <id>`  | Filter logs to a specific deployment ID.                                                                        | —       |
 
 Output shows one line per request (`HH:MM:SS METHOD URL STATUS`) with indented console log and exception lines beneath. Errors and exceptions are colored red, warnings yellow.
 
+### `void project rollback [deployId]`
+
+```
+void project rollback [deployId]
+```
+
+Roll back to a previous deployment. Traffic instantly switches to the target deployment's worker script via KV routing update.
+
+- If `[deployId]` is omitted, shows an interactive select menu of retained deployments
+- If the target deployment has fewer applied migrations than the current one, a warning is shown listing the migration diff before confirmation
+
+Only **retained** deployments can be rolled back to. The number of retained deployments depends on your plan (free: 1, solo: 5, pro: 25, unlimited for sponsored/custom).
+
 ### `void project delete [name]`
 
 Permanently delete a project and all its resources (databases, KV namespaces, R2 buckets, deployments). Requires typing the project slug to confirm.

packages/void/package.json

@@ -91,6 +91,10 @@
       "types": "./dist/runtime/remote/binding-handler.d.mts",
       "import": "./dist/runtime/remote/binding-handler.mjs"
     },
+    "./runtime/migration-handler": {
+      "types": "./dist/runtime/migration-handler.d.mts",
+      "import": "./dist/runtime/migration-handler.mjs"
+    },
     "./pages": {
       "types": "./dist/pages/index.d.mts",
       "import": "./dist/pages/index.mjs"

packages/void/src/cli/cli.ts

@@ -44,6 +44,7 @@ function printHelp() {
       helpLine("void project link [name]", "Link directory to a project"),
       helpLine("void project list", "List your projects"),
       helpLine("void project logs [--filter] [--range]", "Show runtime logs from deployed project"),
+      helpLine("void project rollback [deployId]", "Roll back to a previous deployment"),
       helpLine("void project delete [name]", "Delete a project and all its resources"),
       "",
       categoryTitle("secrets"),
@@ -238,7 +239,7 @@ if (command === "staging") {
     },
     {
       name: "project",
-      hint: "status | link | list | logs | delete",
+      hint: "status | link | list | logs | rollback | delete",
       description: "Manage projects and deployments",
     },
     { name: "secret", hint: "list | put | delete | sync", description: "Manage project secrets" },

packages/void/src/cli/client.ts

@@ -29,10 +29,17 @@ export interface DeploymentResponse {
   commit: string | null;
   manifest: string | null;
   error_message: string | null;
+  retained: boolean;
+  applied_migrations: string | null;
   created_at: string;
   deployed_at: string | null;
 }
 
+export interface DeploymentListResponse {
+  deployments: DeploymentResponse[];
+  activeDeploymentId: string | null;
+}
+
 export interface SecretResponse {
   ok: boolean;
   name: string;
@@ -105,7 +112,7 @@ export class PlatformClient {
     return res.json();
   }
 
-  async listDeployments(projectId: string): Promise<DeploymentResponse[]> {
+  async listDeployments(projectId: string): Promise<DeploymentListResponse> {
     const res = await fetch(`${this.baseUrl}/projects/${projectId}/deployments`, {
       headers: {
         Authorization: `Bearer ${this.token}`,
@@ -120,6 +127,27 @@ export class PlatformClient {
     return res.json();
   }
 
+  async rollback(
+    projectId: string,
+    deploymentId: string,
+  ): Promise<{ ok: boolean; deploymentId?: string; migrationDiff?: string[]; error?: string }> {
+    const res = await fetch(`${this.baseUrl}/projects/${projectId}/rollback`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.token}`,
+      },
+      body: JSON.stringify({ deploymentId }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`Rollback failed: ${res.status} ${body}`);
+    }
+
+    return res.json();
+  }
+
   async createProject(slug: string): Promise<CreateProjectResponse> {
     const res = await fetch(`${this.baseUrl}/projects`, {
       method: "POST",
@@ -351,15 +379,23 @@ export class PlatformClient {
     return res.json();
   }
 
-  async getLogs(projectId: string, since: string, limit = 200): Promise<LogEntry[]> {
-    const res = await fetch(
-      `${this.baseUrl}/projects/${projectId}/logs?since=${encodeURIComponent(since)}&limit=${limit}`,
-      {
-        headers: {
-          Authorization: `Bearer ${this.token}`,
-        },
+  async getLogs(
+    projectId: string,
+    since: string,
+    limit = 200,
+    deploymentId?: string,
+  ): Promise<LogEntry[]> {
+    const params = new URLSearchParams({
+      since,
+      limit: String(limit),
+    });
+    if (deploymentId) params.set("deploymentId", deploymentId);
+
+    const res = await fetch(`${this.baseUrl}/projects/${projectId}/logs?${params}`, {
+      headers: {
+        Authorization: `Bearer ${this.token}`,
       },
-    );
+    });
 
     if (!res.ok) {
       const body = await res.text();

packages/void/src/cli/deploy.ts

@@ -213,8 +213,11 @@ async function streamDeploy(
       case "provisioning":
         s.message(`Provisioning ${event.bindings.join(", ")}`);
         break;
+      case "migration_start":
+        s.message(`Running ${event.pending} migration${event.pending > 1 ? "s" : ""}...`);
+        break;
       case "migration":
-        s.message(`Running migration ${event.index}/${event.total}: ${event.name}`);
+        s.message(`Applied migration: ${event.name} (${event.durationMs}ms)`);
         break;
       case "worker_upload":
         s.message("Uploading worker...");

packages/void/src/cli/list.ts

@@ -1,6 +1,6 @@
 import { intro, outro, log } from "@clack/prompts";
 import { getToken } from "./auth";
-import { PlatformClient, type DeploymentResponse } from "./client";
+import { PlatformClient, type DeploymentResponse, type DeploymentListResponse } from "./client";
 import { readProjectConfig } from "./project";
 import { resolveProjectBySlug } from "./resolve-project";
 import { cliTitle, dim, pc, tablePrefix } from "./output";
@@ -47,7 +47,7 @@ async function showDeployments(
   projectId: string,
   slug: string,
 ): Promise<void> {
-  const deployments = await client.listDeployments(projectId);
+  const { deployments, activeDeploymentId } = await client.listDeployments(projectId);
 
   if (deployments.length === 0) {
     outro(`No deployments for ${slug}.`);
@@ -59,7 +59,7 @@ async function showDeployments(
     log.error(`Latest deploy failed: ${latest.error_message}`);
   }
 
-  const rows = deployments.map((d) => formatDeploymentRow(d));
+  const rows = deployments.map((d) => formatDeploymentRow(d, activeDeploymentId));
 
   const idWidth = Math.max("id".length, ...rows.map((r) => r.id.length));
   const typeWidth = Math.max("type".length, ...rows.map((r) => r.appType.length));
@@ -93,7 +93,33 @@ interface DeploymentRow {
   deployed: string;
 }
 
-function formatDeploymentRow(d: DeploymentResponse): DeploymentRow {
+function computeDisplayStatus(d: DeploymentResponse, activeDeploymentId: string | null): string {
+  if (d.status === "failed") return "failed";
+  if (d.status !== "live") return d.status;
+  if (d.id === activeDeploymentId) return "live";
+  if (d.retained) return "retained";
+  return "evicted";
+}
+
+function colorStatus(status: string): string {
+  switch (status) {
+    case "live":
+      return pc.bold(pc.green(status));
+    case "retained":
+      return dim(pc.green(status));
+    case "evicted":
+      return dim(status);
+    case "failed":
+      return pc.red(status);
+    default:
+      return status;
+  }
+}
+
+function formatDeploymentRow(
+  d: DeploymentResponse,
+  activeDeploymentId: string | null,
+): DeploymentRow {
   let manifest: {
     type?: string;
     static?: string;
@@ -113,13 +139,8 @@ function formatDeploymentRow(d: DeploymentResponse): DeploymentRow {
   const source = d.source ?? "-";
   const commit = d.commit ? d.commit.slice(0, 7) : "-";
 
-  const statusRaw = d.status;
-  let statusColored = statusRaw;
-  if (d.status === "live") {
-    statusColored = pc.green(statusRaw);
-  } else if (d.status === "failed") {
-    statusColored = pc.red(statusRaw);
-  }
+  const statusRaw = computeDisplayStatus(d, activeDeploymentId);
+  const statusColored = colorStatus(statusRaw);
 
   const deployed = d.deployed_at ? formatRelativeTime(d.deployed_at) : "-";
 

packages/void/src/cli/logs.ts

@@ -4,7 +4,12 @@ import { PlatformClient, type LogEntry } from "./client";
 import { readProjectConfig } from "./project";
 import { cliTitle, dim, pc } from "./output";
 
-export async function runLogsCommand(root: string, filter: string, range: string): Promise<void> {
+export async function runLogsCommand(
+  root: string,
+  filter: string,
+  range: string,
+  deployment?: string,
+): Promise<void> {
   console.log();
   intro(cliTitle("project logs"));
 
@@ -29,7 +34,7 @@ export async function runLogsCommand(root: string, filter: string, range: string
 
   let entries: LogEntry[];
   try {
-    entries = await client.getLogs(linked.projectId, range);
+    entries = await client.getLogs(linked.projectId, range, 200, deployment || undefined);
   } catch (err) {
     log.error(err instanceof Error ? err.message : String(err));
     process.exit(1);

packages/void/src/cli/package.ts

@@ -112,7 +112,7 @@ export function packageBuild(
   const formData = new FormData();
 
   // Build manifest from inferred bindings
-  const manifest: DeployManifest = { version: 2, bindings: {} };
+  const manifest: DeployManifest = { version: 3, bindings: {} };
   if (bindings.needsD1) manifest.bindings.d1 = [options?.bindingNames?.d1 ?? "DB"];
   if (bindings.needsKV) manifest.bindings.kv = [options?.bindingNames?.kv ?? "KV"];
   if (bindings.needsR2) manifest.bindings.r2 = [options?.bindingNames?.r2 ?? "STORAGE"];
@@ -124,10 +124,10 @@ export function packageBuild(
 
   // Add migration metadata to manifest + SQL content as FormData entries
   if (migrations && migrations.length > 0) {
-    manifest.migrations = migrations.map((m) => ({
-      name: m.name,
-      destructive: m.destructive,
-    }));
+    manifest.migrations = {
+      dialect: "sqlite",
+      pending: migrations.length,
+    };
     for (const m of migrations) {
       formData.append(`migration:${m.name}`, new Blob([m.sql]), m.name);
     }
@@ -234,7 +234,7 @@ export function packageStaticBuild(
   const formData = new FormData();
 
   const manifest: DeployManifest = {
-    version: 2,
+    version: 3,
     bindings: {},
     type: appType,
     assetConfig: {
@@ -300,7 +300,7 @@ export function packageFrameworkBuild(opts: {
   const po = opts.packageOptions;
 
   // Build manifest
-  const manifest: DeployManifest = { version: 2, bindings: {} };
+  const manifest: DeployManifest = { version: 3, bindings: {} };
   if (opts.bindings.needsD1) manifest.bindings.d1 = [po?.bindingNames?.d1 ?? "DB"];
   if (opts.bindings.needsKV) manifest.bindings.kv = [po?.bindingNames?.kv ?? "KV"];
   if (opts.bindings.needsR2) manifest.bindings.r2 = [po?.bindingNames?.r2 ?? "STORAGE"];
@@ -311,10 +311,10 @@ export function packageFrameworkBuild(opts: {
   }
 
   if (opts.migrations && opts.migrations.length > 0) {
-    manifest.migrations = opts.migrations.map((m) => ({
-      name: m.name,
-      destructive: m.destructive,
-    }));
+    manifest.migrations = {
+      dialect: "sqlite",
+      pending: opts.migrations.length,
+    };
     for (const m of opts.migrations) {
       formData.append(`migration:${m.name}`, new Blob([m.sql]), m.name);
     }

packages/void/src/cli/project-args.ts

@@ -5,6 +5,7 @@ export const projectSubcommands: SubcommandDef[] = [
   { name: "link", arg: "[name]", description: "Link directory to a project" },
   { name: "list", description: "List your projects" },
   { name: "logs", description: "Show runtime logs from the deployed project" },
+  { name: "rollback", arg: "[deployId]", description: "Roll back to a previous deployment" },
   {
     name: "delete",
     arg: "[name]",
@@ -16,7 +17,8 @@ export type ProjectArgs =
   | { subcommand: "status"; name: string }
   | { subcommand: "link"; name: string }
   | { subcommand: "list" }
-  | { subcommand: "logs"; filter: string; range: string }
+  | { subcommand: "logs"; filter: string; range: string; deployment: string }
+  | { subcommand: "rollback"; deployId: string }
   | { subcommand: "delete"; name: string; force: boolean };
 
 export function parseProjectArgs(args: string[]): ProjectArgs {
@@ -48,16 +50,27 @@ export function parseProjectArgs(args: string[]): ProjectArgs {
   if (subcommand === "logs") {
     let filter = "";
     let range = "1h";
+    let deployment = "";
     for (let i = 0; i < rest.length; i++) {
       if (rest[i] === "--filter" && rest[i + 1]) {
         filter = rest[++i];
       } else if (rest[i] === "--range" && rest[i + 1]) {
         range = rest[++i];
+      } else if (rest[i] === "--deployment" && rest[i + 1]) {
+        deployment = rest[++i];
       } else {
         throw new Error(`Error: Unexpected argument: ${rest[i]}`);
       }
     }
-    return { subcommand, filter, range };
+    return { subcommand, filter, range, deployment };
+  }
+
+  if (subcommand === "rollback") {
+    const [deployId, extra] = rest;
+    if (extra) {
+      throw new Error(`Error: Unexpected argument: ${extra}`);
+    }
+    return { subcommand, deployId: deployId ?? "" };
   }
 
   if (subcommand === "delete") {
@@ -77,5 +90,5 @@ export function parseProjectArgs(args: string[]): ProjectArgs {
     return { subcommand, name, force };
   }
 
-  throw new Error("Error: Usage: void project <status|link|list|logs|delete>");
+  throw new Error("Error: Usage: void project <status|link|list|logs|rollback|delete>");
 }

packages/void/src/cli/project-cmd.ts

@@ -15,7 +15,11 @@ export async function runProjectCommand(root: string, args: ProjectArgs): Promis
   }
   if (args.subcommand === "logs") {
     const { runLogsCommand } = await import("./logs");
-    return runLogsCommand(root, args.filter, args.range);
+    return runLogsCommand(root, args.filter, args.range, args.deployment || undefined);
+  }
+  if (args.subcommand === "rollback") {
+    const { runRollbackCommand } = await import("./rollback");
+    return runRollbackCommand(root, args.deployId || undefined);
   }
   if (args.subcommand === "delete") {
     const { runDeleteCommand } = await import("./delete");