@decocms/start 2.16.0 → 2.18.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.18.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/migrate/phase-scaffold.ts

@@ -18,6 +18,7 @@ import { generateCommerceLoaders } from "./templates/commerce-loaders";
 import { generateSectionLoaders } from "./templates/section-loaders";
 import { generateCacheConfig } from "./templates/cache-config";
 import { generateSdkFiles } from "./templates/sdk-gen";
+import { generateMigrationPolicyPointerRule } from "./templates/cursor-rules";
 // `lib-utils` is imported lazily — see end of phase-cleanup. Eager
 // generation of all 11 shims left every site with dead code that had
 // to be cleaned up by hand.
@@ -139,6 +140,17 @@ export function scaffold(ctx: MigrationContext): void {
     writeFile(ctx, "src/components/ui/Theme.tsx", generateSiteThemeComponent());
   }
 
+  // Migration tooling policy pointer rule (D1–D5 + priorities).
+  // The canonical rule lives in decocms/deco-start; this is a tiny
+  // pointer that loads on every Cursor session in the migrated site
+  // so agents working on the site know where the policy is and what
+  // it means here. See MIGRATION_TOOLING_PLAN.md (Wave 12-H).
+  writeFile(
+    ctx,
+    ".cursor/rules/migration-tooling-policy.mdc",
+    generateMigrationPolicyPointerRule(ctx.siteName),
+  );
+
   // Create public/ directory
   if (!ctx.dryRun) {
     fs.mkdirSync(path.join(ctx.sourceDir, "public"), { recursive: true });

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/cursor-rules.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { generateMigrationPolicyPointerRule } from "./cursor-rules";
+
+describe("generateMigrationPolicyPointerRule", () => {
+	const body = generateMigrationPolicyPointerRule("acme");
+
+	it("emits a Cursor MDC rule with alwaysApply: true frontmatter", () => {
+		expect(body.startsWith("---\n")).toBe(true);
+		expect(body).toContain("alwaysApply: true");
+		expect(body).toContain("description:");
+	});
+
+	it("interpolates the site name into the body", () => {
+		expect(body).toContain("`acme`");
+	});
+
+	it("links to the canonical rule and plan in decocms/deco-start", () => {
+		expect(body).toContain(
+			"https://github.com/decocms/deco-start/blob/main/.cursor/rules/migration-tooling-policy.mdc",
+		);
+		expect(body).toContain(
+			"https://github.com/decocms/deco-start/blob/main/MIGRATION_TOOLING_PLAN.md",
+		);
+	});
+
+	it("documents D1–D5 by ID, not just by name", () => {
+		expect(body).toContain("**D1**");
+		expect(body).toContain("**D2**");
+		expect(body).toContain("**D3**");
+		expect(body).toContain("**D4**");
+		expect(body).toContain("**D5**");
+	});
+
+	it("points at the post-cleanup --fix command rather than restating policy", () => {
+		expect(body).toContain("deco-post-cleanup --fix");
+		expect(body).toContain("deco-post-cleanup --strict");
+	});
+
+	it("does NOT restate the canonical rule body verbatim (pointer, not a copy)", () => {
+		// Length budget: pointer must stay short to discourage drift.
+		// The canonical rule in decocms/deco-start is ~110 lines / 4–5 KB;
+		// the pointer must be substantially smaller than a copy.
+		expect(body.length).toBeLessThan(3000);
+	});
+
+	it("is deterministic — same site name, same output", () => {
+		const a = generateMigrationPolicyPointerRule("foo");
+		const b = generateMigrationPolicyPointerRule("foo");
+		expect(a).toBe(b);
+	});
+
+	it("escapes nothing weird from siteName — siteName is used as a label only", () => {
+		// We don't sanitise; we trust the migration script to pass a real
+		// package name. But verify nothing surprising happens with hyphens
+		// (a common shape, e.g. "casaevideo-storefront").
+		const out = generateMigrationPolicyPointerRule("casaevideo-storefront");
+		expect(out).toContain("`casaevideo-storefront`");
+	});
+});

package/scripts/migrate/templates/cursor-rules.ts

@@ -0,0 +1,70 @@
+/**
+ * Cursor rule scaffolding for migrated sites.
+ *
+ * The canonical migration tooling policy (D1–D5, priorities, process)
+ * lives in `decocms/deco-start`. We don't duplicate it into every site
+ * — that would drift the moment the canonical changes. Instead the
+ * migration scaffolds a tiny pointer rule, marked `alwaysApply: true`,
+ * that loads on every agent session inside the migrated site and tells
+ * the agent where the real policy lives.
+ *
+ * Closes Wave 12-H from MIGRATION_TOOLING_PLAN.md.
+ */
+
+/**
+ * Generate the contents of `.cursor/rules/migration-tooling-policy.mdc`
+ * for a freshly migrated site. Pure function: `siteName` is the only
+ * input that influences the body, and only as a friendly mention.
+ */
+export function generateMigrationPolicyPointerRule(
+	siteName: string,
+): string {
+	return `---
+description: Pointer to the canonical migration tooling policy (D1–D5, PR-only, etc.). Always loaded.
+alwaysApply: true
+---
+
+# Migration Tooling Policy — Pointer
+
+> This site (\`${siteName}\`) was generated by the \`@decocms/start\`
+> migration script. The canonical policy that governs how the migration
+> tooling, framework (\`@decocms/start\`), and commerce layer
+> (\`@decocms/apps\`) evolve lives **upstream**, not in this repo.
+
+## Where to read
+
+- **Rule (always-applied) — full text:**
+  https://github.com/decocms/deco-start/blob/main/.cursor/rules/migration-tooling-policy.mdc
+- **Plan (living tracker, decisions + waves):**
+  https://github.com/decocms/deco-start/blob/main/MIGRATION_TOOLING_PLAN.md
+- **Migration skill (phase playbook):**
+  \`@decocms/start/.agents/skills/deco-to-tanstack-migration\`
+
+## What you need to know in this site
+
+| ID | Decision | What it means here |
+|----|----------|--------------------|
+| **D1** | Force convergence — no fork runtime support | Site customisations live in \`src/apps/local/\` or open a PR to \`@decocms/apps\`. Don't wrap framework/commerce code in soft adapters. |
+| **D2** | Rewrite HTMX on migration | If you find HTMX residue, rewrite to React. Don't bring back \`hx-*\` runtime. |
+| **D3** | Generated stubs throw at runtime | If a \`~/lib/vtex-*\` import comes from a stub that returns \`null\` / \`{}\` / identity-cast, replace it. \`npx -p @decocms/start deco-post-cleanup --fix\` does the safe swaps automatically. |
+| **D4** | Site-local apps by default, promote at 3+ sites | Don't try to upstream a pattern that has only shipped here. Build it twice in different sites first, then PR it to \`@decocms/apps\`. |
+| **D5** | Failed migrations: \`rm -rf\` and re-run | No restart-mode magic. If the migration goes sideways, blow away the working tree and run again. |
+
+## How to find issues this rule wants you to fix
+
+\`\`\`bash
+npx -p @decocms/start deco-post-cleanup           # audit only
+npx -p @decocms/start deco-post-cleanup --fix     # auto-fix the safe rules
+npx -p @decocms/start deco-post-cleanup --strict  # exit 1 on any finding (CI)
+\`\`\`
+
+## Process
+
+- **PR-only.** No direct pushes to \`main\`. Self-merge after green CI is fine.
+- **Conventional commits** (\`feat\`, \`fix\`, \`chore\`, \`docs\`, \`refactor\`, \`test\`, \`perf\`).
+- **CI must be green before merge.**
+- When the canonical rule changes upstream, update this pointer if any
+  link or table heading goes stale. Keep it short — body content lives
+  upstream.
+`;
+}

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