@decocms/start 2.12.0 → 2.14.0

package/.cursor/skills/deco-to-tanstack-migration/references/imports/README.md

@@ -1,70 +0,0 @@
-# Preact -> React Import Migration
-
-Mechanical find-and-replace. Safe to automate with `sed`.
-
-## Replacements
-
-| Find | Replace |
-|------|---------|
-| `from "preact/hooks"` | `from "react"` |
-| `from "preact/compat"` | `from "react"` |
-| `from "preact"` | `from "react"` |
-
-## Special Cases
-
-### ComponentChildren -> ReactNode
-
-Preact's `ComponentChildren` maps to React's `ReactNode`:
-
-```typescript
-// OLD
-import type { ComponentChildren } from "preact";
-
-// NEW
-import type { ReactNode as ComponentChildren } from "react";
-```
-
-If you want to modernize fully, rename `ComponentChildren` to `ReactNode` across the codebase.
-
-### JSX type
-
-```typescript
-// OLD
-import type { JSX } from "preact";
-
-// NEW (works unchanged)
-import type { JSX } from "react";
-```
-
-### FunctionalComponent -> FC
-
-```typescript
-// OLD
-const Foo: preact.FunctionalComponent<Props> = ...
-
-// NEW
-import React from "react";
-const Foo: React.FC<Props> = ...
-```
-
-## Automation
-
-```bash
-# Bulk replace (macOS sed)
-find src/ -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \
-  -e 's|from "preact/hooks"|from "react"|g' \
-  -e 's|from "preact/compat"|from "react"|g'
-
-# Bare preact requires care (don't match preact/hooks or preact/compat)
-find src/ -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \
-  's|from "preact"|from "react"|g'
-```
-
-Then handle `ComponentChildren` files individually.
-
-## Verification
-
-```bash
-grep -r 'from "preact' src/ --include='*.ts' --include='*.tsx'
-# Should return ZERO matches
-```

package/.cursor/skills/deco-to-tanstack-migration/references/platform-hooks/README.md

@@ -1,121 +0,0 @@
-# Platform Hooks Migration
-
-Platform hooks (useCart, useUser, useWishlist) are the most complex migration target because they have real business logic.
-
-## Strategy
-
-All hooks are **site-local**. No Vite alias tricks. No compat layers.
-
-- Active platform hooks (VTEX for this store) -> `~/hooks/useCart.ts` with real implementation
-- Inactive platform hooks (Wake, Shopify, etc.) -> `~/hooks/platform/{name}.ts` with no-op stubs
-- Auth hooks -> `~/hooks/useUser.ts`, `~/hooks/useWishlist.ts`
-
-## VTEX useCart (Real Implementation)
-
-### Why Server Functions Are Required
-
-The storefront domain (e.g., `my-store.deco.site`) differs from the VTEX checkout domain (`account.vtexcommercestable.com.br`). Direct browser `fetch()` calls are blocked by CORS. Additionally, VTEX API credentials (`AppKey`/`AppToken`) must stay server-side.
-
-Use TanStack Start `createServerFn` to create server-side proxy functions that the client hook calls transparently.
-
-> See `references/server-functions/README.md` for the full pattern and all TypeScript pitfalls.
-
-### Server Functions (`src/server/invoke.ts`)
-
-Wrap `@decocms/apps` VTEX actions in `createServerFn`. Always use `.inputValidator()` (not `.validator()`) and return `Promise<any>` to bypass `ValidateSerializable`:
-
-```typescript
-import { createServerFn } from "@tanstack/react-start";
-import { getOrCreateCart } from "@decocms/apps/vtex/actions/checkout";
-
-// Preferred: wrap @decocms/apps actions (handles auth + API details internally)
-const _getOrCreateCart = createServerFn({ method: "POST" })
-  .inputValidator((data: { orderFormId?: string }) => data)
-  .handler(async ({ data }): Promise<any> => {
-    const result = await getOrCreateCart(data.orderFormId);
-    return (result as any).data;
-  });
-
-export const invoke = {
-  vtex: { actions: { getOrCreateCart: _getOrCreateCart } },
-} as const;
-```
-
-### Hook (~/hooks/useCart.ts)
-
-Key design decisions:
-- **Module-level singleton state** shared across all component instances
-- **Pub/sub pattern** (`_listeners` Set) for notifying React components of changes
-- **Cookie-based session**: reads/writes `checkout.vtex.com__orderFormId` on the **client** side (not VTEX's domain cookie)
-- Returns `cart` and `loading` with `.value` getter/setter for backward compat with Preact-era components
-- Lazy initialization: cart is fetched on first component mount, not on module load
-- Exports `itemToAnalyticsItem` for cart-specific analytics mapping
-
-### Cross-Domain Checkout
-
-The minicart's "Finalizar Compra" button must link to the VTEX checkout domain with the `orderFormId` as a query parameter — the VTEX domain can't read the storefront's cookies:
-
-```typescript
-const checkoutUrl = `https://secure.${STORE_DOMAIN}/checkout/?orderFormId=${orderFormId}`;
-```
-
-### VTEX Types (~/types/vtex.ts)
-
-Site-local types for VTEX-specific structures:
-- `OrderFormItem`, `SimulationOrderForm`, `Sla`, `SKU`, `VtexProduct`
-
-## Inactive Platform Stubs
-
-For non-VTEX platforms, create minimal no-op files:
-
-```typescript
-// ~/hooks/platform/wake.ts
-export function useCart() {
-  return {
-    cart: { value: null },
-    loading: { value: false },
-    addItem: async (_params: any) => {},
-    updateItems: async (_params: any) => {},
-    removeItem: async (_index: any) => {},
-  };
-}
-
-export function useUser() {
-  return {
-    user: { value: null as { email?: string; name?: string } | null },
-    loading: { value: false },
-  };
-}
-
-export function useWishlist() {
-  return {
-    loading: { value: false },
-    addItem: async (_props: any) => {},
-    removeItem: async (_props: any) => {},
-    getItem: (_props: any) => undefined as any,
-  };
-}
-```
-
-Create similar stubs for: `shopify.ts`, `linx.ts`, `vnda.ts`, `nuvemshop.ts`.
-
-Match the return shape to what each platform's AddToCartButton expects (some use `addItem`, others `addItems`).
-
-## Import Rewrites
-
-```bash
-sed -i '' 's|from "apps/vtex/hooks/useCart.ts"|from "~/hooks/useCart"|g'
-sed -i '' 's|from "apps/vtex/hooks/useUser.ts"|from "~/hooks/useUser"|g'
-sed -i '' 's|from "apps/vtex/hooks/useWishlist.ts"|from "~/hooks/useWishlist"|g'
-sed -i '' 's|from "apps/vtex/utils/types.ts"|from "~/types/vtex"|g'
-sed -i '' 's|from "apps/shopify/hooks/useCart.ts"|from "~/hooks/platform/shopify"|g'
-sed -i '' 's|from "apps/wake/hooks/useCart.ts"|from "~/hooks/platform/wake"|g'
-# etc. for all platforms
-```
-
-## Verification
-
-```bash
-grep -r 'from "apps/' src/ --include='*.ts' --include='*.tsx'
-# Should return ZERO matches
-```

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

@@ -1,231 +0,0 @@
-# Post-Migration Cleanup
-
-After the migration script runs and the site builds + boots, there's a
-recurring set of dead-code and boilerplate cleanup that every migrated
-site benefits from. Run this checklist before the first PR review, not
-after the site has been shipping for weeks.
-
-## Run the audit first
-
-This whole checklist is now automated by the **`deco-post-cleanup`**
-audit script (added in `@decocms/start >= 2.11.0`, `--fix` mode in
-`>= 2.12.0`). Run it from the site repo to get a structured report
-of which sections below actually apply to your codebase:
-
-```bash
-# Pretty text output, exits 0 unless --strict is passed
-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.
-# Other rules stay detect-only — they require human judgment.
-npx -p @decocms/start deco-post-cleanup --fix
-
-# Combine for CI: auto-fix safe rules, fail (exit 2) if warnings remain.
-npx -p @decocms/start deco-post-cleanup --fix --strict
-
-# Machine-readable JSON for dashboards
-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.
-
-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.
-
-## 1. Delete unused `src/lib/*` shims
-
-The migration script's `templates/lib-utils.ts` generates 11 shim files
-under `src/lib/`. Most of them are NO-OP stubs intended as defensive
-bridges for signature mismatches. In practice many sites use zero of them
-because their loaders import directly from `@decocms/apps/vtex/utils/*`.
-
-### How to detect
-
-```bash
-# From repo root.
-for f in src/lib/*.ts; do
-  base=$(basename "$f" .ts)
-  symbols=$(grep -oE "^export (function|const|interface|type|class) [A-Za-z_][A-Za-z0-9_]*" "$f" | awk '{print $NF}')
-  for s in $symbols; do
-    # Search for the symbol anywhere in src/ outside src/lib/
-    hits=$(rg -l "\\b$s\\b" src/ --type ts --type tsx -g '!src/lib/**')
-    if [ -z "$hits" ]; then
-      echo "DEAD: $f exports $s with zero external imports"
-    fi
-  done
-done
-```
-
-If every export in a file is dead, delete the file. If `src/lib/` ends
-up empty, delete the directory too.
-
-### Real-world data
-
-| Site | Files generated | Files used |
-|------|-----------------|-----------|
-| baggagio-tanstack | 11 | 0 (all dead) |
-| casaevideo-storefront | 11 | 1 (wrapped manually) |
-
-The files that tend to be dead in every site:
-
-- `vtex-client.ts` — type-only export, sites usually grab it from `@decocms/apps`
-- `vtex-fetch.ts` — `fetchSafe` wrapper, supplanted by `@decocms/apps/vtex/utils/fetch`
-- `vtex-id.ts` — manual `parseCookie`, usually shadowed by `~/sdk/orderForm`'s real one
-- `vtex-segment.ts` — NO-OP stubs returning empty; never useful
-- `vtex-intelligent-search.ts` — stubs returning `{}`; supplanted by apps
-- `vtex-transform.ts` — re-exports from `@decocms/apps/vtex/utils/transform` directly
-- `vtex-send-event.ts` — claims to mirror an unreleased apps export; almost never imported
-
-The files that occasionally stay used:
-
-- `http-utils.ts` — `createHttpClient` proxy bridge for sites with custom
-  HTTP clients
-- `graphql-utils.ts` — same shape for GraphQL
-- `fetch-utils.ts` — single `STALE` cache header constant (very small)
-- `filter-navigate.ts` — VTEX filter URL string transformer
-
-If `apps/utils/*` imports never appear in your Fresh source, ALL FOUR of
-the latter are also dead.
-
-## 2. Drop inline vite plugins that are now framework-provided
-
-Two plugins that older site templates inline are obsolete on
-`@decocms/start >= 2.5.0`:
-
-```ts
-// site-manual-chunks — overrides framework default chunking
-{ name: "site-manual-chunks", config(_cfg, { command }) { ... ~25 lines ... } }
-
-// deco-stub-meta-gen — stubs admin schema on client
-{ name: "deco-stub-meta-gen", enforce: "pre", resolveId(...), load(...) }
-```
-
-The framework's `decoVitePlugin()` now handles both:
-- `manualChunks` no longer splits `@decocms/start` / `@decocms/apps` (the
-  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).
-
-## 3. Drop the `runtime.ts` `invoke` shim
-
-Older migrations create `src/runtime.ts` with a manual `createNestedInvokeProxy`
-implementation (~45 lines). The framework's `@decocms/start/sdk` now exports
-both `invoke` (default singleton) and `createAppInvoke` (for typed app-scoped
-proxies). Replace the file with a re-export, or delete it and update import
-sites:
-
-```diff
-- import { invoke } from "~/runtime";
-+ import { invoke } from "@decocms/start/sdk";
-```
-
-If `~/runtime` was only used for `invoke`, delete the file entirely. If
-it had additional helpers, keep it but trim it down to those.
-
-## 4. Drop site-local `withSiteGlobals` workaround
-
-If your site's `cmsRouteConfig` has a `cmsRouteWithGlobals` wrapper that
-manually merges `site.global` sections into the page sections list,
-delete it and use `@decocms/start/routes`'s opt-in helper:
-
-```ts
-import { cmsRouteConfig, withSiteGlobals } from "@decocms/start/routes";
-
-export const Route = createFileRoute(...)({
-  ...cmsRouteConfig({
-    ...withSiteGlobals,
-    // your route options
-  }),
-});
-```
-
-The site-side wrapper is typically ~390 LOC; the framework helper is
-opt-in and tested.
-
-## 5. Verify `vtex-* shim regression` is not still happening
-
-Older versions of the migration script's `phase-cleanup` had a bug where
-it actively rewrote valid `@decocms/apps/vtex/utils/*` and
-`@decocms/apps/vtex/client` imports back to the dead `~/lib/vtex-*` shims.
-Confirm your loaders import direct from `@decocms/apps`:
-
-```bash
-rg "from ['\"]~/lib/vtex-" src/
-# Expected: 0 hits (or only site-specific reasons you can articulate)
-```
-
-If you see hits, update the imports to point at `@decocms/apps/vtex/...`
-directly (or the corresponding `commerce/utils/*` if it's a generic
-utility). Your runtime behavior gets MUCH better — segment cookies, IS
-cookies, VTEX session auth all start working again instead of being
-silently stubbed to `{}` / `null`.
-
-## 6. Drop `src/types/widgets.ts` — framework owns it
-
-Older migrations scaffold a local `src/types/widgets.ts` containing 8
-string-aliased widget types (`ImageWidget`, `HTMLWidget`, …). The
-framework now exports the same set (plus `TextArea`) at
-`@decocms/start/types/widgets`, and the schema generator detects the
-widgets via type-text matching, so the local file is purely
-duplicated boilerplate.
-
-```bash
-# Quick check
-rg -n "from ['\"]~/types/widgets['\"]" src/ | wc -l   # >0 → cleanup applies
-```
-
-Replace all imports in one pass:
-
-```bash
-# macOS / BSD sed: drop the empty quotes after -i
-rg -l "from ['\"]~/types/widgets['\"]" src/ \
-  | xargs sed -i '' "s|from ['\"]~/types/widgets['\"]|from \"@decocms/start/types/widgets\"|g"
-```
-
-Then delete the now-orphan local file:
-
-```bash
-rm src/types/widgets.ts
-```
-
-Confirm `tsc --noEmit` is still clean — the framework version is a
-strict superset of what the migration script generated.
-
-## 7. Search for orphan `TODO: move into framework` comments
-
-Real sites accumulate `TODO` comments like `// TODO: move into decoVitePlugin
-in next @decocms/start release`. These are roadmap items the framework
-team should pick up, but they often go stale.
-
-```bash
-rg -n "TODO.*deco|TODO.*framework|TODO.*move into" src/ vite.config.ts
-```
-
-For each hit, decide:
-- Has the framework feature shipped? → migrate to it now and delete the comment
-- Is it deferred indefinitely? → file a tracking issue and link from the comment
-- Is it obsolete? → delete the comment
-
-## Verification checklist
-
-After completing 1-7:
-
-- [ ] `npm run typecheck` baseline matches pre-cleanup count (no new errors)
-- [ ] `npm run dev` starts and `/`, `/some-pdp/p`, `/s?q=foo` all render
-- [ ] `npm run build` succeeds with no chunk-load crashes
-- [ ] Smoke a logged-in PDP to confirm session cookies and segment auth
-      work (this is what the `~/lib/vtex-*` regression silently broke)
-- [ ] `git diff --stat` shows only deletions or framework-helper substitutions
-      — no new site-local logic added

package/.cursor/skills/deco-to-tanstack-migration/references/signals/README.md

@@ -1,220 +0,0 @@
-# @preact/signals -> TanStack Store Migration
-
-Two distinct patterns need different handling.
-
-## Pattern A: Component Hooks (useSignal, useComputed)
-
-These are component-local state. Replace with React hooks directly.
-
-### useSignal -> useState
-
-```typescript
-// OLD
-import { useSignal } from "@preact/signals";
-const loading = useSignal(false);
-loading.value = true;          // write
-if (loading.value) { ... }     // read
-
-// NEW
-import { useState } from "react";
-const [loading, setLoading] = useState(false);
-setLoading(true);              // write
-if (loading) { ... }           // read
-```
-
-Setter naming convention: `set` + capitalized variable name.
-
-### useComputed -> useMemo
-
-```typescript
-// OLD
-import { useComputed } from "@preact/signals";
-const isValid = useComputed(() => name.value.length > 0);
-return <div>{isValid.value}</div>;
-
-// NEW
-import { useMemo } from "react";
-const isValid = useMemo(() => name.length > 0, [name]);
-return <div>{isValid}</div>;
-```
-
-### Automation Tips
-
-- `useSignal`/`useComputed` changes are NOT safe for bulk sed (variable names, setter names, `.value` removal all differ per file)
-- Process each file individually: read, identify variable names, transform
-- Watch for: toggle patterns (`x.value = !x.value` -> `setX(prev => !prev)`), object state, conditional assignments
-
-## Pattern B: Module-Level Signals (Global State)
-
-These create shared state across components. Use `@tanstack/store`.
-
-### Create ~/sdk/signal.ts
-
-```typescript
-import { Store } from "@tanstack/store";
-import { useSyncExternalStore, useMemo } from "react";
-
-export interface Signal<T> {
-  readonly store: Store<T>;
-  value: T;
-  peek(): T;
-  subscribe(fn: () => void): () => void;
-}
-
-export function signal<T>(initialValue: T): Signal<T> {
-  const store = new Store<T>(initialValue);
-  return {
-    store,
-    get value() { return store.state; },
-    set value(v: T) { store.setState(() => v); },
-    peek() { return store.state; },
-    subscribe(fn) {
-      // CRITICAL: @tanstack/store@0.9.x returns { unsubscribe: Function },
-      // NOT a plain function. React's useSyncExternalStore and useEffect
-      // cleanup both expect a bare function. Passing the object causes
-      // "TypeError: destroy_ is not a function" at runtime.
-      const sub = store.subscribe(() => fn());
-      return typeof sub === "function" ? sub : sub.unsubscribe;
-    },
-  };
-}
-
-export function useSignal<T>(initialValue: T): Signal<T> {
-  const sig = useMemo(() => signal(initialValue), []);
-  useSyncExternalStore(
-    (cb) => sig.subscribe(cb),
-    () => sig.value,
-    () => sig.value,
-  );
-  return sig;
-}
-
-export function useComputed<T>(fn: () => T): Signal<T> {
-  const sig = useMemo(() => signal(fn()), []);
-  return sig;
-}
-
-export function computed<T>(fn: () => T): Signal<T> {
-  return signal(fn());
-}
-
-export function effect(fn: () => void | (() => void)): () => void {
-  const cleanup = fn();
-  return typeof cleanup === "function" ? cleanup : () => {};
-}
-
-export function batch(fn: () => void): void {
-  fn();
-}
-
-export function useSignalEffect(fn: () => void | (() => void)): void {
-  fn();
-}
-
-export type { Signal as ReadonlySignal };
-```
-
-> **WARNING**: The `subscribe()` unwrapping is the single most critical line in
-> this file. Without it, every component using `useSignal` will crash with
-> "TypeError: J is not a function" (minified) or "TypeError: destroy_ is not a
-> function" (non-minified), which then cascades into React #419 hydration
-> failures and #130 undefined component errors across the entire page.
-
-### Replace Imports
-
-```bash
-# Safe for bulk sed
-sed -i '' 's|from "@preact/signals"|from "~/sdk/signal"|g'
-```
-
-### React Subscriptions
-
-The signal shim's `.value` getter/setter does NOT create automatic React subscriptions. Reading `signal.value` during render won't re-render when the signal changes. This is the #1 source of "it works in Preact but not React" bugs.
-
-Replace manual useEffect+subscribe boilerplate with `useStore`:
-
-```typescript
-// OLD (manual subscription -- works but verbose)
-const { displayCart } = useUI();
-const [open, setOpen] = useState(false);
-useEffect(() => {
-  setOpen(displayCart.value);
-  return displayCart.subscribe(() => setOpen(displayCart.value));
-}, []);
-
-// NEW (useStore from @tanstack/react-store -- recommended)
-import { useStore } from "@tanstack/react-store";
-const { displayCart } = useUI();
-const open = useStore(displayCart.store);
-```
-
-Write-only consumers (event handlers) don't need `useStore`:
-```typescript
-// This still works -- .value setter backed by TanStack Store
-onClick={() => { displayCart.value = true; }}
-```
-
-### DaisyUI Drawer Workaround
-
-DaisyUI drawers use a hidden checkbox to toggle visibility. Since signal changes don't trigger React re-renders, the checkbox `checked` attribute never updates. Pragmatic workaround: directly toggle the DOM checkbox alongside the signal:
-
-```typescript
-// After setting the signal, also toggle the drawer checkbox
-displayCart.value = true;
-const checkbox = document.getElementById("cart-drawer") as HTMLInputElement;
-if (checkbox) checkbox.checked = true;
-```
-
-This is an interim pattern until all signal consumers use `useStore`. The `useStore` approach is the proper fix because it makes the Drawer component re-render, which updates the checkbox `checked` prop through React.
-
-### Global State Hook Pattern (useCart, useUI)
-
-Hooks that manage global state (cart, UI drawers) need module-level singleton state with a subscription mechanism. The pattern:
-
-```typescript
-let _state: CartData | null = null;
-const _listeners = new Set<() => void>();
-
-function notify() { _listeners.forEach((fn) => fn()); }
-
-export function useCart() {
-  const [, forceUpdate] = useState(0);
-
-  useEffect(() => {
-    const listener = () => forceUpdate((n) => n + 1);
-    _listeners.add(listener);
-    return () => { _listeners.delete(listener); };
-  }, []);
-
-  return {
-    cart: {
-      get value() { return _state; },
-      set value(v) { _state = v; notify(); },
-    },
-    // ... methods that update _state and call notify()
-  };
-}
-```
-
-Every component calling `useCart()` subscribes to changes, and state updates trigger re-renders across all subscribers. This replaces the Preact signals global reactivity.
-
-## Signal Type References
-
-If components use `Signal<T>` as a prop type:
-
-```typescript
-// OLD
-import { Signal } from "@preact/signals";
-interface Props { quantity: Signal<number>; }
-
-// NEW
-import type { ReactiveSignal } from "~/sdk/signal";
-interface Props { quantity: ReactiveSignal<number>; }
-```
-
-## Verification
-
-```bash
-grep -r '@preact/signals' src/ --include='*.ts' --include='*.tsx'
-# Should return ZERO matches
-```