@decocms/blocks-cli 7.5.1 → 7.5.3

package/package.json

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

package/scripts/generate-invoke.ts

@@ -21,6 +21,16 @@
  * compiled and shipped as part of the site's application code, so it lives
  * in `src/` alongside the code it's compiled with, not in `.deco/`.
  *
+ * This is empirically load-bearing, not taste (tested 2026-07-08 on a real
+ * site): with the file moved to `.deco/invoke.gen.ts`, the CLIENT half of
+ * the Start compiler works fine (stubs generated, IDs re-derived from the
+ * new path), but the SERVER half cannot resolve the split module back to an
+ * executable handler — every `/_serverFn/...` call returns an unhandled 500
+ * with no logged stack, i.e. every cart/session/MasterData action dies.
+ * Same site, file back under `src/`: identical RPC probe returns 200 with a
+ * real VTEX orderForm. Do not move this default without re-running that
+ * round-trip test end to end.
+ *
  * Usage (from site root):
  *   npx tsx node_modules/@decocms/blocks-cli/scripts/generate-invoke.ts
  *

package/scripts/generate-schema.ts

@@ -40,6 +40,17 @@ import { warnLegacyArtifact } from "./lib/legacyArtifact";
 
 // ---------------------------------------------------------------------------
 // CLI arg parsing
+//
+// Guarded by isMainModule() (defined below — hoisted, so it's callable up
+// here) so that importing this module for its pure exports
+// (definitionIdForPath, applyWidgetFormat, typeToJsonSchema — see
+// generate-schema.test.ts) never reads argv or touches the filesystem.
+// Without the guard, every import used to run an `fs.existsSync` check
+// against the *importing process's* cwd and could print a legacy-artifact
+// warning to stderr as an import-time side effect, unrelated to whatever
+// the test actually wanted to exercise. generateMeta() (below) and the
+// final write are themselves only reached inside `if (isMainModule())`, so
+// these vars only need real values in that same case.
 // ---------------------------------------------------------------------------
 const argv = process.argv.slice(2);
 function arg(name: string, fallback: string): string {
@@ -47,20 +58,33 @@ function arg(name: string, fallback: string): string {
   return idx !== -1 && argv[idx + 1] ? argv[idx + 1] : fallback;
 }
 
-const SITE_NAMESPACE = arg("namespace", "site");
-const SITE_NAME = arg("site", "storefront");
-const FRAMEWORK_VERSION = arg("version", "1.0.0");
-const SECTIONS_REL = arg("sections", "src/sections");
-const LOADERS_REL = arg("loaders", "src/loaders");
-const APPS_REL = arg("apps", "src/apps");
-const SKIP_APPS = argv.includes("--skip-apps");
-const OUT_FILE_EXPLICIT = argv.includes("--out");
 const NEW_DEFAULT_OUT_REL = ".deco/meta.gen.json";
 const OLD_DEFAULT_OUT_REL = "src/server/admin/meta.gen.json";
-const OUT_REL = arg("out", NEW_DEFAULT_OUT_REL);
-const PLATFORM = arg("platform", "cloudflare");
-if (!OUT_FILE_EXPLICIT && fs.existsSync(path.resolve(process.cwd(), OLD_DEFAULT_OUT_REL))) {
-  warnLegacyArtifact(OLD_DEFAULT_OUT_REL, NEW_DEFAULT_OUT_REL);
+
+let SITE_NAMESPACE = "site";
+let SITE_NAME = "storefront";
+let FRAMEWORK_VERSION = "1.0.0";
+let SECTIONS_REL = "src/sections";
+let LOADERS_REL = "src/loaders";
+let APPS_REL = "src/apps";
+let SKIP_APPS = false;
+let OUT_REL = NEW_DEFAULT_OUT_REL;
+let PLATFORM = "cloudflare";
+
+if (isMainModule()) {
+  SITE_NAMESPACE = arg("namespace", SITE_NAMESPACE);
+  SITE_NAME = arg("site", SITE_NAME);
+  FRAMEWORK_VERSION = arg("version", FRAMEWORK_VERSION);
+  SECTIONS_REL = arg("sections", SECTIONS_REL);
+  LOADERS_REL = arg("loaders", LOADERS_REL);
+  APPS_REL = arg("apps", APPS_REL);
+  SKIP_APPS = argv.includes("--skip-apps");
+  const outFileExplicit = argv.includes("--out");
+  OUT_REL = arg("out", NEW_DEFAULT_OUT_REL);
+  PLATFORM = arg("platform", PLATFORM);
+  if (!outFileExplicit && fs.existsSync(path.resolve(process.cwd(), OLD_DEFAULT_OUT_REL))) {
+    warnLegacyArtifact(OLD_DEFAULT_OUT_REL, NEW_DEFAULT_OUT_REL);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -758,10 +782,17 @@ function findTsxFiles(dir: string): string[] {
   const results: string[] = [];
   if (!fs.existsSync(dir)) return results;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    if (isExcludedCodegenFile(entry.name)) continue;
     const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) results.push(...findTsxFiles(full));
-    else if (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) results.push(full);
+    if (entry.isDirectory()) {
+      // The exclusion predicate targets generated/test *files* — a directory
+      // named e.g. `foo.gen.ts` is a real path segment and must still be walked.
+      results.push(...findTsxFiles(full));
+    } else if (
+      !isExcludedCodegenFile(entry.name) &&
+      (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts"))
+    ) {
+      results.push(full);
+    }
   }
   return results;
 }

package/scripts/generate-sections.test.ts

@@ -258,4 +258,71 @@ describe("generate-sections --registry", () => {
     const importResult = cp.spawnSync("npx", ["tsx", checkerFile], { encoding: "utf8" });
     expect(importResult.status, importResult.stderr).toBe(0);
   }, 30_000);
+
+  it("ends with exactly one trailing newline and no doubled blank line before the registry block (output hygiene)", () => {
+    fs.writeFileSync(
+      path.join(sectionsDir, "Hero.tsx"),
+      "export const sync = true\nexport default function Hero() { return null }\n",
+    );
+
+    const { code } = runGenerator([
+      "--sections-dir", sectionsDir,
+      "--out-file", outFile,
+      "--registry",
+    ]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+    expect(generated.endsWith("\n")).toBe(true);
+    expect(generated.endsWith("\n\n")).toBe(false);
+    // No run of 3+ consecutive newlines (i.e. no blank-line pair) anywhere,
+    // in particular right before the registry doc comment.
+    expect(generated).not.toMatch(/\n{3,}/);
+  }, 30_000);
+});
+
+describe("generate-sections output hygiene (non-registry)", () => {
+  let tmpDir: string;
+  let sectionsDir: string;
+  let outFile: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-sections-hygiene-"));
+    sectionsDir = path.join(tmpDir, "sections");
+    outFile = path.join(tmpDir, "out", "sections.gen.ts");
+    fs.mkdirSync(sectionsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("ends with exactly one trailing newline without --registry", () => {
+    fs.writeFileSync(
+      path.join(sectionsDir, "Hero.tsx"),
+      "export const eager = true;\nexport default function Hero() { return null; }\n",
+    );
+
+    const { code } = runGenerator(["--sections-dir", sectionsDir, "--out-file", outFile]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+    expect(generated.endsWith("\n")).toBe(true);
+    expect(generated.endsWith("\n\n")).toBe(false);
+    expect(generated).not.toMatch(/\n{3,}/);
+  }, 30_000);
+
+  it("ends with exactly one trailing newline when the sections dir is missing (empty-output early-exit path)", () => {
+    const missingSectionsDir = path.join(tmpDir, "does-not-exist");
+
+    const { code } = runGenerator([
+      "--sections-dir", missingSectionsDir,
+      "--out-file", outFile,
+    ]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+    expect(generated.endsWith("\n")).toBe(true);
+    expect(generated.endsWith("\n\n")).toBe(false);
+  }, 30_000);
 });

package/scripts/generate-sections.ts

@@ -248,7 +248,10 @@ lines.push("");
 // Lazy section-import registry — opt-in via --registry, built from every
 // scanned section file (not just convention-carrying `entries`).
 if (EMIT_REGISTRY) {
-  lines.push("");
+  // NOTE: no extra `lines.push("")` here — the loadingFallbacks block above
+  // already pushed a single trailing blank line as its separator. Pushing
+  // another one here doubled the blank line before this comment block in
+  // every site's committed .deco/sections.gen.ts.
   lines.push("/**");
   lines.push(" * Lazy section registry — the Next.js/webpack equivalent of Vite's");
   lines.push(" * `import.meta.glob` scan over every file under ./sections, recursively.");
@@ -265,7 +268,18 @@ if (EMIT_REGISTRY) {
 }
 
 fs.mkdirSync(path.dirname(outFile), { recursive: true });
-fs.writeFileSync(outFile, lines.join("\n"));
+// Output hygiene: several sections above push a trailing "" separator
+// unconditionally (e.g. after the header comment, after the sync/fallback
+// import blocks) — when a following section has nothing to emit (no sync
+// imports, --registry off, etc.) those separators stack into a doubled
+// blank line. Collapse any run of blank lines down to a single one, then
+// normalize to exactly one trailing newline: without --registry, `lines`
+// ends with a pushed "" separator (one trailing "\n" once joined); with
+// --registry, the last pushed line is "};" (no trailing newline at all).
+fs.writeFileSync(
+  outFile,
+  lines.join("\n").replace(/\n{3,}/g, "\n\n").replace(/\n*$/, "\n"),
+);
 
 console.log(
   `Generated section metadata for ${entries.length} sections → ${path.relative(process.cwd(), outFile)}`,

package/scripts/lib/codegenExclusions.test.ts

@@ -9,14 +9,24 @@ describe("isExcludedCodegenFile", () => {
     "Hero.stories.tsx",
     "sections.gen.ts",
     "meta.gen.json",
+    // Bare names (no prefix before the dot) must be excluded too.
+    "test.ts",
+    "test.tsx",
+    "spec.tsx",
+    "stories.ts",
+    "gen.ts",
   ])("excludes %s", (name) => {
     expect(isExcludedCodegenFile(name)).toBe(true);
   });
 
-  it.each(["Hero.tsx", "Product/SearchResult.tsx", "testimonials.tsx", "generic.ts"])(
-    "keeps %s",
-    (name) => {
-      expect(isExcludedCodegenFile(name)).toBe(false);
-    },
-  );
+  it.each([
+    "Hero.tsx",
+    "Product/SearchResult.tsx",
+    // Marker word embedded mid-identifier (not its own dot-delimited
+    // segment) must stay INCLUDED, even with the bare-name matching above.
+    "testimonials.tsx",
+    "generic.ts",
+  ])("keeps %s", (name) => {
+    expect(isExcludedCodegenFile(name)).toBe(false);
+  });
 });

package/scripts/lib/codegenExclusions.ts

@@ -3,8 +3,20 @@
  * `generate-schema.ts` once emitted a site's co-located test file as a
  * section block (it scans every .ts/.tsx under the sections dir), so both
  * generators route their directory walks through this predicate.
+ *
+ * Matches both the usual `<name>.test.ts` co-located form and a bare
+ * `test.ts` / `spec.tsx` / `stories.ts` / `gen.ts` file (no prefix before
+ * the dot) — `(?:^|\.)` anchors the marker word to either the start of the
+ * filename or a preceding dot, so `testimonials.tsx` / `generic.ts` (marker
+ * word embedded mid-identifier, not its own dot-delimited segment) are
+ * correctly left INCLUDED.
+ *
+ * IMPORTANT: only ever apply this predicate to file entries, not
+ * directories, during a directory walk — a directory named e.g.
+ * `foo.gen.ts` is a real (if unusual) path segment, not a generated file,
+ * and must still be descended into.
  */
-const EXCLUDED_SUFFIX_RE = /\.(test|spec|stories|gen)\.(ts|tsx|js|jsx|json)$/;
+const EXCLUDED_SUFFIX_RE = /(?:^|\.)(test|spec|stories|gen)\.(ts|tsx|js|jsx|json)$/;
 
 export function isExcludedCodegenFile(fileName: string): boolean {
   return EXCLUDED_SUFFIX_RE.test(fileName);

package/scripts/migrate/analyzers/loader-inventory.ts

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import type { MigrationContext, LoaderInfo, Platform } from "../types";
 import { log } from "../types";
 
-/** Well-known loaders that map directly to @decocms/apps equivalents */
+/** Well-known loaders that map directly to @decocms/apps-* equivalents */
 const APPS_EQUIVALENTS: Record<string, string> = {
   "loaders/availableIcons.ts": "", // deleted
   "loaders/icons.ts": "", // deleted

package/scripts/migrate/phase-analyze.ts

@@ -255,7 +255,7 @@ function decideAction(
   if (SDK_DELETE.has(relPath)) {
     return {
       action: "delete",
-      notes: "Use framework equivalent from @decocms/start or @decocms/apps",
+      notes: "Use framework equivalent from @decocms/blocks or @decocms/apps-vtex",
     };
   }
 
@@ -263,13 +263,13 @@ function decideAction(
   if (COMPONENT_DELETE.has(relPath)) {
     return {
       action: "delete",
-      notes: "Scaffolded fresh from @decocms/apps re-exports",
+      notes: "Scaffolded fresh from @decocms/blocks re-exports",
     };
   }
 
   // cart/ directory → delete
   if (relPath.startsWith("sdk/cart/")) {
-    return { action: "delete", notes: "Use @decocms/apps cart hooks" };
+    return { action: "delete", notes: "Use @decocms/apps-vtex cart hooks" };
   }
 
   // Non-platform cleanup is done in analyze() post-processing (needs ctx.platform)

package/scripts/migrate/phase-cleanup.test.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { writeImportedLibShims } from "./phase-cleanup";
+import { upgradeSectionRenderer, writeImportedLibShims } from "./phase-cleanup";
 import type { MigrationContext } from "./types";
 
 /**
@@ -139,3 +139,72 @@ describe("writeImportedLibShims (integration)", () => {
     }
   });
 });
+
+describe("upgradeSectionRenderer (integration)", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "render-section-test-"));
+    fs.mkdirSync(path.join(tmpDir, "src", "components"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it(
+    "adds the missing RenderSection import when a .Component call is " +
+      "converted to JSX usage and no import exists yet (regression: the " +
+      "inner check used to always be false)",
+    () => {
+      const file = path.join(tmpDir, "src", "components", "Nested.tsx");
+      fs.writeFileSync(
+        file,
+        `export function Nested({ block }: { block: any }) {\n` +
+          `  return <block.Component {...block?.props} />;\n` +
+          `}\n`,
+      );
+
+      upgradeSectionRenderer(makeCtx(tmpDir));
+
+      const result = fs.readFileSync(file, "utf-8");
+      expect(result).toContain(
+        `import { RenderSection } from "@decocms/blocks/hooks";`,
+      );
+      expect(result).toContain(`<RenderSection section={block} />`);
+      // Import must appear before its first usage.
+      expect(result.indexOf("import { RenderSection }")).toBeLessThan(
+        result.indexOf("<RenderSection"),
+      );
+    },
+  );
+
+  it("does not duplicate the import when one already exists", () => {
+    const file = path.join(tmpDir, "src", "components", "Nested.tsx");
+    fs.writeFileSync(
+      file,
+      `import { RenderSection } from "@decocms/blocks/hooks";\n\n` +
+        `export function Nested({ block }: { block: any }) {\n` +
+        `  return <block.Component {...block?.props} />;\n` +
+        `}\n`,
+    );
+
+    upgradeSectionRenderer(makeCtx(tmpDir));
+
+    const result = fs.readFileSync(file, "utf-8");
+    const importCount = (
+      result.match(/import\s*\{\s*RenderSection\s*\}\s*from/g) ?? []
+    ).length;
+    expect(importCount).toBe(1);
+  });
+
+  it("does not touch files with no SectionRenderer/.Component usage", () => {
+    const file = path.join(tmpDir, "src", "components", "Plain.tsx");
+    const original = `export const Plain = () => <div>hi</div>;\n`;
+    fs.writeFileSync(file, original);
+
+    upgradeSectionRenderer(makeCtx(tmpDir));
+
+    expect(fs.readFileSync(file, "utf-8")).toBe(original);
+  });
+});

package/scripts/migrate/phase-cleanup.ts

@@ -963,7 +963,7 @@ function convertDirectComponentCalls(src: string, onFix: (msg: string) => void):
  * Also converts direct `<section.Component {...props}/>` patterns to use
  * RenderSection for robustness.
  */
-function upgradeSectionRenderer(ctx: MigrationContext) {
+export function upgradeSectionRenderer(ctx: MigrationContext) {
   rewriteFilesRecursive(ctx, path.join(ctx.sourceDir, "src"), (content, relPath) => {
     if (!relPath.endsWith(".tsx") && !relPath.endsWith(".ts")) return null;
 
@@ -971,12 +971,22 @@ function upgradeSectionRenderer(ctx: MigrationContext) {
     let changed = false;
 
     // 1. Replace `import { SectionRenderer } from "@decocms/start/hooks"`
-    //    with `import { RenderSection } from "@decocms/start/hooks"`
+    //    with `import { RenderSection } from "@decocms/blocks/hooks"`
+    //    (RenderSection is a distinct component from tanstack's
+    //    SectionRenderer — it lives in @decocms/blocks/hooks, not
+    //    @decocms/tanstack.)
+    //
+    //    HANDOFF MARKER: the "@decocms/start/hooks" specifier this matches
+    //    is written earlier in the same migration run by
+    //    transforms/jsx.ts (the `.Component`/`.props` → `<SectionRenderer>`
+    //    rewrite), which deliberately emits that pre-split package path as
+    //    a same-run handoff to this function. If the transform/cleanup
+    //    phase order ever changes, this match target must move with it.
     const sectionRendererImport =
       /import\s*\{([^}]*)\bSectionRenderer\b([^}]*)\}\s*from\s*["']@decocms\/start\/hooks["']/g;
     const newContent = result.replace(sectionRendererImport, (_m, before, after) => {
       changed = true;
-      return `import {${before}RenderSection${after}} from "@decocms/start/hooks"`;
+      return `import {${before}RenderSection${after}} from "@decocms/blocks/hooks"`;
     });
     if (newContent !== result) {
       result = newContent;
@@ -998,9 +1008,17 @@ function upgradeSectionRenderer(ctx: MigrationContext) {
       log(ctx, `  ${msg}: src/${relPath}`);
     });
 
-    // 4. Add RenderSection import if we introduced usages but no import exists
-    if (changed && result.includes("<RenderSection") && !result.includes("RenderSection")) {
-      result = `import { RenderSection } from "@decocms/start/hooks";\n` + result;
+    // 4. Add RenderSection import if we introduced usages but no import exists.
+    //    Must check for the actual import statement, not just the substring
+    //    "RenderSection" — every `<RenderSection` JSX usage also contains that
+    //    substring, so a naive `!result.includes("RenderSection")` check is
+    //    always false once step 2/3 above have run and this never fires.
+    const hasRenderSectionImport =
+      /import\s*\{[^}]*\bRenderSection\b[^}]*\}\s*from\s*["']@decocms\/blocks\/hooks["']/.test(
+        result,
+      );
+    if (changed && result.includes("<RenderSection") && !hasRenderSectionImport) {
+      result = `import { RenderSection } from "@decocms/blocks/hooks";\n` + result;
     }
 
     if (!changed) return null;
@@ -1013,16 +1031,18 @@ function upgradeSectionRenderer(ctx: MigrationContext) {
  *
  * Historical context:
  * Earlier versions of this script rewrote `@decocms/apps/vtex/utils/*` imports
- * to local `~/lib/vtex-*` shims because those modules did not exist yet in
- * `@decocms/apps`. They now do (apps-start exports `./vtex/utils/*` and
- * `./vtex/client` directly), so any further rewrite would actively REGRESS
- * working direct imports back into NO-OP shims and silently break runtime
- * behavior on every migrated site.
+ * (the pre-split Fresh/Deno site's original import shape) to local
+ * `~/lib/vtex-*` shims because those modules did not exist yet as
+ * directly-importable subpaths. They now do — the post-7.x split
+ * `@decocms/apps-vtex` package exports `./utils/*` and `./client`
+ * directly — so any further rewrite would actively REGRESS working direct
+ * imports back into NO-OP shims and silently break runtime behavior on
+ * every migrated site.
  *
  * Scope kept here:
  * - `@decocms/apps/vtex/loaders/intelligentSearch/*` → inline stubs
- *   (loaders moved under `inline-loaders/` in apps-start; this is still a
- *    real path-mismatch fixup)
+ *   (loaders moved under `inline-loaders/` in `@decocms/apps-vtex`; this
+ *    is still a real path-mismatch fixup)
  * - `LabelledFuzzy` type + `mapLabelledFuzzyToFuzzy` helper inlined when
  *   `intelligentSearch/productListingPage` is imported
  * - `createHttpClient<Type>(...)` → `createHttpClient(...)` (Proxy handles types)
@@ -1034,12 +1054,13 @@ function upgradeSectionRenderer(ctx: MigrationContext) {
  * What was removed:
  * The four `@decocms/apps/vtex/utils/* → ~/lib/vtex-*` rewrites that the
  * first-pass `transforms/imports.ts` (lines 50-52) already produces in the
- * correct, direct form. See discovery notes in MIGRATION_TOOLING_PLAN.md.
+ * correct, direct `@decocms/apps-vtex/utils/*` form. See discovery notes
+ * in MIGRATION_TOOLING_PLAN.md.
  */
 function rewriteVtexUtilImports(ctx: MigrationContext) {
   // Intentionally empty — see docstring. First-pass `transforms/imports.ts`
   // already maps `apps/vtex/utils/*` and `apps/vtex/client` directly to the
-  // `@decocms/apps` equivalents; rewriting them again here would dead-shim them.
+  // `@decocms/apps-vtex` equivalents; rewriting them again here would dead-shim them.
   const importRewrites: Array<{ pattern: RegExp; replacement: string; desc: string }> = [];
 
   rewriteFilesRecursive(ctx, path.join(ctx.sourceDir, "src"), (content, relPath) => {
@@ -1117,12 +1138,12 @@ function rewriteVtexUtilImports(ctx: MigrationContext) {
       log(ctx, `  Replaced inline getISCookiesFromBag stub → ~/lib/vtex-intelligent-search: src/${relPath}`);
     }
 
-    // Rewrite ~/utils/retry → @decocms/start/sdk/retry
+    // Rewrite ~/utils/retry → @decocms/blocks/sdk/retry
     const retryImport = /from\s+["']~\/utils\/retry["']/g;
     if (retryImport.test(result)) {
-      result = result.replace(retryImport, 'from "@decocms/start/sdk/retry"');
+      result = result.replace(retryImport, 'from "@decocms/blocks/sdk/retry"');
       changed = true;
-      log(ctx, `  Rewrote retry import → @decocms/start/sdk/retry: src/${relPath}`);
+      log(ctx, `  Rewrote retry import → @decocms/blocks/sdk/retry: src/${relPath}`);
     }
 
     // Rewrite type-only imports from productListingPage (Props type)
@@ -1301,7 +1322,7 @@ function moveRootConstantsToSrc(ctx: MigrationContext) {
  * with broken imports.
  *
  * New stack: the canonical Minicart contract + VTEX transform live in
- * `@decocms/apps/vtex/inline-loaders/minicart`. We replace the loader with a
+ * `@decocms/apps-vtex/inline-loaders/minicart`. We replace the loader with a
  * thin VTEX-only re-export. Sites on Shopify/VNDA/Wake/Linx/Nuvemshop are
  * not currently in production on the new stack — when one is, swap this for
  * a runtime dispatcher again or add a platform-flagged rewrite.
@@ -1325,19 +1346,19 @@ function rewriteMinicartLoader(ctx: MigrationContext) {
 //
 // The legacy site shipped per-platform loaders behind a \`usePlatform()\`
 // switch (vnda, wake, linx, shopify, nuvemshop). The canonical minicart
-// contract now lives in \`@decocms/apps\`. Until a non-VTEX customer comes
+// contract now lives in \`@decocms/apps-vtex\`. Until a non-VTEX customer comes
 // online on the new stack, we re-export the framework loader directly.
 // TODO: when adding another platform, replace this with a runtime
 // dispatcher and import the matching framework loader.
-export { default } from "@decocms/apps/vtex/inline-loaders/minicart";
-export type { MinicartProps } from "@decocms/apps/vtex/inline-loaders/minicart";
+export { default } from "@decocms/apps-vtex/inline-loaders/minicart";
+export type { MinicartProps } from "@decocms/apps-vtex/inline-loaders/minicart";
 `;
 
     if (ctx.dryRun) {
       log(ctx, `[DRY] Would rewrite: ${path.relative(ctx.sourceDir, filePath)} (VTEX-only re-export)`);
     } else {
       fs.writeFileSync(filePath, newContent);
-      log(ctx, `Rewrote: ${path.relative(ctx.sourceDir, filePath)} (VTEX-only re-export of @decocms/apps/vtex/inline-loaders/minicart)`);
+      log(ctx, `Rewrote: ${path.relative(ctx.sourceDir, filePath)} (VTEX-only re-export of @decocms/apps-vtex/inline-loaders/minicart)`);
     }
   }
 }
@@ -1422,7 +1443,7 @@ export function cleanup(ctx: MigrationContext): void {
 
   // 5. Override contexts/device.tsx with SSR-safe useSyncExternalStore version.
   // The transform phase copies and transforms the source file (createContext-based),
-  // but @decocms/start shell-renders sections without a Device.Provider, so we
+  // but @decocms/tanstack shell-renders sections without a Device.Provider, so we
   // must replace it with a standalone implementation.
   console.log("  Overriding contexts/device.tsx...");
   overrideDeviceContext(ctx);
@@ -1452,7 +1473,7 @@ export function cleanup(ctx: MigrationContext): void {
 
   // 11. Rewrite VTEX utility imports to use ~/lib/ wrappers
   //    The old stack imports from apps/vtex/utils/* which get rewritten to
-  //    @decocms/apps/vtex/utils/* — but the signatures are incompatible
+  //    @decocms/apps-vtex/utils/* — but the signatures are incompatible
   //    and some types (VTEXCommerceStable) don't exist. Replace with
   //    simplified ~/lib/ wrappers generated during scaffold.
   console.log("  Rewriting VTEX utility imports → ~/lib/ wrappers...");
@@ -1467,7 +1488,7 @@ export function cleanup(ctx: MigrationContext): void {
   // 11b. Rewrite legacy multi-platform minicart loader → VTEX-only re-export.
   //    `sdk/cart/` is deleted by DIRS_TO_DELETE, leaving loaders/minicart.ts
   //    with broken imports. Replace it with a thin re-export of the
-  //    framework's @decocms/apps/vtex/inline-loaders/minicart loader.
+  //    framework's @decocms/apps-vtex/inline-loaders/minicart loader.
   console.log("  Rewriting loaders/minicart.ts → VTEX-only re-export...");
   rewriteMinicartLoader(ctx);
 

package/scripts/migrate/phase-report.ts

@@ -5,11 +5,11 @@ import { logPhase } from "./types";
 
 const FRAMEWORK_FINDINGS = [
   "Session/analytics SDK is boilerplate duplicated across all sites — should be a single framework function",
-  "GTM event system (useGTMEvent, data-gtm-* listeners) is universal pattern — should be in @decocms/start",
+  "GTM event system (useGTMEvent, data-gtm-* listeners) is universal pattern — should be in @decocms/blocks",
   "Route files (__root.tsx, index.tsx, $.tsx, deco/*) are near-identical across sites — should be generated by framework",
   "server.ts, worker-entry.ts, router.tsx are pure boilerplate — should be a single createSite() call",
   "setup.ts section registration via import.meta.glob is 100% boilerplate — framework should handle this",
-  "runtime.ts invoke proxy is identical across sites — already in @decocms/start but sites still have local copies",
+  "runtime.ts invoke proxy is identical across sites — already in @decocms/blocks/sdk/invoke but sites still have local copies",
   "apps/site.ts is mostly empty after migration — platform config should be in a config file, not code",
 ];
 
@@ -124,7 +124,7 @@ export function report(ctx: MigrationContext): void {
     lines.push("## Loader Inventory");
     lines.push("");
     lines.push(`- **${ctx.loaderInventory.length}** loaders inventoried`);
-    lines.push(`- **${mapped}** mapped to \`@decocms/apps\` equivalents`);
+    lines.push(`- **${mapped}** mapped to \`@decocms/apps-*\` equivalents`);
     lines.push(`- **${custom}** custom (included in \`setup/commerce-loaders.ts\`)`);
     lines.push("");
   }
@@ -175,7 +175,7 @@ export function report(ctx: MigrationContext): void {
   lines.push("## Framework Findings");
   lines.push("");
   lines.push(
-    "> These are patterns found during migration that should eventually be handled by `@decocms/start` instead of being duplicated in every site.",
+    "> These are patterns found during migration that should eventually be handled by `@decocms/blocks` instead of being duplicated in every site.",
   );
   lines.push("");
   for (const finding of ctx.frameworkFindings) {
@@ -215,11 +215,11 @@ export function report(ctx: MigrationContext): void {
   lines.push("#");
   lines.push("#    Forwarding to a future ClickHouse-backed OTel collector is on the");
   lines.push("#    roadmap (placeholder lives at");
-  lines.push("#    @decocms/start/sdk/otelAdapters/clickhouseCollector); when it");
+  lines.push("#    @decocms/blocks/sdk/otelAdapters/clickhouseCollector); when it");
   lines.push("#    ships, the codemod gains a `--destination-logs` /");
   lines.push("#    `--destination-traces` flag to point at it.");
-  lines.push("npx -p @decocms/start deco-cf-observability         # dry-run");
-  lines.push("npx -p @decocms/start deco-cf-observability --write # apply");
+  lines.push("npx -p @decocms/blocks-cli deco-cf-observability         # dry-run");
+  lines.push("npx -p @decocms/blocks-cli deco-cf-observability --write # apply");
   lines.push("```");
   lines.push("");
 

package/scripts/migrate/phase-scaffold.ts

@@ -135,7 +135,7 @@ export function scaffold(ctx: MigrationContext): void {
   // some file actually imports. See `writeImportedLibShims` in phase-cleanup.
 
   // Replace Context-based useDevice with SSR-safe useSyncExternalStore version.
-  // @decocms/start shell-renders sections in a separate React root without
+  // @decocms/tanstack shell-renders sections in a separate React root without
   // Device.Provider, so the old createContext pattern throws during SSR.
   writeFile(ctx, "src/contexts/device.tsx", generateDeviceContext());
 
@@ -312,7 +312,7 @@ export default debounce;
 
 function generateSignalShim(): string {
   return `import { useState, useRef, useEffect, useMemo, useCallback } from "react";
-export { signal, type ReactiveSignal } from "@decocms/start/sdk/signal";
+export { signal, type ReactiveSignal } from "@decocms/blocks/sdk/signal";
 
 /** Run a function immediately. Kept for legacy module-level side effects. */
 export function effect(fn: () => void | (() => void)): () => void {
@@ -535,8 +535,8 @@ function generateLocationMatcher(): string {
  * rules server-side.
  */
 
-import { registerMatcher } from "@decocms/start/cms";
-import type { MatcherContext } from "@decocms/start/cms";
+import { registerMatcher } from "@decocms/blocks/cms";
+import type { MatcherContext } from "@decocms/blocks/cms";
 
 const COUNTRY_NAME_TO_CODE: Record<string, string> = {
   Brasil: "BR",