@decocms/blocks-admin 7.0.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@decocms/blocks-admin",
+  "version": "7.0.0",
+  "type": "module",
+  "description": "Deco admin protocol: /live/_meta, /.decofile, /deco/invoke, /deco/render, plus admin-facing site setup and commerce-app auto-configuration",
+  "main": "./src/admin/index.ts",
+  "exports": {
+    ".": "./src/admin/index.ts",
+    "./setup": "./src/createAdminSetup.ts",
+    "./admin/setup": "./src/admin/setup.ts",
+    "./apps": "./src/apps/index.ts",
+    "./apps/autoconfig": "./src/apps/autoconfig.ts",
+    "./sdk/htmlShell": "./src/sdk/htmlShell.ts",
+    "./sdk/setupApps": "./src/sdk/setupApps.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --root ../.. packages/blocks-admin/",
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip"
+  },
+  "dependencies": {
+    "@decocms/blocks": "7.0.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "knip": "^5.86.0",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/admin/cors.ts

@@ -0,0 +1,49 @@
+const ADMIN_ORIGINS = new Set([
+  "https://admin.deco.cx",
+  "https://v0-admin.deco.cx",
+  "https://play.deco.cx",
+  "https://admin-cx.deco.page",
+  "https://deco.chat",
+  "https://admin.decocms.com",
+  "https://decocms.com",
+]);
+
+/**
+ * Register additional allowed admin origins.
+ * Useful for self-hosted admin UIs or custom dashboards.
+ */
+export function registerAdminOrigin(origin: string): void {
+  ADMIN_ORIGINS.add(origin);
+}
+
+/**
+ * Register multiple additional allowed admin origins.
+ */
+export function registerAdminOrigins(origins: string[]): void {
+  for (const origin of origins) {
+    ADMIN_ORIGINS.add(origin);
+  }
+}
+
+export function isAdminOrLocalhost(request: Request): boolean {
+  const origin = request.headers.get("origin") || request.headers.get("referer") || "";
+
+  if (origin.includes("localhost") || origin.includes("127.0.0.1")) {
+    return true;
+  }
+
+  for (const domain of ADMIN_ORIGINS) {
+    if (origin.startsWith(domain)) return true;
+  }
+  return false;
+}
+
+export function corsHeaders(request: Request): Record<string, string> {
+  const origin = request.headers.get("origin") || "*";
+  return {
+    "Access-Control-Allow-Origin": origin,
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, If-None-Match",
+    "Access-Control-Allow-Credentials": "true",
+  };
+}

package/src/admin/decofile.test.ts

@@ -0,0 +1,146 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { KV_KEYS, type KVNamespace, getRevision, loadBlocks, setBlocks } from "@decocms/blocks/cms";
+import { handleDecofileReload, setFastDeployKVGetter } from "./decofile";
+
+// In vitest, import.meta.env.DEV is true, so handleDecofileReload skips the
+// auth check (same branch the dev Vite plugin uses) — no token needed here.
+
+// decofile.ts no longer hard-imports getFastDeployKV (that would create a
+// admin → tanstack dependency, which is backwards). Instead the
+// getter is injected — mirror the enablement rule that used to live in
+// sdk/kvHydration.ts (DECO_FAST_DEPLOY flag + duck-typed DECO_KV binding) so
+// these tests still exercise the KV write-through path end-to-end.
+setFastDeployKVGetter((env) => {
+  const flag = env.DECO_FAST_DEPLOY;
+  if (flag !== "1" && flag !== "true") return null;
+  const binding = env.DECO_KV as KVNamespace | undefined;
+  if (binding && typeof binding.get === "function") return binding;
+  return null;
+});
+
+function reload(payload: unknown, env?: Record<string, unknown>) {
+  const req = new Request("http://x/.decofile", {
+    method: "POST",
+    body: JSON.stringify(payload),
+    headers: { "Content-Type": "application/json" },
+  });
+  return handleDecofileReload(req, env);
+}
+
+function makeKV() {
+  const store = new Map<string, string>();
+  const kv: KVNamespace = {
+    get: (k) => Promise.resolve(store.get(k) ?? null),
+    put: (k, v) => {
+      store.set(k, v);
+      return Promise.resolve();
+    },
+    delete: (k) => {
+      store.delete(k);
+      return Promise.resolve();
+    },
+  };
+  return { kv, store };
+}
+
+beforeEach(() => {
+  setBlocks({ Site: { name: "base" }, "pages-home": { path: "/" } });
+});
+
+describe("handleDecofileReload — full replacement (back-compat)", () => {
+  it("replaces the whole decofile when body is a raw block map", async () => {
+    const full = { Site: { name: "new" }, "pages-x": { path: "/x" } };
+    const res = await reload(full);
+    const json = (await res.json()) as { mode: string; ok: boolean };
+    expect(res.status).toBe(200);
+    expect(json.ok).toBe(true);
+    expect(json.mode).toBe("full");
+    expect(loadBlocks()).toEqual(full);
+  });
+});
+
+describe("handleDecofileReload — delta payloads", () => {
+  it("adds/updates blocks, leaving others intact", async () => {
+    const res = await reload({ blocks: { "pages-x": { path: "/x" } } });
+    const json = (await res.json()) as { mode: string };
+    expect(json.mode).toBe("delta");
+    expect(loadBlocks()).toEqual({
+      Site: { name: "base" },
+      "pages-home": { path: "/" },
+      "pages-x": { path: "/x" },
+    });
+  });
+
+  it("deletes a block when its delta value is null", async () => {
+    await reload({ blocks: { "pages-home": null } });
+    expect(loadBlocks()).toEqual({ Site: { name: "base" } });
+  });
+
+  it("does NOT treat a full decofile that has many keys as a delta", async () => {
+    const res = await reload({ Site: { name: "a" }, blocks: { name: "a block named blocks" } });
+    const json = (await res.json()) as { mode: string };
+    // Two top-level keys → full replacement, not a delta envelope.
+    expect(json.mode).toBe("full");
+  });
+});
+
+describe("handleDecofileReload — KV write-through", () => {
+  it("writes the snapshot + revision to KV when DECO_KV is bound", async () => {
+    const { kv, store } = makeKV();
+    const res = await reload(
+      { blocks: { "pages-x": { path: "/x" } } },
+      { DECO_KV: kv, DECO_FAST_DEPLOY: "1" },
+    );
+    const json = (await res.json()) as { kvWritten: boolean; revision: string };
+
+    expect(json.kvWritten).toBe(true);
+    expect(store.get(KV_KEYS.SNAPSHOT)).toBe(JSON.stringify(loadBlocks()));
+    expect(store.get(KV_KEYS.REVISION)).toBe(getRevision());
+    expect(store.get(KV_KEYS.REVISION)).toBe(json.revision);
+  });
+
+  it("reports kvWritten=false when no KV binding is present", async () => {
+    const res = await reload({ blocks: { "pages-x": { path: "/x" } } }, {});
+    const json = (await res.json()) as { kvWritten: boolean };
+    expect(json.kvWritten).toBe(false);
+  });
+
+  it("reports kvWritten=false when bound but DECO_FAST_DEPLOY is not set", async () => {
+    const { kv, store } = makeKV();
+    const res = await reload({ blocks: { "pages-x": { path: "/x" } } }, { DECO_KV: kv });
+    const json = (await res.json()) as { kvWritten: boolean };
+    expect(json.kvWritten).toBe(false);
+    expect(store.size).toBe(0); // nothing written to KV
+  });
+
+  it("does not fail the request when the KV write throws", async () => {
+    const env = {
+      DECO_FAST_DEPLOY: "1",
+      DECO_KV: {
+        get: () => Promise.resolve(null),
+        put: () => Promise.reject(new Error("KV down")),
+        delete: () => Promise.resolve(),
+      } as KVNamespace,
+    };
+    const res = await reload({ blocks: { "pages-x": { path: "/x" } } }, env);
+    const json = (await res.json()) as { ok: boolean; kvWritten: boolean };
+    expect(res.status).toBe(200);
+    expect(json.ok).toBe(true);
+    expect(json.kvWritten).toBe(false);
+    // Local state still updated despite KV failure.
+    expect(loadBlocks()["pages-x"]).toEqual({ path: "/x" });
+  });
+});
+
+describe("handleDecofileReload — validation", () => {
+  it("returns 400 on invalid JSON", async () => {
+    const req = new Request("http://x/.decofile", { method: "POST", body: "{not json" });
+    const res = await handleDecofileReload(req, {});
+    expect(res.status).toBe(400);
+  });
+
+  it("returns 400 when the body is not an object", async () => {
+    const res = await reload([1, 2, 3], {});
+    expect(res.status).toBe(400);
+  });
+});

package/src/admin/decofile.ts

@@ -0,0 +1,189 @@
+import { KV_KEYS, getRevision, loadBlocks, setBlocks } from "@decocms/blocks/cms";
+import { clearLoaderCache } from "@decocms/blocks/sdk/cachedLoader";
+import { getRuntimeEnv } from "@decocms/blocks/sdk/otelAdapters";
+import { invalidateMetaCache } from "./meta";
+
+type FastDeployKVGetter = (
+  env: Record<string, unknown>,
+) => { get: Function; put: Function; delete: Function } | null;
+
+let getFastDeployKV: FastDeployKVGetter = () => null;
+
+/**
+ * Inject the fast-deploy KV getter. Fast-deploy is Cloudflare/tanstack-only —
+ * `admin` cannot depend on `tanstack`'s `sdk/kvHydration`
+ * directly (that dependency direction is backwards), so the site's own
+ * setup wiring calls this once at startup, e.g.
+ * `setFastDeployKVGetter(getFastDeployKV)` from its own
+ * `sdk/kvHydration`. `next` never calls it, so the KV write-through
+ * below silently no-ops there.
+ */
+export function setFastDeployKVGetter(getter: FastDeployKVGetter): void {
+  getFastDeployKV = getter;
+}
+
+export function handleDecofileRead(): Response {
+  const blocks = loadBlocks();
+  const revision = getRevision();
+
+  return new Response(JSON.stringify(blocks), {
+    status: 200,
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-cache",
+      ...(revision ? { ETag: `"${revision}"` } : {}),
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Delta payloads
+//
+// Studio (admin.deco.cx) and CI can POST a partial update instead of the whole
+// decofile. The delta envelope is:
+//
+//   { "blocks": { "<blockName>": <blockJson> | null, ... } }
+//
+// where a `null` value deletes that block. A delta is identified by a body that
+// has EXACTLY one top-level key, `blocks`, holding an object — a full decofile
+// always carries many top-level block keys (Site, pages-*, …), so there is no
+// realistic collision. Any other object body is treated as a full decofile
+// replacement (backward-compatible with the dev Vite plugin).
+// ---------------------------------------------------------------------------
+
+interface DeltaPayload {
+  blocks: Record<string, unknown | null>;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+function isDeltaPayload(body: unknown): body is DeltaPayload {
+  return isObject(body) && Object.keys(body).length === 1 && isObject(body.blocks);
+}
+
+/** Apply a delta over the current decofile: set non-null values, delete nulls. */
+function applyDelta(
+  base: Record<string, unknown>,
+  delta: Record<string, unknown | null>,
+): Record<string, unknown> {
+  const merged = { ...base };
+  for (const [name, value] of Object.entries(delta)) {
+    if (value === null || value === undefined) {
+      delete merged[name];
+    } else {
+      merged[name] = value;
+    }
+  }
+  return merged;
+}
+
+/**
+ * Write the current in-memory decofile snapshot to KV so other isolates pick
+ * it up on their next revision poll. No-op (returns false) when fast-deploy is
+ * disabled. The revision stored MUST equal the runtime's `getRevision()` so
+ * pollers don't see a permanent mismatch.
+ */
+async function writeSnapshotToKV(env: Record<string, unknown> | undefined): Promise<boolean> {
+  const kv = env ? getFastDeployKV(env) : null;
+  if (!kv) return false;
+
+  const blocks = loadBlocks();
+  const revision = getRevision();
+  await kv.put(KV_KEYS.SNAPSHOT, JSON.stringify(blocks));
+  if (revision) await kv.put(KV_KEYS.REVISION, revision);
+  return true;
+}
+
+export async function handleDecofileReload(
+  request: Request,
+  env?: Record<string, unknown>,
+): Promise<Response> {
+  // Resolve the runtime env once. Prefer an explicitly-passed env, then the
+  // per-request Workers env stashed by workerEntry (`setRuntimeEnv`). Used for
+  // both the reload token and the fast-deploy KV binding.
+  const runtimeEnv = env ?? getRuntimeEnv();
+
+  // In dev mode the Vite plugin POSTs new blocks here to hot-reload without
+  // module invalidation (which breaks TanStack Start/Router state). Skip auth
+  // so the plugin can POST from localhost.
+  // Uses import.meta.env.DEV directly (not isDevMode()) because isDevMode()
+  // bypass auth. Vite statically replaces import.meta.env.DEV with `false`
+  // in production builds, so this branch is dead-code-eliminated.
+  const isViteDev = !!(import.meta as unknown as { env?: { DEV?: boolean } }).env?.DEV;
+  if (!isViteDev) {
+    const authHeader = request.headers.get("Authorization") || "";
+    const expectedToken =
+      (runtimeEnv?.DECO_RELEASE_RELOAD_TOKEN as string | undefined) ??
+      (typeof globalThis.process !== "undefined"
+        ? globalThis.process.env?.DECO_RELEASE_RELOAD_TOKEN
+        : undefined);
+
+    if (!expectedToken || authHeader !== expectedToken) {
+      return new Response("Unauthorized", { status: 401 });
+    }
+  }
+
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return new Response(JSON.stringify({ error: "Invalid JSON body" }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  if (!isObject(body)) {
+    return new Response(JSON.stringify({ error: "Body must be a JSON object" }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  const previousBlockCount = Object.keys(loadBlocks()).length;
+
+  // Delta merge (partial update) or full decofile replacement.
+  let nextBlocks: Record<string, unknown>;
+  let isDelta: boolean;
+  if (isDeltaPayload(body)) {
+    nextBlocks = applyDelta(loadBlocks(), body.blocks);
+    isDelta = true;
+  } else {
+    nextBlocks = body;
+    isDelta = false;
+  }
+
+  setBlocks(nextBlocks);
+  // Invalidate the meta ETag so the admin re-fetches the schema on next poll.
+  invalidateMetaCache();
+  // Clear stale loader cache entries after decofile update
+  clearLoaderCache();
+
+  // Fast-deploy: persist the new snapshot to KV so other isolates converge.
+  // A failed KV write does NOT fail the request — this isolate is already
+  // updated; we surface `kvWritten: false` so the caller can retry.
+  let kvWritten = false;
+  try {
+    kvWritten = await writeSnapshotToKV(runtimeEnv);
+  } catch (e) {
+    console.warn("[CMS/KV] write-through after publish failed:", e);
+  }
+
+  const newBlockCount = Object.keys(nextBlocks).length;
+  const revision = getRevision();
+
+  return new Response(
+    JSON.stringify({
+      ok: true,
+      mode: isDelta ? "delta" : "full",
+      previousBlockCount,
+      newBlockCount,
+      revision,
+      kvWritten,
+      timestamp: Date.now(),
+    }),
+    { status: 200, headers: { "Content-Type": "application/json" } },
+  );
+}

package/src/admin/index.ts

@@ -0,0 +1,29 @@
+export { corsHeaders, isAdminOrLocalhost, registerAdminOrigin, registerAdminOrigins } from "./cors";
+export { handleDecofileRead, handleDecofileReload, setFastDeployKVGetter } from "./decofile";
+export {
+  clearInvokeHandlers,
+  handleInvoke,
+  type InvokeAction,
+  type InvokeLoader,
+  registerInvokeHandlers,
+  setInvokeActions,
+  setInvokeLoaders,
+} from "./invoke";
+export { LIVE_CONTROLS_SCRIPT } from "./liveControls";
+export { handleMeta, setMetaData } from "./meta";
+export { handleRender, setPreviewWrapper, setRenderShell } from "./render";
+export {
+  composeMeta,
+  getRegisteredLoaders,
+  getRegisteredMatchers,
+  type ActionConfig,
+  type LoaderConfig,
+  type MatcherConfig,
+  type MetaResponse,
+  registerActionSchema,
+  registerActionSchemas,
+  registerLoaderSchema,
+  registerLoaderSchemas,
+  registerMatcherSchema,
+  registerMatcherSchemas,
+} from "@decocms/blocks/cms";

package/src/admin/invoke.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Regression tests for /deco/invoke Set-Cookie propagation.
+ *
+ * The historical bug: the single- and batch-invoke paths copied
+ * `RequestContext.responseHeaders` to the HTTP response via
+ * `headers.entries()`, which collapses multiple `Set-Cookie` values
+ * into a single comma-joined string. Browsers silently discard those,
+ * so every VTEX cart action lost its session cookies and the user
+ * ended up at /checkout with an empty cart.
+ *
+ * These tests pin the fix: when a handler appends multiple
+ * Set-Cookie values to `RequestContext.responseHeaders`, the response
+ * returned by `handleInvoke` must surface them as N distinct
+ * Set-Cookie headers (readable via `response.headers.getSetCookie()`).
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import {
+  clearInvokeHandlers,
+  handleInvoke,
+  registerInvokeHandlers,
+} from "./invoke";
+
+const COOKIE_A = "checkout.vtex.com__orderFormId=of-123; Path=/; HttpOnly";
+const COOKIE_B = "segment=eyJjYW1wYWlnbnMiOiJ4In0=; Path=/; HttpOnly";
+const COOKIE_C = "sc=1; Path=/; HttpOnly";
+
+function makeInvokeRequest(key: string, body: unknown = {}): Request {
+  return new Request(`http://localhost/deco/invoke/${key}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+function makeBatchRequest(body: Record<string, unknown>): Request {
+  return new Request("http://localhost/deco/invoke", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+describe("handleInvoke — Set-Cookie propagation (single)", () => {
+  beforeEach(() => clearInvokeHandlers());
+  afterEach(() => clearInvokeHandlers());
+
+  it("forwards multiple Set-Cookie values as distinct headers", async () => {
+    registerInvokeHandlers({
+      "vtex/actions/addItemsToCart": async () => {
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_A);
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_B);
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_C);
+        return { orderFormId: "of-123" };
+      },
+    });
+
+    const request = makeInvokeRequest("vtex/actions/addItemsToCart");
+    const response = await RequestContext.run(request, () => handleInvoke(request));
+
+    const cookies = response.headers.getSetCookie();
+    expect(cookies).toHaveLength(3);
+    expect(cookies).toContain(COOKIE_A);
+    expect(cookies).toContain(COOKIE_B);
+    expect(cookies).toContain(COOKIE_C);
+  });
+
+  it("does not collapse cookies into a single Set-Cookie entry", async () => {
+    registerInvokeHandlers({
+      "vtex/actions/foo": async () => {
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_A);
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_B);
+        return {};
+      },
+    });
+
+    const request = makeInvokeRequest("vtex/actions/foo");
+    const response = await RequestContext.run(request, () => handleInvoke(request));
+
+    // The regressed bug appended a single comma-joined string, so
+    // `getSetCookie()` returned a 1-element array. The fix appends each
+    // value individually — verifying the count alone catches the regression.
+    expect(response.headers.getSetCookie()).toHaveLength(2);
+  });
+
+  it("forwards non-cookie headers unchanged", async () => {
+    registerInvokeHandlers({
+      "vtex/actions/withHeader": async () => {
+        RequestContext.responseHeaders.append("x-vtex-trace-id", "abc-123");
+        return {};
+      },
+    });
+
+    const request = makeInvokeRequest("vtex/actions/withHeader");
+    const response = await RequestContext.run(request, () => handleInvoke(request));
+    expect(response.headers.get("x-vtex-trace-id")).toBe("abc-123");
+  });
+
+  it("does not forward Set-Cookie when handler writes none", async () => {
+    registerInvokeHandlers({
+      "vtex/loaders/productList": async () => ({ items: [] }),
+    });
+
+    const request = makeInvokeRequest("vtex/loaders/productList");
+    const response = await RequestContext.run(request, () => handleInvoke(request));
+    expect(response.headers.getSetCookie()).toEqual([]);
+  });
+});
+
+describe("handleInvoke — Set-Cookie propagation (batch)", () => {
+  beforeEach(() => clearInvokeHandlers());
+  afterEach(() => clearInvokeHandlers());
+
+  it("forwards cookies that batch handlers append to the shared context", async () => {
+    registerInvokeHandlers({
+      "vtex/actions/addItemsToCart": async () => {
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_A);
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_B);
+        return { orderFormId: "of-123" };
+      },
+      "vtex/loaders/productList": async () => {
+        // Loader writes its own cookie (e.g. segment) — must also propagate.
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_C);
+        return { items: [] };
+      },
+    });
+
+    const request = makeBatchRequest({
+      "vtex/actions/addItemsToCart": { orderFormId: "x" },
+      "vtex/loaders/productList": {},
+    });
+    const response = await RequestContext.run(request, () => handleInvoke(request));
+
+    const cookies = response.headers.getSetCookie();
+    expect(cookies).toHaveLength(3);
+    expect(cookies).toContain(COOKIE_A);
+    expect(cookies).toContain(COOKIE_B);
+    expect(cookies).toContain(COOKIE_C);
+  });
+});