@decocms/blocks-cli 7.22.1 → 7.23.0

package/package.json

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

package/scripts/migrate/phase-transform.ts

@@ -6,6 +6,7 @@ import { log, logPhase } from "./types";
 import { transformImports } from "./transforms/imports";
 import { transformJsx } from "./transforms/jsx";
 import { transformFreshApis } from "./transforms/fresh-apis";
+import { transformCtxCompat } from "./transforms/ctx-compat";
 import { transformDenoIsms } from "./transforms/deno-isms";
 import { transformTailwind } from "./transforms/tailwind";
 import { transformDeadCode } from "./transforms/dead-code";
@@ -55,16 +56,19 @@ function applyTransforms(content: string, filePath: string, ctx?: MigrationConte
     return { content, changed: false, notes: [] };
   }
 
-  // Pipeline: imports → jsx → htmx-on-events → fresh-apis → dead-code → deno-isms → tailwind
+  // Pipeline: imports → jsx → htmx-on-events → fresh-apis → ctx-compat → dead-code → deno-isms → tailwind
   // htmx-on-events runs after jsx (which renames class/onChange) and
   // before fresh-apis (which removes useScript imports the htmx
   // codemod's TODO might still reference). The codemod is a no-op on
   // files without hx-on, so it never adds latency to non-htmx sites.
+  // ctx-compat runs after fresh-apis so it sees the settled loader body; it's
+  // a no-op on files without a `loader` export (#305).
   const pipeline: Array<{ name: string; fn: (content: string) => TransformResult }> = [
     { name: "imports", fn: (c) => transformImports(c, ctx?.islandWrapperTargets) },
     { name: "jsx", fn: transformJsx },
     { name: "htmx-on-events", fn: transformHtmxOnEvents },
     { name: "fresh-apis", fn: transformFreshApis },
+    { name: "ctx-compat", fn: transformCtxCompat },
     { name: "dead-code", fn: (c) => transformDeadCode(c, ctx?.platform) },
     { name: "deno-isms", fn: transformDenoIsms },
     { name: "tailwind", fn: transformTailwind },

package/scripts/migrate/templates/section-loaders.ts

@@ -314,9 +314,11 @@ export function generateSectionLoaders(ctx: MigrationContext): string {
   // ---------- SEO + analytics delegation ----------
   if (hasSEOPDP) {
     entries.push(``);
-    entries.push(`  "site/sections/SEOPDP.tsx": async (props: any, _req) => {`);
+    // The framework supplies the real compat ctx as the 3rd arg (#305) —
+    // forward it instead of faking `{ seo: {} }` (which violated policy D3).
+    entries.push(`  "site/sections/SEOPDP.tsx": async (props: any, _req, ctx) => {`);
     entries.push(`    const mod = await import("../sections/SEOPDP");`);
-    entries.push(`    const result = mod.loader(props, _req, { seo: {} } as any);`);
+    entries.push(`    const result = mod.loader(props, _req, ctx);`);
     entries.push(`    return result ?? props;`);
     entries.push(`  },`);
   }
@@ -329,9 +331,9 @@ export function generateSectionLoaders(ctx: MigrationContext): string {
   }
 
   if (hasIsEvents) {
-    entries.push(`  "site/sections/Analytics/IsEvents.tsx": async (props: any, req) => {`);
+    entries.push(`  "site/sections/Analytics/IsEvents.tsx": async (props: any, req, ctx) => {`);
     entries.push(`    const mod = await import("../sections/Analytics/IsEvents");`);
-    entries.push(`    return mod.loader(props, req) as unknown as Record<string, unknown>;`);
+    entries.push(`    return mod.loader(props, req, ctx) as unknown as Record<string, unknown>;`);
     entries.push(`  },`);
   }
 

package/scripts/migrate/transforms/ctx-compat.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { transformCtxCompat } from "./ctx-compat";
+
+const withLoader = (body: string) =>
+  `export const loader = (props: Props, req: Request, ctx?: AppContext) => {\n${body}\n};`;
+
+describe("transformCtxCompat", () => {
+  it("optional-chains a deep app-state read", () => {
+    const src = withLoader("  const ext = ctx.salesforce.cartExtension[0];");
+    const r = transformCtxCompat(src);
+    expect(r.changed).toBe(true);
+    expect(r.content).toContain("ctx?.salesforce?.cartExtension?.[0]");
+  });
+
+  it("optional-chains ctx.device and ctx.invoke calls (harmless no-op safety)", () => {
+    const src = withLoader(
+      "  const isMobile = ctx.device !== 'desktop';\n  const page = await ctx.invoke.vtex.loaders.product.detailsPageGQL({ slug });",
+    );
+    const r = transformCtxCompat(src);
+    expect(r.content).toContain("ctx?.device !== 'desktop'");
+    expect(r.content).toContain("ctx?.invoke?.vtex?.loaders?.product?.detailsPageGQL({ slug })");
+  });
+
+  it("leaves already-optional chains intact (no double ??.)", () => {
+    const src = withLoader("  const x = ctx?.salesforce?.cartExtension?.[0];");
+    const r = transformCtxCompat(src);
+    // No change needed → not flagged as changed.
+    expect(r.content).toContain("ctx?.salesforce?.cartExtension?.[0]");
+    expect(r.content).not.toContain("??.");
+  });
+
+  it("does not optional-chain an assignment target (would be a syntax error)", () => {
+    const src = withLoader("  ctx.state.count = 1;");
+    const r = transformCtxCompat(src);
+    expect(r.content).toContain("ctx.state.count = 1;");
+    expect(r.content).not.toContain("ctx?.state?.count =");
+  });
+
+  it("still rewrites reads while leaving assignment targets alone", () => {
+    const src = withLoader("  ctx.state.count = ctx.state.count + 1;");
+    const r = transformCtxCompat(src);
+    // LHS untouched, RHS optional-chained.
+    expect(r.content).toContain("ctx.state.count = ctx?.state?.count + 1;");
+  });
+
+  it("is a no-op on files without a loader export", () => {
+    const src = "const ctx = canvas.getContext('2d');\nctx.fillRect(0, 0, 1, 1);";
+    const r = transformCtxCompat(src);
+    expect(r.changed).toBe(false);
+    expect(r.content).toBe(src);
+  });
+
+  it("does not touch the ctx parameter declaration", () => {
+    const src = withLoader("  return props;");
+    const r = transformCtxCompat(src);
+    expect(r.changed).toBe(false);
+    expect(r.content).toContain("ctx?: AppContext");
+  });
+
+  it("does not match identifiers that merely contain ctx", () => {
+    const src = withLoader("  const c = canvasCtx.foo;\n  const d = a.ctx.bar;");
+    const r = transformCtxCompat(src);
+    expect(r.content).toContain("canvasCtx.foo");
+    expect(r.content).toContain("a.ctx.bar");
+  });
+});

package/scripts/migrate/transforms/ctx-compat.ts

@@ -0,0 +1,151 @@
+import type { TransformResult } from "../types";
+
+/**
+ * Make ported deco.cx section loaders defensive about the compat `ctx`
+ * (issue #305).
+ *
+ * The framework now hands section loaders a real 3rd-arg `ctx`
+ * (`@decocms/blocks`'s `buildSectionLoaderContext`) with `device`, `invoke`,
+ * `response` and per-app state (`ctx.vtex`, `ctx.salesforce`, …). But an app
+ * that isn't configured on the target site yields `undefined`, so a
+ * *non-optional* deep read like `ctx.salesforce.cartExtension[0]` still throws
+ * — and `withSectionLoader`'s try/catch would swallow it, dropping the
+ * section's props (blank render). The hand-fixed reference migration
+ * (`granadobr-tanstack`) solves this by optional-chaining every `ctx` read.
+ *
+ * This codemod reproduces that: every `ctx.` member-access chain becomes an
+ * optional chain (`ctx?.a?.b?.[0]`). Optional chaining short-circuits to
+ * `undefined` instead of throwing, which is exactly the defensive behavior the
+ * working migration relies on. `ctx.device`/`ctx.invoke` are always present so
+ * the extra `?.` is a harmless no-op there.
+ *
+ * Scope: only files that export a `loader` (section/loader files), so an
+ * unrelated `ctx` (e.g. a canvas 2D context) elsewhere isn't touched.
+ * Assignment targets (`ctx.x = …`, invalid as an optional chain) are skipped.
+ */
+
+const IDENT = /[A-Za-z0-9_$]/;
+
+const LOADER_EXPORT_RE =
+  /export\s+(?:const|(?:async\s+)?function)\s+loader\b|export\s*\{\s*[^}]*\bloader\b/;
+
+function isIdentChar(c: string | undefined): boolean {
+  return c !== undefined && IDENT.test(c);
+}
+
+/**
+ * Scan a single `ctx` member-access chain starting at `start` (which must
+ * point at the `c` of `ctx`). Returns the rewritten (optional) chain, the
+ * original text, the index just past the chain, and whether the chain is the
+ * target of an assignment (in which case it must NOT be optional-chained).
+ */
+function scanChain(
+  code: string,
+  start: number,
+): { rewritten: string; original: string; end: number; isAssignTarget: boolean } {
+  let i = start + 3; // past "ctx"
+  const pieces: string[] = ["ctx"];
+
+  while (i < code.length) {
+    if (code.startsWith("?.", i)) {
+      // already optional — keep it, then consume the identifier OR, for an
+      // optional computed access (`?.[expr]`), the balanced bracket group.
+      i += 2;
+      if (code[i] === "[") {
+        let depth = 1;
+        let j = i + 1;
+        while (j < code.length && depth > 0) {
+          if (code[j] === "[") depth++;
+          else if (code[j] === "]") depth--;
+          j++;
+        }
+        pieces.push("?.[", code.slice(i + 1, j));
+        i = j;
+      } else {
+        let j = i;
+        while (j < code.length && isIdentChar(code[j])) j++;
+        pieces.push("?.", code.slice(i, j));
+        i = j;
+      }
+    } else if (code[i] === ".") {
+      i += 1;
+      let j = i;
+      while (j < code.length && isIdentChar(code[j])) j++;
+      pieces.push("?.", code.slice(i, j));
+      i = j;
+    } else if (code[i] === "[") {
+      let depth = 1;
+      let j = i + 1;
+      while (j < code.length && depth > 0) {
+        if (code[j] === "[") depth++;
+        else if (code[j] === "]") depth--;
+        j++;
+      }
+      pieces.push("?.[", code.slice(i + 1, j)); // slice includes closing "]"
+      i = j;
+    } else {
+      break;
+    }
+  }
+
+  // Peek past trailing whitespace to detect an assignment target.
+  let k = i;
+  while (k < code.length && (code[k] === " " || code[k] === "\t")) k++;
+  const isAssignTarget = code[k] === "=" && code[k + 1] !== "=" && code[k + 1] !== ">";
+
+  return {
+    rewritten: pieces.join(""),
+    original: code.slice(start, i),
+    end: i,
+    isAssignTarget,
+  };
+}
+
+export function transformCtxCompat(content: string): TransformResult {
+  // Only touch files that actually export a loader — avoids rewriting an
+  // unrelated `ctx` variable (canvas context, etc.) in components.
+  if (!LOADER_EXPORT_RE.test(content)) {
+    return { content, changed: false, notes: [] };
+  }
+
+  let out = "";
+  let i = 0;
+  let count = 0;
+
+  while (i < content.length) {
+    const isCtxToken =
+      content.startsWith("ctx", i) &&
+      !isIdentChar(content[i - 1]) &&
+      content[i - 1] !== "." &&
+      (content[i + 3] === "." || content[i + 3] === "[" || content.startsWith("?.", i + 3));
+
+    if (isCtxToken) {
+      const { rewritten, original, end, isAssignTarget } = scanChain(content, i);
+      if (!isAssignTarget && rewritten !== original) {
+        out += rewritten;
+        count++;
+      } else {
+        out += original;
+      }
+      i = end;
+      continue;
+    }
+
+    out += content[i];
+    i++;
+  }
+
+  if (count === 0) {
+    return { content, changed: false, notes: [] };
+  }
+
+  return {
+    content: out,
+    changed: true,
+    notes: [
+      `Optional-chained ${count} ctx.* read(s) so unconfigured app state degrades to undefined instead of throwing (#305)`,
+    ],
+  };
+}
+
+export const _internals = { scanChain, LOADER_EXPORT_RE };

package/scripts/migrate/transforms/fresh-apis.ts

@@ -202,9 +202,11 @@ export function transformFreshApis(content: string): TransformResult {
     notes.push("Removed allowCorsFor (not needed in TanStack)");
   }
 
-  // ctx.response.headers → not available, flag
+  // ctx.response.headers → supported by the compat ctx (#305): section loaders
+  // receive a 3rd-arg ctx whose `response.headers` maps to
+  // RequestContext.responseHeaders. Just an INFO note (no manual work).
   if (result.includes("ctx.response")) {
-    notes.push("MANUAL: ctx.response usage found — FnContext in @decocms/blocks does not have response object");
+    notes.push("INFO: ctx.response.headers is provided by the compat ctx (RequestContext.responseHeaders) inside the worker request scope; writes are dropped on the dev/SPA serverFn path");
   }
 
   // { crypto } from "@std/crypto" → use globalThis.crypto (Web Crypto API)