@decocms/blocks-cli 7.20.3 → 7.20.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.20.3",
+  "version": "7.20.5",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -30,7 +30,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.20.3",
+    "@decocms/blocks": "7.20.5",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/migrate/phase-scaffold.ts

@@ -14,6 +14,7 @@ import { generateAppCss } from "./templates/app-css";
 import { generateTypeFiles } from "./templates/types-gen";
 import { generateUiComponents } from "./templates/ui-components";
 import { generateHooks } from "./templates/hooks";
+import { generateCommerceInit } from "./templates/commerce-init";
 import { generateCommerceLoaders } from "./templates/commerce-loaders";
 import { generateSectionLoaders } from "./templates/section-loaders";
 import { generateCacheConfig } from "./templates/cache-config";
@@ -110,6 +111,10 @@ export function scaffold(ctx: MigrationContext): void {
   writeFile(ctx, "src/setup.ts", generateSetup(ctx));
   writeFile(ctx, "src/cache-config.ts", generateCacheConfig(ctx));
   writeFile(ctx, "src/setup/commerce-loaders.ts", generateCommerceLoaders(ctx));
+  // Server-only registration of COMMERCE_LOADERS + invoke — imported by
+  // worker-entry.ts, not setup.ts, so the loader/action graph stays out of the
+  // client bundle.
+  writeFile(ctx, "src/setup/commerce-init.ts", generateCommerceInit(ctx));
   writeFile(ctx, "src/setup/section-loaders.ts", generateSectionLoaders(ctx));
 
   // Theme extraction + Styles
@@ -262,13 +267,13 @@ vite.config.timestamp_*
 
 # Deco CMS
 .deco/metadata/*
-# Generated snapshots — do NOT commit. Both are 100% derived (blocks.gen.json
-# merges .deco/blocks/*.json; meta.gen.json is built from the TS source) and are
-# regenerated by \`npm run generate\` (build) and on dev cold-start. blocks.gen.json
-# is a single 10MB+ line, so committing it makes every content PR conflict
-# irresolvably. The small .gen.ts stubs and generate.digests.json stay committed.
+# The decofile snapshot only. blocks.gen.json is a single 10MB+ line (merge of
+# .deco/blocks/*.json), so committing it makes every content PR conflict
+# irresolvably; it is regenerated by \`npm run generate\` (build) and on dev
+# cold-start. meta.gen.json (the schema) stays COMMITTED — it merges cleanly and
+# keeps admin/Studio working on a fresh clone without a regen. The small .gen.ts
+# stubs and generate.digests.json also stay committed.
 .deco/blocks.gen.json
-.deco/meta.gen.json
 
 # IDE
 .vscode/

package/scripts/migrate/phase-verify.ts

@@ -32,6 +32,7 @@ const REQUIRED_FILES = [
   "src/setup.ts",
   "src/cache-config.ts",
   "src/setup/commerce-loaders.ts",
+  "src/setup/commerce-init.ts",
   "src/setup/section-loaders.ts",
   "src/styles/app.css",
   "src/apps/site.ts",
@@ -354,10 +355,10 @@ export const checks: Check[] = [
         "node_modules/",
         ".tanstack/",
         "src/routeTree.gen.ts",
-        // Generated snapshots must be ignored — committing them causes
+        // The decofile snapshot must be ignored — its 10MB+ single line causes
         // constant PR merge conflicts (see generateGitignore in phase-scaffold).
+        // meta.gen.json stays committed on purpose, so it is NOT required here.
         ".deco/blocks.gen.json",
-        ".deco/meta.gen.json",
       ];
       const missing = required.filter((r) => !content.includes(r));
       if (missing.length > 0) {
@@ -417,6 +418,7 @@ export const checks: Check[] = [
         "src/setup.ts",
         "src/cache-config.ts",
         "src/setup/commerce-loaders.ts",
+        "src/setup/commerce-init.ts",
         "src/setup/section-loaders.ts",
       ];
       const missing = setupFiles.filter(

package/scripts/migrate/templates/commerce-init.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import type { MigrationContext } from "../types";
+import { createContext } from "../types";
+import { generateCommerceInit } from "./commerce-init";
+import { generateServerEntry } from "./server-entry";
+import { generateSetup } from "./setup";
+
+function makeCtx(platform: MigrationContext["platform"]): MigrationContext {
+  const ctx = createContext("/tmp/commerce-init-template-fixture-site");
+  ctx.siteName = "acme-storefront";
+  ctx.platform = platform;
+  ctx.vtexAccount = platform === "vtex" ? "acme" : null;
+  return ctx;
+}
+
+/**
+ * Regression guard for the site loader/action bundle-leak boundary.
+ *
+ * COMMERCE_LOADERS (and every site loader/action module it imports) must be
+ * registered in a server-only module imported by the worker entry, NEVER by
+ * setup.ts — which router.tsx imports into the client bundle. If the
+ * registration leaks back into setup.ts, the whole loader/action graph (and any
+ * credential hardcoded in it) ships to the browser assets again.
+ */
+describe("server-only commerce/invoke registration boundary", () => {
+  for (const platform of ["vtex", "custom"] as const) {
+    describe(`platform: ${platform}`, () => {
+      const ctx = makeCtx(platform);
+      const commerceInit = generateCommerceInit(ctx);
+      const setup = generateSetup(ctx);
+      const serverFiles = generateServerEntry(ctx);
+
+      it("commerce-init registers COMMERCE_LOADERS + invoke server-side", () => {
+        expect(commerceInit).toContain(`import { COMMERCE_LOADERS } from "./commerce-loaders"`);
+        expect(commerceInit).toContain("registerCommerceLoaders(COMMERCE_LOADERS)");
+        expect(commerceInit).toContain("setInvokeLoaders(() => COMMERCE_LOADERS)");
+      });
+
+      it("setup.ts (client-imported) does NOT import or register COMMERCE_LOADERS", () => {
+        // The doc comment may reference COMMERCE_LOADERS; what must be absent is
+        // the actual import + the server-only registration calls.
+        expect(setup).not.toContain('from "./setup/commerce-loaders"');
+        expect(setup).not.toContain("registerCommerceLoaders(");
+        expect(setup).not.toContain("setInvokeLoaders(");
+      });
+
+      it("worker-entry imports commerce-init, router.tsx does not", () => {
+        expect(serverFiles["src/worker-entry.ts"]).toContain('import "./setup/commerce-init"');
+        expect(serverFiles["src/router.tsx"]).not.toContain("commerce-init");
+        // router.tsx still imports the client-safe setup for section registration.
+        expect(serverFiles["src/router.tsx"]).toContain('import "./setup"');
+      });
+    });
+  }
+});

package/scripts/migrate/templates/commerce-init.ts

@@ -0,0 +1,42 @@
+import type { MigrationContext } from "../types";
+
+/**
+ * Server-only commerce + invoke registration.
+ *
+ * `commerce-loaders.ts` statically imports COMMERCE_LOADERS, which pulls in the
+ * site's loader/action modules and the platform commerce loaders. If that graph
+ * is reachable from the CLIENT entry (router.tsx -> setup.ts), Vite bundles all
+ * of it — and any credential hardcoded in a site loader/action — into the
+ * browser assets. So the registration lives here instead and is imported ONLY by
+ * the worker entry (server), never by router.tsx.
+ *
+ * This is safe because both consumers run server-side:
+ *   - CMS commerce-loader resolution (loadCmsPage server fn), via
+ *     registerCommerceLoaders.
+ *   - the /deco/invoke handler, via setInvokeLoaders(() => COMMERCE_LOADERS)
+ *     -> getRegisteredLoaders() inside handleInvoke.
+ *
+ * Client components reach loaders/actions exclusively through the HTTP `invoke`
+ * proxy (@decocms/blocks/sdk/invoke), which imports no modules.
+ */
+export function generateCommerceInit(_ctx: MigrationContext): string {
+  return `/**
+ * Server-only commerce + invoke registration.
+ *
+ * Imported ONLY by the worker entry (src/worker-entry.ts), never by
+ * src/router.tsx. This keeps COMMERCE_LOADERS — and every site loader/action
+ * module it imports — out of the client bundle, so no server-side credential
+ * can leak into the browser assets. Both consumers run server-side:
+ *   - CMS commerce-loader resolution (registerCommerceLoaders)
+ *   - the /deco/invoke handler (setInvokeLoaders)
+ * The client reaches loaders/actions only via the HTTP invoke proxy.
+ */
+import { registerCommerceLoaders } from "@decocms/blocks/cms";
+import { setInvokeLoaders } from "@decocms/blocks-admin";
+
+import { COMMERCE_LOADERS } from "./commerce-loaders";
+
+registerCommerceLoaders(COMMERCE_LOADERS);
+setInvokeLoaders(() => COMMERCE_LOADERS);
+`;
+}

package/scripts/migrate/templates/no-legacy-packages.test.ts

@@ -5,6 +5,7 @@ import { generateRoutes } from "./routes";
 import { generateServerEntry } from "./server-entry";
 import { generateSetup } from "./setup";
 import { generateViteConfig } from "./vite-config";
+import { generateCommerceInit } from "./commerce-init";
 import { generateCommerceLoaders } from "./commerce-loaders";
 import { generateSectionLoaders } from "./section-loaders";
 import { generateHooks } from "./hooks";
@@ -76,6 +77,10 @@ describe("scaffolder templates never emit @decocms/start or @decocms/apps/*", ()
         );
       });
 
+      it("commerce-init.ts", () => {
+        assertNoLegacyPackageNames("commerce-init.ts", generateCommerceInit(ctx));
+      });
+
       it("section-loaders.ts", () => {
         assertNoLegacyPackageNames(
           "section-loaders.ts",

package/scripts/migrate/templates/server-entry.ts

@@ -65,6 +65,10 @@ function generateWorkerEntry(ctx: MigrationContext): string {
  *   npx -p @decocms/blocks-cli deco-cf-observability --write
  */
 import "./setup";
+// Server-only: registers COMMERCE_LOADERS + invoke. Kept out of ./setup (which
+// router.tsx imports) so the loader/action module graph never enters the client
+// bundle. See setup/commerce-init.ts.
+import "./setup/commerce-init";
 import handler, { createServerEntry } from "@tanstack/react-start/server-entry";
 import { createDecoWorkerEntry } from "@decocms/tanstack";
 import { instrumentWorker } from "@decocms/blocks/sdk/observability";
@@ -109,6 +113,10 @@ function generateVtexWorkerEntry(ctx: MigrationContext): string {
   const vtexAccount = ctx.vtexAccount || ctx.siteName;
 
   return `import "./setup";
+// Server-only: registers COMMERCE_LOADERS + invoke. Kept out of ./setup (which
+// router.tsx imports) so the loader/action module graph never enters the client
+// bundle. See setup/commerce-init.ts.
+import "./setup/commerce-init";
 import handler, { createServerEntry } from "@tanstack/react-start/server-entry";
 import { createDecoWorkerEntry } from "@decocms/tanstack";
 import { instrumentWorker } from "@decocms/blocks/sdk/observability";

package/scripts/migrate/templates/setup.ts

@@ -82,20 +82,23 @@ export function generateSetup(ctx: MigrationContext): string {
  *
  * Actual logic lives in focused modules:
  *   setup/commerce-loaders.ts  — COMMERCE_LOADERS map (VTEX + site data fetchers)
+ *   setup/commerce-init.ts     — server-only registration of COMMERCE_LOADERS +
+ *                                invoke. Imported by worker-entry.ts, NOT here,
+ *                                so the loader/action module graph (and any
+ *                                credential in it) never enters the client bundle.
  *   setup/section-loaders.ts   — registerSectionLoaders (per-section prop enrichment)
  *
+ * This file IS imported by router.tsx (client) for section registration/hydration,
+ * so it must stay free of server-only imports (COMMERCE_LOADERS, invoke, secrets).
+ *
  * Section metadata (eager, sync, layout, cache, LoadingFallback) is declared
  * in each section file and auto-extracted by generate-sections.ts.
  */
 
 import "./cache-config";
 
-import {
-  registerCommerceLoaders,
-  applySectionConventions,
-} from "@decocms/blocks/cms";
-import { createSiteSetup } from "@decocms/blocks/setup";
-import { setInvokeLoaders } from "@decocms/blocks-admin";${isVtex ? `
+import { applySectionConventions } from "@decocms/blocks/cms";
+import { createSiteSetup } from "@decocms/blocks/setup";${isVtex ? `
 import { createInstrumentedFetch } from "@decocms/blocks/sdk/instrumentedFetch";
 import { initVtexFromBlocks, setVtexFetch } from "@decocms/apps-vtex";` : ""}${hasLocationMatcher ? `
 import { registerLocationMatcher } from "./matchers/location";` : ""}
@@ -105,7 +108,6 @@ import { PreviewProviders } from "@decocms/tanstack";
 // @ts-ignore Vite ?url import
 import appCss from "./styles/app.css?url";
 
-import { COMMERCE_LOADERS } from "./setup/commerce-loaders";
 import "./setup/section-loaders";
 
 // -- Framework setup --
@@ -142,7 +144,8 @@ applySectionConventions({
 });
 
 // -- Commerce + invoke --
-registerCommerceLoaders(COMMERCE_LOADERS);
-setInvokeLoaders(() => COMMERCE_LOADERS);
+// Registration lives in setup/commerce-init.ts, imported ONLY by
+// src/worker-entry.ts (server). Importing it here would drag COMMERCE_LOADERS —
+// and every site loader/action module it references — into the client bundle.
 `;
 }