@decocms/blocks-cli 7.20.4 → 7.20.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.20.4",
+  "version": "7.20.6",
   "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.4",
+    "@decocms/blocks": "7.20.6",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/audit-secrets.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { isActionOrLoaderPath, scanFileForSecrets } from "./audit-secrets";
+
+// All fixtures use a synthetic sentinel — never a real credential.
+const FAKE = "FAKE0SECRET0SENTINEL0abcdef1234";
+
+describe("isActionOrLoaderPath", () => {
+  it("matches Fresh- and TanStack-style action/loader paths", () => {
+    expect(isActionOrLoaderPath("actions/foo.ts")).toBe(true);
+    expect(isActionOrLoaderPath("src/actions/foo.ts")).toBe(true);
+    expect(isActionOrLoaderPath("src/loaders/bar/baz.ts")).toBe(true);
+  });
+  it("ignores non-action/loader paths", () => {
+    expect(isActionOrLoaderPath("src/sections/Hero.tsx")).toBe(false);
+    expect(isActionOrLoaderPath("src/components/actionsMenu.tsx")).toBe(false);
+  });
+});
+
+describe("scanFileForSecrets — hardcoded credential in an action", () => {
+  it("flags a hardcoded Bearer token", () => {
+    const src = `export default async function h() {
+  const headers = { Authorization: "Bearer ${FAKE}" };
+  return fetch("https://api.example.com", { headers });
+}`;
+    const f = scanFileForSecrets("src/actions/simulate.ts", src);
+    expect(f).toHaveLength(1);
+    expect(f[0].id).toBe("hardcoded_bearer_token");
+    expect(f[0].severity).toBe("error");
+    expect(f[0].line).toBe(2);
+  });
+
+  it("flags a keyed secret literal (apiKey/token/secret)", () => {
+    const src = `const apiKey = "${FAKE}";\n`;
+    const f = scanFileForSecrets("actions/pay.ts", src);
+    expect(f.map((x) => x.id)).toContain("hardcoded_secret_literal");
+  });
+
+  it("does NOT flag env/context/interpolated reads", () => {
+    const src = `const headers = {
+  Authorization: \`Bearer \${process.env.API_TOKEN}\`,
+  apiKey: ctx.state.config.apiKey,
+  token: process.env.TOKEN,
+};`;
+    expect(scanFileForSecrets("src/actions/ok.ts", src)).toHaveLength(0);
+  });
+
+  it("does NOT flag obvious placeholders", () => {
+    const src = `const token = "changeme";\nconst apiKey = "xxxxxxxxxxxx";\n`;
+    expect(scanFileForSecrets("src/actions/ph.ts", src)).toHaveLength(0);
+  });
+
+  it("does NOT scan hardcoded literals OUTSIDE actions/loaders", () => {
+    const src = `const apiKey = "${FAKE}";\n`;
+    expect(scanFileForSecrets("src/sections/Hero.tsx", src)).toHaveLength(0);
+  });
+});
+
+describe("scanFileForSecrets — server-only crypto in a client module", () => {
+  it('flags @decocms/blocks/sdk/crypto imported in a "use client" file', () => {
+    const src = `"use client";
+import { resolveSecret } from "@decocms/blocks/sdk/crypto";
+export function C() { return null; }`;
+    const f = scanFileForSecrets("src/components/C.tsx", src);
+    expect(f).toHaveLength(1);
+    expect(f[0].id).toBe("crypto_imported_in_client");
+    expect(f[0].severity).toBe("error");
+  });
+
+  it("does NOT flag crypto imported from a server module", () => {
+    const src = `import { resolveSecret } from "@decocms/blocks/sdk/crypto";
+export function config() {}`;
+    expect(scanFileForSecrets("src/setup.ts", src)).toHaveLength(0);
+  });
+});

package/scripts/audit-secrets.ts

@@ -0,0 +1,327 @@
+#!/usr/bin/env tsx
+/**
+ * @decocms/blocks-cli — hardcoded-secret audit
+ *
+ * Read-only source scanner. Catches the two ways a credential ends up
+ * publicly downloadable from a storefront's client assets:
+ *
+ *   1. A secret literal hardcoded in a site `action`/`loader` module. In a
+ *      TanStack Start build these modules are registered in `.deco/loaders.gen.ts`
+ *      behind a dynamic `import()`, and that file is reachable from the client
+ *      entry (router -> setup -> commerce-loaders -> loaders.gen). Unless the
+ *      framework stubs loaders.gen on the client (it now does — see
+ *      packages/tanstack/src/vite/plugin.js), Vite emits each action/loader as a
+ *      public chunk, baking the literal into the browser bundle. Even with the
+ *      stub, a hardcoded credential in source is a committed-secret problem, so
+ *      we flag it at author time.
+ *
+ *   2. An import of `@decocms/blocks/sdk/crypto` (the secret-decryption SDK)
+ *      from a file marked `"use client"`. crypto is server-only; pulling it into
+ *      a client module drags decryption code toward the browser bundle.
+ *
+ * The scanner intentionally only inspects `actions/` and `loaders/` directories
+ * for rule (1) — that's where request-time credentials live and where the
+ * bundle-leak path exists. Rule (2) applies to any file.
+ *
+ * CI-friendly: mirrors audit-observability-config.ts (Severity/Finding, --json,
+ * --mode warn|block, --github, exit 0/1/2).
+ *
+ * Usage (from a site or package directory):
+ *   tsx audit-secrets.ts --source ./src
+ *   tsx audit-secrets.ts --source ./src --mode block   # exit 1 on error findings
+ *   tsx audit-secrets.ts --json
+ *   tsx audit-secrets.ts --github
+ *
+ * Exit codes:
+ *   0 — no findings, or `--mode warn` (default) regardless of findings
+ *   1 — `--mode block` and at least one `error`-severity finding
+ *   2 — source directory missing
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export type Severity = "error" | "warn" | "info";
+
+export interface Finding {
+  id: string;
+  severity: Severity;
+  /** Repo-relative file the finding is in. */
+  file: string;
+  /** 1-indexed line the finding anchors to. */
+  line: number;
+  message: string;
+  /** Suggested remediation. */
+  fix?: string;
+}
+
+export type GateMode = "warn" | "block";
+
+// A file is in scope for the hardcoded-secret rule if it lives under an
+// actions/ or loaders/ directory (Fresh `actions/foo.ts` or TanStack
+// `src/actions/foo.ts` both match on the path segment).
+export function isActionOrLoaderPath(relPath: string): boolean {
+  const norm = relPath.replaceAll("\\", "/");
+  return /(^|\/)(actions|loaders)\//.test(norm);
+}
+
+// Keys whose value being a plain string literal is a strong secret signal.
+const SECRET_KEY =
+  "(?:api[_-]?key|token|secret|password|passwd|authorization|auth[_-]?token|access[_-]?token|client[_-]?secret|private[_-]?key)";
+
+// A quoted literal with no `${` interpolation and a token-ish payload.
+// Requires length >= 12 to avoid flagging short placeholders like "changeme".
+const TOKENISH = "[A-Za-z0-9][A-Za-z0-9._\\-+/=]{11,}";
+
+const BEARER_RE = new RegExp(`["'\`]\\s*Bearer\\s+(${TOKENISH})\\s*["'\`]`, "i");
+const KEYED_SECRET_RE = new RegExp(`\\b${SECRET_KEY}\\b\\s*[:=]\\s*["'\`](${TOKENISH})["'\`]`, "i");
+
+// Values that look like a real literal but are safe: obvious placeholders.
+const PLACEHOLDER_RE =
+  /^(?:x+|y+|z+|changeme|placeholder|example|your[_-]?\w+|todo|xxx+|test|dummy|none|null|undefined)$/i;
+
+/**
+ * Scan a single file's source for hardcoded credentials + client crypto import.
+ * Pure — exported for unit testing.
+ */
+export function scanFileForSecrets(relPath: string, content: string): Finding[] {
+  const findings: Finding[] = [];
+  const lines = content.split("\n");
+
+  // Rule 2: crypto import in a "use client" file (any path).
+  const isClient = /^\s*["']use client["'];?\s*$/m.test(content);
+  if (isClient) {
+    lines.forEach((ln, i) => {
+      if (
+        /from\s+["']@decocms\/blocks\/sdk\/crypto["']/.test(ln) ||
+        /import\s*\(\s*["']@decocms\/blocks\/sdk\/crypto["']\s*\)/.test(ln)
+      ) {
+        findings.push({
+          id: "crypto_imported_in_client",
+          severity: "error",
+          file: relPath,
+          line: i + 1,
+          message:
+            "`@decocms/blocks/sdk/crypto` (server-only secret decryption) is imported from a " +
+            '"use client" module. Decrypt secrets server-side (in an app configure()/loader) and ' +
+            "never in client-bundled code.",
+          fix: "Move the secret resolution to a server-only module (action/loader/app config).",
+        });
+      }
+    });
+  }
+
+  // Rule 1: hardcoded secret literal in an action/loader.
+  if (isActionOrLoaderPath(relPath)) {
+    lines.forEach((ln, i) => {
+      for (const [id, re, label] of [
+        ["hardcoded_bearer_token", BEARER_RE, "a Bearer token"],
+        ["hardcoded_secret_literal", KEYED_SECRET_RE, "a credential"],
+      ] as const) {
+        const m = re.exec(ln);
+        if (!m) continue;
+        const value = m[1];
+        if (PLACEHOLDER_RE.test(value)) continue;
+        // The regexes only match a literal token (the charset excludes `${}`),
+        // so `Bearer ${t}` / `token: process.env.X` never reach here. Both rules
+        // therefore only fire on a genuinely hardcoded string.
+        findings.push({
+          id,
+          severity: "error",
+          file: relPath,
+          line: i + 1,
+          message:
+            `Hardcoded ${label} in an action/loader. In a TanStack build this source can be ` +
+            "emitted as a public client chunk, exposing the credential in the browser assets. " +
+            "It is also a committed secret regardless of bundling.",
+          fix: "Move the value to an environment variable / CMS Secret and read it via ctx or process.env; then rotate the exposed credential.",
+        });
+      }
+    });
+  }
+
+  return findings;
+}
+
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".deco",
+  ".vite",
+  ".cache",
+  "coverage",
+]);
+const SCAN_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mts", ".cts"]);
+
+function walk(dir: string, out: string[]): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      walk(full, out);
+    } else if (e.isFile() && SCAN_EXT.has(path.extname(e.name))) {
+      // Don't scan test files or the scanner's own fixtures.
+      if (/\.test\.[cm]?[jt]sx?$/.test(e.name)) continue;
+      out.push(full);
+    }
+  }
+}
+
+/** Scan a directory tree. Pure-ish (reads the filesystem); returns findings. */
+export function auditSourceDir(sourceDir: string): Finding[] {
+  const files: string[] = [];
+  walk(sourceDir, files);
+  const findings: Finding[] = [];
+  for (const full of files) {
+    const rel = path.relative(sourceDir, full);
+    let content: string;
+    try {
+      content = fs.readFileSync(full, "utf8");
+    } catch {
+      continue;
+    }
+    findings.push(...scanFileForSecrets(rel, content));
+  }
+  return findings;
+}
+
+interface CliOpts {
+  source: string;
+  json: boolean;
+  help: boolean;
+  mode: GateMode;
+  github: boolean;
+}
+
+function parseArgs(argv: string[]): CliOpts {
+  const opts: CliOpts = { source: ".", json: false, help: false, mode: "warn", github: false };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    switch (flag) {
+      case "--source":
+        opts.source = argv[++i] ?? ".";
+        break;
+      case "--json":
+        opts.json = true;
+        break;
+      case "--mode": {
+        const value = argv[++i];
+        if (value !== "warn" && value !== "block") {
+          console.error(`audit-secrets: --mode must be "warn" or "block" (got "${value ?? ""}")`);
+          process.exit(2);
+        }
+        opts.mode = value;
+        break;
+      }
+      case "--github":
+        opts.github = true;
+        break;
+      case "--help":
+      case "-h":
+        opts.help = true;
+        break;
+    }
+  }
+  return opts;
+}
+
+function showHelp(): void {
+  console.log(`
+  @decocms/blocks-cli — hardcoded-secret audit
+
+  Read-only scan for credentials hardcoded in action/loader source and for
+  server-only crypto imported into "use client" modules.
+
+  Usage:
+    tsx audit-secrets.ts [options]
+
+  Options:
+    --source <dir>   Directory to scan (default: .)
+    --json           Emit findings as JSON
+    --mode <m>       "warn" (default, exit 0) | "block" (exit 1 on errors)
+    --github         Emit ::error::/::warning:: lines for GitHub Actions
+    --help, -h       This message
+
+  Exit codes:
+    0   no findings, OR --mode warn (default)
+    1   --mode block AND at least one error-severity finding
+    2   source directory missing
+`);
+}
+
+function findingsToText(findings: Finding[]): string {
+  if (findings.length === 0) return "OK   no hardcoded secrets found";
+  const lines = ["Hardcoded-secret findings:"];
+  for (const f of findings) {
+    lines.push(`  [${f.severity.toUpperCase()}] ${f.id} — ${f.file}:${f.line}`);
+    lines.push(`    ${f.message}`);
+    if (f.fix) lines.push(`    fix: ${f.fix}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function main(): void {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const dir = path.resolve(opts.source);
+  if (!fs.existsSync(dir)) {
+    console.error(`audit-secrets: ${dir} not found`);
+    process.exit(2);
+  }
+
+  const findings = auditSourceDir(dir);
+
+  if (opts.json) {
+    process.stdout.write(
+      JSON.stringify({ source: dir, mode: opts.mode, findings }, null, 2) + "\n",
+    );
+  } else {
+    process.stdout.write(findingsToText(findings) + "\n");
+  }
+
+  if (opts.github) {
+    for (const f of findings) {
+      const level =
+        opts.mode === "block" && f.severity === "error"
+          ? "error"
+          : f.severity === "info"
+            ? "notice"
+            : "warning";
+      const msg = `${f.message}${f.fix ? ` (fix: ${f.fix})` : ""}`;
+      const escaped = msg.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+      process.stdout.write(`::${level} file=${f.file},line=${f.line},title=${f.id}::${escaped}\n`);
+    }
+  }
+
+  const shouldFail = opts.mode === "block" && findings.some((f) => f.severity === "error");
+  process.exit(shouldFail ? 1 : 0);
+}
+
+const isCjsEntry =
+  typeof require !== "undefined" && typeof module !== "undefined" && require.main === module;
+let isEsmEntry = false;
+try {
+  isEsmEntry =
+    typeof process !== "undefined" &&
+    Array.isArray(process.argv) &&
+    process.argv[1] !== undefined &&
+    import.meta.url === `file://${process.argv[1]}`;
+} catch {
+  // ignore in CJS
+}
+if (isCjsEntry || isEsmEntry) {
+  main();
+}

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

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",
@@ -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.
 `;
 }

package/scripts/upgrade-loader-leak-fix.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import {
+  applyDepBumps,
+  isAffectedSite,
+  planDepBumps,
+  type SitePkg,
+} from "./upgrade-loader-leak-fix";
+
+function pkg(over: Partial<SitePkg> = {}): SitePkg {
+  return {
+    dependencies: {
+      "@decocms/blocks": "^7.20.2",
+      "@decocms/tanstack": "^7.20.2",
+      "@decocms/apps-vtex": "^7.20.2",
+      react: "19.0.0",
+      "@tanstack/react-start": "1.166.8",
+    },
+    devDependencies: {
+      "@decocms/blocks-cli": "^7.20.2",
+      typescript: "^5.9.0",
+    },
+    ...over,
+  };
+}
+
+describe("isAffectedSite", () => {
+  it("true when @decocms/tanstack is a dependency", () => {
+    expect(isAffectedSite(pkg())).toBe(true);
+  });
+  it("false for a non-deco or non-tanstack site", () => {
+    expect(isAffectedSite({ dependencies: { react: "19.0.0" } })).toBe(false);
+    expect(isAffectedSite({ dependencies: { "@decocms/nextjs": "^7.20.2" } })).toBe(false);
+  });
+});
+
+describe("planDepBumps", () => {
+  it("bumps every @decocms/* dep across deps + devDeps, leaving others alone", () => {
+    const bumps = planDepBumps(pkg(), "^7.21.0");
+    const names = bumps.map((b) => b.name).sort();
+    expect(names).toEqual([
+      "@decocms/apps-vtex",
+      "@decocms/blocks",
+      "@decocms/blocks-cli",
+      "@decocms/tanstack",
+    ]);
+    // non-@decocms deps are never touched
+    expect(names).not.toContain("react");
+    expect(names).not.toContain("@tanstack/react-start");
+    expect(names).not.toContain("typescript");
+    // devDeps are covered
+    expect(bumps.find((b) => b.name === "@decocms/blocks-cli")?.field).toBe("devDependencies");
+  });
+
+  it("returns nothing when already at the target spec (idempotent)", () => {
+    const bumped = applyDepBumps(pkg(), planDepBumps(pkg(), "^7.21.0"));
+    expect(planDepBumps(bumped, "^7.21.0")).toHaveLength(0);
+  });
+});
+
+describe("applyDepBumps", () => {
+  it("rewrites only @decocms/* specs and does not mutate the input", () => {
+    const original = pkg();
+    const next = applyDepBumps(original, planDepBumps(original, "^7.21.0"));
+    expect(next.dependencies!["@decocms/tanstack"]).toBe("^7.21.0");
+    expect(next.dependencies!["@decocms/apps-vtex"]).toBe("^7.21.0");
+    expect(next.devDependencies!["@decocms/blocks-cli"]).toBe("^7.21.0");
+    // untouched
+    expect(next.dependencies!.react).toBe("19.0.0");
+    // input unchanged
+    expect(original.dependencies!["@decocms/tanstack"]).toBe("^7.20.2");
+  });
+});

package/scripts/upgrade-loader-leak-fix.ts

@@ -0,0 +1,440 @@
+#!/usr/bin/env tsx
+/**
+ * @decocms/blocks-cli — loader/action bundle-leak rollout
+ *
+ * Updates one or more already-in-prod TanStack Start sites so site
+ * loaders/actions (and any credential hardcoded in them) stop being emitted
+ * into the public client bundle.
+ *
+ * The actual fix ships in the framework: `@decocms/tanstack`'s vite plugin
+ * stubs `.deco/loaders.gen.ts` on the client, so once a site is on a fixed
+ * version its NEXT build is safe — no site source change is required. This
+ * script therefore just:
+ *
+ *   1. bumps every `@decocms/*` dependency to the fixed version,
+ *   2. installs (updates the lockfile),
+ *   3. audits the site source for credentials hardcoded in actions/loaders
+ *      (these must be ROTATED by hand — a leaked secret stays compromised even
+ *      after it stops shipping), and
+ *   4. optionally rebuilds and greps the client output for a known leaked
+ *      value to confirm it's gone.
+ *
+ * It never deploys. After a green run, redeploy with your normal pipeline
+ * (e.g. `wrangler deploy`).
+ *
+ * Usage:
+ *   tsx upgrade-loader-leak-fix.ts [siteDir...] [options]
+ *   tsx upgrade-loader-leak-fix.ts ./site-a ./site-b --version 7.21.0
+ *   tsx upgrade-loader-leak-fix.ts . --dry-run
+ *   tsx upgrade-loader-leak-fix.ts . --build --verify-secret "$LEAKED_TOKEN"
+ *
+ * Options:
+ *   --version <v>       Target @decocms/* version (e.g. 7.21.0). Default: resolve
+ *                       the latest published @decocms/tanstack via `npm view`.
+ *   --exact            Pin exact ("7.21.0") instead of caret ("^7.21.0").
+ *   --pm <bun|npm|pnpm> Package manager. Default: detect from lockfile.
+ *   --no-install       Don't run install after bumping package.json.
+ *   --build            Run the site's build script after install.
+ *   --verify-secret <s> After --build, fail if <s> appears in the client output.
+ *                       Supply your known-leaked token at runtime; never commit it.
+ *   --dry-run          Show what would change; write/run nothing.
+ *   --json             Machine-readable summary.
+ *   --help, -h         This message.
+ *
+ * Exit codes:
+ *   0  every site updated cleanly (any hardcoded-secret findings are reported
+ *      as warnings — rotation is a manual step this script can't do)
+ *   1  at least one site failed (install/build/verify error) OR --verify-secret
+ *      was still present in a client build
+ *   2  bad arguments / no site found
+ */
+
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { auditSourceDir, type Finding } from "./audit-secrets";
+
+export interface SitePkg {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  scripts?: Record<string, string>;
+  [k: string]: unknown;
+}
+
+const DECO_SCOPE = /^@decocms\//;
+
+/** A site is affected if it depends on the TanStack framework binding. */
+export function isAffectedSite(pkg: SitePkg): boolean {
+  const all = { ...pkg.dependencies, ...pkg.devDependencies };
+  return Boolean(all["@decocms/tanstack"]);
+}
+
+export interface DepBump {
+  name: string;
+  field: "dependencies" | "devDependencies";
+  from: string;
+  to: string;
+}
+
+/**
+ * Compute the version-spec changes needed to move every `@decocms/*` dep to
+ * `spec`. Pure — exported for testing. Only returns entries that actually change.
+ */
+export function planDepBumps(pkg: SitePkg, spec: string): DepBump[] {
+  const bumps: DepBump[] = [];
+  for (const field of ["dependencies", "devDependencies"] as const) {
+    const deps = pkg[field];
+    if (!deps) continue;
+    for (const [name, from] of Object.entries(deps)) {
+      if (!DECO_SCOPE.test(name)) continue;
+      if (from === spec) continue;
+      bumps.push({ name, field, from, to: spec });
+    }
+  }
+  return bumps;
+}
+
+/** Apply bumps in place on a cloned pkg. Pure — returns the new object. */
+export function applyDepBumps(pkg: SitePkg, bumps: DepBump[]): SitePkg {
+  const next: SitePkg = JSON.parse(JSON.stringify(pkg));
+  for (const b of bumps) {
+    const deps = next[b.field] as Record<string, string> | undefined;
+    if (deps) deps[b.name] = b.to;
+  }
+  return next;
+}
+
+type PkgManager = "bun" | "npm" | "pnpm";
+
+function detectPm(siteDir: string): PkgManager {
+  if (
+    fs.existsSync(path.join(siteDir, "bun.lock")) ||
+    fs.existsSync(path.join(siteDir, "bun.lockb"))
+  ) {
+    return "bun";
+  }
+  if (fs.existsSync(path.join(siteDir, "pnpm-lock.yaml"))) return "pnpm";
+  return "npm";
+}
+
+function run(cmd: string, args: string[], cwd: string): void {
+  execFileSync(cmd, args, { cwd, stdio: "inherit" });
+}
+
+/** Resolve the latest published version of a package via `npm view`. */
+function resolveLatest(pkgName: string): string {
+  const out = execFileSync("npm", ["view", pkgName, "version"], {
+    encoding: "utf8",
+  }).trim();
+  if (!/^\d+\.\d+\.\d+/.test(out)) {
+    throw new Error(`could not resolve latest version of ${pkgName} (got "${out}")`);
+  }
+  return out;
+}
+
+// Directories a Vite/TanStack-Start + CF Workers build may emit client assets to.
+const CLIENT_OUTPUT_DIRS = ["dist", ".output", "build", ".vercel/output", ".wrangler"];
+const CLIENT_ASSET_EXT = new Set([".js", ".mjs", ".cjs", ".css", ".html", ".json", ".map"]);
+
+/** Recursively collect built client asset files under a site dir. */
+function collectClientAssets(siteDir: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === "node_modules" || e.name === ".git") continue;
+        walk(full);
+      } else if (e.isFile() && CLIENT_ASSET_EXT.has(path.extname(e.name))) {
+        out.push(full);
+      }
+    }
+  };
+  for (const d of CLIENT_OUTPUT_DIRS) {
+    const full = path.join(siteDir, d);
+    if (fs.existsSync(full)) walk(full);
+  }
+  return out;
+}
+
+/** Grep built client assets for a literal. Returns matching file paths. */
+export function findSecretInAssets(files: string[], secret: string): string[] {
+  const hits: string[] = [];
+  for (const f of files) {
+    let content: string;
+    try {
+      content = fs.readFileSync(f, "utf8");
+    } catch {
+      continue;
+    }
+    if (content.includes(secret)) hits.push(f);
+  }
+  return hits;
+}
+
+export interface SiteResult {
+  site: string;
+  affected: boolean;
+  bumps: DepBump[];
+  secretFindings: Finding[];
+  built: boolean;
+  leakedAssetFiles: string[];
+  error?: string;
+}
+
+interface CliOpts {
+  sites: string[];
+  version: string | null;
+  exact: boolean;
+  pm: PkgManager | null;
+  install: boolean;
+  build: boolean;
+  verifySecret: string | null;
+  dryRun: boolean;
+  json: boolean;
+  help: boolean;
+}
+
+function parseArgs(argv: string[]): CliOpts {
+  const opts: CliOpts = {
+    sites: [],
+    version: null,
+    exact: false,
+    pm: null,
+    install: true,
+    build: false,
+    verifySecret: null,
+    dryRun: false,
+    json: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--version":
+        opts.version = argv[++i] ?? null;
+        break;
+      case "--exact":
+        opts.exact = true;
+        break;
+      case "--pm": {
+        const v = argv[++i];
+        if (v !== "bun" && v !== "npm" && v !== "pnpm") {
+          console.error(`upgrade: --pm must be bun|npm|pnpm (got "${v ?? ""}")`);
+          process.exit(2);
+        }
+        opts.pm = v;
+        break;
+      }
+      case "--no-install":
+        opts.install = false;
+        break;
+      case "--build":
+        opts.build = true;
+        break;
+      case "--verify-secret":
+        opts.verifySecret = argv[++i] ?? null;
+        break;
+      case "--dry-run":
+        opts.dryRun = true;
+        break;
+      case "--json":
+        opts.json = true;
+        break;
+      case "--help":
+      case "-h":
+        opts.help = true;
+        break;
+      default:
+        if (a.startsWith("--")) {
+          console.error(`upgrade: unknown option "${a}"`);
+          process.exit(2);
+        }
+        opts.sites.push(a);
+    }
+  }
+  if (opts.sites.length === 0) opts.sites.push(".");
+  return opts;
+}
+
+function showHelp(): void {
+  console.log(`
+  @decocms/blocks-cli — loader/action bundle-leak rollout
+
+  Bumps @decocms/* to the fixed framework version, installs, audits for
+  hardcoded credentials, and (optionally) rebuilds + verifies the client
+  output no longer contains a known leaked value. Never deploys.
+
+  Usage:
+    tsx upgrade-loader-leak-fix.ts [siteDir...] [options]
+
+  Options:
+    --version <v>        Target @decocms/* version (default: latest published)
+    --exact              Pin exact instead of caret
+    --pm <bun|npm|pnpm>  Package manager (default: detect)
+    --no-install         Skip install
+    --build              Run the site build after install
+    --verify-secret <s>  Fail if <s> appears in the client build (supply at runtime)
+    --dry-run            Show changes; write/run nothing
+    --json               Machine-readable summary
+    --help, -h           This message
+`);
+}
+
+function upgradeSite(siteDir: string, opts: CliOpts, spec: string): SiteResult {
+  const result: SiteResult = {
+    site: siteDir,
+    affected: false,
+    bumps: [],
+    secretFindings: [],
+    built: false,
+    leakedAssetFiles: [],
+  };
+
+  const pkgPath = path.join(siteDir, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    result.error = "no package.json";
+    return result;
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as SitePkg;
+
+  result.affected = isAffectedSite(pkg);
+  if (!result.affected) return result; // not a TanStack deco site — skip
+
+  // 1. Plan + apply dependency bumps.
+  result.bumps = planDepBumps(pkg, spec);
+  if (result.bumps.length > 0 && !opts.dryRun) {
+    const next = applyDepBumps(pkg, result.bumps);
+    fs.writeFileSync(pkgPath, JSON.stringify(next, null, 2) + "\n");
+  }
+
+  // 2. Install (updates the lockfile so the fixed framework is resolved).
+  const pm = opts.pm ?? detectPm(siteDir);
+  if (result.bumps.length > 0 && opts.install && !opts.dryRun) {
+    run(pm, ["install"], siteDir);
+  }
+
+  // 3. Audit source for hardcoded credentials — must be rotated manually.
+  //    Scan the whole site tree (root actions/ + src/).
+  result.secretFindings = auditSourceDir(siteDir);
+
+  // 4. Optional rebuild + verify the leaked value is gone from the client output.
+  if (opts.build && !opts.dryRun) {
+    run(pm, ["run", "build"], siteDir);
+    result.built = true;
+    if (opts.verifySecret) {
+      const assets = collectClientAssets(siteDir);
+      result.leakedAssetFiles = findSecretInAssets(assets, opts.verifySecret);
+    }
+  }
+
+  return result;
+}
+
+function printReport(results: SiteResult[]): void {
+  for (const r of results) {
+    console.log(`\n── ${r.site} ──`);
+    if (r.error) {
+      console.log(`  ERROR: ${r.error}`);
+      continue;
+    }
+    if (!r.affected) {
+      console.log("  skipped — not a @decocms/tanstack site");
+      continue;
+    }
+    if (r.bumps.length === 0) {
+      console.log("  deps already at target version");
+    } else {
+      console.log(`  bumped ${r.bumps.length} @decocms/* dep(s):`);
+      for (const b of r.bumps) console.log(`    ${b.name}: ${b.from} -> ${b.to}`);
+    }
+    if (r.built) {
+      console.log("  rebuilt client");
+      if (r.leakedAssetFiles.length > 0) {
+        console.log(`  ✗ LEAK STILL PRESENT in ${r.leakedAssetFiles.length} asset(s):`);
+        for (const f of r.leakedAssetFiles) console.log(`      ${f}`);
+      } else {
+        console.log("  ✓ verify-secret not found in client build");
+      }
+    }
+    const errors = r.secretFindings.filter((f) => f.severity === "error");
+    if (errors.length > 0) {
+      console.log(`  ⚠ ${errors.length} hardcoded-credential finding(s) — ROTATE these:`);
+      for (const f of errors) console.log(`    ${f.file}:${f.line} — ${f.id}`);
+    }
+  }
+}
+
+function main(): void {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  // Resolve the target spec.
+  let version = opts.version;
+  if (!version) {
+    try {
+      version = resolveLatest("@decocms/tanstack");
+      console.log(`Resolved latest @decocms/tanstack: ${version}`);
+    } catch (e) {
+      console.error(`upgrade: ${(e as Error).message}. Pass --version explicitly.`);
+      process.exit(2);
+    }
+  }
+  const spec = opts.exact ? version : `^${version.replace(/^[\^~]/, "")}`;
+
+  const results: SiteResult[] = [];
+  for (const site of opts.sites) {
+    const dir = path.resolve(site);
+    try {
+      results.push(upgradeSite(dir, opts, spec));
+    } catch (e) {
+      results.push({
+        site: dir,
+        affected: true,
+        bumps: [],
+        secretFindings: [],
+        built: false,
+        leakedAssetFiles: [],
+        error: (e as Error).message,
+      });
+    }
+  }
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ spec, dryRun: opts.dryRun, results }, null, 2) + "\n");
+  } else {
+    printReport(results);
+    console.log(
+      "\nNext steps: rotate any flagged credential, then redeploy each site " +
+        "with your pipeline (e.g. `wrangler deploy`).",
+    );
+  }
+
+  const failed = results.some((r) => r.error || r.leakedAssetFiles.length > 0);
+  process.exit(failed ? 1 : 0);
+}
+
+const isCjsEntry =
+  typeof require !== "undefined" && typeof module !== "undefined" && require.main === module;
+let isEsmEntry = false;
+try {
+  isEsmEntry =
+    typeof process !== "undefined" &&
+    Array.isArray(process.argv) &&
+    process.argv[1] !== undefined &&
+    import.meta.url === `file://${process.argv[1]}`;
+} catch {
+  // ignore in CJS
+}
+if (isCjsEntry || isEsmEntry) {
+  main();
+}