@decocms/start 2.15.0 → 2.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/migrate/post-cleanup/rules.ts

@@ -452,6 +452,60 @@ const ruleVtexShimRegression: Rule = {
     }
     return findings;
   },
+  applyFix({ siteDir, fs }, findings, writer): FixAction[] {
+    if (findings.length === 0) return [];
+    const actions: FixAction[] = [];
+
+    // Per-file rewrite. Conservative: only swap the import path when EVERY
+    // imported symbol from the shim is a `kind: "swap"` hint pointing at
+    // the same canonical module. Mixed surfaces (some swap + some
+    // refactor, or a real impl + a stub) stay untouched — those need a
+    // human looking at call-site signatures.
+    for (const finding of findings) {
+      const stubsBySim = (finding.meta?.stubsBySim ?? {}) as Record<string, string[]>;
+      const abs = `${siteDir}/${finding.file}`;
+      if (!fs.exists(abs)) continue;
+
+      let content = fs.readText(abs);
+      let modified = false;
+
+      for (const [shim, _stubSyms] of Object.entries(stubsBySim)) {
+        const oldSpec = `~/lib/${shim}`;
+        const importedSymbols = namedRuntimeImportsFrom(content, oldSpec);
+        if (importedSymbols.length === 0) continue;
+
+        // Every imported symbol must be a swap-kind hint AND every hint
+        // must point at the same canonical module — otherwise we'd
+        // either drop a real impl or split the import across two paths,
+        // both of which are unsafe to do mechanically here.
+        const hints = importedSymbols.map((s) => STUB_FIX_HINTS[s]);
+        const allSwap = hints.every((h) => h && h.kind === "swap");
+        if (!allSwap) continue;
+        const targets = new Set(
+          hints.map((h) => (h as { kind: "swap"; canonical: string }).canonical),
+        );
+        if (targets.size !== 1) continue;
+        const target = [...targets][0];
+
+        const escaped = oldSpec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const importLineRe = new RegExp(`from\\s+(['"])${escaped}\\1`, "g");
+        const next = content.replace(importLineRe, (_m, q) => `from ${q}${target}${q}`);
+        if (next !== content) {
+          content = next;
+          modified = true;
+          actions.push({
+            file: finding.file,
+            kind: "rewrite-imports",
+            detail: `${oldSpec} → ${target} (${importedSymbols.join(", ")})`,
+          });
+        }
+      }
+
+      if (modified) writer.writeText(abs, content);
+    }
+
+    return actions;
+  },
 };
 
 /* ------------------------------------------------------------------ */

package/scripts/migrate/post-cleanup/runner.test.ts

@@ -587,7 +587,12 @@ describe("runAudit — totals", () => {
       .map((r) => r.rule)
       .sort();
     expect(supported).toEqual(
-      ["dead-lib-shims", "dead-runtime-shim", "local-widgets-types"].sort(),
+      [
+        "dead-lib-shims",
+        "dead-runtime-shim",
+        "local-widgets-types",
+        "vtex-shim-regression",
+      ].sort(),
     );
   });
 });
@@ -681,3 +686,121 @@ describe("runAudit — fix mode", () => {
     expect(store["/site/src/sections/A.tsx"]).toContain('"~/types/widgets-extra"');
   });
 });
+
+/* ------------------------------------------------------------------ */
+/* W12-D / W12-E — vtex-shim-regression --fix for swap-able cases      */
+/* ------------------------------------------------------------------ */
+
+describe("runAudit — fix mode — vtex-shim-regression swap cases", () => {
+  it("rewrites `toProduct` import to canonical when it is the only stub imported", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/lib/vtex-transform.ts":
+        "export function toProduct(p: any): unknown { return p as unknown; }\n",
+      "/site/src/loaders/search.ts":
+        'import { toProduct } from "~/lib/vtex-transform";\nconsole.log(toProduct);\n',
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.fixes).toHaveLength(1);
+    expect(r.fixes![0].file).toBe("src/loaders/search.ts");
+    expect(r.fixes![0].kind).toBe("rewrite-imports");
+    expect(r.fixes![0].detail).toContain("@decocms/apps/vtex/utils/transform");
+    expect(r.fixes![0].detail).toContain("toProduct");
+    expect(store["/site/src/loaders/search.ts"]).toContain(
+      '"@decocms/apps/vtex/utils/transform"',
+    );
+    expect(store["/site/src/loaders/search.ts"]).not.toContain('"~/lib/vtex-transform"');
+  });
+
+  it("rewrites `withSegmentCookie` import to canonical when it is the only stub imported", () => {
+    const { fs, writer, store } = makeMutableFs({
+      // Mirrors the post-#123 throwing-stub body — `throw new Error(...)`
+      // is recognised by the shim classifier as `unconditional throw`.
+      "/site/src/lib/vtex-segment.ts":
+        'export function withSegmentCookie(..._args: any[]): any { throw new Error("stub"); }\n',
+      "/site/src/loaders/x.ts":
+        'import { withSegmentCookie } from "~/lib/vtex-segment";\nconsole.log(withSegmentCookie);\n',
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.fixes).toHaveLength(1);
+    expect(r.fixes![0].detail).toContain("@decocms/apps/vtex/utils/segment");
+    expect(store["/site/src/loaders/x.ts"]).toContain(
+      '"@decocms/apps/vtex/utils/segment"',
+    );
+  });
+
+  it("does NOT rewrite mixed swap+refactor surface (getSegmentFromBag is refactor-only)", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/lib/vtex-segment.ts":
+        "export function getSegmentFromBag(_req?: any): null { return null; }\n" +
+        'export function withSegmentCookie(..._args: any[]): any { throw new Error("stub"); }\n',
+      "/site/src/loaders/x.ts":
+        'import { getSegmentFromBag, withSegmentCookie } from "~/lib/vtex-segment";\n',
+    });
+    const before = store["/site/src/loaders/x.ts"];
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    // Finding still emitted (audit), but no fix applied (mixed surface).
+    expect(r.findings).toHaveLength(1);
+    expect(r.fixes).toEqual([]);
+    expect(store["/site/src/loaders/x.ts"]).toBe(before);
+  });
+
+  it("does NOT rewrite when the file imports a real impl from the same shim", () => {
+    // vtex-intelligent-search exports both `getISCookiesFromBag` (stub →
+    // refactor) and `isFilterParam` (real impl, not in STUB_FIX_HINTS).
+    // Even if only one symbol is imported, the rule's classifier already
+    // skips real impls. But if a file imports BOTH, our --fix must not
+    // rewrite — the canonical doesn't expose isFilterParam.
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/lib/vtex-intelligent-search.ts":
+        "export function getISCookiesFromBag(_r?: any): Record<string,string> { return {}; }\n" +
+        "export function isFilterParam(k: string): boolean { return k.startsWith('filter.'); }\n",
+      "/site/src/loaders/x.ts":
+        'import { getISCookiesFromBag, isFilterParam } from "~/lib/vtex-intelligent-search";\n',
+    });
+    const before = store["/site/src/loaders/x.ts"];
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.fixes).toEqual([]);
+    expect(store["/site/src/loaders/x.ts"]).toBe(before);
+  });
+
+  it("rewrites multiple files using the same swap-able shim in one pass", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/lib/vtex-transform.ts":
+        "export function toProduct(p: any): unknown { return p as unknown; }\n",
+      "/site/src/loaders/A.ts":
+        'import { toProduct } from "~/lib/vtex-transform";\n',
+      "/site/src/loaders/B.ts":
+        "import { toProduct } from '~/lib/vtex-transform';\n",
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.fixes!.length).toBe(2);
+    expect(store["/site/src/loaders/A.ts"]).toContain(
+      '"@decocms/apps/vtex/utils/transform"',
+    );
+    expect(store["/site/src/loaders/B.ts"]).toContain(
+      "'@decocms/apps/vtex/utils/transform'",
+    );
+  });
+
+  it("preserves the named-imports list verbatim when swapping", () => {
+    // The fix only rewrites the FROM clause, not the imported names. Keeps
+    // local aliases (`as`) intact.
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/lib/vtex-transform.ts":
+        "export function toProduct(p: any): unknown { return p as unknown; }\n",
+      "/site/src/loaders/x.ts":
+        'import { toProduct as toP } from "~/lib/vtex-transform";\n' +
+        "console.log(toP);\n",
+    });
+    runAudit(SITE, fs, { writer });
+    expect(store["/site/src/loaders/x.ts"]).toContain(
+      'import { toProduct as toP } from "@decocms/apps/vtex/utils/transform"',
+    );
+  });
+});

package/scripts/migrate/templates/hooks.test.ts

@@ -66,6 +66,43 @@ describe("generateHooks (vtex)", () => {
 		// Should be well under 20 lines (factory call + re-export + imports).
 		expect(lineCount).toBeLessThan(20);
 	});
+
+	it("useUser is the createUseUser factory shim (no signal-stub boilerplate)", () => {
+		const code = files["src/hooks/useUser.ts"];
+		expect(code).toContain(
+			'import { createUseUser } from "@decocms/apps/vtex/hooks/createUseUser"',
+		);
+		expect(code).toContain('import { invoke } from "~/server/invoke"');
+		expect(code).toContain(
+			'export type { Person } from "@decocms/apps/vtex/loaders/user"',
+		);
+		expect(code).toContain("export const { useUser, resetUser } = createUseUser");
+		// Must NOT scaffold the legacy signal stub.
+		expect(code).not.toContain('signal<User | null>(null)');
+		expect(code).not.toContain("export interface User {");
+	});
+
+	it("useWishlist is the createUseWishlist factory shim", () => {
+		const code = files["src/hooks/useWishlist.ts"];
+		expect(code).toContain(
+			'import { createUseWishlist } from "@decocms/apps/vtex/hooks/createUseWishlist"',
+		);
+		expect(code).toContain('import { invoke } from "~/server/invoke"');
+		expect(code).toContain(
+			'export type { WishlistItem } from "@decocms/apps/vtex/loaders/wishlist"',
+		);
+		expect(code).toContain(
+			"export const { useWishlist, resetWishlist } = createUseWishlist",
+		);
+		// Must NOT scaffold the legacy stub with TODO action bodies.
+		expect(code).not.toContain("TODO: Implement");
+		expect(code).not.toContain("getItem(_productId: string): boolean");
+	});
+
+	it("useUser + useWishlist VTEX shims are each well under 10 lines", () => {
+		expect(files["src/hooks/useUser.ts"].split("\n").length).toBeLessThan(10);
+		expect(files["src/hooks/useWishlist.ts"].split("\n").length).toBeLessThan(10);
+	});
 });
 
 describe("generateHooks (non-vtex)", () => {
@@ -82,4 +119,23 @@ describe("generateHooks (non-vtex)", () => {
 		// Until a shopify factory exists, non-vtex platforms get the generic stub.
 		expect(code).toContain("Cart Hook stub");
 	});
+
+	it("non-vtex platforms keep the legacy signal-based useUser stub", () => {
+		const files = generateHooks(makeCtx("custom"));
+		const code = files["src/hooks/useUser.ts"];
+		// No factory CALL — docstring may mention it as a pointer for VTEX.
+		expect(code).not.toContain("createUseUser({");
+		expect(code).not.toContain("export const { useUser, resetUser }");
+		// Legacy stub shape (signal + User interface).
+		expect(code).toContain("signal<User | null>(null)");
+		expect(code).toContain("export interface User {");
+	});
+
+	it("non-vtex platforms keep the legacy useWishlist stub", () => {
+		const files = generateHooks(makeCtx("custom"));
+		const code = files["src/hooks/useWishlist.ts"];
+		expect(code).not.toContain("createUseWishlist({");
+		expect(code).not.toContain("export const { useWishlist, resetWishlist }");
+		expect(code).toContain("TODO: Implement");
+	});
 });

package/scripts/migrate/templates/hooks.ts

@@ -5,13 +5,14 @@ export function generateHooks(ctx: MigrationContext): Record<string, string> {
 
   if (ctx.platform === "vtex") {
     files["src/hooks/useCart.ts"] = generateVtexUseCart();
+    files["src/hooks/useUser.ts"] = generateVtexUseUser();
+    files["src/hooks/useWishlist.ts"] = generateVtexUseWishlist();
   } else {
     files["src/hooks/useCart.ts"] = generateGenericUseCart();
+    files["src/hooks/useUser.ts"] = generateGenericUseUser();
+    files["src/hooks/useWishlist.ts"] = generateGenericUseWishlist();
   }
 
-  files["src/hooks/useUser.ts"] = generateUseUser();
-  files["src/hooks/useWishlist.ts"] = generateUseWishlist();
-
   return files;
 }
 
@@ -66,9 +67,39 @@ export default useCart;
 `;
 }
 
-function generateUseUser(): string {
+// VTEX path — these are five-line factory shims. The heavy lifting
+// (singleton state, listener pattern, async actions, signal-shaped
+// accessors, legacy arg-swap conventions) lives in
+// @decocms/apps/vtex/hooks/createUseUser and createUseWishlist.
+function generateVtexUseUser(): string {
+  return `import { createUseUser } from "@decocms/apps/vtex/hooks/createUseUser";
+import { invoke } from "~/server/invoke";
+
+export type { Person } from "@decocms/apps/vtex/loaders/user";
+
+export const { useUser, resetUser } = createUseUser({ invoke });
+`;
+}
+
+function generateVtexUseWishlist(): string {
+  return `import { createUseWishlist } from "@decocms/apps/vtex/hooks/createUseWishlist";
+import { invoke } from "~/server/invoke";
+
+export type { WishlistItem } from "@decocms/apps/vtex/loaders/wishlist";
+
+export const { useWishlist, resetWishlist } = createUseWishlist({ invoke });
+`;
+}
+
+// Non-VTEX fallback — keeps the legacy signal-based stub shape so any
+// generic platform port that already consumes `~/hooks/useUser` keeps
+// type-checking. Sites must wire their own platform-specific impl.
+function generateGenericUseUser(): string {
   return `/**
  * User Hook — wire to invoke.site.loaders for your platform's user API.
+ *
+ * VTEX sites get a real factory from @decocms/apps/vtex/hooks/createUseUser;
+ * see migration template hooks.ts for the canonical five-line shim.
  */
 import { signal } from "~/sdk/signal";
 
@@ -90,12 +121,12 @@ export default useUser;
 `;
 }
 
-function generateUseWishlist(): string {
+function generateGenericUseWishlist(): string {
   return `/**
  * Wishlist Hook — wire to invoke.site.loaders/actions for your platform.
  *
- * For VTEX: use invoke.site.loaders.getWishlistItems and
- *           invoke.site.actions.addWishlistItem / removeWishlistItem.
+ * VTEX sites get a real factory from @decocms/apps/vtex/hooks/createUseWishlist;
+ * see migration template hooks.ts for the canonical five-line shim.
  */
 import { signal } from "~/sdk/signal";
 
@@ -105,7 +136,7 @@ export function useWishlist() {
   return {
     loading,
     async addItem(_productId: string, _productGroupId: string) {
-      // TODO: Implement
+      // TODO: Implement for your platform
     },
     async removeItem(_productId: string) {
       // TODO: Implement

package/scripts/migrate/templates/lib-utils.test.ts

@@ -89,3 +89,51 @@ describe("selectImportedLibTemplates()", () => {
     }
   });
 });
+
+describe("D3 — generated stubs throw at runtime", () => {
+  // Each stub MUST throw an Error whose message identifies:
+  //  - the stub path so the dev sees it in their stack trace
+  //  - the canonical replacement (so the fix is mechanical)
+  //
+  // See migration-tooling-policy.mdc § Decision 3.
+  it("vtex-transform.toProduct throws and points at the canonical path", () => {
+    const src = LIB_TEMPLATES["src/lib/vtex-transform.ts"];
+    expect(src).toMatch(/throw new Error/);
+    expect(src).toMatch(/@decocms\/apps\/vtex\/utils\/transform/);
+    expect(src).toMatch(/\[deco-migrate\]/);
+  });
+
+  it("vtex-intelligent-search.getISCookiesFromBag throws", () => {
+    const src = LIB_TEMPLATES["src/lib/vtex-intelligent-search.ts"];
+    expect(src).toMatch(/getISCookiesFromBag[\s\S]*?throw new Error/);
+    expect(src).toMatch(/\[deco-migrate\]/);
+    // The other helpers in this file (isFilterParam, toPath,
+    // withDefaultFacets, withDefaultParams) are real impls — must not
+    // throw.
+    expect(src).toMatch(/export function isFilterParam[\s\S]*?return key\.startsWith/);
+  });
+
+  it("vtex-segment.getSegmentFromBag and withSegmentCookie both throw", () => {
+    const src = LIB_TEMPLATES["src/lib/vtex-segment.ts"];
+    expect(src).toMatch(/getSegmentFromBag[\s\S]*?throw new Error/);
+    expect(src).toMatch(/withSegmentCookie[\s\S]*?throw new Error/);
+    expect(src).toMatch(/@decocms\/apps\/vtex\/utils\/segment/);
+  });
+
+  it("non-stub helpers stay implemented (negative check — no throw)", () => {
+    // These are real impls, not stubs. They must not throw.
+    const real = [
+      "src/lib/http-utils.ts",
+      "src/lib/vtex-id.ts",
+      "src/lib/graphql-utils.ts",
+      "src/lib/filter-navigate.ts",
+      "src/lib/fetch-utils.ts",
+    ];
+    for (const key of real) {
+      const src = LIB_TEMPLATES[key];
+      expect(src, `${key} should not contain a generated stub throw`).not.toMatch(
+        /\[deco-migrate\][^"]*generated stub/,
+      );
+    }
+  });
+});

package/scripts/migrate/templates/lib-utils.ts

@@ -38,15 +38,41 @@ export function selectImportedLibTemplates(
   return out;
 }
 
+// Per the migration tooling policy (D3 — Throwing stubs):
+// generated stubs MUST throw at runtime so the first call surfaces the
+// gap loudly. Silent identity-cast `toProduct` was the bug behind
+// baggagio-tanstack#10 (PDP product data was being dropped on the floor
+// for weeks before anyone noticed).
+//
+// Each thrown message points at the canonical replacement so the fix
+// is mechanical. `deco-post-cleanup --fix` automates the swap.
 const LIB_VTEX_TRANSFORM = `import type { Product } from "@decocms/apps/commerce/types";
 
-export function toProduct(vtexProduct: any): Product {
-  return vtexProduct as Product;
+const STUB =
+  "[deco-migrate] \`~/lib/vtex-transform.toProduct\` is a generated stub. " +
+  "Replace with: import { toProduct } from '@decocms/apps/vtex/utils/transform' " +
+  "(canonical signature: \`toProduct(product, sku, level, options)\`). " +
+  "Run \`deco-post-cleanup --fix\` or see the deco-to-tanstack-migration skill " +
+  "(post-migration-cleanup § 5).";
+
+export function toProduct(_vtexProduct: any, ..._rest: any[]): Product {
+  throw new Error(STUB);
 }
 `;
 
-const LIB_VTEX_INTELLIGENT_SEARCH = `export function getISCookiesFromBag(_req?: any): Record<string, string> {
-  return {};
+const LIB_VTEX_INTELLIGENT_SEARCH = `// Per the migration tooling policy (D3): \`getISCookiesFromBag\` cannot
+// be implemented on TanStack Start because the bag-based lookup
+// mechanism does not exist. Sites must read cookies directly from the
+// request — see the \`vtex-shim-regression\` audit rule for guidance.
+const STUB_GET_IS_COOKIES =
+  "[deco-migrate] \`~/lib/vtex-intelligent-search.getISCookiesFromBag\` is a " +
+  "generated stub. Refactor: extract IS cookies from " +
+  "\`request.headers.get('cookie')\` directly. The bag-based lookup mechanism " +
+  "does not exist on TanStack Start. See the deco-to-tanstack-migration " +
+  "skill (post-migration-cleanup § 5).";
+
+export function getISCookiesFromBag(_req?: any): Record<string, string> {
+  throw new Error(STUB_GET_IS_COOKIES);
 }
 
 export function isFilterParam(key: string): boolean {
@@ -85,17 +111,30 @@ export function withDefaultParams(
 }
 `;
 
-const LIB_VTEX_SEGMENT = `export function getSegmentFromBag(_req?: any): Record<string, unknown> | null {
-  return null;
+const LIB_VTEX_SEGMENT = `// Per the migration tooling policy (D3): both these stubs throw at
+// runtime to force the call site to be fixed. Silent fallbacks here
+// mean the storefront silently fails to forward VTEX segment data
+// (sales channel, regionId, currency, etc.) and pricing/inventory
+// quietly diverge from what the user should see.
+const STUB_GET_SEGMENT_FROM_BAG =
+  "[deco-migrate] \`~/lib/vtex-segment.getSegmentFromBag\` is a generated " +
+  "stub. Refactor: read cookies via \`request.headers.get('cookie')\` then " +
+  "call \`buildSegmentFromCookies()\` from '@decocms/apps/vtex/utils/segment'. " +
+  "The bag-based lookup mechanism does not exist on TanStack Start.";
+
+const STUB_WITH_SEGMENT_COOKIE =
+  "[deco-migrate] \`~/lib/vtex-segment.withSegmentCookie\` is a generated " +
+  "stub. Replace with: import { withSegmentCookie } from " +
+  "'@decocms/apps/vtex/utils/segment' (canonical signature: " +
+  "\`withSegmentCookie(segment, headers?)\`). Run \`deco-post-cleanup --fix\` " +
+  "or see the deco-to-tanstack-migration skill.";
+
+export function getSegmentFromBag(_req?: any): Record<string, unknown> | null {
+  throw new Error(STUB_GET_SEGMENT_FROM_BAG);
 }
 
 export function withSegmentCookie(..._args: any[]): any {
-  for (const arg of _args) {
-    if (arg instanceof Headers) {
-      return arg;
-    }
-  }
-  return new Headers();
+  throw new Error(STUB_WITH_SEGMENT_COOKIE);
 }
 `;