@decocms/start 4.5.0 → 4.6.0

package/.cursor/skills/deco-edge-caching/SKILL.md

@@ -183,17 +183,21 @@ This is per-isolate in-memory cache (V8 Map). Resets on cold start. Includes req
 
 ## Cache Versioning with BUILD_HASH
 
-Deploy-time cache busting uses a `BUILD_HASH` environment variable (typically the git short SHA) passed to `wrangler deploy`. The worker-entry appends this to cache keys so deploying a new version automatically serves fresh content.
-
-```yaml
-# .github/workflows/deploy.yml
-- name: Deploy to Cloudflare Workers
-  run: npx wrangler deploy
-  env:
-    BUILD_HASH: ${{ github.sha }}
-```
+Every cached entry's key is suffixed with `__v=<hash>` so a new deploy starts a fresh cache namespace and previously-cached HTML (which references now-deleted asset filenames like `/assets/main-XYZ.js`) stops being served the moment the new worker is live. Old entries become orphaned and expire naturally — no purge endpoint call required.
+
+The hash is resolved automatically by `decoVitePlugin()` at build time and injected into the worker bundle as `__DECO_BUILD_HASH__`. Resolution order:
+
+1. `WORKERS_CI_COMMIT_SHA` — Cloudflare Workers Builds default env var ([CF docs](https://developers.cloudflare.com/changelog/2025-06-10-default-env-vars/)). This is the production deploy path-of-record per `MIGRATION_TOOLING_PLAN.md` D6.3.
+2. `git rev-parse --short=12 HEAD` — for someone running `wrangler deploy` from a developer laptop.
+3. `Date.now().toString(36)` — last-resort fallback so the cache-bust invariant never silently regresses.
+
+`createDecoWorkerEntry` reads `env.BUILD_HASH` first (explicit override path, e.g. `wrangler deploy --var BUILD_HASH:foo`) and falls back to the `__DECO_BUILD_HASH__` constant. Sites running `decoVitePlugin()` get the behaviour for free — **no per-site dashboard, `wrangler.jsonc`, or `--var` configuration required**.
 
-The worker-entry reads `env.BUILD_HASH` and injects it into cache keys. On new deploys, old cache entries simply expire naturally — no purge needed.
+The active version is exposed on every cached response via the `X-Cache-Version` header for observability. Confirm a new deploy is shipping the right hash with:
+
+```bash
+curl -sI https://www.example.com/ | grep -i x-cache-version
+```
 
 ## Site-Level Cache Pattern Registration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/src/sdk/workerEntry.ts

@@ -45,6 +45,17 @@ import { getAppMiddleware } from "./setupApps";
 import { cleanPathForCacheKey } from "./urlUtils";
 import { type Device, isMobileUA } from "./useDevice";
 
+/**
+ * Build-time identifier injected by `decoVitePlugin()` (see
+ * `src/vite/plugin.js`). Falls back to `undefined` if the consuming site
+ * isn't using the plugin or the symbol wasn't `define`d at bundle time.
+ *
+ * The runtime `env.BUILD_HASH` (when explicitly set, e.g. via
+ * `wrangler deploy --var BUILD_HASH:foo`) takes precedence — see
+ * `getBuildHash()` below.
+ */
+declare const __DECO_BUILD_HASH__: string | undefined;
+
 /**
  * Append Link preload headers for CSS and fonts so the browser starts
  * fetching them before parsing HTML. Only applied to HTML responses.
@@ -673,6 +684,23 @@ export function createDecoWorkerEntry(
     return parts.join("|");
   }
 
+  /**
+   * Resolve the per-deploy cache-key version with this priority:
+   *   1. `env[cacheVersionEnv]` — explicit override (e.g. `wrangler
+   *      deploy --var BUILD_HASH:foo`). Wins so callers can always
+   *      force a specific value.
+   *   2. `__DECO_BUILD_HASH__` — build-time constant injected by
+   *      `decoVitePlugin()` from WORKERS_CI_COMMIT_SHA / git rev-parse.
+   *      This is the production path on Cloudflare Workers Builds.
+   *   3. Empty string — versioning disabled (legacy pre-plugin sites).
+   */
+  function getBuildHash(env: Record<string, unknown>): string {
+    if (cacheVersionEnv === false) return "";
+    const fromEnv = (env[cacheVersionEnv] as string) || "";
+    if (fromEnv) return fromEnv;
+    return typeof __DECO_BUILD_HASH__ !== "undefined" ? __DECO_BUILD_HASH__ : "";
+  }
+
   function buildCacheKey(
     request: Request,
     env: Record<string, unknown>,
@@ -685,11 +713,9 @@ export function createDecoWorkerEntry(
       url.search = cleanUrl.search;
     }
 
-    if (cacheVersionEnv !== false) {
-      const version = (env[cacheVersionEnv] as string) || "";
-      if (version) {
-        url.searchParams.set("__v", version);
-      }
+    const version = getBuildHash(env);
+    if (version) {
+      url.searchParams.set("__v", version);
     }
 
     // Include CF geo data in cache key so location matcher results don't leak
@@ -791,10 +817,8 @@ export function createDecoWorkerEntry(
         for (const seg of segments) {
           for (const cc of geoKeys) {
             const url = new URL(p, baseUrl);
-            if (cacheVersionEnv !== false) {
-              const version = (env[cacheVersionEnv] as string) || "";
-              if (version) url.searchParams.set("__v", version);
-            }
+            const purgeVersion = getBuildHash(env);
+            if (purgeVersion) url.searchParams.set("__v", purgeVersion);
             url.searchParams.set("__seg", hashSegment(seg));
             if (cc) url.searchParams.set("__cf_geo", cc);
             const key = new Request(url.toString(), { method: "GET" });
@@ -816,10 +840,8 @@ export function createDecoWorkerEntry(
         for (const device of devices) {
           for (const cc of geoKeys) {
             const url = new URL(p, baseUrl);
-            if (cacheVersionEnv !== false) {
-              const version = (env[cacheVersionEnv] as string) || "";
-              if (version) url.searchParams.set("__v", version);
-            }
+            const purgeVersion = getBuildHash(env);
+            if (purgeVersion) url.searchParams.set("__v", purgeVersion);
             if (device) url.searchParams.set("__cf_device", device);
             if (cc) url.searchParams.set("__cf_geo", cc);
             const key = new Request(url.toString(), { method: "GET" });
@@ -1190,10 +1212,8 @@ export function createDecoWorkerEntry(
       // different regions or channels get separate cache entries.
       const cacheKeyUrl = new URL(request.url);
       cacheKeyUrl.searchParams.set("__body", bodyHash);
-      if (cacheVersionEnv !== false) {
-        const version = (env[cacheVersionEnv] as string) || "";
-        if (version) cacheKeyUrl.searchParams.set("__v", version);
-      }
+      const sfnVersion = getBuildHash(env);
+      if (sfnVersion) cacheKeyUrl.searchParams.set("__v", sfnVersion);
       if (sfnSegment) {
         cacheKeyUrl.searchParams.set("__seg", hashSegment(sfnSegment));
       } else if (deviceSpecificKeys) {
@@ -1409,10 +1429,8 @@ export function createDecoWorkerEntry(
       out.headers.set("X-Cache", xCache);
       out.headers.set("X-Cache-Profile", profile);
       if (segment) out.headers.set("X-Cache-Segment", hashSegment(segment));
-      if (cacheVersionEnv !== false) {
-        const v = (env[cacheVersionEnv] as string) || "";
-        if (v) out.headers.set("X-Cache-Version", v);
-      }
+      const headerVersion = getBuildHash(env);
+      if (headerVersion) out.headers.set("X-Cache-Version", headerVersion);
       if (extra) for (const [k, v] of Object.entries(extra)) out.headers.set(k, v);
       appendResourceHints(out);
       return out;

package/src/vite/plugin.js

@@ -31,8 +31,49 @@
  * export default defineConfig({ plugins: [decoVitePlugin(), ...] });
  * ```
  */
+import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 
+/**
+ * Resolve a per-build identifier for cache-key versioning.
+ *
+ * The returned string is injected into the worker bundle as the
+ * `__DECO_BUILD_HASH__` global via Vite `define`. `createDecoWorkerEntry`
+ * appends it (or `env.BUILD_HASH` if explicitly set) as `__v=<hash>` on
+ * every Cache API key, so each new deploy gets its own cache namespace
+ * — old edge-cached HTML referencing dead asset filenames stops being
+ * served the moment the new worker is live.
+ *
+ * Resolution order:
+ *   1. WORKERS_CI_COMMIT_SHA — Cloudflare Workers Builds default env var
+ *      (the production deploy path-of-record). Sliced to 12 chars.
+ *   2. `git rev-parse --short=12 HEAD` — local `wrangler deploy` from a
+ *      developer laptop. Try/catch so missing git or shallow clones don't
+ *      fail the build.
+ *   3. `Date.now().toString(36)` — last-resort fallback so the cache-bust
+ *      invariant never silently regresses to "always the same key".
+ *
+ * For dev (`command !== "build"`), the value is the literal `"dev"`.
+ *
+ * @returns {string}
+ */
+function resolveBuildHash() {
+  const ciSha = process.env.WORKERS_CI_COMMIT_SHA;
+  if (ciSha?.trim()) return ciSha.trim().slice(0, 12);
+
+  try {
+    const sha = execFileSync("git", ["rev-parse", "--short=12", "HEAD"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (sha) return sha;
+  } catch {
+    // git absent, not a repo, or shallow clone w/o history — fall through.
+  }
+
+  return Date.now().toString(36);
+}
+
 // Bare-specifier stubs resolved by ID before Vite touches them.
 /** @type {Record<string, string>} */
 const CLIENT_STUBS = {
@@ -227,6 +268,20 @@ export function decoVitePlugin() {
         };
       }
 
+      // Inject a per-build identifier as `__DECO_BUILD_HASH__` so
+      // createDecoWorkerEntry can fall back to it when env.BUILD_HASH is
+      // unset (the default on Cloudflare Workers Builds, where there's
+      // no GH-Actions step injecting --var BUILD_HASH).
+      //
+      // Dev gets the literal "dev" so SSR doesn't crash on an undefined
+      // identifier; prod gets WORKERS_CI_COMMIT_SHA → git rev-parse →
+      // time-based fallback (see resolveBuildHash above).
+      const buildHash = command === "build" ? resolveBuildHash() : "dev";
+      cfg.define = {
+        ...cfg.define,
+        __DECO_BUILD_HASH__: JSON.stringify(buildHash),
+      };
+
       // Only split chunks for production builds — dev uses unbundled ESM.
       if (command !== "build") return cfg;
       return {

package/src/vite/plugin.test.js

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { decoVitePlugin } from "./plugin.js";
 
 /**
@@ -52,3 +52,62 @@ describe("decoVitePlugin client stubs (regression guard)", () => {
     expect(id).toBeUndefined();
   });
 });
+
+describe("decoVitePlugin __DECO_BUILD_HASH__ injection", () => {
+  let originalEnv;
+
+  beforeEach(() => {
+    originalEnv = { ...process.env };
+    delete process.env.WORKERS_CI_COMMIT_SHA;
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    vi.restoreAllMocks();
+  });
+
+  function callConfig(command) {
+    const p = getPlugin();
+    return p.config({}, { command });
+  }
+
+  it("injects the literal 'dev' for non-build commands", () => {
+    const cfg = callConfig("serve");
+    expect(cfg.define.__DECO_BUILD_HASH__).toBe(JSON.stringify("dev"));
+  });
+
+  it("uses WORKERS_CI_COMMIT_SHA (sliced to 12 chars) when set on a build", () => {
+    process.env.WORKERS_CI_COMMIT_SHA = "abcdef1234567890fedcba";
+    const cfg = callConfig("build");
+    expect(cfg.define.__DECO_BUILD_HASH__).toBe(JSON.stringify("abcdef123456"));
+  });
+
+  it("falls back to git rev-parse when WORKERS_CI_COMMIT_SHA is unset", async () => {
+    // The plugin module imports execFileSync at top-level, so we can't easily
+    // mock it after the fact. Instead, exercise the real git binary against
+    // this repo (CI runs in the repo working tree). Assert the value is a
+    // 12-char lowercase hex SHA — that proves git was consulted, not that
+    // the time-based fallback was hit.
+    const cfg = callConfig("build");
+    const value = JSON.parse(cfg.define.__DECO_BUILD_HASH__);
+    // Either git produced a SHA (CI / dev machine inside a repo) or the
+    // time-based fallback ran. Both are acceptable; we just assert non-empty
+    // and length sanity.
+    expect(typeof value).toBe("string");
+    expect(value.length).toBeGreaterThan(0);
+    // Time-based fallback produces base36 characters; git short SHAs are
+    // 12 hex chars. Both fit in this superset regex.
+    expect(value).toMatch(/^[0-9a-z]+$/);
+  });
+
+  it("preserves allowedHosts behaviour (regression: define is additive, not replacing)", () => {
+    process.env.DECO_SITE_NAME = "test-site";
+    try {
+      const cfg = callConfig("serve");
+      expect(cfg.server?.allowedHosts).toContain(".deco.studio");
+      expect(cfg.define.__DECO_BUILD_HASH__).toBeDefined();
+    } finally {
+      delete process.env.DECO_SITE_NAME;
+    }
+  });
+});

package/vitest.config.ts

@@ -11,7 +11,7 @@ export default defineConfig({
       ["scripts/**", "node"],
     ],
     include: [
-      "src/**/*.test.{ts,tsx}",
+      "src/**/*.test.{ts,tsx,js}",
       "scripts/**/*.test.ts",
     ],
     globals: true,