feat(eve): warn when Vercel build skips sandbox prewarm (#65)

.changeset/warn-unprewarmed-prebuilt.md

@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Warn when a Vercel build skips sandbox template prewarming because `VERCEL_DEPLOYMENT_ID` is missing, and direct users away from deploying that output with `vercel deploy --prebuilt`.

docs/guides/deployment.md

@@ -94,6 +94,8 @@ During hosted builds, eve prewarms reusable Vercel sandbox templates so the firs
 - Prewarming only covers template construction. `onSession()` still runs at runtime, once per session.
 - **If build-time prewarm fails, the build fails.**
 
+If `VERCEL` is set but `VERCEL_DEPLOYMENT_ID` is missing, eve warns that it skipped prewarming. Do not deploy that build with `vercel deploy --prebuilt`; its output may reference sandbox templates that were never provisioned. Run `vercel deploy` instead so Vercel builds the source in its hosted build environment.
+
 ## 6. Auth
 
 Swap any scaffolded `placeholderAuth()` for your real policy before the first production browser request hits the app. Both the framework default and the placeholder reject production browser traffic, so an unconfigured app fails closed rather than serving open routes. The production policy can be a shipped helper (`httpBasic()`, `jwtHmac()`, `jwtEcdsa()`, `oidc()`, `vercelOidc()`) or a custom `AuthFn` that validates your own sessions, API keys, or identity provider. See [Auth and route protection](./auth-and-route-protection) for the ordered auth walk and the fail-closed guarantee.

packages/eve/src/internal/nitro/host/vercel-build-prewarm.ts

@@ -2,6 +2,11 @@ import { prewarmAppSandboxes } from "#execution/sandbox/prewarm.js";
 
 type PrewarmAppSandboxesInput = Parameters<typeof prewarmAppSandboxes>[0];
 
+const VERCEL_BUILD_PREWARM_SKIPPED_WARNING =
+  "[eve] WARNING: Skipped Vercel sandbox template prewarm because VERCEL_DEPLOYMENT_ID is missing. " +
+  "The generated .vercel/output may reference sandbox templates that were not provisioned. " +
+  'Do not deploy it with "vercel deploy --prebuilt"; use "vercel deploy" so Vercel builds from source.';
+
 /**
  * Detects whether the current build is running inside Vercel with a
  * stable deployment identifier. Build-time sandbox prewarm runs only
@@ -30,6 +35,9 @@ export function shouldPrewarmVercelBuild(): boolean {
  */
 export async function runVercelBuildPrewarm(input: PrewarmAppSandboxesInput): Promise<boolean> {
   if (!shouldPrewarmVercelBuild()) {
+    if (process.env.VERCEL?.trim() && !process.env.VERCEL_DEPLOYMENT_ID?.trim()) {
+      console.warn(VERCEL_BUILD_PREWARM_SKIPPED_WARNING);
+    }
     return false;
   }
   await prewarmAppSandboxes(input);

packages/eve/test/scenarios/vercel-build-prewarm.scenario.test.ts

@@ -80,6 +80,21 @@ describe("Vercel build-time sandbox prewarm", () => {
     expect(shouldPrewarmVercelBuild()).toBe(true);
   });
 
+  it("warns when a Vercel build cannot prewarm sandbox templates", async () => {
+    vi.stubEnv("VERCEL", "1");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+
+    await expect(
+      runVercelBuildPrewarm({
+        appRoot: "/unused",
+      }),
+    ).resolves.toBe(false);
+
+    expect(warn).toHaveBeenCalledWith(
+      '[eve] WARNING: Skipped Vercel sandbox template prewarm because VERCEL_DEPLOYMENT_ID is missing. The generated .vercel/output may reference sandbox templates that were not provisioned. Do not deploy it with "vercel deploy --prebuilt"; use "vercel deploy" so Vercel builds from source.',
+    );
+  });
+
   it("prewarms sandbox templates with per-agent skill seed files", async () => {
     vi.stubEnv("VERCEL", "1");
     vi.stubEnv("VERCEL_DEPLOYMENT_ID", "dpl_test_build_prewarm");