@decocms/blocks 8.10.0 → 8.11.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.
- package/dist/v8/cli/index.d.ts +1 -0
- package/dist/v8/cli/index.d.ts.map +1 -1
- package/dist/v8/cli/index.js +1 -0
- package/dist/v8/cli/index.js.map +1 -1
- package/dist/v8/cli/run.d.ts +2 -0
- package/dist/v8/cli/run.d.ts.map +1 -1
- package/dist/v8/cli/run.js +30 -1
- package/dist/v8/cli/run.js.map +1 -1
- package/dist/v8/cli/skills.d.ts +25 -0
- package/dist/v8/cli/skills.d.ts.map +1 -0
- package/dist/v8/cli/skills.js +70 -0
- package/dist/v8/cli/skills.js.map +1 -0
- package/package.json +3 -2
- package/skills/deco-apps/SKILL.md +82 -0
- package/skills/deco-apps/references/algolia.md +51 -0
- package/skills/deco-apps/references/commerce-types.md +132 -0
- package/skills/deco-apps/references/instrumented-fetch.md +144 -0
- package/skills/deco-apps/references/magento.md +55 -0
- package/skills/deco-apps/references/messaging.md +76 -0
- package/skills/deco-apps/references/shopify.md +69 -0
- package/skills/deco-apps/references/vendored-loaders.md +135 -0
- package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
- package/skills/deco-apps/references/vtex.md +150 -0
- package/skills/deco-apps/references/wake.md +75 -0
- package/skills/deco-cms-schema/SKILL.md +80 -0
- package/skills/deco-cms-schema/references/annotations.md +147 -0
- package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
- package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
- package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
- package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
- package/skills/deco-go-live/SKILL.md +127 -0
- package/skills/deco-go-live/references/content-releases.md +90 -0
- package/skills/deco-go-live/references/process.md +106 -0
- package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
- package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
- package/skills/deco-go-live/references/qa-inventory.md +120 -0
- package/skills/deco-go-live/references/react-spa.md +183 -0
- package/skills/deco-go-live/references/seo-analytics.md +114 -0
- package/skills/deco-go-live/references/traffic-ramp.md +87 -0
- package/skills/deco-go-live/references/worker-runtime.md +93 -0
- package/skills/deco-go-live/scripts/preflight.sh +221 -0
- package/skills/deco-images-media/SKILL.md +64 -0
- package/skills/deco-images-media/references/asset-upload.md +191 -0
- package/skills/deco-images-media/references/components-per-binding.md +167 -0
- package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
- package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
- package/skills/deco-images-media/references/troubleshooting.md +147 -0
- package/skills/deco-images-media/references/video.md +122 -0
- package/skills/deco-make-editable/SKILL.md +94 -0
- package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
- package/skills/deco-make-editable/references/content-shapes.md +198 -0
- package/skills/deco-make-editable/references/from-figma.md +110 -0
- package/skills/deco-make-editable/references/i18n-fields.md +112 -0
- package/skills/deco-make-editable/references/inventory.md +79 -0
- package/skills/deco-make-editable/references/pixel-parity.md +175 -0
- package/skills/deco-make-editable/references/seeding-content.md +119 -0
- package/skills/deco-nextjs-site/SKILL.md +74 -0
- package/skills/deco-nextjs-site/references/caching.md +116 -0
- package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
- package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
- package/skills/deco-nextjs-site/references/rendering.md +171 -0
- package/skills/deco-nextjs-site/references/setup.md +190 -0
- package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
- package/skills/deco-site-authoring/SKILL.md +75 -0
- package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
- package/skills/deco-site-authoring/references/loaders.md +192 -0
- package/skills/deco-site-authoring/references/pages.md +156 -0
- package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
- package/skills/deco-site-authoring/references/sections.md +158 -0
- package/skills/deco-site-authoring/references/seo.md +116 -0
- package/skills/deco-site-workflow/SKILL.md +92 -0
- package/skills/deco-site-workflow/references/check.md +116 -0
- package/skills/deco-site-workflow/references/cli-reference.md +104 -0
- package/skills/deco-site-workflow/references/content-layout.md +93 -0
- package/skills/deco-site-workflow/references/content-sync.md +146 -0
- package/skills/deco-site-workflow/references/delivery.md +51 -0
- package/skills/deco-site-workflow/references/deploy.md +87 -0
- package/skills/deco-site-workflow/references/schema.md +173 -0
- package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
- package/skills/deco-storefront-caching/SKILL.md +67 -0
- package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
- package/skills/deco-storefront-caching/references/case-study.md +82 -0
- package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
- package/skills/deco-storefront-caching/references/nextjs.md +60 -0
- package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
- package/skills/deco-storefront-caching/references/verification.md +136 -0
- package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
- package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
- package/skills/deco-storefront-performance/SKILL.md +81 -0
- package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
- package/skills/deco-storefront-performance/references/hydration.md +116 -0
- package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
- package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
- package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
- package/skills/deco-storefront-performance/references/render-location.md +152 -0
- package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
- package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
- package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
- package/skills/deco-tanstack-site/SKILL.md +68 -0
- package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
- package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
- package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
- package/skills/deco-tanstack-site/references/server-functions.md +123 -0
- package/skills/deco-tanstack-site/references/setup.md +153 -0
- package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
- package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
- package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
- package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
- package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
- package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
- package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
- package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
- package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
- package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
- package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
- package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
- package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
- package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
- package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
- package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
- package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
- package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
- package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
- package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
- package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
- package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
- package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
- package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
- package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
- package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
- package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
- package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
- package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
- package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
- package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
- package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
- package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
- package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
- package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
- package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
- package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
- package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
- package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
- package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
- package/skills/deco-variants/SKILL.md +57 -0
- package/skills/deco-variants/references/caching-variants.md +63 -0
- package/skills/deco-variants/references/custom-matchers.md +83 -0
- package/skills/deco-variants/references/draft-preview.md +59 -0
- package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
- package/skills/deco-variants/references/multivariate.md +85 -0
- package/skills/deco-variants/references/v7-matchers.md +71 -0
- package/src/v8/cli/index.ts +1 -0
- package/src/v8/cli/run.ts +35 -1
- package/src/v8/cli/skills.ts +91 -0
|
@@ -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/v8/cli/index.ts
CHANGED
|
@@ -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
|
+
}
|