v7: @decocms/start → 14-package lockstep monorepo (blocks core, admin, CLI, Next.js + TanStack bindings, per-platform apps)

.agents/skills/deco-migrate-script/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: deco-migrate-script
-description: Automated migration script that converts Deco storefronts from Fresh/Preact/Deno to TanStack Start/React/Cloudflare Workers. Runs 8 phases (analyze, scaffold, transform, cleanup, report, verify, bootstrap, compile). Use when running the migration script, debugging its output, extending it with new transforms, or understanding what it does. Located at scripts/migrate.ts in @decocms/start.
+description: Automated migration script that converts Deco storefronts from Fresh/Preact/Deno to TanStack Start/React/Cloudflare Workers. Runs 8 phases (analyze, scaffold, transform, cleanup, report, verify, bootstrap, compile). Use when running the migration script, debugging its output, extending it with new transforms, or understanding what it does. Located at packages/blocks-cli/scripts/migrate.ts in @decocms/blocks-cli.
 globs:
-  - "scripts/migrate.ts"
-  - "scripts/migrate/**/*"
+  - "packages/blocks-cli/scripts/migrate.ts"
+  - "packages/blocks-cli/scripts/migrate/**/*"
 ---
 
 # Deco Migration Script
@@ -13,11 +13,11 @@ Automated TypeScript script that converts a Deco storefront from Fresh/Preact/De
 ## Quick Start
 
 ```bash
-# From the NEW site root (already has @decocms/start installed):
-npx tsx node_modules/@decocms/start/scripts/migrate.ts --source /path/to/old-site
+# From the NEW site root (already has @decocms/blocks-cli linked/installed):
+npx tsx node_modules/@decocms/blocks-cli/scripts/migrate.ts --source /path/to/old-site
 
 # Dry run first:
-npx tsx node_modules/@decocms/start/scripts/migrate.ts --source /path/to/old-site --dry-run --verbose
+npx tsx node_modules/@decocms/blocks-cli/scripts/migrate.ts --source /path/to/old-site --dry-run --verbose
 ```
 
 ### Options
@@ -64,8 +64,8 @@ When the file is absent the baked-in casaevideo defaults apply, so existing migr
 ## Architecture
 
 ```
-scripts/migrate.ts              ← Entry point, runs all phases
-scripts/migrate/
+packages/blocks-cli/scripts/migrate.ts              ← Entry point, runs all phases
+packages/blocks-cli/scripts/migrate/
 ├── types.ts                    ← MigrationContext, FileRecord, DetectedPattern
 ├── colors.ts                   ← Terminal output formatting
 ├── phase-analyze.ts            ← Phase 1: scan source, detect patterns
@@ -160,9 +160,9 @@ Applies 6 transforms in sequence to every source file:
 preact/hooks     → react
 preact/compat    → react
 preact           → react
-@preact/signals  → @decocms/start/sdk/signal
-@deco/deco/hooks → @decocms/start/sdk/useScript
-@deco/deco/blocks→ @decocms/start/types
+@preact/signals  → @decocms/blocks/sdk/signal
+@deco/deco/hooks → @decocms/blocks/sdk/useScript
+@deco/deco/blocks→ @decocms/blocks/types
 apps/commerce/*  → @decocms/apps/commerce/*
 apps/website/*   → ~/components/ui/* or @decocms/apps/*
 site/*           → ~/*
@@ -250,7 +250,7 @@ bg-black bg-opacity-20 → bg-black/20
 **Deletes root files:**
 - `deno.json`, `fresh.gen.ts`, `main.ts`, `dev.ts`, `tailwind.config.ts`, `runtime.ts`, `constants.ts`
 
-**Deletes SDK files** (now in @decocms/start or @decocms/apps):
+**Deletes SDK files** (now in @decocms/blocks or @decocms/apps):
 - `sdk/clx.ts`, `sdk/useId.ts`, `sdk/useOffer.ts`, `sdk/useVariantPossiblities.ts`, `sdk/usePlatform.tsx`
 
 **Moves:**
@@ -264,7 +264,7 @@ Generates `MIGRATION_REPORT.md` with:
 - Manual review items with severity
 - Always-check section (FormEmail, Slider, Theme, DaisyUI, Tailwind)
 - Known issues (z-index stacking, opacity modifiers)
-- Framework findings (patterns to consolidate into @decocms/start)
+- Framework findings (patterns to consolidate into @decocms/blocks)
 - Next steps
 
 ### Phase 6: Verify
@@ -294,8 +294,8 @@ Generates `MIGRATION_REPORT.md` with:
 
 Runs automatically after all phases (skipped in `--dry-run`):
 1. `bun install`
-2. `bunx tsx node_modules/@decocms/start/scripts/generate-blocks.ts`
-3. `bunx tsx node_modules/@decocms/start/scripts/generate-invoke.ts` — emits `src/server/invoke.gen.ts` (top-level `createServerFn` declarations for every VTEX action, plus the `forwardResponseCookies()` Set-Cookie bridge). Without this step the site falls back to the `/deco/invoke/...` proxy and the cart breaks at `/checkout` after addItemToCart. See `.cursor/skills/deco-server-functions-invoke/troubleshooting.md` ("Cart 'forgets' items between requests") for the failure mode.
+2. `bunx tsx node_modules/@decocms/blocks-cli/scripts/generate-blocks.ts`
+3. `bunx tsx node_modules/@decocms/blocks-cli/scripts/generate-invoke.ts` — emits `src/server/invoke.gen.ts` (top-level `createServerFn` declarations for every VTEX action, plus the `forwardResponseCookies()` Set-Cookie bridge). Without this step the site falls back to the `/deco/invoke/...` proxy and the cart breaks at `/checkout` after addItemToCart. See `.cursor/skills/deco-server-functions-invoke/troubleshooting.md` ("Cart 'forgets' items between requests") for the failure mode.
 4. `bunx tsr generate`
 
 ### Phase 8: Compile
@@ -374,7 +374,7 @@ Platform affects: commerce type imports, loader registration, setup.ts template,
 
 ### Adding a New Transform
 
-1. Create `scripts/migrate/transforms/my-transform.ts`:
+1. Create `packages/blocks-cli/scripts/migrate/transforms/my-transform.ts`:
 
 ```typescript
 import type { TransformResult } from "../types";
@@ -407,7 +407,7 @@ const transforms = [imports, jsx, freshApis, deadCode, denoIsms, tailwind, myTra
 
 ### Adding a New Template
 
-1. Create `scripts/migrate/templates/my-file.ts`:
+1. Create `packages/blocks-cli/scripts/migrate/templates/my-file.ts`:
 
 ```typescript
 import type { MigrationContext } from "../types";
@@ -495,13 +495,13 @@ script leaves behind on existing-but-pre-framework-helpers sites:
 
 ```bash
 # Read-only audit (default)
-npx -p @decocms/start deco-post-cleanup
+npx -p @decocms/blocks-cli deco-post-cleanup
 
 # Auto-fix the safe rules (dead-lib-shims, dead-runtime-shim, local-widgets-types)
-npx -p @decocms/start deco-post-cleanup --fix
+npx -p @decocms/blocks-cli deco-post-cleanup --fix
 
 # CI gate: auto-fix safe rules, exit 2 if any warnings remain
-npx -p @decocms/start deco-post-cleanup --fix --strict
+npx -p @decocms/blocks-cli deco-post-cleanup --fix --strict
 ```
 
 The audit covers 7 rules (delete dead lib shims, drop obsolete inline
@@ -522,5 +522,5 @@ detection logic mirrors the canonical checklist at
 shim files have valid TypeScript signatures. The audit's pattern
 matches surface what compilation cannot.
 
-Source: `scripts/migrate-post-cleanup.ts` + `scripts/migrate/post-cleanup/`.
-Tests: `scripts/migrate/post-cleanup/runner.test.ts`.
+Source: `packages/blocks-cli/scripts/migrate-post-cleanup.ts` + `packages/blocks-cli/scripts/migrate/post-cleanup/`.
+Tests: `packages/blocks-cli/scripts/migrate/post-cleanup/runner.test.ts`.

.agents/skills/deco-next-package-migration/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: deco-next-package-migration
+description: Migrates a Next.js App Router site off the abandoned @decocms/start@5.x /next, /core, /node export tiers onto the current @decocms/blocks, @decocms/blocks-admin, and @decocms/nextjs packages. Use when a site's package.json pins @decocms/start to a 5.x-next prerelease, or imports from @decocms/start/next, @decocms/start/core, or @decocms/start/node.
+---
+
+# Deco Next.js Package Migration
+
+Moves a Next.js site off the reverted `@decocms/start@5.x` framework-agnostic-entrypoints tiers onto the current package split. Proven on faststore-fila, a production Next.js 15 App Router VTEX FastStore storefront with a pre-existing `.deco/blocks/*.json` legacy content snapshot.
+
+## When this applies
+
+- `package.json` has `"@decocms/start": "5.x-next.*"` or similar prerelease pin
+- Code imports from `@decocms/start/next`, `@decocms/start/core`, or `@decocms/start/node`
+- The site has its own `src/sdk/deco/`-style wrapper layer (or equivalent) around the framework, rather than using the framework's route/page helpers directly
+
+## Import mapping
+
+See `references/import-mapping.md` for the full table. Summary: `@decocms/start/core`'s CMS functions (`setBlocks`, `registerSectionLoaders`, etc.) move to `@decocms/blocks/cms` under the *same names* — these did not change across the package split, only the import path. `@decocms/start/next`'s `createDecoAdminRouteHandlers`/`loadCmsPage` have no direct equivalent — `@decocms/nextjs` splits the admin protocol into one function per concern (`metaGET`, `decofileGET`/`decofilePOST`, `invokePOST`, `renderGET`/`renderPOST`) instead of one dispatcher, and page-level CMS resolution goes through `@decocms/blocks/cms`'s `resolveDecoPage` + `extractSeoFromSections` directly (or `@decocms/nextjs`'s generic `createDecoPage` helper, if the site doesn't need custom SEO-merging/curated-block-override logic). `@decocms/start/node`'s `loadAllDecofileBlocks` has no equivalent — if the site loads a directory of pre-existing legacy block JSON files (not build-time-generated ones), use `@decocms/blocks/cms/loadDecofileDirectory` (new).
+
+## Steps
+
+1. **Dependencies**: remove the old `@decocms/start` pin, add `@decocms/blocks`, `@decocms/blocks-admin`, and (if the site uses Next.js pages/route handlers directly rather than its own wrapper) `@decocms/nextjs`. During development before anything is published, use `bun link` against a local `deco-start` checkout — see `docs/fast-deploy.md`'s general local-dev-linking pattern, or this migration's own Task 2 for the exact commands.
+2. **Section registration**: swap `@decocms/start/core`'s `registerSection`/`registerSectionsSync` imports for `@decocms/blocks/cms` — same names, no other changes needed.
+3. **CMS setup/resolution**: rewrite the site's setup wrapper against `@decocms/blocks/cms`'s `setBlocks`/`setResolveErrorHandler`/`registerLayoutSections`/`registerSectionLoaders` (same names) plus `resolveDecoPage`/`extractSeoFromSections` (replacing `loadCmsPage`) and, if needed, `loadDecofileDirectory` (replacing `loadAllDecofileBlocks`). See `templates/setup-ts.md` for a full worked example derived from the faststore-fila migration. Keep the wrapper's own exported function names and return shapes unchanged wherever possible — this is what let faststore-fila's page files avoid any changes at all.
+4. **Admin routes**: `@decocms/nextjs` exports one function per admin concern rather than one dispatcher — rewrite the site's admin-route wrapper as thin per-concern re-exports. See `templates/admin-routes.md`. Any route the old dispatcher served that has no `@decocms/blocks-admin`/`@decocms/nextjs` equivalent (live-editing dev tunnel: file-watch SSE, JSON-Patch file mutation) should be deleted or replaced with a simple non-daemon stub (e.g. a readiness check reading `loadBlocks()`'s size directly) — these were deliberately scoped out of the current package split, not omitted by oversight.
+5. **Validate end-to-end against a real dev server**, not just unit tests — specifically the site's actual `.deco/blocks`-derived content (a real page path, not a synthetic fixture), since the on-disk block format and its resolution are exactly the surface most likely to have a real, only-visible-at-runtime discrepancy (see this migration's own Task 6).
+
+## Gotchas
+
+- `resolveDecoPage`'s return shape (`DecoPageResult`) is `{name, path, params, blockKey, resolvedSections, deferredSections, seoSection}` — note `seoSection` is a *resolved section*, not a plain `{title, description}` object. Call `extractSeoFromSections([result.seoSection].filter(Boolean))` to get a plain SEO object.
+- `findPageByPath` matches on each page block's `.path` field, not on the blocks map's key — so a `loadDecofileDirectory`-style loader can assign any unique key per file without needing to reverse-engineer the original admin's exact key-naming convention.
+- Next.js App Router route folder naming is asymmetric between `_` and `.` prefixes, and it's easy to get backwards: `_`-prefixed folders (e.g. `_healthcheck`) must be URL-encoded as `%5Ffoldername`, because Next treats a literal `_folder` as a private folder and excludes it from routing. Dot-prefixed folders (e.g. `.decofile`) must do the **opposite** — keep the literal dot. The URL-encoded form (`%2E…`) is NOT decoded by Next App Router (verified against Next 16.2.6 / Turbopack) — it resolves to the catchall route instead of the intended handler. This is a Next.js routing constraint, unrelated to the deco-start package split, and was already handled in whatever site is being migrated (verify it still is, post-migration).