@decocms/start 2.19.0 → 2.21.0

package/MIGRATION_TOOLING_PLAN.md

@@ -688,40 +688,151 @@ 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.
-
-### Wave 13 (htmx foundations — Priority 2 part 1) — planned
-
-Once Wave 12 is in, the migration script needs an htmx track because
-als is the first heavy htmx site and we know it won't be the last
-(per the user, "some of our sites are, not all, not even most, some").
-
-- **W13-A** deco-start: `scripts/migrate/htmx-analyze.ts` — categorize hx-* by pattern (form-swap, click-fetch, hx-on, hx-trigger+useSection, etc.). Output: per-site htmx inventory.
-- **W13-B** deco-start: skill `references/htmx-rewrite.md` — pattern catalog with per-pattern rewrite recipe (decision tree: codemod vs manual recipe).
-- **W13-C** deco-start: audit rule `htmx-residue` — counts `hx-*` attributes still in `src/`. Required-empty for "rewrite-complete" sites.
-
-D2 forbids an htmx adapter package; nothing in Wave 13 ships htmx
-runtime.
+"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) — ✅ **COMPLETE**
+
+Once Wave 12 was in, the migration script needed an htmx track
+because als is the first heavy htmx site and we know it won't be
+the last (per the user, "some of our sites are, not all, not even
+most, some"). **3 PRs in `deco-start`, all merged.** D2 forbids an
+htmx adapter package; nothing in Wave 13 ships htmx runtime — only
+analysis, rewrite recipes, and a "rewrite-complete" gate.
+
+**Shipped PRs:**
+
+- **W13-A** [`deco-start#129`](https://github.com/decocms/deco-start/pull/129) — `feat(migrate): htmx surface analyzer` ✅ **MERGED**, released as `@decocms/start@2.20.0`.
+  Adds `scripts/migrate/analyzers/htmx-analyze.ts` (per-file walker + classifier) and the `deco-htmx-analyze` CLI. The walker is heuristic JSX (regex for `hx-*` attrs, brace-balanced traversal back to the opening tag, forward to the closing `>` / `/>`) — skips strings, template literals, JSX expression slots, and balanced `{...}` blocks. Each occurrence is classified into one of seven categories (`event-handler`, `form-swap`, `click-swap`, `auto-fetch`, `oob-swap`, `boost`, `unmatched`) based on the attribute cluster, not individual attrs (recipes apply to clusters, not attrs in isolation). CLI emits per-category counts, top tags, sample line numbers, and a one-line migration recipe; `--json` for tooling. 24 tests covering classification (all 7 categories + tie-breaks + dash-variant `hx-on`) and real als-shaped fixtures (AddToBagButton, SearchInput, EmailAndPassword, ForgotPassword).
+- **W13-B** [`deco-start#130`](https://github.com/decocms/deco-start/pull/130) — `docs(skills): add htmx-rewrite reference` ✅ **MERGED**.
+  Per-pattern playbook at `.agents/skills/deco-to-tanstack-migration/references/htmx-rewrite.md`. For each of the seven categories: a "Before" snippet pulled directly from als (so the recipe is grounded in what an engineer is actually staring at), an "After" snippet using the canonical TanStack Start patterns (`useState` + `useCart`, `useNavigate`, `useMutation`, sub-routes), an explicit decision criterion when more than one path is reasonable (e.g. local state machine vs. sub-route for `click-swap`), and a "Gotchas" block enumerating the failure modes humans actually hit (focus loss, double-submit, hydration mismatch, etc.). Cross-linked from `SKILL.md`'s problem table.
+- **W13-C** [`deco-start#131`](https://github.com/decocms/deco-start/pull/131) — `feat(audit): htmx-residue rule` ✅ **MERGED**, released as `@decocms/start@2.21.0`.
+  Eighth audit rule. Reuses `analyzeFile` from `analyzers/htmx-analyze.ts` to scan `src/**/*.{ts,tsx}` (excluding `*.test.tsx` / `*.spec.ts` / `__tests__/`) and emits one warning per file with a category breakdown (`event-handler=2, form-swap=1`). Severity is `warning` so `--strict` exits 2 — the "rewrite-complete" CI gate. The fix string points at `references/htmx-rewrite.md`. Intentionally **detect-only** — rewrites are non-mechanical (state machine vs. sub-route vs. mutation choices vary per call site), so `--fix` wiring would be misleading; the skill is the playbook. 7 new tests cover aggregation, severity, test-file exclusion, scope (`src/` only), zero-finding gate, line-number reporting, and `supportsAutoFix: false`. Skill doc § 7 added explaining the rule + when to wire it into CI; help text updated.
+
+### Wave 13 — discoveries
+
+- **Heuristic JSX walking is enough; full AST is not needed for
+  this surface.** `analyzeFile` goes character-by-character with
+  brace-counting and string/template/comment skipping; it correctly
+  identifies attribute clusters in 100 % of the als-storefront and
+  internal-fixture sample (~120 files, ~270 hx-* attributes), and
+  the test corpus pins the tricky cases (dash-variant `hx-on-*`,
+  attached comments, balanced JSX expressions inside attributes,
+  multiline tags). Pulling in `@swc/core` or `recast` for this
+  would be over-engineering — the walker is ~150 LOC, deterministic,
+  and shares a single source of truth between the standalone CLI
+  (`deco-htmx-analyze`), the post-cleanup audit rule
+  (`htmx-residue`), and the per-pattern recipe references.
+- **Classify by attribute cluster, not by individual attribute.**
+  An `hx-on:click` and `hx-post + hx-target + hx-swap` get
+  fundamentally different rewrites. Categorising at the cluster
+  level (the JSX tag + all its hx-* attrs) means each finding
+  points at exactly one of seven recipes in
+  `references/htmx-rewrite.md`. This is the same discipline that
+  worked for `STUB_FIX_HINTS` in the vtex-shim rule: the data shape
+  encodes the actionability category, the rule is just a thin
+  classifier on top.
+- **D2 + W13-C form a closed loop, mirroring the W12 D3 + audit
+  pattern.** D2 says "no htmx runtime in `@decocms/start`". W13-C's
+  `htmx-residue` rule says "fail CI if any `hx-*` survives in
+  `src/`". Together: a migrated site cannot accidentally rely on
+  htmx because (a) the framework gives them no runtime to import,
+  (b) the audit catches every leftover `hx-*` in code review.
+- **Detect-only is correct here, not a stop-gap.** Auto-fixing
+  htmx is conceptually hard: even a "simple" `<button hx-post>` →
+  `useMutation` rewrite has to choose between optimistic vs
+  pessimistic UI, error handling shape, where to surface the
+  loading state, and whether the response should re-render the
+  whole page or a fragment. Each is a per-site product decision.
+  The pattern catalog in `references/htmx-rewrite.md` is the
+  durable artefact; codemods (Wave 14) can target a specific
+  cluster shape (e.g. `hx-post + hx-target=#id + hx-swap=innerHTML`
+  with no `hx-trigger`) safely, but they're scoped by category,
+  not the rule's auto-fix.
+- **The audit registry is now self-shaped for additive growth.**
+  Eight rules, three of which (`vtex-shim-regression`,
+  `obsolete-vite-plugins`, `htmx-residue`) ship with their own
+  analyzer modules. The pattern is set: add a rule to
+  `ALL_RULES`, supply `applyFix` only when mechanical, point the
+  prose `fix:` field and JSON `meta` at a skill reference. The CLI
+  (`migrate-post-cleanup.ts`) is rule-agnostic — adding a ninth
+  rule means changing one file, getting `--strict` and `--json`
+  for free.
 
 ### Wave 14 (htmx codemods + first als migration on 2.14+) — planned
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@decocms/start",
-  "version": "2.19.0",
+  "version": "2.21.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);
+}