@decocms/blocks 7.6.0 → 7.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.6.0",
+  "version": "7.7.0",
   "type": "module",
   "description": "Deco framework-agnostic core: CMS block resolution, section registry, matchers, portable SDK utilities",
   "repository": {

package/src/cms/blockSource.test.ts

@@ -2,8 +2,11 @@ import { describe, expect, it } from "vitest";
 import {
   BundledBlockSource,
   computeRevision,
-  KV_KEYS,
+  DEPLOYMENTS_KEY,
   type KVNamespace,
+  LIVE_KEY,
+  revisionKey,
+  snapshotKey,
 } from "./blockSource";
 import { djb2Hex } from "../sdk/djb2";
 
@@ -37,10 +40,15 @@ describe("BundledBlockSource", () => {
   });
 });
 
-describe("KV_KEYS", () => {
-  it("exposes the snapshot and revision key contract", () => {
-    expect(KV_KEYS.SNAPSHOT).toBe("decofile:current");
-    expect(KV_KEYS.REVISION).toBe("index:revision");
+describe("KV key layout (per deployment)", () => {
+  it("keys the snapshot and revision by deployment id", () => {
+    expect(snapshotKey("abc123")).toBe("decofile:abc123");
+    expect(revisionKey("abc123")).toBe("index:revision:abc123");
+  });
+
+  it("exposes stable pointer/bookkeeping keys", () => {
+    expect(LIVE_KEY).toBe("index:live");
+    expect(DEPLOYMENTS_KEY).toBe("index:deployments");
   });
 });
 
@@ -59,9 +67,10 @@ describe("KVNamespace structural type", () => {
       },
     };
 
-    await kv.put(KV_KEYS.REVISION, "abc");
-    await expect(kv.get(KV_KEYS.REVISION)).resolves.toBe("abc");
-    await kv.delete(KV_KEYS.REVISION);
-    await expect(kv.get(KV_KEYS.REVISION)).resolves.toBeNull();
+    const key = revisionKey("abc123");
+    await kv.put(key, "abc");
+    await expect(kv.get(key)).resolves.toBe("abc");
+    await kv.delete(key);
+    await expect(kv.get(key)).resolves.toBeNull();
   });
 });

package/src/cms/blockSource.ts

@@ -37,8 +37,8 @@ export interface BlockSnapshot {
  * - `BundledBlockSource` — the build-time `blocks.gen` snapshot (fallback /
  *   local dev). A no-op here because `setup.ts` already loads it via
  *   `setBlocks()` at module init.
- * - `KVBlockSource` (PR2) — reads `decofile:current` + `index:revision` from a
- *   Cloudflare KV namespace.
+ * - `KVBlockSource` — reads `decofile:<id>` + `index:revision:<id>` (keyed by
+ *   deployment id) from a Cloudflare KV namespace.
  */
 export interface BlockSource {
   /**
@@ -111,14 +111,81 @@ export interface KVNamespace {
 }
 
 // ---------------------------------------------------------------------------
-// KV key names — shared by the runtime reader (PR2), the write-through path
-// (PR3), and the CI sync/migrate scripts (PR4). Single source of truth so the
-// contract can't drift between read and write sides.
+// KV key layout — keyed by DEPLOYMENT ID so every code deployment reads its own
+// content snapshot (deploy isolation, cheap rollback, build-time content sync).
+//
+// The deployment id is the git commit sha (see `getDeploymentId` below).
+// Shared by the runtime reader (`kvBlockSource.ts`), the write-through path
+// (`admin/decofile.ts`), and the CI sync/migrate scripts, so the contract can't
+// drift between read and write sides.
+//
+//   decofile:<id>          full decofile JSON for deployment <id>
+//   index:revision:<id>    DJB2 hex revision of that snapshot (polled)
+//   index:live             pointer to the currently-live <id> (set post-deploy)
+//   index:deployments      JSON [{id, ts}] (newest last) — GC bookkeeping
 // ---------------------------------------------------------------------------
 
-export const KV_KEYS = {
-  /** Full decofile JSON (the blocks map). */
-  SNAPSHOT: "decofile:current",
-  /** DJB2 hex revision of the snapshot — polled for change detection. */
-  REVISION: "index:revision",
-} as const;
+/** KV key holding the full decofile JSON for deployment `id`. */
+export function snapshotKey(id: string): string {
+  return `decofile:${id}`;
+}
+
+/** KV key holding the DJB2 hex revision of deployment `id`'s snapshot. */
+export function revisionKey(id: string): string {
+  return `index:revision:${id}`;
+}
+
+/** Pointer key naming the currently-live deployment id. Written by a code
+ * deploy AFTER the new version has activated (so a rolling deploy never points
+ * live at a version that isn't serving yet). */
+export const LIVE_KEY = "index:live";
+
+/** Bookkeeping key: JSON array of `{ id, ts }` (newest last) tracking known
+ * deployment snapshots so the sync script can GC all but the last N. */
+export const DEPLOYMENTS_KEY = "index:deployments";
+
+// ---------------------------------------------------------------------------
+// Deployment id resolution
+//
+// Which snapshot key does THIS running worker read/write? The deployment id.
+// Kept here (framework-agnostic) alongside the key builders it feeds, so the
+// runtime read path (`@decocms/tanstack` kvHydration) and the write-through
+// path (`@decocms/blocks-admin` decofile) resolve it identically — no drift.
+// ---------------------------------------------------------------------------
+
+/** Deploy-time var naming this version's content snapshot key. Set by the
+ * deploy command (`wrangler deploy --var DECO_DEPLOYMENT_ID:<sha>`). */
+export const DEPLOYMENT_ID_ENV = "DECO_DEPLOYMENT_ID";
+
+/** Fallback var (cache-key version) — the same commit sha, already threaded by
+ * some sites via `--var BUILD_HASH:<sha>`. */
+export const BUILD_HASH_ENV = "BUILD_HASH";
+
+// Build-time constant injected by the tanstack `decoVitePlugin()` (git
+// rev-parse / WORKERS_CI_COMMIT_SHA) as the last-resort deployment id. Declared
+// here with a `typeof` guard so it's inert where the define isn't applied
+// (e.g. the Next.js build, or this package's own tsc output).
+declare const __DECO_BUILD_HASH__: string | undefined;
+
+/**
+ * Resolve this worker's deployment id — the key its content is stored under
+ * (`decofile:<id>`). Priority:
+ *   1. `env.DECO_DEPLOYMENT_ID` — set by the deploy command (authoritative).
+ *   2. `env.BUILD_HASH` — the cache-key version var; the same commit sha.
+ *   3. `__DECO_BUILD_HASH__` — build-time constant (the commit the bundle, and
+ *      thus the build-time content sync, was produced from).
+ * Returns `null` when none resolves — the caller then serves the bundled
+ * snapshot (never another deployment's content).
+ */
+export function getDeploymentId(env: Record<string, unknown>): string | null {
+  const fromDeploymentVar = env[DEPLOYMENT_ID_ENV];
+  if (typeof fromDeploymentVar === "string" && fromDeploymentVar) {
+    return fromDeploymentVar;
+  }
+  const fromBuildHash = env[BUILD_HASH_ENV];
+  if (typeof fromBuildHash === "string" && fromBuildHash) return fromBuildHash;
+  if (typeof __DECO_BUILD_HASH__ !== "undefined" && __DECO_BUILD_HASH__) {
+    return __DECO_BUILD_HASH__;
+  }
+  return null;
+}

package/src/cms/index.ts

@@ -1,5 +1,15 @@
 export type { BlockSnapshot, BlockSource, KVNamespace } from "./blockSource";
-export { BundledBlockSource, computeRevision, KV_KEYS } from "./blockSource";
+export {
+  BUILD_HASH_ENV,
+  BundledBlockSource,
+  computeRevision,
+  DEPLOYMENT_ID_ENV,
+  DEPLOYMENTS_KEY,
+  getDeploymentId,
+  LIVE_KEY,
+  revisionKey,
+  snapshotKey,
+} from "./blockSource";
 export type { DecoPage, Resolvable } from "./loader";
 export {
   findPageByPath,

package/src/cms/layoutCacheRace.test.ts

@@ -9,7 +9,7 @@ import {
 
 /**
  * Regression test for the layout-cache index-corruption bug that shipped in
- * @decocms/start@6.12.1 and was fixed in 6.12.2 (deco-start commit 73d4f19,
+ * @decocms/start@6.12.1 and was fixed in 6.12.2 (blocks commit 73d4f19,
  * "fix(cms): don't mutate shared cached section objects when stamping
  * index"). Two live production sites (casaevideo-tanstack, bagaggio-tanstack)
  * hit this in the wild as an intermittent "footer renders above other

package/src/cms/loadDecofileDirectory.ts

@@ -18,7 +18,7 @@ import { join } from "node:path";
  * passes the on-disk filename through.
  *
  * Replaces the abandoned @decocms/start/node tier's loadAllDecofileBlocks,
- * which no longer exists on any reachable deco-start version — ported
+ * which no longer exists on any reachable blocks version — ported
  * fresh rather than resurrected. Namespace-imported node:fs/promises to
  * match this codebase's existing pattern for Node-only code that must not
  * break Vite/webpack client bundle analysis (see cms/loader.ts's

package/src/cms/resolve.ts

@@ -331,7 +331,7 @@ function hasForceEagerParam(ctx?: MatcherContext): boolean {
  * they CAN hydrate and resolve deferred sections. SPA navigations (TanStack
  * `<Link>` → `/_serverFn`) also send `empty` but set `isClientNavigation`, and
  * are excluded here so page-SEO commerce loaders stay off for humans
- * (decocms/deco-start#286); their sections already render eagerly via the
+ * (decocms/blocks#286); their sections already render eagerly via the
  * `!isClientNav` branch of the `useAsync` gate.
  *
  * Like {@link hasForceEagerParam}, this must stay in lock-step with the edge
@@ -395,7 +395,7 @@ export interface MatcherContext {
    * deferral: deferral is a streaming-SSR optimization, but a client nav
    * receives the server-fn JSON in one shot, so deferral adds a round-trip +
    * skeleton with no benefit (and breaks loaders that need per-request app
-   * context — see decocms/deco-start#277). Set by the route loaders.
+   * context — see decocms/blocks#277). Set by the route loaders.
    */
   isClientNavigation?: boolean;
 }
@@ -667,7 +667,7 @@ export function evaluateMatcher(
 /**
  * Matcher types whose decision must stick per user instead of re-rolling every
  * request. Mirrors the `sticky = "session"` export on the corresponding
- * matchers in @decocms/apps (deco-start re-implements matchers inline, so it
+ * matchers in @decocms/apps (blocks re-implements matchers inline, so it
  * declares the set here rather than importing those exports).
  */
 const STICKY_MATCHER_TYPES = new Set(["website/matchers/random.ts"]);

package/src/sdk/flags.ts

@@ -18,7 +18,7 @@
  * `btoa(encodeURIComponent(JSON.stringify({ active, inactiveDrawn, pct })))`.
  * - `active` — flag names the visitor was assigned to (`true` branch).
  * - `inactiveDrawn` — flag names drawn but not matched (`false` branch).
- * - `pct` — `{ name: round(traffic*100) }`, a deco-start extension (analytics
+ * - `pct` — `{ name: round(traffic*100) }`, a blocks extension (analytics
  *   ignores unknown fields) used as the re-roll fingerprint: when the operator
  *   changes `traffic` and redeploys, the fingerprint no longer matches and the
  *   visitor is re-rolled once, then re-sticks — same self-healing scheme as
@@ -47,7 +47,7 @@ export interface StoredFlag {
 interface DecoSegment {
   active?: string[];
   inactiveDrawn?: string[];
-  /** deco-start extension: per-flag traffic fingerprint. Ignored by analytics. */
+  /** blocks extension: per-flag traffic fingerprint. Ignored by analytics. */
   pct?: Record<string, number>;
 }
 

package/src/sdk/inflightTimeout.ts

@@ -42,7 +42,7 @@ export function withInflightTimeout<T>(
     timer = setTimeout(() => {
       reject(
         new Error(
-          `[deco-start] inflight cache entry "${label}" timed out after ${ms}ms`,
+          `[blocks] inflight cache entry "${label}" timed out after ${ms}ms`,
         ),
       );
     }, ms);

package/src/sdk/otelAdapters/clickhouseCollector.ts

@@ -60,6 +60,6 @@ export function createClickhouseCollectorAdapter(_options: ClickhouseCollectorOp
       "Until then, use Cloudflare-native observability " +
       "(observability.{logs,traces} in wrangler.jsonc) plus the Workers " +
       "Analytics Engine meter wired by instrumentWorker(). Track progress " +
-      "at https://github.com/decocms/deco-start/issues.",
+      "at https://github.com/decocms/blocks/issues.",
   );
 }