@decocms/start 2.17.0 → 2.18.0

package/package.json

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