@decocms/blocks-cli 7.5.1 → 7.5.3

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

@@ -20,7 +20,7 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"@preact\/signals"$/, `"~/sdk/signal"`],
 
   // Deco framework — hooks need splitting (useDevice, useScript, useSection)
-  [/^"@deco\/deco\/hooks"$/, `"@decocms/start/sdk/useScript"`],
+  [/^"@deco\/deco\/hooks"$/, `"@decocms/blocks/sdk/useScript"`],
   [/^"@deco\/deco\/blocks"$/, `"~/types/deco"`],
   [/^"@deco\/deco\/o11y"$/, null], // logger — use console.log/warn/error instead
   [/^"@deco\/deco\/web"$/, null], // runtime.ts is rewritten
@@ -32,66 +32,82 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   // Widget aliases (ImageWidget, HTMLWidget, ...) are framework-owned —
   // every site has the same type set, and the schema generator detects
   // them via type-text matching, not module identity. Re-export from
-  // @decocms/start/types/widgets so we don't keep a duplicated 8-line
+  // @decocms/blocks/types/widgets so we don't keep a duplicated 8-line
   // file in every site.
-  [/^"apps\/admin\/widgets\.ts"$/, `"@decocms/start/types/widgets"`],
+  [/^"apps\/admin\/widgets\.ts"$/, `"@decocms/blocks/types/widgets"`],
   [/^"apps\/website\/components\/Image\.tsx"$/, `"~/components/ui/Image"`],
   [/^"apps\/website\/components\/Picture\.tsx"$/, `"~/components/ui/Picture"`],
   [/^"apps\/website\/components\/Video\.tsx"$/, `"~/components/ui/Video"`],
   [/^"apps\/website\/components\/Theme\.tsx"$/, `"~/components/ui/Theme"`],
   [/^"apps\/website\/components\/_seo\/[^"]+?"$/, null], // SEO preview — framework-only, remove
   [/^"apps\/website\/components\/([^"]+?)(?:\.tsx?)?"$/, `"~/components/ui/$1"`],
-  [/^"apps\/commerce\/types\.ts"$/, `"@decocms/apps/commerce/types"`],
+  [/^"apps\/commerce\/types\.ts"$/, `"@decocms/apps-commerce/types"`],
   [/^"apps\/commerce\/mod\.ts"$/, `"~/types/commerce-app"`],
-  [/^"apps\/commerce\/types"$/, `"@decocms/apps/commerce/types"`],
+  [/^"apps\/commerce\/types"$/, `"@decocms/apps-commerce/types"`],
 
-  // Apps — VTEX hooks: useUser/useCart/useWishlist → local hooks (react-query based @decocms/apps hooks crash Workers SSR)
+  // Apps — VTEX hooks: useUser/useCart/useWishlist → local hooks (react-query based @decocms/apps-vtex hooks crash Workers SSR)
   [/^"apps\/vtex\/hooks\/useUser(?:\.ts)?"$/, `"~/hooks/useUser"`],
   [/^"apps\/vtex\/hooks\/useCart(?:\.ts)?"$/, `"~/hooks/useCart"`],
   [/^"apps\/vtex\/hooks\/useWishlist(?:\.ts)?"$/, `"~/hooks/useWishlist"`],
-  [/^"apps\/vtex\/hooks\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/hooks/$1"`],
-  // Specific VTEX utils that moved to different paths in @decocms/apps
+  [/^"apps\/vtex\/hooks\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps-vtex/hooks/$1"`],
+  // Specific VTEX utils that moved to different paths in @decocms/apps-vtex
   // fetchVTEX (generic fetchSafe + QS sanitization) lives at vtex/utils/fetch in apps-start.
-  [/^"apps\/vtex\/utils\/fetchVTEX(?:\.ts)?"$/, `"@decocms/apps/vtex/utils/fetch"`],
-  [/^"apps\/vtex\/utils\/client(?:\.ts)?"$/, `"@decocms/apps/vtex/client"`],
-  [/^"apps\/vtex\/utils\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/utils/$1"`],
-  [/^"apps\/vtex\/actions\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/actions/$1"`],
+  [/^"apps\/vtex\/utils\/fetchVTEX(?:\.ts)?"$/, `"@decocms/apps-vtex/utils/fetch"`],
+  [/^"apps\/vtex\/utils\/client(?:\.ts)?"$/, `"@decocms/apps-vtex/client"`],
+  [/^"apps\/vtex\/utils\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps-vtex/utils/$1"`],
+  [/^"apps\/vtex\/actions\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps-vtex/actions/$1"`],
   // Tier B loader path rewrites (apps-start has no `intelligentSearch/`, `legacy/<file>`, or `paths/` subdirs).
   // Intelligent Search loaders moved to inline-loaders/.
   [
     /^"apps\/vtex\/loaders\/intelligentSearch\/productList(?:\.ts)?"$/,
-    `"@decocms/apps/vtex/inline-loaders/productList"`,
+    `"@decocms/apps-vtex/inline-loaders/productList"`,
   ],
   [
     /^"apps\/vtex\/loaders\/intelligentSearch\/productListingPage(?:\.ts)?"$/,
-    `"@decocms/apps/vtex/inline-loaders/productListingPage"`,
+    `"@decocms/apps-vtex/inline-loaders/productListingPage"`,
   ],
   [
     /^"apps\/vtex\/loaders\/intelligentSearch\/productDetailsPage(?:\.ts)?"$/,
-    `"@decocms/apps/vtex/inline-loaders/productDetailsPage"`,
+    `"@decocms/apps-vtex/inline-loaders/productDetailsPage"`,
   ],
   [
     /^"apps\/vtex\/loaders\/intelligentSearch\/suggestions(?:\.ts)?"$/,
-    `"@decocms/apps/vtex/inline-loaders/suggestions"`,
+    `"@decocms/apps-vtex/inline-loaders/suggestions"`,
   ],
   // Legacy product loaders are consolidated into a single file (named exports).
   [
     /^"apps\/vtex\/loaders\/legacy\/(?:productList|productListingPage|productDetailsPage|search|category)(?:\.ts)?"$/,
-    `"@decocms/apps/vtex/loaders/legacy"`,
+    `"@decocms/apps-vtex/loaders/legacy"`,
   ],
   // Path-default loaders (sitemap seeds) don't exist in TanStack Start — paths resolve at request time.
   [/^"apps\/vtex\/loaders\/paths\/(?:[^"]+)(?:\.ts)?"$/, null],
-  [/^"apps\/vtex\/loaders\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/loaders/$1"`],
-  [/^"apps\/vtex\/types(?:\.ts)?"$/, `"@decocms/apps/vtex/types"`],
+  [/^"apps\/vtex\/loaders\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps-vtex/loaders/$1"`],
+  [/^"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"`],
-  [/^"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"`],
+  // 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"`],
   // Apps — commerce (types, SDK, utils)
-  [/^"apps\/commerce\/sdk\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/commerce/sdk/$1"`],
-  [/^"apps\/commerce\/utils\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/commerce/utils/$1"`],
+  [/^"apps\/commerce\/sdk\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps-commerce/sdk/$1"`],
+  [/^"apps\/commerce\/utils\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps-commerce/utils/$1"`],
 
   // Apps — shared utils (STALE, fetchSafe, createHttpClient, etc.)
   [/^"apps\/utils\/fetch(?:\.ts)?"$/, `"~/lib/fetch-utils"`],
@@ -116,7 +132,7 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"@std\/crypto"$/, null], // Use globalThis.crypto instead
 
   // site/sdk/* → framework equivalents (before the catch-all site/ → ~/ rule)
-  [/^"site\/sdk\/clx(?:\.tsx?)?.*"$/, `"@decocms/start/sdk/clx"`],
+  [/^"site\/sdk\/clx(?:\.tsx?)?.*"$/, `"@decocms/blocks/sdk/clx"`],
   [/^"site\/sdk\/useId(?:\.tsx?)?.*"$/, `"react"`],
   // useOffer and useVariantPossiblities kept as site files (~/sdk/)
   [/^"site\/sdk\/usePlatform(?:\.tsx?)?.*"$/, null],
@@ -127,10 +143,10 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"~\/account\.json"$/, `"~/constants/account"`],
 
   // $store/ → ~/ (common Deno import map alias for project root)
-  [/^"\$store\/sdk\/clx(?:\.tsx?)?.*"$/, `"@decocms/start/sdk/clx"`],
+  [/^"\$store\/sdk\/clx(?:\.tsx?)?.*"$/, `"@decocms/blocks/sdk/clx"`],
   [/^"\$store\/sdk\/useId(?:\.tsx?)?.*"$/, `"react"`],
   // useOffer and useVariantPossiblities kept as site files (~/sdk/)
-  [/^"\$store\/sdk\/format(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/formatPrice"`],
+  [/^"\$store\/sdk\/format(?:\.tsx?)?.*"$/, `"@decocms/apps-commerce/sdk/formatPrice"`],
   [/^"\$store\/sdk\/usePlatform(?:\.tsx?)?.*"$/, null],
   // islands → components (must be before $store catch-all)
   [/^"\$store\/islands\/ui\/([^"]+?)(?:\.tsx?)?"$/, `"~/components/ui/$1"`],
@@ -141,10 +157,10 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"\$home\/(.+)"$/, `"~/$1"`],
 
   // site/ → ~/
-  [/^"site\/sdk\/clx(?:\.tsx?)?.*"$/, `"@decocms/start/sdk/clx"`],
+  [/^"site\/sdk\/clx(?:\.tsx?)?.*"$/, `"@decocms/blocks/sdk/clx"`],
   [/^"site\/sdk\/useId(?:\.tsx?)?.*"$/, `"react"`],
   // useOffer and useVariantPossiblities kept as site files (~/sdk/)
-  [/^"site\/sdk\/format(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/formatPrice"`],
+  [/^"site\/sdk\/format(?:\.tsx?)?.*"$/, `"@decocms/apps-commerce/sdk/formatPrice"`],
   [/^"site\/sdk\/usePlatform(?:\.tsx?)?.*"$/, null],
   // islands → components (must be before site/ catch-all)
   [/^"site\/islands\/ui\/([^"]+?)(?:\.tsx?)?"$/, `"~/components/ui/$1"`],
@@ -155,10 +171,16 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"~\/islands\/ui\/([^"]+?)(?:\.tsx?)?"$/, `"~/components/ui/$1"`],
   [/^"~\/islands\/([^"]+?)(?:\.tsx?)?"$/, `"~/components/$1"`],
 
-  // @decocms/apps hooks → local hooks (react-query hooks crash Workers SSR at module eval)
+  // @decocms/apps-vtex hooks → local hooks (react-query hooks crash Workers SSR at module eval)
+  // Pre-7.x monolith path — kept for sites whose Deno import map already
+  // aliased directly to the npm specifier instead of the "apps/vtex/..." form.
   [/^"@decocms\/apps\/vtex\/hooks\/useUser"$/, `"~/hooks/useUser"`],
   [/^"@decocms\/apps\/vtex\/hooks\/useCart"$/, `"~/hooks/useCart"`],
   [/^"@decocms\/apps\/vtex\/hooks\/useWishlist"$/, `"~/hooks/useWishlist"`],
+  // Post-7.x split package path — same rationale, current package name.
+  [/^"@decocms\/apps-vtex\/hooks\/useUser"$/, `"~/hooks/useUser"`],
+  [/^"@decocms\/apps-vtex\/hooks\/useCart"$/, `"~/hooks/useCart"`],
+  [/^"@decocms\/apps-vtex\/hooks\/useWishlist"$/, `"~/hooks/useWishlist"`],
 ];
 
 /**
@@ -167,14 +189,14 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
  * The key is the ending of the import path, the value is the replacement specifier.
  */
 const RELATIVE_SDK_REWRITES: Array<[RegExp, string]> = [
-  // sdk/clx → @decocms/start/sdk/clx (framework utility)
-  [/(?:\.\.\/)*sdk\/clx(?:\.tsx?)?$/, "@decocms/start/sdk/clx"],
+  // sdk/clx → @decocms/blocks/sdk/clx (framework utility)
+  [/(?:\.\.\/)*sdk\/clx(?:\.tsx?)?$/, "@decocms/blocks/sdk/clx"],
   // sdk/useId → react (useId is built-in in React 19)
   [/(?:\.\.\/)*sdk\/useId(?:\.tsx?)?$/, "react"],
   // sdk/useOffer — kept as-is (sites customize offer logic)
   // sdk/useVariantPossiblities — kept as-is (sites customize variant logic)
-  // sdk/format → @decocms/apps/commerce/sdk/formatPrice
-  [/(?:\.\.\/)*sdk\/format(?:\.tsx?)?$/, "@decocms/apps/commerce/sdk/formatPrice"],
+  // sdk/format → @decocms/apps-commerce/sdk/formatPrice
+  [/(?:\.\.\/)*sdk\/format(?:\.tsx?)?$/, "@decocms/apps-commerce/sdk/formatPrice"],
   // sdk/usePlatform → remove entirely
   [/(?:\.\.\/)*sdk\/usePlatform(?:\.tsx?)?$/, ""],
   // static/adminIcons → deleted (icon loaders need rewriting)
@@ -234,16 +256,16 @@ export function transformImports(
   /**
    * Post-process: split @deco/deco/hooks imports.
    * In the old stack, @deco/deco/hooks exported useDevice, useScript, useSection, etc.
-   * In @decocms/start, useDevice is at @decocms/start/sdk/useDevice.
+   * In @decocms/blocks, useDevice is at @decocms/blocks/sdk/useDevice.
    * After import rewriting, we need to split lines like:
-   *   import { useDevice, useScript } from "@decocms/start/sdk/useScript"
+   *   import { useDevice, useScript } from "@decocms/blocks/sdk/useScript"
    * into:
-   *   import { useDevice } from "@decocms/start/sdk/useDevice"
-   *   import { useScript } from "@decocms/start/sdk/useScript"
+   *   import { useDevice } from "@decocms/blocks/sdk/useDevice"
+   *   import { useScript } from "@decocms/blocks/sdk/useScript"
    */
   function splitDecoHooksImports(code: string): string {
     return code.replace(
-      /^(import\s+(?:type\s+)?\{)([^}]*\buseDevice\b[^}]*)(\}\s+from\s+["']@decocms\/start\/sdk\/useScript["'];?)$/gm,
+      /^(import\s+(?:type\s+)?\{)([^}]*\buseDevice\b[^}]*)(\}\s+from\s+["']@decocms\/blocks\/sdk\/useScript["'];?)$/gm,
       (_match, _prefix, importList, _suffix) => {
         const items = importList.split(",").map((s: string) => s.trim()).filter(Boolean);
         const deviceItems = items.filter((s: string) => s.includes("useDevice"));
@@ -251,10 +273,10 @@ export function transformImports(
 
         const lines: string[] = [];
         if (deviceItems.length > 0) {
-          lines.push(`import { ${deviceItems.join(", ")} } from "@decocms/start/sdk/useDevice";`);
+          lines.push(`import { ${deviceItems.join(", ")} } from "@decocms/blocks/sdk/useDevice";`);
         }
         if (otherItems.length > 0) {
-          lines.push(`import { ${otherItems.join(", ")} } from "@decocms/start/sdk/useScript";`);
+          lines.push(`import { ${otherItems.join(", ")} } from "@decocms/blocks/sdk/useScript";`);
         }
         return lines.join("\n");
       },
@@ -356,7 +378,7 @@ export function transformImports(
   if (afterSplit !== result) {
     result = afterSplit;
     changed = true;
-    notes.push("Split useDevice into separate import from @decocms/start/sdk/useDevice");
+    notes.push("Split useDevice into separate import from @decocms/blocks/sdk/useDevice");
   }
 
   // Rewrite dynamic imports: route through rewriteSpecifier so sdk-specific

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)) {

package/scripts/migrate/transforms/section-conventions.ts

@@ -8,7 +8,7 @@ import type { SectionMeta, TransformResult } from "../types";
  * Adds section convention exports (sync, eager, layout, cache)
  * to section files based on metadata extracted during analysis.
  *
- * These exports are read by generate-sections.ts in @decocms/start
+ * These exports are read by generate-sections.ts in @decocms/blocks-cli
  * to build the sections.gen.ts registry.
  *
  * The set of section *names* that get hints applied is configurable

package/scripts/migrate/types.ts

@@ -122,7 +122,7 @@ export interface LoaderInfo {
   hasCache: boolean;
   /** Has export const cacheKey */
   hasCacheKey: boolean;
-  /** Maps to a known @decocms/apps equivalent */
+  /** Maps to a known @decocms/apps-* equivalent */
   appsEquivalent: string | null;
   /** Is a custom loader that needs dynamic import in commerce-loaders */
   isCustom: boolean;

package/scripts/migrate-post-cleanup.ts

@@ -8,8 +8,8 @@
  * but turns it into something CI can actually run.
  *
  * Usage (from a migrated site directory):
- *   npx -p @decocms/start deco-post-cleanup
- *   npx -p @decocms/start deco-post-cleanup --json
+ *   npx -p @decocms/blocks-cli deco-post-cleanup
+ *   npx -p @decocms/blocks-cli deco-post-cleanup --json
  *
  * Options:
  *   --source <dir>   Site directory to audit (default: current directory)
@@ -65,13 +65,13 @@ function parseArgs(args: string[]): CliOpts {
 
 function showHelp() {
   console.log(`
-  @decocms/start — Post-Migration Cleanup Audit
+  @decocms/blocks-cli — Post-Migration Cleanup Audit
 
   Scans a migrated site for dead code and obsolete boilerplate that the
   framework now owns. Read-only — prints findings, does not modify files.
 
   Usage:
-    npx -p @decocms/start deco-post-cleanup [options]
+    npx -p @decocms/blocks-cli deco-post-cleanup [options]
 
   Options:
     --source <dir>   Site directory to audit (default: .)
@@ -88,10 +88,10 @@ function showHelp() {
     --help, -h       Show this help
 
   Examples:
-    npx -p @decocms/start deco-post-cleanup
-    npx -p @decocms/start deco-post-cleanup --source ./my-site --json
-    npx -p @decocms/start deco-post-cleanup --fix
-    npx -p @decocms/start deco-post-cleanup --fix --strict   # fail CI if anything left
+    npx -p @decocms/blocks-cli deco-post-cleanup
+    npx -p @decocms/blocks-cli deco-post-cleanup --source ./my-site --json
+    npx -p @decocms/blocks-cli deco-post-cleanup --fix
+    npx -p @decocms/blocks-cli deco-post-cleanup --fix --strict   # fail CI if anything left
 
   See: .agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md
   `);

package/scripts/migrate.ts

@@ -4,10 +4,10 @@
  * Migration Script: Fresh/Deno/Preact → TanStack Start/React/Cloudflare Workers
  *
  * Converts a Deco storefront from the old Fresh/Deno stack to the new TanStack Start stack.
- * Part of the @decocms/start framework — run from a site's root directory.
+ * Ships as part of @decocms/blocks-cli — run from a site's root directory.
  *
  * Usage (from your Fresh site directory):
- *   npx -p @decocms/start deco-migrate [options]
+ *   npx -p @decocms/blocks-cli deco-migrate [options]
  *
  * Options:
  *   --source <dir>    Source directory (default: current directory)
@@ -102,10 +102,10 @@ function parseArgs(args: string[]): {
 
 function showHelp() {
   console.log(`
-  @decocms/start — Migration Script: Fresh/Deno → TanStack Start
+  @decocms/blocks-cli — Migration Script: Fresh/Deno → TanStack Start
 
   Usage:
-    npx -p @decocms/start deco-migrate [options]
+    npx -p @decocms/blocks-cli deco-migrate [options]
 
   Options:
     --source <dir>        Source directory (default: .)
@@ -119,10 +119,10 @@ function showHelp() {
     --help, -h            Show this help message
 
   Examples:
-    npx -p @decocms/start deco-migrate --dry-run --verbose
-    npx -p @decocms/start deco-migrate --source ./my-site
-    npx -p @decocms/start deco-migrate --strict --with-build
-    npx -p @decocms/start deco-migrate
+    npx -p @decocms/blocks-cli deco-migrate --dry-run --verbose
+    npx -p @decocms/blocks-cli deco-migrate --source ./my-site
+    npx -p @decocms/blocks-cli deco-migrate --strict --with-build
+    npx -p @decocms/blocks-cli deco-migrate
   `);
 }
 
@@ -136,7 +136,7 @@ async function main() {
 
   const sourceDir = path.resolve(opts.source);
 
-  banner("@decocms/start — Migrate: Fresh/Deno → TanStack Start");
+  banner("@decocms/blocks-cli — Migrate: Fresh/Deno → TanStack Start");
   stat("Source", sourceDir);
   stat("Mode", opts.dryRun ? yellow("DRY RUN") : green("EXECUTE"));
   stat("Verbose", opts.verbose ? "yes" : "no");
@@ -254,7 +254,7 @@ function bootstrap(ctx: { sourceDir: string }) {
   // matching `packageManager` field that pins the version.
   const pm = "bun";
   if (!run(`${pm} install`, "Install dependencies", true)) return;
-  run("bunx tsx node_modules/@decocms/start/scripts/generate-blocks.ts", "Generate CMS blocks");
+  run("bunx tsx node_modules/@decocms/blocks-cli/scripts/generate-blocks.ts", "Generate CMS blocks");
   // generate-invoke emits src/server/invoke.gen.ts with top-level
   // createServerFn declarations + the forwardResponseCookies bridge that
   // propagates VTEX Set-Cookie headers (orderFormId, segment, sc…) to the
@@ -265,7 +265,7 @@ function bootstrap(ctx: { sourceDir: string }) {
   // running the generator gives every freshly-migrated site the canonical
   // RPC path so VTEX hooks (useCart, useUser, useWishlist) work end-to-end.
   run(
-    "bunx tsx node_modules/@decocms/start/scripts/generate-invoke.ts",
+    "bunx tsx node_modules/@decocms/blocks-cli/scripts/generate-invoke.ts",
     "Generate VTEX invoke server functions",
   );
   run("bunx tsr generate", "Generate TanStack routes");