@decocms/blocks 8.10.0 → 8.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js.map +1 -1
  4. package/dist/protocol/conformance/blockMetaVectors.json +80 -0
  5. package/dist/protocol/index.d.ts +5 -2
  6. package/dist/protocol/index.d.ts.map +1 -1
  7. package/dist/protocol/index.js +5 -2
  8. package/dist/protocol/index.js.map +1 -1
  9. package/dist/v8/blockMeta.d.ts +33 -4
  10. package/dist/v8/blockMeta.d.ts.map +1 -1
  11. package/dist/v8/blockMeta.js +70 -13
  12. package/dist/v8/blockMeta.js.map +1 -1
  13. package/dist/v8/cli/index.d.ts +1 -0
  14. package/dist/v8/cli/index.d.ts.map +1 -1
  15. package/dist/v8/cli/index.js +1 -0
  16. package/dist/v8/cli/index.js.map +1 -1
  17. package/dist/v8/cli/run.d.ts +2 -0
  18. package/dist/v8/cli/run.d.ts.map +1 -1
  19. package/dist/v8/cli/run.js +30 -1
  20. package/dist/v8/cli/run.js.map +1 -1
  21. package/dist/v8/cli/skills.d.ts +25 -0
  22. package/dist/v8/cli/skills.d.ts.map +1 -0
  23. package/dist/v8/cli/skills.js +70 -0
  24. package/dist/v8/cli/skills.js.map +1 -0
  25. package/dist/v8/client.d.ts +6 -4
  26. package/dist/v8/client.d.ts.map +1 -1
  27. package/dist/v8/client.js +26 -70
  28. package/dist/v8/client.js.map +1 -1
  29. package/dist/v8/cms.d.ts.map +1 -1
  30. package/dist/v8/cms.js +1 -2
  31. package/dist/v8/cms.js.map +1 -1
  32. package/dist/v8/contentIndex.d.ts +18 -7
  33. package/dist/v8/contentIndex.d.ts.map +1 -1
  34. package/dist/v8/contentIndex.js +46 -17
  35. package/dist/v8/contentIndex.js.map +1 -1
  36. package/dist/v8/draftChanges.d.ts.map +1 -1
  37. package/dist/v8/draftChanges.js +4 -1
  38. package/dist/v8/draftChanges.js.map +1 -1
  39. package/dist/v8/index.d.ts +1 -1
  40. package/dist/v8/index.d.ts.map +1 -1
  41. package/dist/v8/remoteLoader.d.ts +4 -2
  42. package/dist/v8/remoteLoader.d.ts.map +1 -1
  43. package/dist/v8/remoteLoader.js +13 -3
  44. package/dist/v8/remoteLoader.js.map +1 -1
  45. package/dist/v8/types.d.ts +47 -7
  46. package/dist/v8/types.d.ts.map +1 -1
  47. package/package.json +3 -2
  48. package/skills/deco-apps/SKILL.md +82 -0
  49. package/skills/deco-apps/references/algolia.md +51 -0
  50. package/skills/deco-apps/references/commerce-types.md +132 -0
  51. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  52. package/skills/deco-apps/references/magento.md +55 -0
  53. package/skills/deco-apps/references/messaging.md +76 -0
  54. package/skills/deco-apps/references/shopify.md +69 -0
  55. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  56. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  57. package/skills/deco-apps/references/vtex.md +150 -0
  58. package/skills/deco-apps/references/wake.md +75 -0
  59. package/skills/deco-cms-schema/SKILL.md +80 -0
  60. package/skills/deco-cms-schema/references/annotations.md +147 -0
  61. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  62. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  63. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  64. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  65. package/skills/deco-go-live/SKILL.md +127 -0
  66. package/skills/deco-go-live/references/content-releases.md +90 -0
  67. package/skills/deco-go-live/references/process.md +106 -0
  68. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  69. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  70. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  71. package/skills/deco-go-live/references/react-spa.md +183 -0
  72. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  73. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  74. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  75. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  76. package/skills/deco-images-media/SKILL.md +64 -0
  77. package/skills/deco-images-media/references/asset-upload.md +191 -0
  78. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  79. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  80. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  81. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  82. package/skills/deco-images-media/references/video.md +122 -0
  83. package/skills/deco-make-editable/SKILL.md +94 -0
  84. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  85. package/skills/deco-make-editable/references/content-shapes.md +203 -0
  86. package/skills/deco-make-editable/references/from-figma.md +110 -0
  87. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  88. package/skills/deco-make-editable/references/inventory.md +79 -0
  89. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  90. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  91. package/skills/deco-nextjs-site/SKILL.md +74 -0
  92. package/skills/deco-nextjs-site/references/caching.md +116 -0
  93. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  94. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  95. package/skills/deco-nextjs-site/references/rendering.md +172 -0
  96. package/skills/deco-nextjs-site/references/setup.md +190 -0
  97. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  98. package/skills/deco-site-authoring/SKILL.md +75 -0
  99. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  100. package/skills/deco-site-authoring/references/loaders.md +192 -0
  101. package/skills/deco-site-authoring/references/pages.md +158 -0
  102. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  103. package/skills/deco-site-authoring/references/sections.md +158 -0
  104. package/skills/deco-site-authoring/references/seo.md +116 -0
  105. package/skills/deco-site-workflow/SKILL.md +101 -0
  106. package/skills/deco-site-workflow/references/check.md +116 -0
  107. package/skills/deco-site-workflow/references/cli-reference.md +106 -0
  108. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  109. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  110. package/skills/deco-site-workflow/references/delivery.md +51 -0
  111. package/skills/deco-site-workflow/references/deploy.md +87 -0
  112. package/skills/deco-site-workflow/references/schema.md +173 -0
  113. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  114. package/skills/deco-storefront-caching/SKILL.md +67 -0
  115. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  116. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  117. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  118. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  119. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  120. package/skills/deco-storefront-caching/references/verification.md +136 -0
  121. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  122. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  123. package/skills/deco-storefront-performance/SKILL.md +81 -0
  124. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  125. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  126. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  127. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  128. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  129. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  130. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  131. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  132. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  133. package/skills/deco-tanstack-site/SKILL.md +68 -0
  134. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  135. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  136. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  137. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  138. package/skills/deco-tanstack-site/references/setup.md +153 -0
  139. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  140. package/skills/deco-v7-to-v8-migration/SKILL.md +123 -0
  141. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  142. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  143. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  144. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  145. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  146. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  147. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  148. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  149. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  150. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  151. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  152. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  153. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  154. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  155. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  156. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  157. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  158. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  159. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  160. package/skills/deco-v7-to-v8-migration/references/verify.md +23 -0
  161. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  162. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  163. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  164. package/skills/deco-v7-to-v8-migration/scripts/checkContentReads.ts +32 -0
  165. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  166. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  167. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  168. package/skills/deco-v7-to-v8-migration/scripts/contentReads.ts +157 -0
  169. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  170. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  171. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  172. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  173. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  174. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  175. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  176. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  177. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  178. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +180 -0
  179. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  180. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  181. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  182. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  183. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  184. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  185. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  186. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  187. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  188. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  189. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  190. package/skills/deco-variants/SKILL.md +57 -0
  191. package/skills/deco-variants/references/caching-variants.md +63 -0
  192. package/skills/deco-variants/references/custom-matchers.md +83 -0
  193. package/skills/deco-variants/references/draft-preview.md +59 -0
  194. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  195. package/skills/deco-variants/references/multivariate.md +85 -0
  196. package/skills/deco-variants/references/v7-matchers.md +71 -0
  197. package/src/index.ts +1 -1
  198. package/src/protocol/conformance/blockMetaVectors.json +80 -0
  199. package/src/protocol/index.ts +8 -1
  200. package/src/v8/blockMeta.ts +75 -11
  201. package/src/v8/cli/index.ts +1 -0
  202. package/src/v8/cli/run.ts +35 -1
  203. package/src/v8/cli/skills.ts +91 -0
  204. package/src/v8/client.ts +32 -77
  205. package/src/v8/cms.ts +1 -2
  206. package/src/v8/contentIndex.ts +49 -19
  207. package/src/v8/draftChanges.ts +5 -1
  208. package/src/v8/index.ts +1 -1
  209. package/src/v8/remoteLoader.ts +13 -3
  210. package/src/v8/types.ts +48 -7
@@ -0,0 +1,584 @@
1
+ /**
2
+ * The block map (spec: renames-and-migrations › Rename a block type). Saved
3
+ * content names v7 types by file path, like `site/sections/Product/Shelf.tsx`;
4
+ * the next major resolves a name only through `.deco/index.ts`. This step
5
+ * writes that file: one entry per v7 name the content stores (and per section
6
+ * in `src/sections`), so the content keeps resolving. No short names: the
7
+ * site editor lists every name, so a block under two would be offered twice
8
+ * (PO 2026-10-15).
9
+ *
10
+ * - The site's own modules (`site/…`) are registered from `src/`, every
11
+ * section under `src/sections` included, so editors can still add them.
12
+ * - App loaders and actions the content calls are vendored first (see
13
+ * ./vendor.ts) and registered from the copy.
14
+ * - Built-ins and the legacy names the runtime already maps (`page`,
15
+ * `multivariate`, …) need no entry.
16
+ * - Everything else has no v8 equivalent; it is reported, not registered.
17
+ *
18
+ * Sections return render descriptors, `{ component, props }`, and `page`
19
+ * takes them (see /next/tanstack-start-descriptors): it works in any
20
+ * framework, and the site's view registry maps each component name to the
21
+ * section it renders.
22
+ */
23
+ import fs from "node:fs";
24
+ import path from "node:path";
25
+ import { BUILT_IN_BLOCKS, LEGACY_ALIASES } from "@decocms/blocks/cli";
26
+ import { type Framework, siteBlocksVersion, siteFramework } from "./framework";
27
+ import { matcherEntry, V7_MATCHER_HINT, v7Matcher } from "./matchers";
28
+ import type { Report } from "./report";
29
+ import { V7_SECRET_TYPES } from "./secrets";
30
+ import type { SectionLoaderWiring } from "./sectionLoaders";
31
+ import { firstFile, locateAppModule, vendorModule } from "./vendor";
32
+ import { forEachBlock, readContent } from "./walk";
33
+
34
+ type Kind = "section" | "function";
35
+
36
+ interface Entry {
37
+ /** The module that holds the block function (default export). */
38
+ file: string;
39
+ kind: Kind;
40
+ /** The v7 names content stores for it: the names it's registered under. */
41
+ legacy: string[];
42
+ ident: string;
43
+ /** Whether the module exports a `loader` (a section's, run by `loadSections`). */
44
+ loader: boolean;
45
+ /** A section's descriptor `component`: its v7 type name, `site/sections/….tsx`. */
46
+ component: string;
47
+ }
48
+
49
+ const ANALYTICS_SECTION = /^website\/sections\/Analytics\//;
50
+
51
+ /** Where to look for a type without a v8 equivalent. */
52
+ const HINTS: [RegExp, string][] = [
53
+ [
54
+ /\/apps\//,
55
+ "a v7 app block; the next major has no apps: create the platform's client in code with these settings (/next/upstream-clients#call-a-client), then delete the saved block",
56
+ ],
57
+ [
58
+ /^website\/sections\/Rendering\/(Lazy|Deferred|SingleDeferred)\.tsx?$/,
59
+ "a v7 async-rendering wrapper the migration couldn't unwrap (no section, or several where one block goes); the next major has no async rendering: replace it with its section(s) in the content",
60
+ ],
61
+ [
62
+ /\/sections\/Seo\//,
63
+ "an SEO section: register a block under this name. In a page's seo field it returns the block map's PageSeo type (.deco/index.ts), the fields the page's head shows (the built-in page's seo field takes any block returning only optional SEO fields: a title or a description, strings); in sections, a descriptor or nothing. v7's SeoV2 also merged the website app's seo settings (defaults, titleTemplate, descriptionTemplate) into its fields, and v7's head took fields from sections registered with registerSeoSections too: carry those into the block (/next/renames-and-migrations#rename-a-type-with-an-alias)",
64
+ ],
65
+ [
66
+ ANALYTICS_SECTION,
67
+ "v7's Analytics section: move its tag IDs into your template's tag-manager block (/next/renames-and-migrations#telemetry-and-analytics)",
68
+ ],
69
+ [/\/matchers\//, V7_MATCHER_HINT],
70
+ [
71
+ /^website\/functions\/requestToParam/,
72
+ "reads the request; take route params from matchRoute's `params` instead (/next/api-reference#matchroute-url-items)",
73
+ ],
74
+ ];
75
+ const DEFAULT_HINT =
76
+ "no v8 equivalent and no installed source to vendor: register a block under this name in .deco/index.ts, or migrate the content";
77
+
78
+ function hintFor(type: string): string {
79
+ return HINTS.find(([pattern]) => pattern.test(type))?.[1] ?? DEFAULT_HINT;
80
+ }
81
+
82
+ function kebab(name: string): string {
83
+ return name
84
+ .replace(/\.(tsx?|jsx?)$/, "")
85
+ .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
86
+ .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
87
+ .replace(/[^A-Za-z0-9]+/g, "-")
88
+ .replace(/^-+|-+$/g, "")
89
+ .toLowerCase();
90
+ }
91
+
92
+ const RESERVED_WORDS = new Set(
93
+ `arguments await break case catch class const continue debugger default delete do else enum eval
94
+ export extends false finally for function if implements import in instanceof interface let new null
95
+ package private protected public return static super switch this throw true try typeof var void
96
+ while with yield`.split(/\s+/),
97
+ );
98
+
99
+ function camel(name: string): string {
100
+ const ident = name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
101
+ if (/^[0-9]/.test(ident)) return `_${ident}`;
102
+ return RESERVED_WORDS.has(ident) ? `${ident}Block` : ident;
103
+ }
104
+
105
+ function moduleFile(base: string): string | undefined {
106
+ return /\.(tsx?)$/.test(base) ? firstFile([base]) : firstFile([`${base}.ts`, `${base}.tsx`]);
107
+ }
108
+
109
+ function listFiles(dir: string, ext: RegExp): string[] {
110
+ if (!fs.existsSync(dir)) return [];
111
+ return fs
112
+ .readdirSync(dir, { recursive: true, withFileTypes: true })
113
+ .filter((d) => d.isFile() && ext.test(d.name) && !/\.test\.tsx?$/.test(d.name))
114
+ .map((d) => path.join(d.parentPath, d.name));
115
+ }
116
+
117
+ const HAS_DEFAULT = /\bexport\s+default\b|\bexport\s*\{[^}]*\bdefault\b/;
118
+ const HAS_LOADER =
119
+ /\bexport\s+(?:async\s+)?(?:function|const|let)\s+loader\b|\bexport\s*\{[^}]*\bloader\b/;
120
+
121
+ function posix(p: string): string {
122
+ return p.split(path.sep).join("/");
123
+ }
124
+
125
+ function importPath(root: string, file: string): string {
126
+ const rel = posix(path.relative(path.join(root, ".deco"), file)).replace(/\.tsx?$/, "");
127
+ return rel.startsWith(".") ? rel : `./${rel}`;
128
+ }
129
+
130
+ interface BlockMapResult {
131
+ /** Each vendored module: installed source → its copy in the site. */
132
+ vendored: Map<string, string>;
133
+ }
134
+
135
+ /**
136
+ * Write `.deco/index.ts` from the site's content and sources, and the view
137
+ * registry `src/views.ts`. Keeps an existing block map. `wiring` says where
138
+ * the site's v7 section loaders are exported now (./sectionLoaders.ts).
139
+ */
140
+ export function writeBlockMap(
141
+ root: string,
142
+ report: Report,
143
+ wiring: SectionLoaderWiring = {},
144
+ /** v7 app types the apps step turned into client code (./apps.ts): not reported again. */
145
+ apps: ReadonlySet<string> = new Set(),
146
+ ): BlockMapResult {
147
+ const existing = ["index.ts", "index.tsx"].find((f) =>
148
+ fs.existsSync(path.join(root, ".deco", f)),
149
+ );
150
+ if (existing) {
151
+ report.manual.push({
152
+ step: "block map",
153
+ subject: `.deco/${existing}`,
154
+ message: "already exists, so it was kept; delete it and run again to generate one",
155
+ });
156
+ return { vendored: new Map() };
157
+ }
158
+
159
+ const { blocks, files } = readContent(root);
160
+ const used = new Map<string, Set<string>>();
161
+ /** v7 Analytics sections' GTM/GA4 IDs, so the report carries them over. */
162
+ const tagIds = new Map<string, Set<string>>();
163
+ for (const [entry, block] of Object.entries(blocks)) {
164
+ forEachBlock(block, (node) => {
165
+ const type = node.__resolveType;
166
+ if (!used.has(type)) used.set(type, new Set());
167
+ used.get(type)!.add(files[entry]);
168
+ if (!ANALYTICS_SECTION.test(type)) return;
169
+ for (const field of ["trackingIds", "googleAnalyticsIds"]) {
170
+ const ids = node[field];
171
+ if (!Array.isArray(ids)) continue;
172
+ if (!tagIds.has(type)) tagIds.set(type, new Set());
173
+ for (const id of ids) if (typeof id === "string" && id) tagIds.get(type)!.add(id);
174
+ }
175
+ });
176
+ }
177
+ const builtIn = new Set(BUILT_IN_BLOCKS);
178
+ const types = new Set(
179
+ [...used.keys()].filter(
180
+ (t) =>
181
+ !Object.hasOwn(blocks, t) &&
182
+ !builtIn.has(t) &&
183
+ !Object.hasOwn(LEGACY_ALIASES, t) &&
184
+ !V7_SECRET_TYPES.has(t),
185
+ ),
186
+ );
187
+ for (const file of listFiles(path.join(root, "src", "sections"), /\.tsx$/)) {
188
+ const type = `site/${posix(path.relative(path.join(root, "src"), file))}`;
189
+ if (!types.has(type) && !types.has(type.replace(/\.tsx$/, ""))) types.add(type);
190
+ }
191
+
192
+ const framework = siteFramework(root);
193
+ const byFile = new Map<string, Entry>();
194
+ /** v7 matchers registered from @decocms/compat-v7/matchers: v7 name → the matcher. */
195
+ const matchers = new Map<string, string>();
196
+ const vendored = new Map<string, string>();
197
+ const leave = (type: string, hint: string) => {
198
+ const ids = [...(tagIds.get(type) ?? [])];
199
+ const message = ids.length > 0 ? `${hint}; its tag IDs: ${ids.join(", ")}` : hint;
200
+ const where = [...(used.get(type) ?? [])];
201
+ const usedIn =
202
+ where.length > 0
203
+ ? ` (in ${where.slice(0, 3).join(", ")}${where.length > 3 ? ", …" : ""})`
204
+ : "";
205
+ report.manual.push({ step: "block map", subject: `${type}${usedIn}`, message });
206
+ };
207
+
208
+ for (const type of [...types].sort()) {
209
+ const [namespace, group] = type.split("/");
210
+ const kind: Kind = group === "sections" ? "section" : "function";
211
+ let file: string | undefined;
212
+ if (namespace === "site") {
213
+ const rest = type.slice("site/".length);
214
+ if (rest.split("/").includes("..")) {
215
+ leave(
216
+ type,
217
+ "not a path inside src/; register a block under this name, or migrate the content",
218
+ );
219
+ continue;
220
+ }
221
+ if (rest.startsWith("apps/")) {
222
+ if (!apps.has(type)) leave(type, hintFor(type));
223
+ continue;
224
+ }
225
+ file = moduleFile(path.join(root, "src", rest));
226
+ if (!file) {
227
+ leave(
228
+ type,
229
+ `no src/${rest} in the site; register a block under this name, or migrate the content`,
230
+ );
231
+ continue;
232
+ }
233
+ } else if (group === "loaders" || group === "actions") {
234
+ const located = locateAppModule(root, type);
235
+ if (!located) {
236
+ leave(type, hintFor(type));
237
+ continue;
238
+ }
239
+ const before = vendored.size;
240
+ file = vendorModule(root, located, vendored, report);
241
+ const count = vendored.size - before;
242
+ report.done.push({
243
+ step: "vendor",
244
+ subject: type,
245
+ message: `copied to ${posix(path.relative(root, file))}${count > 1 ? ` with ${count - 1} more files` : ""}; rewrite it over the platform's upstream client (/next/upstream-clients)`,
246
+ });
247
+ } else {
248
+ const matcher = v7Matcher(type);
249
+ if (matcher && matcher !== "environment" && framework) {
250
+ matchers.set(type, matcher);
251
+ continue;
252
+ }
253
+ leave(type, hintFor(type));
254
+ continue;
255
+ }
256
+
257
+ const source = fs.readFileSync(file, "utf8");
258
+ if (!HAS_DEFAULT.test(source)) {
259
+ leave(type, `${posix(path.relative(root, file))} has no default export to register`);
260
+ continue;
261
+ }
262
+ const entry = byFile.get(file);
263
+ if (entry) {
264
+ entry.legacy.push(type);
265
+ continue;
266
+ }
267
+ const component = `site/${posix(path.relative(path.join(root, "src"), file))}`;
268
+ const loader = kind === "section" && HAS_LOADER.test(source);
269
+ byFile.set(file, { file, kind, legacy: [type], ident: "", component, loader });
270
+ if (loader && !wiring.loaders?.keys?.has(component)) {
271
+ report.manual.push({
272
+ step: "block map",
273
+ subject: type,
274
+ message:
275
+ wiring.loaders?.keys === null
276
+ ? "its loader now runs (loadSections in .deco/index.ts), unless the site's sectionLoaders lists it, which then runs instead: v7 ran a section's loader only when registerSectionLoaders listed it, and the script couldn't read that list's names. Where v7 didn't list it, v7 rendered its saved props and v8 runs the loader, an approved difference (PO 2026-10-15): list it in the PR"
277
+ : "its loader now runs (loadSections in .deco/index.ts), which v7 never did: registerSectionLoaders didn't list it, so v7 rendered its saved props (the loader's input). The migration wires every section loader, an approved difference (PO 2026-10-15): list it in the PR",
278
+ });
279
+ }
280
+ if (group === "actions") {
281
+ leave(
282
+ type,
283
+ "an action: block functions should only read; call it from a server function or route handler instead (/next/renames-and-migrations#loaders-actions-and-invoke)",
284
+ );
285
+ }
286
+ }
287
+
288
+ // Identifiers: the file's name, then its path, then a number.
289
+ const taken = new Set<string>();
290
+ const idents = new Set<string>([
291
+ "section",
292
+ "PropsOf",
293
+ "matchers",
294
+ "matcherContext",
295
+ "matcherInput",
296
+ "matchPage",
297
+ "pageUrls",
298
+ "getRequest",
299
+ "runSectionLoaders",
300
+ "loadSections",
301
+ "sectionLoaders",
302
+ "nonCriticalSections",
303
+ "views",
304
+ "SectionView",
305
+ "ComponentType",
306
+ "loaders",
307
+ ]);
308
+ const entries = [...byFile.values()];
309
+ for (const entry of entries) {
310
+ const type = entry.legacy[0];
311
+ const segments = type.split("/");
312
+ const prefix = segments[0] === "site" ? "" : `${segments[0]}-`;
313
+ const candidates = [
314
+ prefix + kebab(segments.at(-1)!),
315
+ prefix + kebab(segments.slice(2).join("-")),
316
+ ];
317
+ let base = candidates.find((c) => c && !taken.has(c));
318
+ for (let n = 2; !base; n++)
319
+ if (!taken.has(`${candidates[1]}-${n}`)) base = `${candidates[1]}-${n}`;
320
+ taken.add(base);
321
+ let ident = camel(base);
322
+ const free = (id: string) => !idents.has(id) && !(entry.loader && idents.has(`${id}Loader`));
323
+ for (let n = 2; !free(ident); n++) ident = `${camel(base)}${n}`;
324
+ idents.add(ident);
325
+ if (entry.loader) idents.add(`${ident}Loader`);
326
+ entry.ident = ident;
327
+ }
328
+
329
+ const version = siteBlocksVersion(root);
330
+ fs.writeFileSync(
331
+ path.join(root, ".deco", "index.ts"),
332
+ renderBlockMap(root, entries, { framework, matchers, wiring, version }),
333
+ );
334
+ const aliases = entries.reduce((n, e) => n + e.legacy.length, 0);
335
+ report.done.push({
336
+ step: "block map",
337
+ subject: ".deco/index.ts",
338
+ message: `${entries.length} blocks under their ${aliases} v7 names (no short names, so the site editor lists each once)${matchers.size > 0 ? `, and v7's ${[...new Set(matchers.values())].sort().join(", ")} matchers from @decocms/compat-v7/matchers` : ""}`,
339
+ });
340
+ const sections = entries.filter((e) => e.kind === "section");
341
+ if (sections.length > 0) writeViews(root, sections, report);
342
+ if (wiring.loaders || entries.some((e) => e.loader)) {
343
+ report.manual.push({
344
+ step: "block map",
345
+ subject: "loadSections (.deco/index.ts)",
346
+ message: `run the section loaders as v7 ran its registered ones: after the page resolved, call loadSections(sections, request, pageUrl) on every section of the page, the site's globals included, and render what it returns${framework === "tanstack" ? "; in the page's server function, pass the page's URL (the request is the server-function call on a client-side navigation)" : framework === "nextjs" ? "; on Next.js build the request from next/headers at the page's URL" : ""}. When degraded isn't empty, send X-Deco-Degraded: 1 and don't cache the page, as v7 did`,
347
+ });
348
+ }
349
+ if (matchers.size > 0) reportMatchers(framework!, report);
350
+ return { vendored };
351
+ }
352
+
353
+ /** What the site wires around v7's matchers, by binding. */
354
+ function reportMatchers(framework: Framework, report: Report): void {
355
+ const message =
356
+ framework === "tanstack"
357
+ ? "call matchPage(href) from .deco/index.ts in the page's server function before resolving the page"
358
+ : "forward the page's URL in proxy.ts with pageUrlRequestHeaders from @decocms/compat-v7/nextjs/proxy, so the matchers read the page";
359
+ report.manual.push({ step: "block map", subject: "v7 matchers (.deco/index.ts)", message });
360
+ }
361
+
362
+ /** `src/views.ts`: each section descriptor's component → the module that renders it. */
363
+ function writeViews(root: string, sections: Entry[], report: Report): void {
364
+ const existing = ["views.ts", "views.tsx"].find((f) => fs.existsSync(path.join(root, "src", f)));
365
+ if (existing) {
366
+ report.manual.push({
367
+ step: "block map",
368
+ subject: `src/${existing}`,
369
+ message:
370
+ "already exists, so it was kept: it must map each section's v7 type name (the descriptor's component) to its module",
371
+ });
372
+ return;
373
+ }
374
+ const from = (file: string) => {
375
+ const rel = posix(path.relative(path.join(root, "src"), file)).replace(/\.tsx?$/, "");
376
+ return rel.startsWith(".") ? rel : `./${rel}`;
377
+ };
378
+ const sorted = [...sections].sort((a, b) => (a.component < b.component ? -1 : 1));
379
+ const lines = [
380
+ "/**",
381
+ " * The view registry (/next/rendering): the section each descriptor's `component` names, by its",
382
+ " * v7 type name. Generated by the deco-v7-to-v8-migration skill with .deco/index.ts. It's your code now.",
383
+ " */",
384
+ 'import type { ComponentType } from "react";',
385
+ ...sorted.map((e) => `import * as ${e.ident} from "${from(e.file)}";`),
386
+ "",
387
+ "export interface SectionView {",
388
+ " default: ComponentType<any>;",
389
+ "}",
390
+ "",
391
+ "export const views: Record<string, SectionView> = {",
392
+ ...sorted.map((e) => ` ${JSON.stringify(e.component)}: ${e.ident},`),
393
+ "};",
394
+ "",
395
+ ];
396
+ fs.writeFileSync(path.join(root, "src", "views.ts"), lines.join("\n"));
397
+ report.done.push({
398
+ step: "block map",
399
+ subject: "src/views.ts",
400
+ message: `the view registry: ${sections.length} sections by their v7 type names; render each descriptor with views[component].default and its props (/next/rendering)`,
401
+ });
402
+ }
403
+
404
+ interface RenderOptions {
405
+ framework: Framework | undefined;
406
+ /** v7 name → matcher, from @decocms/compat-v7/matchers. */
407
+ matchers: Map<string, string>;
408
+ wiring: SectionLoaderWiring;
409
+ /** The site's 7.x version: the nested-section walk of its section loaders. */
410
+ version: string | undefined;
411
+ }
412
+
413
+ /** v7 walked nested sections for their loaders at any depth from 7.77.13, only directly before. */
414
+ function nestedWalk(version: string | undefined): "deep" | "direct" {
415
+ const [major, minor, patch] = (version ?? "").split(".").map(Number);
416
+ if (major !== 7 || Number.isNaN(minor)) return "deep";
417
+ return minor > 77 || (minor === 77 && patch >= 13) ? "deep" : "direct";
418
+ }
419
+
420
+ function renderBlockMap(root: string, entries: Entry[], options: RenderOptions): string {
421
+ const { framework, matchers, wiring, version } = options;
422
+ const lines = [
423
+ "// Generated by the deco-v7-to-v8-migration skill from a v7 site. It's your code now: edit it freely.",
424
+ "// Each block is registered under the v7 names saved content stores, and only those, so the site",
425
+ "// editor lists it once (see /next/renames-and-migrations).",
426
+ 'import type { Blocks } from "@decocms/blocks";',
427
+ ];
428
+ if (matchers.size > 0) {
429
+ if (framework === "tanstack")
430
+ lines.push('import { getRequest } from "@tanstack/react-start/server";');
431
+ lines.push('import * as matchers from "@decocms/compat-v7/matchers";');
432
+ lines.push(`import { matcherContext } from "@decocms/compat-v7/${framework}/server";`);
433
+ }
434
+ const fileSpecifier = (file: string) => importPath(root, file).replace(/\/index$/, "");
435
+ // The loaders v7 never ran (all of them when its map's names can't be read: the map wins).
436
+ const withLoader = entries.filter((e) => e.loader && !wiring.loaders?.keys?.has(e.component));
437
+ const runsLoaders = wiring.loaders !== undefined || withLoader.length > 0;
438
+ if (runsLoaders) {
439
+ lines.push(
440
+ 'import { type RunSectionLoadersOptions, runSectionLoaders } from "@decocms/compat-v7/sections";',
441
+ );
442
+ }
443
+ for (const e of withLoader) {
444
+ lines.push(`import { loader as ${e.ident}Loader } from "${importPath(root, e.file)}";`);
445
+ }
446
+ if (wiring.loaders) {
447
+ lines.push(`import { sectionLoaders } from "${fileSpecifier(wiring.loaders.file)}";`);
448
+ if (wiring.nonCritical) {
449
+ lines.push(
450
+ `import { nonCriticalSections } from "${fileSpecifier(wiring.nonCritical.file)}";`,
451
+ );
452
+ }
453
+ }
454
+ for (const e of entries.filter((e) => e.kind === "function")) {
455
+ lines.push(`import ${e.ident} from "${importPath(root, e.file)}";`);
456
+ }
457
+ lines.push(
458
+ "",
459
+ "/** What a section block returns: the component to render (its v7 type name) and its props (/next/rendering). */",
460
+ "export interface BlockDescriptor {",
461
+ " component: string;",
462
+ " /** JSON from content and loader results. Loose, so a page's loader data can carry it to the browser. */",
463
+ " // biome-ignore lint/suspicious/noExplicitAny: each view types its own props",
464
+ " props: Record<string, any>;",
465
+ "}",
466
+ "",
467
+ "/**",
468
+ " * v7's page SEO: the fields its SEO sections returned and the page's head shows (src/page-view.tsx on",
469
+ " * TanStack Start, generateMetadata on Next.js). Every field is optional; an SEO block returns this.",
470
+ " */",
471
+ "export interface PageSeo {",
472
+ " title?: string;",
473
+ " description?: string;",
474
+ " titleTemplate?: string;",
475
+ " descriptionTemplate?: string;",
476
+ " image?: string;",
477
+ " canonical?: string;",
478
+ " noIndexing?: boolean;",
479
+ " type?: string;",
480
+ " // biome-ignore lint/suspicious/noExplicitAny: JSON-LD objects",
481
+ " jsonLDs?: Record<string, any>[];",
482
+ "}",
483
+ "",
484
+ "/** A v7 section's saved props: its loader's input when it has one, else its component's props. */",
485
+ "type PropsOf<M> = M extends { loader: (props: infer P, ...rest: any[]) => unknown }",
486
+ " ? P",
487
+ " : M extends { default: (props: infer P, ...rest: any[]) => unknown }",
488
+ " ? P",
489
+ " : Record<string, never>;",
490
+ "",
491
+ "const section =",
492
+ " <M>(component: string) =>",
493
+ " (props: PropsOf<M>): BlockDescriptor => ({ component, props: props as Record<string, any> });",
494
+ "",
495
+ );
496
+ for (const e of entries.filter((e) => e.kind === "section")) {
497
+ lines.push(
498
+ `const ${e.ident} = section<typeof import("${importPath(root, e.file)}")>(${JSON.stringify(e.component)});`,
499
+ );
500
+ }
501
+ if (runsLoaders) {
502
+ const nested = nestedWalk(version);
503
+ lines.push(
504
+ ...(withLoader.length > 0
505
+ ? [
506
+ "",
507
+ "/** A section module's loader as the runner calls it: (props, request), never a v7 ctx. */",
508
+ "const own = (",
509
+ " loader: (props: any, req: Request, ...rest: any[]) => unknown,",
510
+ '): RunSectionLoadersOptions["loaders"][string] => loader;',
511
+ ]
512
+ : []),
513
+ "",
514
+ "/**",
515
+ " * The section loaders, by v7 type name. v7 ran only those its registerSectionLoaders map listed; the",
516
+ ` * migration also runs every other section's own loader (an approved difference, PO 2026-10-15)${wiring.loaders ? "," : "."}`,
517
+ ...(wiring.loaders
518
+ ? [" * and the site's sectionLoaders, v7's map, win where they list a section."]
519
+ : []),
520
+ " */",
521
+ 'const loaders: RunSectionLoadersOptions["loaders"] = {',
522
+ ...withLoader.map((e) => ` ${JSON.stringify(e.component)}: own(${e.ident}Loader),`),
523
+ ...(wiring.loaders ? [" ...sectionLoaders,"] : []),
524
+ "};",
525
+ "",
526
+ "/**",
527
+ " * The section loaders over a page's sections, as v7 ran its registered ones after the",
528
+ " * page resolved: run it once per page, on every section, globals included. `url` is the page's when the",
529
+ " * request isn't for the page (a server-function call on a client-side navigation).",
530
+ nested === "direct"
531
+ ? ` * Nested sections run theirs only directly in a prop, as v7 ${version} did (7.77.13 walks any depth).`
532
+ : " * Nested sections run theirs wherever they sit, as the latest 7.x does.",
533
+ " */",
534
+ "export function loadSections<S extends BlockDescriptor>(",
535
+ " sections: readonly S[],",
536
+ " request: Request,",
537
+ " url?: string | URL,",
538
+ ") {",
539
+ " return runSectionLoaders(sections, {",
540
+ " loaders,",
541
+ " request,",
542
+ " url,",
543
+ ...(wiring.nonCritical ? [" nonCritical: nonCriticalSections,"] : []),
544
+ ...(nested === "direct" ? [' nested: "direct",'] : []),
545
+ " });",
546
+ "}",
547
+ );
548
+ }
549
+ if (matchers.size > 0 && framework === "tanstack") {
550
+ lines.push(
551
+ "",
552
+ "/** The page each request opens, for v7's matchers (see matchPage). */",
553
+ "const pageUrls = new WeakMap<Request, string>();",
554
+ "",
555
+ "/**",
556
+ " * Tells v7's matchers which page this request opens: call it in the page's server function before",
557
+ " * resolving the page. On a client-side navigation the request is the server-function call, and v7",
558
+ " * matched the page being opened.",
559
+ " */",
560
+ "export function matchPage(url: string | URL, request: Request = getRequest()): void {",
561
+ " pageUrls.set(request, new URL(String(url), request.url).href);",
562
+ "}",
563
+ "",
564
+ "/** What v7's matchers read: the page's URL, the request's headers and its A/B decisions. */",
565
+ "const matcherInput = () => {",
566
+ " const request = getRequest();",
567
+ " return matcherContext(pageUrls.get(request), request);",
568
+ "};",
569
+ );
570
+ }
571
+ // No `page` of its own: the built-in page takes the descriptors as its sections.
572
+ lines.push("", "export default {");
573
+ for (const e of entries) {
574
+ for (const legacy of e.legacy) lines.push(` ${JSON.stringify(legacy)}: ${e.ident},`);
575
+ }
576
+ if (matchers.size > 0) {
577
+ lines.push(" // v7's matchers, with v7's results (@decocms/compat-v7/matchers)");
578
+ for (const [type, matcher] of [...matchers].sort(([a], [b]) => (a < b ? -1 : 1))) {
579
+ lines.push(` ${JSON.stringify(type)}: ${matcherEntry(matcher, framework!)},`);
580
+ }
581
+ }
582
+ lines.push("} satisfies Blocks;", "");
583
+ return lines.join("\n");
584
+ }
@@ -0,0 +1,32 @@
1
+ /**
2
+ * `bun scripts/checkContentReads.ts [--root <dir>]`: fails (exit 1) when the
3
+ * site's code still calls `client.list(…)`, which 8.12 removed (it throws
4
+ * at runtime, and still typechecks, so only this check finds it); prints
5
+ * every `.deco/blocks` scan too, without failing on it (see
6
+ * ./contentReads.ts). Run it from the skill's verify step, after the
7
+ * migration and before review.
8
+ */
9
+ import path from "node:path";
10
+ import { parseArgs } from "node:util";
11
+ import { findContentReads } from "./contentReads";
12
+
13
+ const { values } = parseArgs({
14
+ args: process.argv.slice(2),
15
+ options: { root: { type: "string", default: "." } },
16
+ });
17
+ const root = path.resolve(values.root!);
18
+ const reads = findContentReads(root);
19
+ for (const read of reads) {
20
+ const label =
21
+ read.kind === "list" ? "error: client.list() throws" : "warning: scans .deco/blocks";
22
+ console.log(`${read.file}:${read.line}: ${label}: ${read.code}`);
23
+ }
24
+ const lists = reads.filter((read) => read.kind === "list").length;
25
+ if (lists > 0) {
26
+ console.log(
27
+ `\n${lists} client.list() call(s): route with client.routes() and client.redirects(), read client.entries(type) (names, paths, noIndex from the index) or client.resolve(name) (one block) instead.`,
28
+ );
29
+ process.exitCode = 1;
30
+ } else {
31
+ console.log(reads.length === 0 ? "No content reads to change." : "No client.list() calls.");
32
+ }