@decocms/blocks-cli 7.0.0

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

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import { generateHooks } from "./hooks";
+import type { MigrationContext } from "../types";
+
+function makeCtx(platform: MigrationContext["platform"]): MigrationContext {
+	return {
+		sourceDir: "/tmp",
+		siteName: "test",
+		platform,
+		vtexAccount: null,
+		gtmId: null,
+		importMap: {},
+		discoveredNpmDeps: {},
+		themeColors: {},
+		fontFamily: null,
+		files: [],
+		sectionMetas: [],
+		islandClassifications: [],
+		islandWrapperTargets: new Map(),
+		loaderInventory: [],
+		scaffoldedFiles: [],
+		transformedFiles: [],
+		deletedFiles: [],
+		movedFiles: [],
+		manualReviewItems: [],
+		frameworkFindings: [],
+		dryRun: false,
+		verbose: false,
+	};
+}
+
+describe("generateHooks (vtex)", () => {
+	const files = generateHooks(makeCtx("vtex"));
+
+	it("emits all three hook files", () => {
+		expect(Object.keys(files).sort()).toEqual([
+			"src/hooks/useCart.ts",
+			"src/hooks/useUser.ts",
+			"src/hooks/useWishlist.ts",
+		]);
+	});
+
+	it("useCart is the createUseCart factory shim, not 250-line legacy boilerplate", () => {
+		const code = files["src/hooks/useCart.ts"];
+		// Imports from the framework factory.
+		expect(code).toContain(
+			'import { createUseCart } from "@decocms/apps/vtex/hooks/createUseCart"',
+		);
+		expect(code).toContain('import { invoke } from "~/server/invoke"');
+		// Re-exports types from @decocms/apps directly.
+		expect(code).toContain(
+			'export type { OrderForm, OrderFormItem } from "@decocms/apps/vtex/types"',
+		);
+		// Calls the factory with invoke and destructures the public API.
+		expect(code).toContain(
+			"export const { useCart, resetCart, itemToAnalyticsItem } = createUseCart",
+		);
+		// And does NOT contain the old singleton machinery.
+		expect(code).not.toContain("const _listeners = new Set");
+		expect(code).not.toContain("forceRender");
+		expect(code).not.toContain("function getOrderFormIdFromCookie");
+	});
+
+	it("useCart shim is dramatically smaller than the legacy template", () => {
+		const lineCount = files["src/hooks/useCart.ts"].split("\n").length;
+		// 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)", () => {
+	it("custom platform falls back to the generic stub", () => {
+		const files = generateHooks(makeCtx("custom"));
+		const code = files["src/hooks/useCart.ts"];
+		expect(code).toContain("Cart Hook stub");
+		expect(code).toContain("TODO: Implement");
+	});
+
+	it("shopify currently shares the generic stub", () => {
+		const files = generateHooks(makeCtx("shopify"));
+		const code = files["src/hooks/useCart.ts"];
+		// 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

@@ -0,0 +1,152 @@
+import type { MigrationContext } from "../types";
+
+export function generateHooks(ctx: MigrationContext): Record<string, string> {
+  const files: 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();
+  }
+
+  return files;
+}
+
+function generateVtexUseCart(): string {
+  // The legacy invoke-based useCart hook is now a 5-line factory call —
+  // the heavy lifting (singleton state, listener pattern, async actions,
+  // analytics helpers) lives in @decocms/apps/vtex/hooks/createUseCart.
+  return `import { createUseCart } from "@decocms/apps/vtex/hooks/createUseCart";
+import { invoke } from "~/server/invoke";
+
+export type { OrderForm, OrderFormItem } from "@decocms/apps/vtex/types";
+
+export const { useCart, resetCart, itemToAnalyticsItem } = createUseCart({
+  invoke,
+});
+`;
+}
+
+function generateGenericUseCart(): string {
+  return `/**
+ * Cart Hook stub — implement for your platform.
+ *
+ * Wire invoke calls from ~/server/invoke to your commerce platform's
+ * cart API (addItem, updateItem, getCart, etc.).
+ */
+import { signal } from "~/sdk/signal";
+
+const cart = signal<any>(null);
+const loading = signal(false);
+
+export function useCart() {
+  return {
+    cart,
+    loading,
+    async getCart() {
+      // TODO: Implement for your platform
+      return null;
+    },
+    async addItems(_items: any[]) {
+      // TODO: Implement
+    },
+    async updateItems(_items: any[]) {
+      // TODO: Implement
+    },
+    setCart(newCart: any) {
+      cart.value = newCart;
+    },
+  };
+}
+
+export default useCart;
+`;
+}
+
+// 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";
+
+export interface User {
+  "@id": string;
+  email: string;
+  givenName?: string;
+  familyName?: string;
+}
+
+const user = signal<User | null>(null);
+const loading = signal(false);
+
+export function useUser() {
+  return { user, loading };
+}
+
+export default useUser;
+`;
+}
+
+function generateGenericUseWishlist(): string {
+  return `/**
+ * Wishlist Hook — wire to invoke.site.loaders/actions for your platform.
+ *
+ * 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";
+
+const loading = signal(false);
+
+export function useWishlist() {
+  return {
+    loading,
+    async addItem(_productId: string, _productGroupId: string) {
+      // TODO: Implement for your platform
+    },
+    async removeItem(_productId: string) {
+      // TODO: Implement
+    },
+    getItem(_productId: string): boolean {
+      return false;
+    },
+  };
+}
+
+export default useWishlist;
+`;
+}

package/scripts/migrate/templates/knip-config.ts

@@ -0,0 +1,27 @@
+export function generateKnipConfig(): string {
+  return `import type { KnipConfig } from "knip";
+
+const config: KnipConfig = {
+  entry: [
+    "src/routes/**/*.{ts,tsx}",
+    "src/setup.ts",
+    "src/runtime.ts",
+    "src/sections/**/*.{ts,tsx}",
+    "vite.config.ts",
+  ],
+  project: ["src/**/*.{ts,tsx}"],
+  ignore: [
+    "src/server/invoke.gen.ts",
+    "src/server/cms/blocks.gen.ts",
+    "src/routeTree.gen.ts",
+  ],
+  ignoreDependencies: [
+    "babel-plugin-react-compiler",
+    "@vitejs/plugin-react",
+    "wrangler",
+  ],
+};
+
+export default config;
+`;
+}

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

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest";
+import {
+  LIB_TEMPLATES,
+  selectImportedLibTemplates,
+} from "./lib-utils";
+
+describe("LIB_TEMPLATES registry", () => {
+  it("has entries", () => {
+    expect(Object.keys(LIB_TEMPLATES).length).toBeGreaterThan(0);
+  });
+
+  it("uses src/lib/<name>.ts keys (relative paths the writer expects)", () => {
+    for (const key of Object.keys(LIB_TEMPLATES)) {
+      expect(key).toMatch(/^src\/lib\/[a-z][a-z0-9-]*\.ts$/);
+    }
+  });
+
+  it("has non-empty contents for every entry", () => {
+    for (const [key, value] of Object.entries(LIB_TEMPLATES)) {
+      expect(value, `${key} should have content`).toBeTruthy();
+      expect(value.length, `${key} length`).toBeGreaterThan(20);
+    }
+  });
+
+  it("has unique keys (no shadowing)", () => {
+    const keys = Object.keys(LIB_TEMPLATES);
+    const set = new Set(keys);
+    expect(set.size).toBe(keys.length);
+  });
+});
+
+describe("selectImportedLibTemplates()", () => {
+  it("returns empty record when no specifiers are imported", () => {
+    expect(selectImportedLibTemplates(new Set())).toEqual({});
+  });
+
+  it("returns only the templates whose specifier is in the set", () => {
+    const result = selectImportedLibTemplates(new Set(["vtex-segment"]));
+    expect(Object.keys(result)).toEqual(["src/lib/vtex-segment.ts"]);
+    expect(result["src/lib/vtex-segment.ts"]).toBe(LIB_TEMPLATES["src/lib/vtex-segment.ts"]);
+  });
+
+  it("returns multiple templates when multiple specifiers are imported", () => {
+    const result = selectImportedLibTemplates(
+      new Set(["vtex-segment", "vtex-transform", "filter-navigate"]),
+    );
+    const keys = Object.keys(result).sort();
+    expect(keys).toEqual([
+      "src/lib/filter-navigate.ts",
+      "src/lib/vtex-segment.ts",
+      "src/lib/vtex-transform.ts",
+    ]);
+  });
+
+  it("ignores unknown specifiers without throwing", () => {
+    const result = selectImportedLibTemplates(
+      new Set(["vtex-segment", "this-template-does-not-exist"]),
+    );
+    expect(Object.keys(result)).toEqual(["src/lib/vtex-segment.ts"]);
+  });
+
+  it("does not mutate LIB_TEMPLATES (returns a fresh object)", () => {
+    const before = JSON.stringify(LIB_TEMPLATES);
+    const result = selectImportedLibTemplates(new Set(["vtex-segment"]));
+    result["src/lib/vtex-segment.ts"] = "// HIJACKED";
+    expect(JSON.stringify(LIB_TEMPLATES)).toBe(before);
+  });
+
+  it("covers every well-known migration target the writer might emit", () => {
+    // Sanity check: the names that `transforms/imports.ts` rewrites to
+    // and that phase-cleanup hoists for inline-stub injection MUST all
+    // have templates registered, otherwise migrated sites get import
+    // errors with no warning.
+    const expectedSpecifiers = [
+      "vtex-transform",
+      "vtex-intelligent-search",
+      "vtex-segment",
+      "vtex-fetch",
+      "vtex-id",
+      "vtex-client",
+      "fetch-utils",
+      "http-utils",
+      "graphql-utils",
+      "filter-navigate",
+    ];
+    for (const spec of expectedSpecifiers) {
+      const key = `src/lib/${spec}.ts`;
+      expect(LIB_TEMPLATES, `expected template for ${key}`).toHaveProperty(key);
+    }
+  });
+});
+
+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/,
+      );
+    }
+  });
+});