@decocms/start 2.16.0 → 2.17.0

package/.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md

@@ -291,12 +291,30 @@ When you see real findings, update the imports to point at
 gets MUCH better — segment cookies, IS cookies, VTEX session auth all
 start working again instead of being silently stubbed to `{}` / `null`.
 
-**Note on `--fix`**: this rule is intentionally detect-only. Repointing
-imports requires a per-symbol map to canonical apps/start exports
-(e.g. `getSegmentFromBag` → `@decocms/apps/vtex/utils/segment`), which
-the framework doesn't ship yet. Detect-only is still strictly more
-useful than nothing — the precision means each finding maps to exactly
-one PR's worth of mechanical work.
+**Note on `--fix`** (since `@decocms/start >= 2.16.0`): the rule
+auto-fixes the SAFE subset of swaps — when every imported symbol from
+a given shim is a `kind: "swap"` hint to the SAME canonical module.
+Concretely:
+
+| Pattern | `--fix` behaviour |
+|---|---|
+| `import { toProduct } from "~/lib/vtex-transform"` | rewritten to `@decocms/apps/vtex/utils/transform` |
+| `import { withSegmentCookie } from "~/lib/vtex-segment"` | rewritten to `@decocms/apps/vtex/utils/segment` |
+| `import { getSegmentFromBag, withSegmentCookie } from "~/lib/vtex-segment"` | left untouched (mixed swap + refactor) |
+| `import { getISCookiesFromBag } from "~/lib/vtex-intelligent-search"` | left untouched (refactor-only — no canonical drop-in) |
+| `import { toProduct, isFilterParam } from "~/lib/vtex-transform"` | left untouched (would lose the real impl) |
+
+The auto-fix rewrites only the `from "..."` clause — the imported
+names list is preserved verbatim, so `as`-aliased imports (e.g.
+`{ toProduct as toP }`) keep working. After the import swap you may
+still need to expand 1-arg `toProduct(p)` call sites to the canonical
+4-arg signature — see § 5 below.
+
+The refactor-only cases (`getSegmentFromBag`, `getISCookiesFromBag`,
+mixed surfaces) intentionally stay manual: the bag-based lookup
+mechanism doesn't exist on TanStack Start, so each call site needs a
+human reading `request.headers.get('cookie')` and calling
+`buildSegmentFromCookies()` from the canonical module.
 
 ## 6. Drop `src/types/widgets.ts` — framework owns it
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.16.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