@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,85 @@
1
+ # The `multivariate` block
2
+
3
+ `multivariate` is a built-in block (`packages/blocks/src/v8/builtins/multivariate.ts`). Its `variants` is a list of `{ rule, value }`. The result is the value of the first variant whose rule resolves to `true`, or `undefined` when no rule does.
4
+
5
+ ## Shape
6
+
7
+ ```json
8
+ {
9
+ "__resolveType": "multivariate",
10
+ "variants": [
11
+ { "rule": { "__resolveType": "campaign", "name": "black-friday" },
12
+ "value": { "__resolveType": "lazy", "value": "Black Friday: up to 70% off" } },
13
+ { "rule": { "__resolveType": "always" },
14
+ "value": { "__resolveType": "lazy", "value": "Free shipping over $50" } }
15
+ ]
16
+ }
17
+ ```
18
+
19
+ - `rule` is any block whose function returns a boolean (or a promise of one). In Studio's schema the rule field points at the `matchers` group, which holds every block function `deco schema` sees returning a boolean.
20
+ - `value` is wrapped in a `lazy` block. The TypeScript type is `Variant<T> = { rule: boolean; value: Lazy<T> }`, exported from `@decocms/blocks`, with `Lazy<T> = () => Promise<T>`. The wrapper is what makes only the winning value resolve. A section, a loader or a fetch inside a losing variant never runs.
21
+ - The value can be anything a field can hold: a section, a string, a list, a loader call, another `multivariate`.
22
+ - A `multivariate` can sit anywhere a value can: as a page section, inside one field of a section (a single title), or as a saved block of its own.
23
+ - The optional `experiment` field (a string, "the stable ID of an A/B test" in the schema) is not read by the runtime. The rules decide.
24
+
25
+ `deco check` reports a value saved without the `lazy` wrapper: "a variant's value must be a lazy block". At runtime such a value is returned as is instead of failing the page, but it was resolved before the rules ran, so every variant's value did its work.
26
+
27
+ ## How it resolves
28
+
29
+ The resolver treats `multivariate` as a special case (`packages/blocks/src/v8/resolver.ts`, `#resolveFirstMatch`):
30
+
31
+ 1. The other fields resolve as usual.
32
+ 2. The variants resolve one at a time, in order. For each one, the rule resolves first.
33
+ 3. At the first rule that is `true`, it stops. Later variants are left out, so their rules never run.
34
+ 4. The function gets the variants up to the winner and calls the winner's lazy value.
35
+
36
+ What follows from that:
37
+
38
+ - **Order is the logic.** Narrow rules first, `always` last. A `never` rule is how the editor hides a variant.
39
+ - **No fallback, no value.** Without an `always` at the end, a visitor that matches nothing gets `undefined`. Sometimes that is the goal ("desktop only"), often it is a bug.
40
+ - **Later rules have no side effects.** A rule after the winner never runs. With v7's sticky `random`, that means no draw and no cookie for that test on this request, as in v7.
41
+ - **Rules run in sequence, not in parallel.** Each async rule waits for the one before it. A slow rule early in the list delays the whole slot. The built-in `experiment` and `campaign` read a saved block once per client, however many rules ask.
42
+ - **Results are memoized per request.** The resolver keeps one result per block function and inputs for the life of a client, so two identical rules on one page run once. Treat results as read-only.
43
+ - **A rule that throws fails the block** with `BLOCK_FAILED`. v7's matchers from `@decocms/compat-v7/matchers` catch their own errors and answer `false`, as v7 did. A site's own rule should do the same if a failure should mean "no match" (see [`custom-matchers.md`](./custom-matchers.md)).
44
+
45
+ ## Rules as saved blocks
46
+
47
+ A rule can be a saved block, reused by name. A saved block named `Hero test` with `{ "__resolveType": "experiment", "name": "hero" }` is used as:
48
+
49
+ ```json
50
+ { "rule": { "__resolveType": "Hero test" }, "value": { "__resolveType": "lazy", "value": "…" } }
51
+ ```
52
+
53
+ The resolver merges `{ ...saved, ...arguments }` and looks the type up again, so a reference can override the saved inputs. `deco check` follows the reference when it checks the `name` of an `experiment` or `campaign` rule.
54
+
55
+ ## Replacing the built-in
56
+
57
+ A key named `multivariate` in the site's block map replaces the built-in. It is then an ordinary block: every rule resolves before the function runs, and the first-match short-circuit is gone. Do not do this unless you need every rule's result.
58
+
59
+ ## Content from v7 and Fresh
60
+
61
+ The well-known legacy names resolve without a block-map entry (`packages/blocks/src/v8/builtins/legacy.ts`):
62
+
63
+ | Legacy type | Built-in |
64
+ |---|---|
65
+ | `website/flags/multivariate.ts` | `multivariate` |
66
+ | `website/flags/multivariate/section.ts` | `multivariate` |
67
+ | `website/matchers/always.ts` | `always` |
68
+ | `website/matchers/never.ts` | `never` |
69
+
70
+ Under a legacy name, values are saved plain, and the runtime wraps each in `lazy` on the way in, so only the winner runs there too.
71
+
72
+ The other per-kind flag types (`image`, `message`, `page`), `$live/flags/multivariate.ts`, `$live/matchers/MatchAlways.ts` and v7's date matcher have no alias. The one-time migration (the `deco-v7-to-v8-migration` skill) renames the flag and always types to the names above, and renames the date matcher to `date`, which `deco check` then reports with how to move it into `campaigns`. v7's other matchers are in [`v7-matchers.md`](./v7-matchers.md).
73
+
74
+ In v7 a "custom flag type" was a file per value type. v8 has no such files: `multivariate` is generic over its value, so there is nothing to write per type.
75
+
76
+ ## Symptoms
77
+
78
+ | Symptom | Likely cause |
79
+ |---|---|
80
+ | The slot is empty for some visitors | No `always` variant at the end |
81
+ | The second variant never shows | An `always` (or a rule that is always true) sits above it |
82
+ | Every variant's loader runs | Values saved without `lazy`; run `deco check` |
83
+ | `UNKNOWN_BLOCK` on a rule | A v7 matcher that is not registered (see [`v7-matchers.md`](./v7-matchers.md)), or a saved rule that was deleted |
84
+ | `deco check`: "no test … this rule is always false" | The test name is not in the saved block `experiments` (see [`experiments-and-campaigns.md`](./experiments-and-campaigns.md)) |
85
+ | Variant right on a fresh load, wrong from cache | A rule reads something the cache key does not hold (see [`caching-variants.md`](./caching-variants.md)) |
@@ -0,0 +1,71 @@
1
+ # v7's matchers on v8
2
+
3
+ `@decocms/compat-v7/matchers` has v7's website matchers with v7's results (`packages/compat-v7/src/matchers/`). They are not registered for you. A site that keeps content with v7 matcher types registers each one in its block map under v7's name. Without that, the rule fails with `UNKNOWN_BLOCK`.
4
+
5
+ Use them for content migrated from v7. For new A/B tests and dates, prefer the built-in `experiment` and `campaign` (see [`experiments-and-campaigns.md`](./experiments-and-campaigns.md)): they are decided at the edge and the page cache keys on them.
6
+
7
+ ## What is there
8
+
9
+ | Export | v7 type it stands for | Matches |
10
+ |---|---|---|
11
+ | `device` | `website/matchers/device.ts` | `mobile`, `tablet`, `desktop` ticks, from the user agent (tablet checked first). No tick matches everyone |
12
+ | `cookie` | `website/matchers/cookie.ts` | A cookie `name`, with `value` or any value |
13
+ | `host` | `website/matchers/host.ts` | The host (`includes`, `match`, or the older `host`) |
14
+ | `pathname` | `website/matchers/pathname.ts` | The page's path (`case`, `pattern`, `includes`, `excludes`) |
15
+ | `queryString` | `website/matchers/queryString.ts` | Query parameters, with `Exists`, `Equals`, `Greater`, `GreaterOrEquals`, `Lesser`, `LesserOrEquals`, `Includes` |
16
+ | `location` | `website/matchers/location.ts` | Country, region, city or coordinates, included or excluded. Reads the `cf-*` headers, then the Workers `request.cf`, then the `__cf_geo_*` cookies |
17
+ | `multi` | `website/matchers/multi.ts` | `op: "and"` or `"or"` over its `matchers`. No rules matches everyone |
18
+ | `random` | `website/matchers/random.ts` | v7's sticky random: a `traffic` share (0 to 1, default 0.5) keyed on a `cohort` |
19
+ | `environment` | `website/matchers/environment.ts` | Always throws: it read the process environment, which no v8 package does. Register your own rule under that name |
20
+
21
+ `always` and `never` are v8 built-ins, and v7's names for them are aliases (see [`multivariate.md`](./multivariate.md)). v7's date matcher became the `campaign` rule and the saved block `campaigns`.
22
+
23
+ Not in v8 at all: v7's `cron`, `userAgent`, `site` and `negate` matchers. Write a custom rule if you need one (see [`custom-matchers.md`](./custom-matchers.md)).
24
+
25
+ Every matcher except `multi` and `environment` takes the request as a second argument, because a v8 block function gets only its inputs. A matcher that throws counts as not matched, as in v7. `multi` gets its inner rules' results, since v8 resolves them before it runs.
26
+
27
+ ## Wiring on TanStack Start
28
+
29
+ ```ts
30
+ // the block map
31
+ import type { Blocks } from "@decocms/blocks";
32
+ import { device, type DeviceProps, random, type RandomProps } from "@decocms/compat-v7/matchers";
33
+ import { matcherContext } from "@decocms/compat-v7/tanstack/server";
34
+
35
+ export default {
36
+ "website/matchers/device.ts": (props: DeviceProps) => device(props, matcherContext()),
37
+ "website/matchers/random.ts": (props: RandomProps) => random(props, matcherContext()),
38
+ } satisfies Blocks;
39
+ ```
40
+
41
+ - `matcherContext(pageUrl?)` gives the matcher the request being served (TanStack Start's `getRequest()`), the page's URL and one `flags` array per request.
42
+ - On a client-side navigation the request is the server-function call, not the page. Pass the page's URL there: `matcherContext(new URL(href, request.url))`. Without it, the call throws instead of matching `/_serverFn/…`.
43
+ - After the page resolved, in the page's server function, call `commitSegmentCookie()` to set `deco_segment` with the decisions `random` made. It sets nothing when the cookie already says the same.
44
+ - `cohortSegment(request)` gives v7's A/B split of the cache key (`{ abf: <token> }` for a visitor in a test, `{}` otherwise). Spread it into the segment of the site's page cache.
45
+
46
+ ## Wiring on Next.js
47
+
48
+ ```ts
49
+ // the block map
50
+ import { matcherContext } from "@decocms/compat-v7/nextjs/server";
51
+ "website/matchers/random.ts": async (props: RandomProps) => random(props, await matcherContext()),
52
+ ```
53
+
54
+ - The matchers need the page's URL. Forward it from the proxy with `pageUrlRequestHeaders` from `@decocms/compat-v7/nextjs/proxy`, or pass it to `matcherContext(url)`.
55
+ - Render `<SegmentCookie />` from `@decocms/compat-v7/nextjs/server` as the last child of the page, after the content resolved. A server component cannot set a cookie, so it renders a one-line script (and an effect after a client-side navigation) that sets it.
56
+ - A page that reads the request is dynamic: Next never shares it between visitors. Keep a CDN in front from caching it too.
57
+
58
+ ## The sticky `random`
59
+
60
+ - A visitor keeps their group through `deco_segment` until the traffic share changes, then is drawn again once. The draw is `Math.random()`, as in v7.
61
+ - The cookie is keyed on the **cohort**: in v7, the name of the saved matcher block. A v8 block does not know its own name, so the name travels in the `cohort` prop. Set it to the v7 saved block's name. The migration script does not register `random` or fill `cohort`: it reports each random test to move into `experiments`. A random rule written inline uses `website/matchers/random.ts` as its cohort, as v7 did.
62
+ - Keep the cohort when changing the share. Renaming it puts every visitor in a new test.
63
+ - `decideRandom(props, request)` returns `{ value, isFresh, setCookie }` when you need the decision and the cookie together.
64
+ - A response that sets `deco_segment` must not be cached for other visitors.
65
+ - Inside `multi`, a `random` is sticky too. v7 drew it again on every request.
66
+
67
+ The better path for a v7 random test is to move it into the saved block `experiments` under the same name, so visitors keep their groups and the binding owns the cookie. Do not run both on one site.
68
+
69
+ ## The legacy-origin split
70
+
71
+ v7's `withABTesting` (a split of traffic between the new site and the site it replaces, driven by a KV entry) is `abTestingRoutes` from `@decocms/compat-v7/tanstack/worker`, a handler for `createDecoWorker`'s `routes`. It is a traffic split between two deployments, not a content variant. `packages/compat-v7/README.md` documents it.
package/src/index.ts CHANGED
@@ -16,9 +16,9 @@ export {
16
16
  currentClient,
17
17
  type DraftPointer,
18
18
  type EffectiveSettings,
19
+ type Entry,
19
20
  formatDraftPointer,
20
21
  type Lazy,
21
- type ListOptions,
22
22
  type Loader,
23
23
  type Match,
24
24
  matchRoute,
@@ -5,7 +5,10 @@
5
5
  "footer",
6
6
  "footer-a",
7
7
  "header",
8
+ "hidden-seo",
8
9
  "home",
10
+ "noindex-inline",
11
+ "noindex-saved",
9
12
  "plain",
10
13
  "redirects",
11
14
  "variants"
@@ -209,6 +212,83 @@
209
212
  }
210
213
  }
211
214
  }
215
+ },
216
+ {
217
+ "name": "hidden-seo",
218
+ "body": {
219
+ "__resolveType": "website/sections/Seo/SeoV2.tsx",
220
+ "title": "Staging",
221
+ "noIndexing": true
222
+ },
223
+ "version": "TweCqXol6NaqfznIdZHWGA",
224
+ "meta": {
225
+ "type": "website/sections/Seo/SeoV2.tsx"
226
+ },
227
+ "entry": {
228
+ "version": "TweCqXol6NaqfznIdZHWGA",
229
+ "meta": {
230
+ "type": "website/sections/Seo/SeoV2.tsx"
231
+ }
232
+ }
233
+ },
234
+ {
235
+ "name": "noindex-inline",
236
+ "body": {
237
+ "__resolveType": "website/pages/Page.tsx",
238
+ "path": "/staging",
239
+ "seo": {
240
+ "__resolveType": "website/sections/Seo/SeoV2.tsx",
241
+ "noIndexing": true
242
+ },
243
+ "sections": [
244
+ {
245
+ "__resolveType": "header"
246
+ }
247
+ ]
248
+ },
249
+ "version": "9dPY85a3_dAGqgn9HyBymg",
250
+ "meta": {
251
+ "type": "website/pages/Page.tsx",
252
+ "path": "/staging",
253
+ "refs": ["header"],
254
+ "noIndex": true
255
+ },
256
+ "entry": {
257
+ "version": "9dPY85a3_dAGqgn9HyBymg",
258
+ "meta": {
259
+ "type": "website/pages/Page.tsx",
260
+ "path": "/staging",
261
+ "refs": ["header"],
262
+ "noIndex": true
263
+ }
264
+ }
265
+ },
266
+ {
267
+ "name": "noindex-saved",
268
+ "body": {
269
+ "__resolveType": "page",
270
+ "path": "/landing",
271
+ "seo": {
272
+ "__resolveType": "hidden-seo"
273
+ },
274
+ "sections": []
275
+ },
276
+ "version": "sOB07_jkmJqe7Mr5Raj6rg",
277
+ "meta": {
278
+ "type": "page",
279
+ "path": "/landing",
280
+ "refs": ["hidden-seo"],
281
+ "noIndex": true
282
+ },
283
+ "entry": {
284
+ "version": "sOB07_jkmJqe7Mr5Raj6rg",
285
+ "meta": {
286
+ "type": "page",
287
+ "path": "/landing",
288
+ "refs": ["hidden-seo"],
289
+ "noIndex": true
290
+ }
291
+ }
212
292
  }
213
293
  ]
214
294
  }
@@ -19,7 +19,10 @@
19
19
  * the page's bootstrap is `StudioChannel` in `@decocms/blocks/preview`.
20
20
  *
21
21
  * `blockMeta`/`indexEntry` compute a hosted revision index's entries (the
22
- * SDK's own browser-safe module, shared with Studio and the CLI).
22
+ * SDK's own browser-safe module, shared with Studio and the CLI);
23
+ * `META_VERSION` is the `metaVersion` an index they computed carries, and
24
+ * `seoNoIndex`/`pageNoIndex` are the `noIndex` rule, a page's saved SEO block
25
+ * resolved through `bodyOf`.
23
26
  *
24
27
  * The SDK's runtime never imports the protocol, so it never reaches an app
25
28
  * bundle. The canonical hash it re-exports is the SDK's own dependency-free
@@ -30,9 +33,13 @@
30
33
  export {
31
34
  type BlockIndex,
32
35
  type BlockMeta,
36
+ type BodyOf,
33
37
  blockMeta,
34
38
  type IndexEntry,
35
39
  indexEntry,
40
+ META_VERSION,
41
+ pageNoIndex,
42
+ seoNoIndex,
36
43
  } from "../v8/blockMeta.ts";
37
44
  export { isRevisionId, REVISION_ID_RE } from "../v8/revisionId.ts";
38
45
  export {
@@ -1,13 +1,13 @@
1
1
  /**
2
2
  * Index entries of a hosted release (see /next/hosted-releases-internals):
3
3
  * `revisions/<id>/index.json` and `latest.json` map each block name to its
4
- * hash (`version`) plus the little metadata routing and the reference walk
5
- * need, so neither needs a block body.
4
+ * hash (`version`) plus the little metadata routing, the reference walk and
5
+ * `client.entries()` need, so none of them needs a block body.
6
6
  *
7
- * `blockMeta(body, names)` is the one helper Studio, the SDK and the CLI use
8
- * to compute that metadata, so all three write and read the same entries.
9
- * Pure, synchronous, browser-safe; its only import is the dependency-free
10
- * canonical hash (for `indexEntry`).
7
+ * `blockMeta(body, names, bodyOf?)` is the one helper Studio, the SDK and the
8
+ * CLI use to compute that metadata, so all three write and read the same
9
+ * entries. Pure, synchronous, browser-safe; its only import is the
10
+ * dependency-free canonical hash (for `indexEntry`).
11
11
  *
12
12
  * - `type`: the body's raw top-level `__resolveType`, copied without alias
13
13
  * mapping (readers map it with their alias rules).
@@ -15,12 +15,32 @@
15
15
  * - `refs`: every `__resolveType` string anywhere in the body (the top-level
16
16
  * one included, every variant, `never` and `lazy` values included) that is
17
17
  * one of `names`, deduped and sorted in code-unit order.
18
+ * - `noIndex`: `true` when the body is a page that asks search engines not to
19
+ * index it: it has a top-level string `path` and its top-level `seo` says
20
+ * `noIndexing: true`, inline or through the saved SEO block it references
21
+ * (`{ "__resolveType": "DefaultSeo" }`), which `bodyOf` looks up (see
22
+ * `seoNoIndex`). Written only when `true`.
18
23
  *
19
- * A key is present only when it has a value (`refs: []` is left out), so a
20
- * body with nothing to say gives `{}` and its entry carries no `meta`.
24
+ * A key is present only when it has a value (`refs: []` and `noIndex: false`
25
+ * are left out), so a body with nothing to say gives `{}` and its entry
26
+ * carries no `meta`.
27
+ *
28
+ * `META_VERSION` is the version of this metadata. An index says which version
29
+ * computed its entries (its top-level `metaVersion`; absent is 1). A reader
30
+ * trusts a missing `noIndex` as `false` only on an index at version 2 or
31
+ * later, and a publish that finds an older index recomputes every entry.
21
32
  */
22
33
  import { blockVersion } from "./canonical.ts";
23
34
 
35
+ /**
36
+ * The version of the metadata `blockMeta` computes: 1 is `type`, `path` and
37
+ * `refs`; 2 adds `noIndex`. An index without `metaVersion` is version 1.
38
+ */
39
+ export const META_VERSION = 2;
40
+
41
+ /** A saved block's body by name, to follow a reference (`undefined`: not known). */
42
+ export type BodyOf = (name: string) => unknown;
43
+
24
44
  /** What an index says about a block, besides its hash. */
25
45
  export interface BlockMeta {
26
46
  /** The body's raw `__resolveType`. */
@@ -29,6 +49,8 @@ export interface BlockMeta {
29
49
  path?: string;
30
50
  /** The block names the body references, deduped, in code-unit order. */
31
51
  refs?: string[];
52
+ /** `true` when the page says `noIndexing` (meta version 2); never written `false`. */
53
+ noIndex?: boolean;
32
54
  }
33
55
 
34
56
  /** One entry of a revision index. */
@@ -47,10 +69,18 @@ export type BlockIndex = Record<string, IndexEntry>;
47
69
  /** The well-known name whose body every index inlines as `data`. */
48
70
  export const INLINE_BLOCK = "CMS";
49
71
 
50
- /** The metadata of one block body; `names` are the block names of the index being built. */
72
+ /** How many saved blocks `seoNoIndex` follows, one referencing the next. */
73
+ const MAX_SEO_HOPS = 8;
74
+
75
+ /**
76
+ * The metadata of one block body. `names` are the block names of the index
77
+ * being built; `bodyOf` gives the bodies of the saved blocks a page's `seo`
78
+ * may reference (without it, only an inline `seo` counts for `noIndex`).
79
+ */
51
80
  export function blockMeta(
52
81
  body: unknown,
53
82
  names: ReadonlySet<string> | readonly string[],
83
+ bodyOf?: BodyOf,
54
84
  ): BlockMeta {
55
85
  const meta: BlockMeta = {};
56
86
  if (!isRecord(body)) return meta;
@@ -60,17 +90,51 @@ export function blockMeta(
60
90
  const found = new Set<string>();
61
91
  collectRefs(body, known, found);
62
92
  if (found.size > 0) meta.refs = [...found].sort();
93
+ if (pageNoIndex(body, bodyOf)) meta.noIndex = true;
63
94
  return meta;
64
95
  }
65
96
 
66
- /** The index entry for a block: its hash, its metadata when any, and its body when it is `CMS`. */
97
+ /**
98
+ * Whether a page body asks not to be indexed: it has a top-level string
99
+ * `path`, and `seoNoIndex(body.seo, bodyOf)`.
100
+ */
101
+ export function pageNoIndex(body: unknown, bodyOf?: BodyOf): boolean {
102
+ return isRecord(body) && typeof body.path === "string" && seoNoIndex(body.seo, bodyOf);
103
+ }
104
+
105
+ /**
106
+ * Whether a page's `seo` value says `noIndexing: true`: its own boolean
107
+ * `noIndexing` when it has one; otherwise, when its `__resolveType` is a saved
108
+ * block `bodyOf` knows (a saved SEO block such as `DefaultSeo`), that block's
109
+ * answer, following up to 8 saved blocks. Anything else (no `seo`, a variant,
110
+ * a block `bodyOf` doesn't know, a cycle) is `false`.
111
+ */
112
+ export function seoNoIndex(seo: unknown, bodyOf?: BodyOf): boolean {
113
+ let node = seo;
114
+ const seen = new Set<string>();
115
+ for (let hop = 0; hop <= MAX_SEO_HOPS; hop++) {
116
+ if (!isRecord(node)) return false;
117
+ if (typeof node.noIndexing === "boolean") return node.noIndexing;
118
+ const ref = node.__resolveType;
119
+ if (bodyOf === undefined || typeof ref !== "string" || seen.has(ref)) return false;
120
+ seen.add(ref);
121
+ node = bodyOf(ref);
122
+ }
123
+ return false;
124
+ }
125
+
126
+ /**
127
+ * The index entry for a block: its hash, its metadata when any, and its body
128
+ * when it is `CMS`. `bodyOf` as for `blockMeta`.
129
+ */
67
130
  export async function indexEntry(
68
131
  name: string,
69
132
  body: unknown,
70
133
  names: ReadonlySet<string> | readonly string[],
134
+ bodyOf?: BodyOf,
71
135
  ): Promise<IndexEntry> {
72
136
  const entry: IndexEntry = { version: await blockVersion(body) };
73
- const meta = blockMeta(body, names);
137
+ const meta = blockMeta(body, names, bodyOf);
74
138
  if (Object.keys(meta).length > 0) entry.meta = meta;
75
139
  if (name === INLINE_BLOCK) entry.data = body;
76
140
  return entry;
@@ -15,3 +15,4 @@ export { type ContentOptions, content, readSavedBlocks, type SavedBlocks } from
15
15
  export { type Reporter, silentReporter } from "./log.ts";
16
16
  export { runCli } from "./run.ts";
17
17
  export { type SchemaOptions, schema } from "./schema/index.ts";
18
+ export { type InstalledSkills, type InstallSkillsOptions, installSkills } from "./skills.ts";
package/src/v8/cli/run.ts CHANGED
@@ -5,6 +5,7 @@
5
5
  * usage. Every command takes `--json`: stdout then carries exactly one JSON
6
6
  * object, and what a person reads goes to stderr.
7
7
  */
8
+ import path from "node:path";
8
9
  import { readSchemaFile, reportCheck } from "./check/index.ts";
9
10
  import { content, readSavedBlocks, savedBlocksFromMap, writeContent } from "./content.ts";
10
11
  import { consoleReporter, type Reporter, withColor } from "./log.ts";
@@ -24,8 +25,9 @@ import {
24
25
  import type { CommandRunner, Env } from "./remote/env.ts";
25
26
  import type { Fetch } from "./remote/http.ts";
26
27
  import { checkDraftName, findSite, requireDraftName } from "./remote/local.ts";
27
- import { CliError, decoPaths, EXIT, findDecoRoot, usageError } from "./root.ts";
28
+ import { CliError, decoPaths, EXIT, findDecoRoot, packageVersion, usageError } from "./root.ts";
28
29
  import { reportSchema, schema, writeSchema } from "./schema/index.ts";
30
+ import { installSkills } from "./skills.ts";
29
31
  import { watchFiles, watchTree } from "./watch.ts";
30
32
 
31
33
  type FlagKind = "string" | "boolean";
@@ -73,6 +75,11 @@ const COMMANDS: Record<string, CommandSpec> = {
73
75
  flags: { watch: "boolean", check: "boolean" },
74
76
  positionals: 1,
75
77
  },
78
+ skills: {
79
+ usage: "deco skills install [--dir=<path>]",
80
+ flags: { dir: "string" },
81
+ positionals: 1,
82
+ },
76
83
  };
77
84
 
78
85
  /** Flags every command takes. */
@@ -96,6 +103,9 @@ Commands:
96
103
  schema turn the types in .deco/index.ts into .deco/schema.gen.json
97
104
  (--check: write nothing, fail when the file is out of date; for CI)
98
105
  schema push: upload it so Studio can draw forms (CI, on production deploys)
106
+ skills skills install: copy the agent skills of this @decocms/blocks into the site,
107
+ one folder per skill in .claude/skills (or --dir, relative to the folder that
108
+ contains .deco/); replaces those folders, leaves other skills alone; offline
99
109
 
100
110
  ${Object.values(COMMANDS)
101
111
  .map((c) => ` ${c.usage}`)
@@ -167,6 +177,8 @@ export interface RunOptions {
167
177
  runCommand?: CommandRunner;
168
178
  /** Where `--json` writes its object; defaults to stdout. */
169
179
  stdout?: (text: string) => void;
180
+ /** The skills `deco skills install` copies; defaults to the package's `skills/` (tests replace it). */
181
+ skillsDir?: string;
170
182
  }
171
183
 
172
184
  function stopSignal(): Promise<void> {
@@ -426,6 +438,28 @@ async function runCommand(
426
438
  await running;
427
439
  return { exitCode: EXIT.ok, result: {} };
428
440
  }
441
+ case "skills": {
442
+ if (positionals[0] !== "install") {
443
+ throw usageError(
444
+ positionals.length === 0
445
+ ? `deco skills needs a subcommand\n${COMMANDS.skills!.usage}`
446
+ : `unexpected argument "${positionals[0]}"\n${COMMANDS.skills!.usage}`,
447
+ );
448
+ }
449
+ const dir = stringFlag(flags, "dir") ?? undefined;
450
+ const paths = decoPaths(findDecoRoot(base));
451
+ const installed = installSkills({ root: paths.root, dir, from: options.skillsDir });
452
+ const shown = path.relative(paths.root, installed.dir) || ".";
453
+ const where = shown.startsWith("..") || path.isAbsolute(shown) ? installed.dir : shown;
454
+ for (const name of installed.skills) reporter.info(`installed ${path.join(where, name)}/`);
455
+ reporter.info(
456
+ `${installed.skills.length} skill(s) from @decocms/blocks ${packageVersion()} in ${where}`,
457
+ );
458
+ return {
459
+ exitCode: EXIT.ok,
460
+ result: { dir: installed.dir, version: packageVersion(), skills: installed.skills },
461
+ };
462
+ }
429
463
  }
430
464
  throw usageError(`unknown command "${command}"`);
431
465
  }
@@ -0,0 +1,91 @@
1
+ /**
2
+ * `deco skills install`: copies the agent skills this package ships (its
3
+ * `skills/` folder, which scripts/pack-skills.mjs fills from the repo's
4
+ * `.agents/skills` at build) into a site, so coding agents load the skills of
5
+ * the installed version. No network.
6
+ */
7
+ import fs from "node:fs";
8
+ import path from "node:path";
9
+ import { fileURLToPath } from "node:url";
10
+ import { CliError } from "./root.ts";
11
+
12
+ /** Where skills go when `--dir` isn't given, relative to the site's root. */
13
+ export const DEFAULT_SKILLS_DIR = ".claude/skills";
14
+
15
+ /** The package's `skills/` folder: dist/v8/cli (or src/v8/cli) → ../../../skills. */
16
+ export function shippedSkillsDir(): string {
17
+ return fileURLToPath(new URL("../../../skills/", import.meta.url));
18
+ }
19
+
20
+ export interface InstallSkillsOptions {
21
+ /** The site's root (the folder that contains `.deco/`). */
22
+ root: string;
23
+ /** Where to install, relative to `root` or absolute. Default `.claude/skills`. */
24
+ dir?: string;
25
+ /** Where the shipped skills are. Default: the package's `skills/` folder. */
26
+ from?: string;
27
+ }
28
+
29
+ export interface InstalledSkills {
30
+ /** The folder the skills went into, absolute. */
31
+ dir: string;
32
+ /** The skills installed, by name, sorted. */
33
+ skills: string[];
34
+ }
35
+
36
+ /** The skills in a folder: its subfolders with a SKILL.md, sorted. */
37
+ function listSkills(from: string): string[] {
38
+ let entries: fs.Dirent[];
39
+ try {
40
+ entries = fs.readdirSync(from, { withFileTypes: true });
41
+ } catch {
42
+ return [];
43
+ }
44
+ return entries
45
+ .filter(
46
+ (entry) => entry.isDirectory() && fs.existsSync(path.join(from, entry.name, "SKILL.md")),
47
+ )
48
+ .map((entry) => entry.name)
49
+ .sort();
50
+ }
51
+
52
+ /** A path with its symlinks resolved; the path itself when it doesn't exist yet. */
53
+ function realPath(p: string): string {
54
+ try {
55
+ return fs.realpathSync(p);
56
+ } catch {
57
+ return path.resolve(p);
58
+ }
59
+ }
60
+
61
+ /**
62
+ * Copy every shipped skill into `<root>/<dir>/<skill>/`. A skill's folder is
63
+ * replaced as a whole, so a file an older version shipped doesn't linger;
64
+ * any other folder in `dir` (a skill this package doesn't ship) is left alone.
65
+ */
66
+ export function installSkills(options: InstallSkillsOptions): InstalledSkills {
67
+ const from = options.from ?? shippedSkillsDir();
68
+ const skills = listSkills(from);
69
+ if (skills.length === 0) {
70
+ throw new CliError(
71
+ `no skills in ${from}; this @decocms/blocks was built without them (in a checkout, run bun run build)`,
72
+ );
73
+ }
74
+ const dir = path.resolve(options.root, options.dir ?? DEFAULT_SKILLS_DIR);
75
+ // Replacing a skill deletes its folder first: never when that folder is (or,
76
+ // through a symlink, leads to) the copy the package ships.
77
+ if (realPath(dir) === realPath(from)) {
78
+ throw new CliError(`${dir} is where @decocms/blocks keeps its skills; pass another --dir`);
79
+ }
80
+ try {
81
+ fs.mkdirSync(dir, { recursive: true });
82
+ for (const name of skills) {
83
+ const target = path.join(dir, name);
84
+ fs.rmSync(target, { recursive: true, force: true });
85
+ fs.cpSync(path.join(from, name), target, { recursive: true });
86
+ }
87
+ } catch (error) {
88
+ throw new CliError(`can't install the skills into ${dir}: ${(error as Error).message}`);
89
+ }
90
+ return { dir, skills };
91
+ }