@decocms/blocks-cli 7.5.2 → 7.5.4

package/package.json

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

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/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;
 
@@ -975,6 +975,13 @@ function upgradeSectionRenderer(ctx: MigrationContext) {
     //    (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) => {
@@ -1001,8 +1008,16 @@ 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")) {
+    // 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;
     }
 

package/scripts/migrate/templates/package-json.ts

@@ -100,6 +100,12 @@ export function generatePackageJson(ctx: MigrationContext): string {
   // published in lockstep from the same monorepo release, so a single
   // version lookup covers all of them (mirrors how consumer sites bump
   // "@decocms/blocks/blocks-admin/nextjs ranges" together).
+  //
+  // If this ever stops being true (e.g. a package starts shipping
+  // independent version bumps), every `${frameworkVersion}` usage below
+  // (in `dependencies` and `devDependencies`) needs to become its own
+  // `getLatestVersion("<package>", "<fallback>")` call instead of sharing
+  // this one lookup.
   const frameworkVersion = getLatestVersion("@decocms/blocks", "7.5.1");
 
   const platformPackage: Partial<Record<typeof ctx.platform, string>> = {

package/scripts/migrate/transforms/imports.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "vitest";
+import { transformImports } from "./imports";
+
+describe("transformImports — shopify hooks", () => {
+  it("rewrites the three known Shopify hooks to the site-local scaffolded files, mirroring VTEX", () => {
+    const src =
+      `import { useUser } from "apps/shopify/hooks/useUser.ts";\n` +
+      `import { useCart } from "apps/shopify/hooks/useCart.ts";\n` +
+      `import { useWishlist } from "apps/shopify/hooks/useWishlist.ts";\n`;
+
+    const r = transformImports(src);
+
+    expect(r.changed).toBe(true);
+    expect(r.content).toContain(`import { useUser } from "~/hooks/useUser";`);
+    expect(r.content).toContain(`import { useCart } from "~/hooks/useCart";`);
+    expect(r.content).toContain(
+      `import { useWishlist } from "~/hooks/useWishlist";`,
+    );
+    // Must never point at the nonexistent @decocms/apps-shopify/hooks/* target.
+    expect(r.content).not.toContain("@decocms/apps-shopify/hooks");
+  });
+
+  it("does not rewrite an unknown shopify hook name to a nonexistent package export", () => {
+    // No shopify hook other than useCart/useUser/useWishlist has ever existed
+    // (verified against full git history), so there is no generic fallback
+    // rule anymore. Unhandled "apps/*" imports fall through to the general
+    // apps/ catch-all, which removes the import line entirely — surfacing as
+    // an obvious break at the usage site rather than an unresolvable module.
+    const src = `import { useSomethingElse } from "apps/shopify/hooks/useSomethingElse.ts";\n`;
+
+    const r = transformImports(src);
+
+    expect(r.content).not.toContain("@decocms/apps-shopify/hooks");
+    expect(r.content).not.toContain("apps/shopify/hooks");
+  });
+
+  it("still rewrites shopify utils/actions/loaders to the real @decocms/apps-shopify package", () => {
+    const src =
+      `import { formatMoney } from "apps/shopify/utils/formatMoney.ts";\n` +
+      `import { addItems } from "apps/shopify/actions/cart/addItems.ts";\n` +
+      `import ProductList from "apps/shopify/loaders/ProductList.ts";\n`;
+
+    const r = transformImports(src);
+
+    expect(r.content).toContain(
+      `import { formatMoney } from "@decocms/apps-shopify/utils/formatMoney";`,
+    );
+    expect(r.content).toContain(
+      `import { addItems } from "@decocms/apps-shopify/actions/cart/addItems";`,
+    );
+    expect(r.content).toContain(
+      `import ProductList from "@decocms/apps-shopify/loaders/ProductList";`,
+    );
+  });
+});
+
+describe("transformImports — splitDecoHooksImports", () => {
+  it("splits a mixed useDevice + non-useDevice named import from the legacy @deco/deco/hooks specifier", () => {
+    const src = `import { useDevice, useScript, useSection } from "@deco/deco/hooks";\n`;
+
+    const r = transformImports(src);
+
+    expect(r.changed).toBe(true);
+    expect(r.content).toContain(
+      `import { useDevice } from "@decocms/blocks/sdk/useDevice";`,
+    );
+    expect(r.content).toContain(
+      `import { useScript, useSection } from "@decocms/blocks/sdk/useScript";`,
+    );
+    expect(r.notes).toContain(
+      "Split useDevice into separate import from @decocms/blocks/sdk/useDevice",
+    );
+  });
+
+  it("emits only the useDevice import when useDevice is the sole named import", () => {
+    const src = `import { useDevice } from "@deco/deco/hooks";\n`;
+
+    const r = transformImports(src);
+
+    expect(r.content).toBe(
+      `import { useDevice } from "@decocms/blocks/sdk/useDevice";\n`,
+    );
+    expect(r.content).not.toContain("@decocms/blocks/sdk/useScript");
+  });
+
+  it("leaves a non-useDevice-only import pointed at useScript, unsplit", () => {
+    const src = `import { useScript, useSection } from "@deco/deco/hooks";\n`;
+
+    const r = transformImports(src);
+
+    expect(r.content).toBe(
+      `import { useScript, useSection } from "@decocms/blocks/sdk/useScript";\n`,
+    );
+    expect(r.content).not.toContain("@decocms/blocks/sdk/useDevice");
+  });
+
+  it("handles a `type` import with mixed useDevice/non-useDevice specifiers", () => {
+    const src = `import type { useDevice, useScript } from "@deco/deco/hooks";\n`;
+
+    const r = transformImports(src);
+
+    // The base IMPORT_RULES rewrite fires first (regardless of `type`), then
+    // splitDecoHooksImports re-splits the resulting line — confirming the
+    // regex-chain order (rewriteSpecifier → splitDecoHooksImports) still
+    // matches `import type { ... }` shapes, not just bare `import { ... }`.
+    expect(r.content).toContain(
+      `import { useDevice } from "@decocms/blocks/sdk/useDevice";`,
+    );
+    expect(r.content).toContain(
+      `import { useScript } from "@decocms/blocks/sdk/useScript";`,
+    );
+  });
+
+  it("preserves aliased specifiers (useDevice as useDeviceHook) on the split line", () => {
+    const src = `import { useDevice as useDeviceHook, useScript } from "@deco/deco/hooks";\n`;
+
+    const r = transformImports(src);
+
+    expect(r.content).toContain(
+      `import { useDevice as useDeviceHook } from "@decocms/blocks/sdk/useDevice";`,
+    );
+    expect(r.content).toContain(
+      `import { useScript } from "@decocms/blocks/sdk/useScript";`,
+    );
+  });
+
+  it("does not touch @decocms/blocks/sdk/useScript imports that were never routed through @deco/deco/hooks", () => {
+    // Guards the order-of-operations: splitDecoHooksImports must only ever
+    // fire as a post-process of the IMPORT_RULES rewrite, not independently
+    // match any pre-existing import already targeting useScript.
+    const src = `import { useScript } from "@decocms/blocks/sdk/useScript";\n`;
+
+    const r = transformImports(src);
+
+    expect(r.changed).toBe(false);
+    expect(r.content).toBe(src);
+  });
+});

package/scripts/migrate/transforms/imports.ts

@@ -85,7 +85,23 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"apps\/vtex\/types(?:\.ts)?"$/, `"@decocms/apps-vtex/types"`],
   [/^"apps\/vtex\/mod(?:\.ts)?"$/, `"~/types/vtex-app"`],
   // Apps — Shopify (hooks, utils, actions, loaders)
-  [/^"apps\/shopify\/hooks\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps-shopify/hooks/$1"`],
+  // Shopify hooks were never a real package export — not in the pre-split
+  // @decocms/apps monolith, not in @decocms/apps-shopify today (it ships
+  // no src/hooks/ dir and no ./hooks/* export; verified via `git log
+  // --diff-filter=A -- '**/shopify/hooks/**'` returning nothing across all
+  // history). The legacy migration reference
+  // (.agents/skills/deco-to-tanstack-migration/references/platform-hooks/README.md)
+  // confirms Shopify's useCart/useUser/useWishlist were always meant to be
+  // site-local no-op stubs, and templates/hooks.ts's generateHooks() still
+  // scaffolds them at src/hooks/use{Cart,User,Wishlist}.ts for every
+  // non-VTEX platform (shopify included). Mirror the VTEX rule shape below:
+  // route the three known hook names to the scaffolded local files, same as
+  // "apps/vtex/hooks/useUser" → "~/hooks/useUser" above. Do NOT reintroduce
+  // a generic "apps/shopify/hooks/$1" → "@decocms/apps-shopify/hooks/$1"
+  // fallback — that target has never existed.
+  [/^"apps\/shopify\/hooks\/useUser(?:\.ts)?"$/, `"~/hooks/useUser"`],
+  [/^"apps\/shopify\/hooks\/useCart(?:\.ts)?"$/, `"~/hooks/useCart"`],
+  [/^"apps\/shopify\/hooks\/useWishlist(?:\.ts)?"$/, `"~/hooks/useWishlist"`],
   [/^"apps\/shopify\/utils\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps-shopify/utils/$1"`],
   [/^"apps\/shopify\/actions\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps-shopify/actions/$1"`],
   [/^"apps\/shopify\/loaders\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps-shopify/loaders/$1"`],

package/scripts/migrate/transforms/jsx.ts

@@ -257,6 +257,14 @@ export function transformJsx(content: string): TransformResult {
   // In TanStack Start, nested sections have Component as a string key, not a function.
   // SectionRenderer from @decocms/start/hooks handles the lazy registry lookup.
   //
+  // HANDOFF MARKER: "@decocms/start/hooks" below is intentionally the
+  // pre-split package path, not the real current one — it's a same-run
+  // handoff to phase-cleanup.ts's upgradeSectionRenderer(), which runs
+  // later in the same migration and rewrites this exact import specifier
+  // to `import { RenderSection } from "@decocms/blocks/hooks"`. If this
+  // transform's run order relative to the cleanup phase ever changes, that
+  // rewrite target must move with it.
+  //
   // Gate on ANY variant of the .Component/.props pattern (simple, extra props, or multi-line).
   const sectionPatternGate = /\.\s*Component[\s\n]+\{\.\.\.(\w+)\.props\}/;
   if (sectionPatternGate.test(result)) {