@decocms/start 2.18.0 → 2.20.0

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

@@ -17,7 +17,8 @@ of which sections below actually apply to your codebase:
 npx -p @decocms/start deco-post-cleanup
 
 # Auto-apply mechanical fixes for the safe rules, then report what's left.
-# Safe rules: dead-lib-shims, dead-runtime-shim, local-widgets-types.
+# Safe rules: dead-lib-shims, dead-runtime-shim, local-widgets-types,
+# vtex-shim-regression (swap subset), obsolete-vite-plugins.
 # Other rules stay detect-only — they require human judgment.
 npx -p @decocms/start deco-post-cleanup --fix
 
@@ -29,18 +30,23 @@ npx -p @decocms/start deco-post-cleanup --json
 ```
 
 The audit covers all 7 rules below and prints the exact file path +
-suggested fix for each finding. With `--fix`, the three safe rules
-auto-apply (`rm` for dead files, regex-anchored import rewrites for
-shadowed shims). The output explicitly tags rules that require manual
-work as `(0 fixed, manual)`, so you always know what's left after
-auto-fix runs.
+suggested fix for each finding. With `--fix`, the safe rules
+auto-apply: `rm` for dead files, regex-anchored import rewrites for
+shadowed shims (`local-widgets-types`, `dead-runtime-shim`), the swap
+subset of `vtex-shim-regression`, and JS-aware removal of obsolete
+inline plugin literals from `vite.config.ts`. The output explicitly
+tags rules that require manual work as `(0 fixed, manual)`, so you
+always know what's left after auto-fix runs.
 
 Real-world signal: on baggagio, `--fix` produced a byte-identical
 diff to the manual cleanup PR a human had just made (45 files,
 +45/-53). On casaevideo-storefront (production), the audit caught
 six silent VTEX shim regressions that no `tsc --noEmit` run can
-detect — those still require manual cleanup until rule 5 gains a
-per-shim mapping table.
+detect — `--fix` covers the swap subset of those automatically since
+`>= 2.16.0`. On the same site's `vite.config.ts`, `--fix` removes
+both obsolete inline plugins (`site-manual-chunks` +
+`deco-stub-meta-gen`) cleanly — ~74 LOC / 2.5 KB gone, attached
+comments included.
 
 ## 1. Delete unused `src/lib/*` shims
 
@@ -115,8 +121,14 @@ The framework's `decoVitePlugin()` now handles both:
   old split caused circular-dep load-order crashes — every site overrode it)
 - `meta.gen.{json,ts}` is stubbed on the client by default
 
-Delete both inline plugins from the site's `vite.config.ts`. Verify the
-production build still succeeds (`vite build` in the site repo).
+Delete both inline plugins from the site's `vite.config.ts`. Since
+`@decocms/start >= 2.19.0`, `deco-post-cleanup --fix` does this for
+you — it walks the AST with brace-balanced parsing (template literals
+and nested `{}` inside `config()`/`load()` bodies don't trip it up),
+removes the literal **plus its trailing comma + attached `// ...`
+comment block**, and is idempotent (rerunning is a no-op). Block
+comments are left alone. Verify the production build still succeeds
+(`vite build` in the site repo).
 
 ## 3. Drop the `runtime.ts` `invoke` shim
 

package/MIGRATION_TOOLING_PLAN.md

@@ -688,27 +688,83 @@ Releases shipped from Wave 6:
 - `@decocms/apps@1.7.0` — adds `vtex/hooks/createUseCart` factory
 - `@decocms/start@2.8.0` (compile phase) → `2.9.0` (template shim) → `2.10.0` (per-site config)
 
-### Wave 12 (kicked off 2026-05-01 after D1–D5 sign-off) — Priority 1 (framework + commerce)
+### Wave 12 (kicked off 2026-05-01 after D1–D5 sign-off) — Priority 1 (framework + commerce) — ✅ **COMPLETE**
 
 After surfacing als-storefront as the third migration target (heavy on
 htmx, ~120 hx-* files, prior als-tanstack attempt thrown away), the
-"wait for 3rd site" deferrals collapse. Wave 12 ships the abstractions
-that als + casaevideo + baggagio have already justified, plus the
-audit `--fix` work D3 forces us into.
-
-**Planned PRs (will be filled in as they ship):**
-
-- **W12-A** apps-start: `createUseUser` factory (mirrors `createUseCart` from #32)
-- **W12-B** apps-start: `createUseWishlist` factory (same pattern)
-- **W12-C** deco-start: throwing stubs in `lib-utils.ts` template + per-stub message linking to skill (D3 implementation)
-- **W12-D** deco-start: audit `--fix` for `toProduct` swap (uses #121's `meta.fixHints`)
-- **W12-E** deco-start: audit `--fix` for `withSegmentCookie` swap
-- **W12-F** deco-start: audit `--fix` for `obsolete-vite-plugins` rule (mechanical cleanup)
-- **W12-G** apps-start (or deco-start CLAUDE.md cross-link): per-repo pointer to `migration-tooling-policy.mdc` so the constitutional rule is discoverable from any consumer repo
-- **W12-H** deco-start: cleanup phase scaffolds `.cursor/rules/migration-policy-pointer.mdc` in target site, pointing at the canonical rule (D1/D4 enforcement at site level)
-
-Wave 12 ships in priority-1 order; Wave 13 only starts when the
-foundation is in place.
+"wait for 3rd site" deferrals collapse. Wave 12 shipped the abstractions
+that als + casaevideo + baggagio had already justified, plus the
+audit `--fix` work D3 forces us into. **9 PRs across `deco-start` and
+`apps-start`, all merged.**
+
+**Shipped PRs:**
+
+- **W12-A + W12-B** [`apps-start#33`](https://github.com/decocms/apps-start/pull/33) — `feat(vtex/hooks): add createUseUser + createUseWishlist factories` ✅ **MERGED**.
+  Mirrors the `createUseCart` shape: invoke-driven legacy state machine, signal-shaped public API (`.value`), independent instances per call. `createUseWishlist` also exposes the `legacyAddArgsToCanonical` and `findWishlistEntry` helpers so site code can keep its old `productId`/`productGroupId` swap convention while routing through the canonical `vtex.actions.{addToWishlist, removeFromWishlist}` signature. New unit tests assert factory shape, instance independence, the arg-swap convention, and the entry-finder helper.
+- **(Lint unblock)** [`apps-start#34`](https://github.com/decocms/apps-start/pull/34) — `chore(lint): tighten shopify storefront.graphql.gen.ts types + biome formatting` ✅ **MERGED**.
+  Cleared pre-existing `noExplicitAny` failures in `shopify/utils/storefront/storefront.graphql.gen.ts` plus formatting drift in `vtex/__tests__/client-segment-cookie.test.ts` so subsequent Wave 12 PRs in `apps-start` could land on a green CI baseline. Replaced loose `any` types with a structured `ProductFilter` shape (derived from real consumers) and `unknown` elsewhere; ran `biome check --write` to fix import order + formatting.
+- **W12-C** [`deco-start#123`](https://github.com/decocms/deco-start/pull/123) — `feat(migrate): D3 — generated stubs throw at runtime` ✅ **MERGED**, released as `@decocms/start@2.16.0`.
+  Implements **D3** verbatim. The migration-time stubs in `lib-utils.ts` for `toProduct`, `getISCookiesFromBag`, `getSegmentFromBag`, `withSegmentCookie` no longer return identity-cast values, empty objects, or empty `Headers` — they now `throw new Error(STUB_MSG)` with a per-symbol message that names the canonical replacement, the canonical signature, and the `deco-post-cleanup --fix` invocation. Tests assert the throwing bodies + that other functional helpers (e.g. `parseCookie`, `isFilterParam`) are untouched.
+- **W12-D + W12-E** [`deco-start#124`](https://github.com/decocms/deco-start/pull/124) — `feat(audit): vtex-shim-regression --fix for swap-able symbols` ✅ **MERGED**, released as `@decocms/start@2.17.0`.
+  Auto-fixes the swap subset of the regression rule: when every imported symbol from a `~/lib/vtex-*` shim has a `kind: "swap"` hint pointing to the same canonical module, the rule rewrites the `from "..."` clause to canonical and leaves the named-import list (including `as`-aliases) verbatim. Mixed swap + refactor surfaces, and shims that mix stubs with real impls (e.g. `isFilterParam`), are deliberately left for manual fix. 6 new tests + skill doc § 5 update.
+- **W12-i** [`deco-start#125`](https://github.com/decocms/deco-start/pull/125) — `feat(migrate): scaffold useUser + useWishlist as factory shims (vtex)` ✅ **MERGED**.
+  Updates the migration script's `hooks.ts` template so freshly migrated VTEX sites get 3-line factory shims (`export const { useUser, resetUser } = createUseUser({ invoke })`) instead of 200-LOC singletons that were copy-pasted by the old migration. Non-VTEX sites still get the legacy stubs but with docstrings pointing at the factories for parity context. 4 new tests cover both branches and a line-count budget.
+- **W12-F** [`deco-start#127`](https://github.com/decocms/deco-start/pull/127) — `feat(audit): obsolete-vite-plugins --fix` ✅ **MERGED**.
+  JS-aware applyFix for the rule. Walks `vite.config.ts` with a brace-counter that skips strings, template literals (including `${...}` interpolation), and line/block comments, so nested `{}` inside `config()` / `load()` / `resolveId()` bodies do not throw off boundary detection. Removes the inline literal + trailing `,\n` + the contiguous block of `// ...` comments immediately attached above. Idempotent. 7 new tests + smoke verified against real casaevideo `vite.config.ts` (162 LOC → both plugins gone, 2503 bytes / ~74 LOC removed, structurally identical to baggagio's already-clean shape, post-fix audit returns 0 findings).
+- **W12-G** [`apps-start#35`](https://github.com/decocms/apps-start/pull/35) — `docs: add AGENTS.md cross-linking the canonical migration policy` ✅ **MERGED**.
+  Adds an AGENTS.md to `apps-start` so any agent or contributor opening that repo knows the canonical migration policy lives in `decocms/deco-start` and what D1–D5 mean specifically inside `apps-start` (especially D4: site-local apps live in the *site*, not in `apps-start`). Architecture overview + cross-link table.
+- **W12-H** [`deco-start#126`](https://github.com/decocms/deco-start/pull/126) — `feat(migrate): scaffold migration-tooling-policy pointer rule` ✅ **MERGED**, released as `@decocms/start@2.18.0`.
+  Migration scaffold phase now writes `.cursor/rules/migration-tooling-policy.mdc` into every newly migrated site. The pointer is `alwaysApply: true`, links to the canonical rule and plan in `decocms/deco-start`, includes a one-line-per-decision D1–D5 table scoped to the site, and points at the `deco-post-cleanup --fix` / `--strict` commands. Length budget under 3 KB so it stays a pointer, not a copy. 8 new tests.
+
+Wave 12 ships in priority-1 order; Wave 13 starts now.
+
+### Wave 12 — discoveries
+
+- **D3 + audit `--fix` is a closed loop, not an either/or.** The
+  symmetry that `--fix` for swap-able stubs (W12-D/E) combined with
+  throwing stubs (W12-C) produces is significant: the moment a
+  migrated site runs anything that hits a stub'd symbol, it throws
+  with an actionable error pointing at the canonical replacement; the
+  same moment, `--fix` knows what `from "..."` clause to rewrite. The
+  user no longer has a "silent regression" failure mode.
+- **Per-symbol fix-hint table now has 5 consumers.** It's read by:
+  the rule's prose `fix:` field, the rule's `meta.fixHints`
+  structured payload, the runtime stub error message, the `--fix`
+  rewriter (selects swap candidates), and the skill doc table. Adding
+  a 5th, 6th, Nth stub means appending one entry to `STUB_FIX_HINTS`
+  — every consumer picks up the new symbol for free.
+- **Site-level policy enforcement at scaffold time, not runtime.**
+  W12-H ships the canonical D1–D5 policy *as a pointer* into every
+  new site. Cursor sessions in those sites load the rule with
+  `alwaysApply: true`, so they know the policy without us having to
+  pull a copy of the rule into each repo. Drift-free by construction
+  — the canonical rule changes upstream and the pointer keeps
+  pointing.
+- **Brace-balanced parsing + comment attachment makes
+  `obsolete-vite-plugins` `--fix` safe at scale.** The casaevideo
+  smoke test confirmed the approach handles real-world vite configs
+  with multi-line plugins, attached comments describing the
+  workaround, template literals containing `}`, and nested
+  `rollupOptions`. Idempotency falls out of "rule found 0 plugins
+  → no findings → no fix actions". This is the pattern for any
+  future `--fix` that needs to surgically edit a file: extract a
+  span helper, write surface-level tests, smoke against a real
+  production file, ship.
+- **`apps-start` had latent CI debt.** W12 surfaced pre-existing
+  `noExplicitAny` failures in `shopify/utils/storefront/storefront.graphql.gen.ts`
+  that had been failing on `main` for an unknown duration. The lint
+  unblock PR (`apps-start#34`) is the kind of "passing through" fix
+  that should land first whenever a CI gate is red. Don't paper
+  over it.
+- **Factories migrate cleaner than templates.** Comparing
+  `apps-start#33` (factories) to `deco-start#125` (template that
+  *consumes* the factories), the factory PR is the larger artifact
+  but the template PR shipped 4 lines into each generated file.
+  Investing once in a well-shaped factory pays a 50:1 multiplier on
+  every site that runs the migration after that point. This is the
+  D4 promotion path working end-to-end: build it once at site level,
+  prove it on 2 sites, promote to `@decocms/apps`, then rewrite the
+  template to use the canonical.
 
 ### Wave 13 (htmx foundations — Priority 2 part 1) — planned
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@decocms/start",
-  "version": "2.18.0",
+  "version": "2.20.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
   "bin": {
     "deco-migrate": "./scripts/migrate.ts",
-    "deco-post-cleanup": "./scripts/migrate-post-cleanup.ts"
+    "deco-post-cleanup": "./scripts/migrate-post-cleanup.ts",
+    "deco-htmx-analyze": "./scripts/htmx-analyze.ts"
   },
   "exports": {
     ".": "./src/index.ts",

package/scripts/htmx-analyze.ts

@@ -0,0 +1,226 @@
+#!/usr/bin/env tsx
+/**
+ * HTMX surface analyzer — CLI entry point.
+ *
+ * Inventories the `hx-*` surface of a Deco storefront so the engineer
+ * (or the next codemod wave) knows exactly what shapes are out there
+ * before starting the rewrite to React. Per D2 in the migration
+ * tooling policy, all htmx is rewritten on migration; no runtime is
+ * shipped in `@decocms/start`.
+ *
+ * Usage (from a site directory):
+ *   npx -p @decocms/start deco-htmx-analyze
+ *   npx -p @decocms/start deco-htmx-analyze --source /path/to/site
+ *   npx -p @decocms/start deco-htmx-analyze --json
+ *
+ * Options:
+ *   --source <dir>   Site directory to analyze (default: current directory)
+ *   --json           Emit machine-readable JSON instead of pretty text
+ *   --top <n>        Show top N files by occurrence count (default: 20)
+ *   --help, -h       Show this help
+ *
+ * Wave 13-A. Read-only. Codemods land in Wave 14.
+ */
+
+import * as path from "node:path";
+import { realFsAdapter } from "./migrate/post-cleanup/runner";
+import {
+	analyzeHtmx,
+	type HtmxCategory,
+	type HtmxInventory,
+} from "./migrate/analyzers/htmx-analyze";
+import { banner, bold, cyan, gray, green, red, yellow } from "./migrate/colors";
+
+interface CliOpts {
+	source: string;
+	json: boolean;
+	top: number;
+	help: boolean;
+}
+
+function parseArgs(args: string[]): CliOpts {
+	let source = ".";
+	let json = false;
+	let top = 20;
+	let help = false;
+	for (let i = 0; i < args.length; i++) {
+		switch (args[i]) {
+			case "--source":
+				source = args[++i];
+				break;
+			case "--json":
+				json = true;
+				break;
+			case "--top":
+				top = Number.parseInt(args[++i] ?? "20", 10);
+				if (Number.isNaN(top) || top < 0) top = 20;
+				break;
+			case "--help":
+			case "-h":
+				help = true;
+				break;
+			default:
+				console.error(`Unknown argument: ${args[i]}`);
+				process.exit(1);
+		}
+	}
+	return { source, json, top, help };
+}
+
+function printHelp(): void {
+	console.log(`deco-htmx-analyze
+
+Inventory the htmx surface (hx-* attributes) of a Deco storefront.
+
+Usage:
+  npx -p @decocms/start deco-htmx-analyze [options]
+
+Options:
+  --source <dir>   Site directory to analyze (default: cwd)
+  --json           Emit machine-readable JSON
+  --top <n>        Top N files by occurrence count (default: 20)
+  --help, -h       Show this help
+
+The output is read-only. Codemods that rewrite htmx to React are a
+planned follow-up — see the deco-to-tanstack-migration skill for the
+per-pattern rewrite recipes.
+`);
+}
+
+const CATEGORY_DESCRIPTIONS: Record<HtmxCategory, string> = {
+	"event-handler": "hx-on:* with no fetch attr — pure client-side handler",
+	"form-swap": "hx-post on a <form> with hx-target/hx-swap",
+	"click-swap": "hx-get/hx-post on a button with hx-target",
+	"auto-fetch": "hx-trigger=keyup/intersect/etc on input or auto-fired element",
+	"oob-swap": "hx-swap-oob / hx-select-oob — out-of-band patches",
+	boost: "hx-boost=true — link prefetch, already-SPA in TanStack Start",
+	unmatched: "hx-* attribute set that didn't match a known pattern",
+};
+
+const CATEGORY_RECIPES: Record<HtmxCategory, string> = {
+	"event-handler":
+		"replace hx-on:click={useScript(...)} with onClick={() => { ... }}",
+	"form-swap":
+		"<form onSubmit> + useMutation/server function; render result with state",
+	"click-swap":
+		"setState/setView + conditional render, or sub-route via TanStack Router",
+	"auto-fetch":
+		"debounced state + useQuery; for intersect use IntersectionObserver",
+	"oob-swap":
+		"manual: out-of-band has no 1:1; refactor to broadcast event + listener",
+	boost: "replace <a hx-boost> with TanStack Router <Link> (already SPA)",
+	unmatched: "manual review",
+};
+
+const CATEGORY_ORDER: HtmxCategory[] = [
+	"event-handler",
+	"click-swap",
+	"form-swap",
+	"auto-fetch",
+	"boost",
+	"oob-swap",
+	"unmatched",
+];
+
+function printText(inv: HtmxInventory, top: number): void {
+	banner("HTMX surface analysis");
+
+	if (inv.totalOccurrences === 0) {
+		console.log(green("✓ No hx-* attributes found.\n"));
+		return;
+	}
+
+	console.log(`${bold("Files with hx-* usage:")} ${inv.totalFiles}`);
+	console.log(`${bold("Total occurrences:")}    ${inv.totalOccurrences}\n`);
+
+	console.log(bold("By category:"));
+	for (const cat of CATEGORY_ORDER) {
+		const count = inv.byCategory[cat];
+		if (count === 0) continue;
+		const label = `${cat.padEnd(15)}`;
+		const desc = gray(CATEGORY_DESCRIPTIONS[cat]);
+		console.log(`  ${cyan(label)} ${String(count).padStart(4)}  ${desc}`);
+	}
+
+	console.log(`\n${bold("Migration recipes:")}`);
+	for (const cat of CATEGORY_ORDER) {
+		if (inv.byCategory[cat] === 0) continue;
+		console.log(`  ${cyan(cat.padEnd(15))} ${gray(CATEGORY_RECIPES[cat])}`);
+	}
+
+	console.log(`\n${bold(`Top ${top} files by occurrence:`)}`);
+	const slice = inv.files.slice(0, top);
+	const widest = Math.max(...slice.map((f) => f.file.length), 30);
+	for (const f of slice) {
+		const detail = CATEGORY_ORDER.filter((c) => f.byCategory[c] > 0)
+			.map((c) => `${c}=${f.byCategory[c]}`)
+			.join(", ");
+		console.log(
+			`  ${f.file.padEnd(widest)}  ${String(f.total).padStart(3)}  ${gray(detail)}`,
+		);
+	}
+
+	if (inv.files.length > top) {
+		console.log(gray(`  …and ${inv.files.length - top} more file(s)`));
+	}
+
+	console.log(`\n${bold("Sample call sites:")}`);
+	for (const cat of CATEGORY_ORDER) {
+		const samples = inv.samples[cat];
+		if (samples.length === 0) continue;
+		console.log(`  ${cyan(cat)}`);
+		for (const s of samples) {
+			const attrs = s.attrs.join(", ");
+			console.log(
+				`    ${gray(`${s.file}:${s.line}`)} <${s.tag}> [${attrs}]`,
+			);
+		}
+	}
+
+	const hasOob = inv.byCategory["oob-swap"] > 0;
+	const hasUnmatched = inv.byCategory.unmatched > 0;
+	if (hasOob || hasUnmatched) {
+		console.log();
+		if (hasOob) {
+			console.log(
+				yellow(
+					"⚠ oob-swap occurrences require manual rewrite — no 1:1 React equivalent.",
+				),
+			);
+		}
+		if (hasUnmatched) {
+			console.log(
+				yellow(
+					"⚠ unmatched occurrences require manual review — see Sample call sites.",
+				),
+			);
+		}
+	}
+	console.log();
+}
+
+function main(argv: string[]): number {
+	const opts = parseArgs(argv);
+	if (opts.help) {
+		printHelp();
+		return 0;
+	}
+
+	const sourceDir = path.resolve(opts.source);
+	const inv = analyzeHtmx(sourceDir, realFsAdapter);
+
+	if (opts.json) {
+		console.log(JSON.stringify(inv, null, 2));
+	} else {
+		printText(inv, opts.top);
+	}
+	return 0;
+}
+
+try {
+	process.exit(main(process.argv.slice(2)));
+} catch (err) {
+	console.error(red(`✗ deco-htmx-analyze failed: ${(err as Error).message}`));
+	if (process.env.DEBUG) console.error((err as Error).stack);
+	process.exit(1);
+}