@decocms/blocks 8.11.0 → 8.13.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 (67) 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/check/index.d.ts.map +1 -1
  14. package/dist/v8/cli/check/index.js +138 -10
  15. package/dist/v8/cli/check/index.js.map +1 -1
  16. package/dist/v8/client.d.ts +6 -4
  17. package/dist/v8/client.d.ts.map +1 -1
  18. package/dist/v8/client.js +26 -70
  19. package/dist/v8/client.js.map +1 -1
  20. package/dist/v8/cms.d.ts.map +1 -1
  21. package/dist/v8/cms.js +1 -2
  22. package/dist/v8/cms.js.map +1 -1
  23. package/dist/v8/contentIndex.d.ts +18 -7
  24. package/dist/v8/contentIndex.d.ts.map +1 -1
  25. package/dist/v8/contentIndex.js +46 -17
  26. package/dist/v8/contentIndex.js.map +1 -1
  27. package/dist/v8/draftChanges.d.ts.map +1 -1
  28. package/dist/v8/draftChanges.js +4 -1
  29. package/dist/v8/draftChanges.js.map +1 -1
  30. package/dist/v8/index.d.ts +1 -1
  31. package/dist/v8/index.d.ts.map +1 -1
  32. package/dist/v8/remoteLoader.d.ts +4 -2
  33. package/dist/v8/remoteLoader.d.ts.map +1 -1
  34. package/dist/v8/remoteLoader.js +13 -3
  35. package/dist/v8/remoteLoader.js.map +1 -1
  36. package/dist/v8/types.d.ts +47 -7
  37. package/dist/v8/types.d.ts.map +1 -1
  38. package/package.json +1 -1
  39. package/skills/deco-make-editable/SKILL.md +1 -1
  40. package/skills/deco-make-editable/references/content-shapes.md +14 -9
  41. package/skills/deco-nextjs-site/references/rendering.md +6 -5
  42. package/skills/deco-site-authoring/references/pages.md +6 -4
  43. package/skills/deco-site-workflow/SKILL.md +12 -3
  44. package/skills/deco-site-workflow/references/cli-reference.md +2 -0
  45. package/skills/deco-site-workflow/references/content-layout.md +26 -2
  46. package/skills/deco-storefront-performance/references/request-dedupe.md +5 -3
  47. package/skills/deco-v7-to-v8-migration/SKILL.md +2 -1
  48. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +1 -1
  49. package/skills/deco-v7-to-v8-migration/references/nextjs.md +2 -2
  50. package/skills/deco-v7-to-v8-migration/references/verify.md +3 -0
  51. package/skills/deco-v7-to-v8-migration/scripts/checkContentReads.ts +32 -0
  52. package/skills/deco-v7-to-v8-migration/scripts/contentReads.ts +157 -0
  53. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +1 -1
  54. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +4 -0
  55. package/skills/deco-variants/references/multivariate.md +1 -1
  56. package/src/index.ts +1 -1
  57. package/src/protocol/conformance/blockMetaVectors.json +80 -0
  58. package/src/protocol/index.ts +8 -1
  59. package/src/v8/blockMeta.ts +75 -11
  60. package/src/v8/cli/check/index.ts +153 -10
  61. package/src/v8/client.ts +32 -77
  62. package/src/v8/cms.ts +1 -2
  63. package/src/v8/contentIndex.ts +49 -19
  64. package/src/v8/draftChanges.ts +5 -1
  65. package/src/v8/index.ts +1 -1
  66. package/src/v8/remoteLoader.ts +13 -3
  67. package/src/v8/types.ts +48 -7
@@ -67,9 +67,18 @@ takes `--json`.
67
67
 
68
68
  ## Get these skills into a site
69
69
 
70
- These skills live in the `decocms/blocks` repository, under `.agents/skills/` on `main`. The
71
- `@decocms/blocks` package doesn't ship them and the `deco` CLI has no command that installs them.
72
- Copy or link the folders you need into the site's `.claude/skills`.
70
+ From 8.11.0, `@decocms/blocks` ships the skills of `.agents/skills/` and the CLI copies them into the
71
+ site, offline:
72
+
73
+ ```bash
74
+ npx deco skills install # into .claude/skills/<skill>/
75
+ npx deco skills install --dir=.agents/skills # elsewhere; relative to the folder that contains .deco/
76
+ ```
77
+
78
+ It finds `.deco/` like every command (walk up, or `--root`; none found exits 1) and takes `--json`
79
+ (`{ ok, dir, version, skills }`). Each shipped skill's folder is deleted and copied again, so files
80
+ from an older version go away; folders of skills it doesn't ship are left alone. Run it again after
81
+ upgrading `@decocms/blocks`. On 8.10 or older, copy the folders from `.agents/skills/` on `main`.
73
82
 
74
83
  ## Related skills
75
84
 
@@ -19,6 +19,7 @@ The same commands are importable from `@decocms/blocks/cli` (`runCli`, `schema`,
19
19
  | `deco content` | `--watch` | `.deco/blocks` into `.deco/blocks.gen.ts`, for content without a site |
20
20
  | `deco schema` | `--watch` \| `--check` | `.deco/index.ts` into `.deco/schema.gen.json` |
21
21
  | `deco schema push` | | Uploads `.deco/schema.gen.json` to Studio |
22
+ | `deco skills install` | `--dir=<path>` | 8.11.0+. Copies the agent skills this `@decocms/blocks` ships into `.claude/skills/<skill>/` (or `--dir`, relative to the folder that contains `.deco/`). Replaces each shipped skill's folder whole, leaves other folders alone, no network. No `.deco/`: exit 1 |
22
23
  | `deco help`, `--help`, `-h` | | Usage (exit 0). No command at all prints usage and exits 64 |
23
24
 
24
25
  Details: [content-sync.md](./content-sync.md) (pull, diff, push, drafts, publish, releases),
@@ -88,6 +89,7 @@ Per command, the result carries:
88
89
  | `releases` | `live`, `revisions: [{ id, status, meta }]` (`status`: `current`, `listed`, `unreadable`), `nextCursor` |
89
90
  | `check` | `blocks`, `errors`, `warnings`, `problems` |
90
91
  | `schema push` | `etag`, `blocksMajor` |
92
+ | `skills install` | `dir` (absolute), `version`, `skills` (names, sorted) |
91
93
  | `login` | `command` |
92
94
 
93
95
  ## Common errors before any command runs
@@ -59,12 +59,36 @@ Every block is an object with `__resolveType`. The rest are its props.
59
59
  `redirect`, `redirects`, `cms-settings`, `split-traffic`, `calendar`;
60
60
  - **a legacy alias**: a v7 type name the runtime maps to a v8 one (see `deco-v7-to-v8-migration`);
61
61
  - **a saved block's name**: a **reference**. `{ "__resolveType": "Header" }` uses the saved block
62
- `Header`. Other keys next to it override the saved props for this use only. This is how a header or
63
- footer is shared by every page: change the saved block once.
62
+ `Header`. This is how a header or footer is shared by every page: change the saved block once.
64
63
 
65
64
  `deco check` reports a `__resolveType` that is none of these as `no saved block or block type "<name>"`.
66
65
  This is usually a deleted block that something still references.
67
66
 
67
+ ### References Studio can edit
68
+
69
+ The runtime resolves more shapes than Studio's editor can open. `deco check` rejects these as errors,
70
+ so content that passes it opens in Studio:
71
+
72
+ - **A saved block typed as another saved block.** `Footer-Island` =
73
+ `{ "__resolveType": "Footer", "revealOnScroll": true }` renders (the resolver follows the chain and
74
+ merges each hop's props), but Studio's editor follows one hop, finds no form for `Footer` and shows
75
+ an empty one. A bare alias (`{ "__resolveType": "Footer" }` saved under another name) is the same.
76
+ Type the block by its section or loader (`site/sections/Footer.tsx`) and copy in the props it took
77
+ from `Footer`; the error names the chain and those props.
78
+ - **A reference with props of its own.** A page section
79
+ `{ "__resolveType": "Footer", "hasFixedNewsletter": true }` renders with the props merged over
80
+ `Footer`'s, but Studio shows and edits `Footer` itself: it ignores these props and saves every edit
81
+ to `Footer`, for every page that uses it. The merge is shallow, so even `"seo": {}` replaces the
82
+ saved `seo`. Keep the reference bare, or inline it: type it by the section
83
+ (`site/sections/Footer.tsx`) and copy in `Footer`'s props it doesn't set; the error lists them.
84
+ - **A reference to a saved block whose name ends in `.` and letters or digits** (`Promo 2.0`,
85
+ `Banner.v2`). Studio reads such a name as a module path (like `site/sections/Footer.tsx`), finds
86
+ no form for it and shows an empty one. Rename the block and its references. Studio never reads
87
+ `constructor` or `__proto__` as a saved block's name either.
88
+
89
+ A bare reference (`{ "__resolveType": "Footer" }`, nothing else) is fine anywhere: in a page's
90
+ sections, a variant, a lazy block or a prop.
91
+
68
92
  ## Blocks with a fixed role
69
93
 
70
94
  | Saved block | Type | Role |
@@ -40,9 +40,11 @@ named block and reference it from each section, instead of repeating the props i
40
40
  "products": { "__resolveType": "Shelf - Best sellers" }
41
41
  ```
42
42
 
43
- A reference resolves to `{ ...saved, ...overrides }`. With no overrides, every reference
44
- reaches the loader with identical inputs, so the client runs it once. An override in one
45
- place (a different `count`) makes a second call there, which is what you want.
43
+ A bare reference reaches the loader with the saved inputs, so every use has identical
44
+ inputs and the client runs it once. When one place needs different inputs (a different
45
+ `count`), save a second block for it: a reference with props of its own (`{ "__resolveType":
46
+ "Shelf - Best sellers", "count": 4 }`) resolves, but Studio can't edit it and `deco check`
47
+ rejects it.
46
48
 
47
49
  This also stops the copies drifting apart when someone edits one of them in Studio.
48
50
 
@@ -69,6 +69,7 @@ The full text of each step: [`references/manual-steps.md`](./references/manual-s
69
69
  ```bash
70
70
  bunx deco schema && bunx deco content && bunx deco check # 0 errors
71
71
  bun run typecheck && bun run build
72
+ bun <skill>/scripts/checkContentReads.ts --root . # no client.list()
72
73
  ```
73
74
 
74
75
  Then the rest of [`references/verify.md`](./references/verify.md): the committed schema, type errors counted against v7, drafts probed by hand, and a page-by-page parity run with every approved difference encoded as a rule ([`references/parity.md`](./references/parity.md)).
@@ -106,7 +107,7 @@ What the site migrations taught, one subject per file. Commit hashes refer to `d
106
107
  | [`site-code.md`](./references/site-code.md) | What stays site code: SEO, devices, cookies, commerce code, error reporting, A/B splits |
107
108
  | [`server-functions.md`](./references/server-functions.md) | `/deco/invoke` → server functions |
108
109
  | [`caching-and-privacy.md`](./references/caching-and-privacy.md) | Per-visitor data, QueryClient scope, draft bypass, hydration waits |
109
- | [`nextjs.md`](./references/nextjs.md) | Next.js App Router: `@decocms/nextjs` drafts and proxy, `list('page')`, head order, Jest |
110
+ | [`nextjs.md`](./references/nextjs.md) | Next.js App Router: `@decocms/nextjs` drafts and proxy, `entries('page')`, head order, Jest |
110
111
  | [`hosted-releases.md`](./references/hosted-releases.md) | Hosted CMS instead of fast deploy, bundled content, v7 leftovers to delete |
111
112
  | [`content.md`](./references/content.md) | `deco check` as a deploy gate, content it rejects, editing the bundled content, moving it to Studio's hosted CMS |
112
113
  | [`telemetry.md`](./references/telemetry.md) | Telemetry params, resource attributes, dropped v7 bindings, analytics |
@@ -6,7 +6,7 @@ From the site migrations; the sites and what the commit hashes refer to are list
6
6
 
7
7
  **v7 fast deploy becomes the hosted CMS.** A v7 TanStack site that published content without a deploy (`DECO_FAST_DEPLOY` plus a `DECO_KV` namespace) needs `site` on `createCMS` for the same feature (and `token` for hosted telemetry): the site reads its own `DECO_SITE` var and `DECO_SITE_TOKEN` secret and passes them, since the SDK reads no environment variable; without `site` every content change needs a deploy. Put the two `wrangler secret put` commands in the deploy checklist. v8 keeps content out of the bundle too: with `site`, it is fetched at runtime only. On a site with ~300 saved blocks (11 MB of JSON), Node measured about 13 MB per parsed copy, plus a transient string up to twice the JSON while a snapshot parses: under the Workers 128 MB limit, but measure memory and cold start with `wrangler tail` on a preview before turning it on.
8
8
 
9
- With `site` set on `createCMS`, a published release goes live without a deploy, but only for what reads through the CMS client. Before turning it on, grep for direct imports of `.deco/blocks/*.json` (redirects, proxy tables, config blocks) and for build-time scripts that read `.deco/blocks`: those stay on the last deploy. v7 behaved the same, so it isn't a parity break; route them through the client or document the limitation and keep hosted releases off until you do.
9
+ With `site` set on `createCMS`, a published release goes live without a deploy, but only for what reads through the CMS client. Before turning it on, grep for direct imports of `.deco/blocks/*.json` (redirects, proxy tables, config blocks) and for build-time scripts that read `.deco/blocks`: those stay on the last deploy. v7 behaved the same, so it isn't a parity break; route them through the client or document the limitation and keep hosted releases off until you do. Through the client means the index for anything that enumerates (`client.entries(type)`: paths and `noIndex` for a sitemap, a block per path for a path-keyed map) and `resolve(name)` for one block: `client.list()` was removed and throws, and `scripts/checkContentReads.ts` lists the scans left.
10
10
 
11
11
  ## v7 leftovers to delete
12
12
 
@@ -13,7 +13,7 @@ From the site migrations; the sites and what the commit hashes refer to are list
13
13
  - **Images**: `createDecoImageLoader(imageUrl, { fallback: nextImageOptimizer })` from `@decocms/nextjs/image-loader` as `images.loaderFile`, over `createImageUrl` from `@decocms/blocks/image` with the platform's helpers first (`@decocms/apps-vtex/image`; see `framework-code.md`). A Server Component can't pass the URL function to a client component, so use the loader file, not a wrapper component.
14
14
  - **A pointer that doesn't parse.** `cms.draftPointer` ignores a `?__draft=`/cookie value that doesn't parse (it returns `null`, so `?__draft=junk` gets the release). On a `@decocms/blocks` release without that fix it returned the raw value and `cms.forDraft` failed with `LOADER_FAILED`, so `?__draft=junk` on a preview host answered 500: there, treat `parseDraftPointer(pointer) === null` as no draft, in the proxy and the page.
15
15
  - **Views wrapped in `next/dynamic`.** The script types each section from its view (`PropsOf<view>`). A lazy view that re-exports a `next/dynamic` wrapper loses its props type, and its form collapses. Type those sections from the component module (`section<import("…").Props>(…)`) and diff the forms against v7's.
16
- - **`list('page')` order.** It sorts by block name; v7 listed saved pages in file order. Output that lists pages in order (a sitemap) has to keep v7's order explicitly.
17
- - **List pages once per revision.** `list('page')` expands every page's saved-block references; on a site with hundreds of pages that is tens of milliseconds of CPU. Keep the routable list per revision (a revision never changes, a draft has its own) and hand the same array to `matchRoute` so it reuses its lookup. Health and readiness probes go through the same cache, never a fresh `list`.
16
+ - **Sitemaps read the index.** `client.entries('page')` gives every page's `name`, `path` and `noIndex` without reading a body (`client.list()` was removed and throws; on a hosted release it fetched one block per page, 730 requests on umbro). A sitemap is those paths minus templates (a `:param` segment or a `*`) minus `noIndex`. `entries()` sorts by block name; v7 listed saved pages in file order, so output that lists pages in order has to keep v7's order explicitly. `noIndex` is absent on a release last published before Studio wrote it (the next publish adds it): treat that as `false`, as v7 rendered such a page.
17
+ - **Route from the index.** `routes()` and `entries()` return the same array for the same revision (a draft has its own), so hand it to `matchRoute` as is and it reuses its lookup. Health and readiness probes read it too, never a body.
18
18
  - **Head meta order.** If v7 emitted `theme-color`/`color-scheme` after the root layout's metas on some routes, that was a race with Next's viewport resolution. To keep the order deterministic, render those tags from the segment layout (React hoists in tree order) rather than approving a reorder. The race can go the other way: where v7 had the viewport tags *before* the root layout's metas and v8's faster shell now wins, a segment layout can't move them earlier. Look for a deterministic fix (the tags rendered ahead of the root layout's metas on every route, checked against every route's head), and keep the reorder pending, with that reasoning, if none holds.
19
19
  - **Jest** is CJS-only: transform `@decocms/blocks` (ESM) with ts-jest and keep it out of `transformIgnorePatterns`. When mocking a site module in a test, spread `jest.requireActual` so sibling exports other code imports stay real.
@@ -5,8 +5,11 @@ The full checklist behind `SKILL.md` ("Verify").
5
5
  ```bash
6
6
  bunx deco schema && bunx deco content && bunx deco check # 0 errors
7
7
  bun run typecheck && bun run build
8
+ bun <skill>/scripts/checkContentReads.ts --root . # 0 client.list() calls
8
9
  ```
9
10
 
11
+ `checkContentReads.ts` exits 1 while the site's code calls `client.list(…)` (removed in 8.12: it throws at runtime, while the typecheck still passes, since `Client` keeps a deprecated `list` signature; a wrapper that calls it is found only by grepping for `.list(`) and prints every `.deco/blocks` scan. Replace each with `client.routes()` and `client.redirects()` for routing, `client.entries(type)` (names, types, paths, references and `noIndex`, from the index, no body fetched) or one `client.resolve(name)`. A big map keyed by path (SEO texts, highlights per category) becomes one saved block per path: the page reads its own block, found through `entries()`, never the whole map.
12
+
10
13
  The committed `.deco/schema.gen.json` must carry the top-level `"blocksMajor": 8` that `deco schema` writes: Studio treats a site as v8 **only** when its schema has `blocksMajor === 8` (the file name doesn't count; anything else edits as v7), and `deco check` fails without it. A schema generated by a CLI that predates the field must be regenerated with one that writes it, then committed.
11
14
 
12
15
  A v7 site often carries type errors of its own. Count them on the v7 commit first, and report the v8 count against it per file: name every remaining error in a file the migration touched instead of claiming there are none. Fix them with type-only changes, and rerun `deco schema` + `deco check` after each: a section's `Props` type *is* its editor form, so repairing a broken type import there (one that resolved to `any`) changes the schema and can make `deco check` reject saved content. Leave such an error, or fix the content with it, never silently. Don't fix an error by giving code that never ran (an undefined variable in a component) real values: that changes what renders.
@@ -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
+ }
@@ -0,0 +1,157 @@
1
+ /**
2
+ * Reads of the whole content, which v8 sites don't do (8.12 on): a site reads
3
+ * the index (`client.routes()`, `client.redirects()`, `client.entries(type?)`:
4
+ * names, types, paths, references and `noIndex`, never a body) and one named
5
+ * block at a time (`client.resolve(name)`). Since 8.12 `client.list(type)`
6
+ * throws; on a hosted release it fetched every block of the type
7
+ * (one request per block), and a build-time scan of `.deco/blocks` reads
8
+ * content the site no longer bundles.
9
+ *
10
+ * - `list`: a `.list(…)` call on a CMS client (`c`, `cms`, `client`,
11
+ * `…Client`, `cms.forRelease()`, `cms.forDraft(…)`, `cms.client(…)`,
12
+ * `currentClient()`): an error. `scripts/checkContentReads.ts` fails on one. `Client`
13
+ * keeps a deprecated `list` so old code compiles, so the typecheck does
14
+ * not catch one (a wrapper calling it neither): it throws at runtime.
15
+ * - `scan`: a directory read or glob of `.deco/blocks` (`readdir`,
16
+ * `readdirSync`, `glob`, `import.meta.glob`, …; `.deco/blocks.gen` is the
17
+ * content module, not a scan): reported, since a native app may bundle the
18
+ * JSON on purpose (reference/native-apps.md).
19
+ *
20
+ * The fix for both: `entries(type)` for what the index knows (a sitemap is
21
+ * the `page` entries' paths without `:param` or `*` and without `noIndex`),
22
+ * or one `resolve(name)` for one block's body (a map keyed by path becomes
23
+ * one saved block per path, found through `entries()`).
24
+ */
25
+ import fs from "node:fs";
26
+ import path from "node:path";
27
+ import ts from "typescript";
28
+ import { parse } from "./compat";
29
+ import type { Report } from "./report";
30
+
31
+ export interface ContentRead {
32
+ /** Relative to the root, with `/`. */
33
+ file: string;
34
+ /** 1-based. */
35
+ line: number;
36
+ kind: "list" | "scan";
37
+ /** The call, as written (first line). */
38
+ code: string;
39
+ }
40
+
41
+ /** Where a site keeps code: the folders scanned, under the root. */
42
+ const CODE_DIRS = ["src", "app", "server", "lib", "scripts"];
43
+ const SOURCE = /\.(tsx?|mts|cts|jsx?|mjs|cjs)$/;
44
+ const SKIPPED = new Set(["node_modules", "dist", "build", ".next", ".output", ".deco-migrate"]);
45
+
46
+ /** A receiver that is a CMS client by its name or by the call that made it. */
47
+ const CLIENT_RECEIVER =
48
+ /(?:^|[.\s(])(?:c|cms|client|[A-Za-z_$][\w$]*Client)$|\b(?:for(?:Release|Draft)|client|currentClient)\([^)]*\)$/;
49
+ /** A directory read or glob. */
50
+ const SCAN_CALL = /(?:^|\.)(?:readdir|readdirSync|opendir|opendirSync|glob|globSync|sync)$/;
51
+ /** `.deco/blocks`, the folder itself or a file in it (not `.deco/blocks.gen`). */
52
+ const BLOCKS_DIR = /\.deco\/blocks(?:$|\/|[^.\w])/;
53
+
54
+ function sourcesUnder(dir: string): string[] {
55
+ if (!fs.existsSync(dir)) return [];
56
+ const out: string[] = [];
57
+ for (const d of fs.readdirSync(dir, { withFileTypes: true })) {
58
+ if (SKIPPED.has(d.name)) continue;
59
+ const full = path.join(dir, d.name);
60
+ if (d.isDirectory()) out.push(...sourcesUnder(full));
61
+ else if (d.isFile() && SOURCE.test(d.name) && !d.name.endsWith(".d.ts")) out.push(full);
62
+ }
63
+ return out;
64
+ }
65
+
66
+ /** The text of a string literal or a template (its literal parts). */
67
+ function literalText(node: ts.Node): string | undefined {
68
+ if (ts.isStringLiteralLike(node)) return node.text;
69
+ if (ts.isTemplateExpression(node)) {
70
+ return node.head.text + node.templateSpans.map((s) => s.literal.text).join("");
71
+ }
72
+ return undefined;
73
+ }
74
+
75
+ /** Whether any argument (or a string inside it, as in `path.join(…)`) names `.deco/blocks`. */
76
+ function namesBlocksDir(args: readonly ts.Node[]): boolean {
77
+ let found = false;
78
+ const visit = (node: ts.Node): void => {
79
+ if (found) return;
80
+ const text = literalText(node);
81
+ if (text !== undefined && BLOCKS_DIR.test(text)) {
82
+ found = true;
83
+ return;
84
+ }
85
+ ts.forEachChild(node, visit);
86
+ };
87
+ for (const arg of args) visit(arg);
88
+ return found;
89
+ }
90
+
91
+ /** The receiver as written, without parentheses, `await`, `!` or spaces: `(await client())` is `client()`. */
92
+ function receiverText(node: ts.Expression, source: ts.SourceFile): string {
93
+ let inner: ts.Expression = node;
94
+ while (
95
+ ts.isParenthesizedExpression(inner) ||
96
+ ts.isAwaitExpression(inner) ||
97
+ ts.isNonNullExpression(inner)
98
+ ) {
99
+ inner = inner.expression;
100
+ }
101
+ return inner.getText(source).replace(/\s+/g, "");
102
+ }
103
+
104
+ /** Every `list` call on a CMS client and every scan of `.deco/blocks` in the site's code. */
105
+ export function findContentReads(root: string): ContentRead[] {
106
+ const files = CODE_DIRS.flatMap((dir) => sourcesUnder(path.join(root, dir))).sort();
107
+ const found: ContentRead[] = [];
108
+ for (const file of files) {
109
+ const text = fs.readFileSync(file, "utf8");
110
+ if (!text.includes(".list") && !text.includes(".deco/blocks")) continue;
111
+ const source = parse(file, text);
112
+ const at = (node: ts.Node, kind: ContentRead["kind"]) => {
113
+ const { line } = source.getLineAndCharacterOfPosition(node.getStart(source));
114
+ found.push({
115
+ file: path.relative(root, file).split(path.sep).join("/"),
116
+ line: line + 1,
117
+ kind,
118
+ code: node.getText(source).split("\n")[0]!,
119
+ });
120
+ };
121
+ const visit = (node: ts.Node): void => {
122
+ if (ts.isCallExpression(node)) {
123
+ const callee = node.expression;
124
+ if (
125
+ ts.isPropertyAccessExpression(callee) &&
126
+ callee.name.text === "list" &&
127
+ CLIENT_RECEIVER.test(receiverText(callee.expression, source))
128
+ ) {
129
+ at(node, "list");
130
+ } else if (SCAN_CALL.test(callee.getText(source)) && namesBlocksDir(node.arguments)) {
131
+ at(node, "scan");
132
+ }
133
+ }
134
+ ts.forEachChild(node, visit);
135
+ };
136
+ visit(source);
137
+ }
138
+ return found;
139
+ }
140
+
141
+ const LIST_FIX =
142
+ "client.list() throws (removed in 8.12): route with client.routes() and client.redirects(); client.entries(type) gives names, paths and noIndex from the index (a sitemap: page paths without :param or * and without noIndex), and client.resolve(name) reads one block; a map keyed by path becomes one saved block per path";
143
+ const SCAN_FIX =
144
+ "reads every saved block at build time: content comes from the CMS now (hosted releases leave .deco/blocks behind), so read client.entries(type) for paths and noIndex, or resolve one named block; keep it only for a native app that bundles the JSON (reference/native-apps.md)";
145
+
146
+ /** The migration's report lines: one per `list` call and per scan, as work left. */
147
+ export function reportContentReads(root: string, report: Report): ContentRead[] {
148
+ const reads = findContentReads(root);
149
+ for (const read of reads) {
150
+ report.manual.push({
151
+ step: "imports",
152
+ subject: `${read.file}:${read.line}`,
153
+ message: `${read.code}: ${read.kind === "list" ? LIST_FIX : SCAN_FIX}`,
154
+ });
155
+ }
156
+ return reads;
157
+ }
@@ -59,9 +59,9 @@ export const V8_API: Record<string, ReadonlySet<string> | "*"> = {
59
59
  "currentClient",
60
60
  "DraftPointer",
61
61
  "EffectiveSettings",
62
+ "Entry",
62
63
  "formatDraftPointer",
63
64
  "Lazy",
64
- "ListOptions",
65
65
  "Loader",
66
66
  "Match",
67
67
  "matchRoute",
@@ -26,6 +26,8 @@
26
26
  * `createDecoWorkerEntry` configured (the script writes no worker entry);
27
27
  * 6. imports: the codemod over `src/` (v7 helpers to `@decocms/compat-v7`,
28
28
  * `ctx.device` from the loader's request, `src/imageUrl.ts` on TanStack);
29
+ * then every `client.list(…)` call and `.deco/blocks` scan reported
30
+ * (`client.entries()` or one `resolve(name)` instead; ./contentReads.ts);
29
31
  * 7. scripts: `deco schema && deco content` before dev and build, and
30
32
  * `deco schema --check` in the site's CI after the install step.
31
33
  *
@@ -43,6 +45,7 @@ import { writeBlockMap } from "./blockMap";
43
45
  import { addSchemaCheck } from "./ciSchemaCheck";
44
46
  import { listSources, rewriteDeviceReads } from "./compat";
45
47
  import { moveContent } from "./content";
48
+ import { reportContentReads } from "./contentReads";
46
49
  import { reportTestsAndDates } from "./experiments";
47
50
  import { siteFramework, V8_RANGE } from "./framework";
48
51
  import { rewriteImports } from "./imports";
@@ -170,6 +173,7 @@ export async function migrate(options: MigrateOptions): Promise<Report> {
170
173
  reportWorkerEntry(root, report);
171
174
  }
172
175
  rewriteImports(root, report, vendored);
176
+ reportContentReads(root, report);
173
177
  addScripts(root, report);
174
178
  addSchemaCheck(root, report);
175
179
  return report;
@@ -50,7 +50,7 @@ A rule can be a saved block, reused by name. A saved block named `Hero test` wit
50
50
  { "rule": { "__resolveType": "Hero test" }, "value": { "__resolveType": "lazy", "value": "…" } }
51
51
  ```
52
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.
53
+ Keep the reference bare. The resolver would merge props next to it over the saved inputs, but Studio's editor shows and edits the saved rule and ignores them, so `deco check` rejects a reference with props of its own. `deco check` follows the reference when it checks the `name` of an `experiment` or `campaign` rule.
54
54
 
55
55
  ## Replacing the built-in
56
56
 
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 {