@uniweb/build 1.21.0 → 1.23.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.
@@ -17,25 +17,20 @@
17
17
  * path (where the static-host extras — sitemap, robots, search-index,
18
18
  * `llms.txt` and the `.md` projections, `_pages/*` for split content — are
19
19
  * actually consumed). Both paths use
20
- * the same underlying building blocks (`collectSiteContent`,
21
- * `processQueries`, etc.), so behavior stays consistent without forcing
22
- * one path through the other's lifecycle. Media processing — WebP copies and
23
- * video posters — is the bundle path's alone (below).
20
+ * the same underlying building blocks (`collectSiteContent`, etc.), so behavior
21
+ * stays consistent without forcing one path through the other's lifecycle. Media
22
+ * processing — WebP copies and video posters — and the records' compiled query
23
+ * files are the bundle path's alone (below).
24
24
  */
25
25
 
26
- import { writeFile, mkdir, cp } from 'node:fs/promises'
27
- import { existsSync } from 'node:fs'
26
+ import { writeFile, mkdir } from 'node:fs/promises'
28
27
  import { join, resolve } from 'node:path'
29
28
 
30
- import { resolveDefaultLocale, DATA_DIR } from '@uniweb/core'
31
29
  import { collectSiteContent } from './content-collector.js'
32
- import { processQueries, writeQueryFiles } from './query-processor.js'
33
- import { resolveRecordsDir } from './entity-pool.js'
34
30
 
35
31
  /**
36
32
  * Build the site data for `uniweb build --link`, which `uniweb publish` runs.
37
- * `publish` reads two things back from `distDir`: the files of the queries that
38
- * have no data schema, which it uploads, and the languages to make live.
33
+ * `publish` reads one thing back from `distDir`: the languages to make live.
39
34
  *
40
35
  * Emits to `distDir`:
41
36
  * - `site-content.json` — full content tree, sections always inlined.
@@ -60,13 +55,13 @@ import { resolveRecordsDir } from './entity-pool.js'
60
55
  *
61
56
  * ⇒ The rule stands on its own: we do not know which consumers
62
57
  * re-derive, so we always ship enough for the ones that do.
63
- * - `data/<query>.json` (+ each record's own file, `data/<query>/<$name>.json`) —
64
- * same shape `processQueries` produces today. `publish` uploads the files of
65
- * the queries that have no data schema (`collectSchemalessData`).
66
- * - `records/<path under the records directory>` — the records' co-located assets, where
67
- * the compiled records point.
68
58
  *
69
59
  * Does NOT emit:
60
+ * - `data/<query>.json` and each record's own file — the compiled queries. Every
61
+ * record has a data schema [Diego, 2026-11-11], so a push sends it as an entity and
62
+ * a host's records service answers its queries. ⛔ *Until 2026-11-11 this lane
63
+ * compiled them, with the records' co-located assets, for `publish` to upload the
64
+ * files of a query with no data schema.*
70
65
  * - `assets/<media>` — no media is processed here, and a media ref in
71
66
  * `site-content.json` stays the site's own path. `publish` uploads a
72
67
  * site's media from the site's own files (the CLI's `uploadSiteMedia`), so
@@ -122,42 +117,7 @@ export async function buildSiteData({
122
117
  // `blueprint.yml` (`uwx/blueprint.js`); said here too, a publish said it twice.
123
118
  let siteContent = await collectSiteContent(resolvedSiteRoot, { foundationPath, dropUnpublished: true, base: basePath, strict: true, warnBlueprint: false })
124
119
 
125
- // 2. Compile content collections (file-based markdown/yaml/json).
126
- // `writeQueryFiles` lands them under `<siteRoot>/public/data/`;
127
- // in the vite plugin path that's fine because vite copies
128
- // `public/` into `dist/` at build time. The link-mode pipeline
129
- // has no vite, so we mirror that copy ourselves into
130
- // `<distDir>/data/` — the set the CLI's `site-data-upload` lane walks at
131
- // publish time. (This named `uniweb deploy::collectDataFiles` until
132
- // 2026-08-18; no such function has existed for some time.) Same output bytes, same paths, just
133
- // without the vite intermediary.
134
- if (siteContent.config?.queries) {
135
- const byQuery = await processQueries(
136
- resolvedSiteRoot,
137
- siteContent.config.queries,
138
- resolveRecordsDir(resolvedSiteRoot, siteContent.config?.paths).rel,
139
- basePath,
140
- { locale: resolveDefaultLocale(siteContent.config) ?? null }
141
- )
142
- await writeQueryFiles(resolvedSiteRoot, byQuery, siteContent.config.queries)
143
-
144
- const publicDataDir = join(resolvedSiteRoot, 'public', DATA_DIR)
145
- const distDataDir = join(resolvedDistDir, DATA_DIR)
146
- if (existsSync(publicDataDir)) {
147
- await cp(publicDataDir, distDataDir, { recursive: true })
148
- }
149
-
150
- // ⭐ AND THE RECORDS' CO-LOCATED ASSETS — `public/records/<path under records/>`,
151
- // where the compiled records point (`/records/…`), mirrored the way vite mirrors
152
- // all of `public/` on the bundle lane. ⛔ Until 2026-09-14 only `public/data` was
153
- // copied, so a record's image URL named a file this lane's `dist/` did not have.
154
- const publicRecordsDir = join(resolvedSiteRoot, 'public', 'records')
155
- if (existsSync(publicRecordsDir)) {
156
- await cp(publicRecordsDir, join(resolvedDistDir, 'records'), { recursive: true })
157
- }
158
- }
159
-
160
- // 3. No media processing (header, "Does NOT emit"). The collector's asset
120
+ // 2. No media processing (header, "Does NOT emit"). The collector's asset
161
121
  // manifest is internal, so it is dropped — as the vite plugin drops it
162
122
  // when processing is off.
163
123
  let finalContent = { ...siteContent }
@@ -196,7 +156,7 @@ export async function buildSiteData({
196
156
  finalContent = { ...finalContent, config: configWithoutIcons }
197
157
  }
198
158
 
199
- // 4. Write `dist/site-content.json` with FULL sections inlined.
159
+ // 3. Write `dist/site-content.json` with FULL sections inlined.
200
160
  // Important: do NOT strip sections per the split-content rule here.
201
161
  // Stripping would silently break split-mode sites on any consumer that
202
162
  // re-derives split content from the full payload. See the header for
@@ -204,7 +164,7 @@ export async function buildSiteData({
204
164
  const contentPath = join(resolvedDistDir, 'site-content.json')
205
165
  await writeFile(contentPath, JSON.stringify(finalContent, null, 2))
206
166
 
207
- // 5. (removed 2026-08-01) This lane used to emit a search index — the split
167
+ // (removed 2026-08-01) This lane used to emit a search index — the split
208
168
  // `_search/{locale}/*.json` for a server, and `search-index.json` for the
209
169
  // browser — gated by `features: [search]`.
210
170
  //
@@ -216,7 +176,7 @@ export async function buildSiteData({
216
176
  // identically on both lanes.
217
177
  //
218
178
  // The browser one was doubly dead: nothing ever uploaded it. `dist/` on
219
- // this lane reaches a backend only through the data ball and the media
179
+ // this lane reached a backend only through the data ball and the media
220
180
  // refs, and the ball read `dist/data` and `dist/_search` — never the dist
221
181
  // root. So it was serialized on every publish and dropped.
222
182
  //
@@ -225,9 +185,9 @@ export async function buildSiteData({
225
185
  // That is what GitHub Pages and every other static target serve, and the
226
186
  // framework has more targets than one backend.
227
187
 
228
- // 6. (removed 2026-10-25) This lane wrote `llms.txt` and a `.md` per page, for the default
188
+ // (removed 2026-10-25) This lane wrote `llms.txt` and a `.md` per page, for the default
229
189
  // language only, on the ground that both lanes publish a site. Nothing read them: `publish`
230
- // reads the schema-less query files and the languages, and a host that serves the site
190
+ // reads the languages, and a host that serves the site
231
191
  // derives its projections from the content, as it derives its search. The static host’s are
232
192
  // the bundle lane’s, in every language (`./projections.js`).
233
193
 
@@ -334,7 +334,10 @@ export async function defineSiteConfig(options = {}) {
334
334
  await generateEntryPoint(srcDir, entryPath)
335
335
  server.ws.send({ type: 'full-reload' })
336
336
  } catch (err) {
337
+ // The last good entry stays, and the page shows why it did not move: a `meta.js` that
338
+ // does not load, or a declaration the build cannot use, stops the build (schema.js).
337
339
  console.warn('[site] Failed to regenerate foundation entry:', err.message)
340
+ server.ws.send({ type: 'error', err: { message: err.message, stack: '' } })
338
341
  }
339
342
  }
340
343
  })
@@ -2607,6 +2607,28 @@ function payloadSiteConfig(siteConfig) {
2607
2607
  return runtimeSiteConfig
2608
2608
  }
2609
2609
 
2610
+ /**
2611
+ * Warn when a page writes `{name}` for one of the site's placeholders and the foundation has no
2612
+ * content handler to resolve it, so the page prints the braces. A placeholder no page writes
2613
+ * says nothing: a foundation may read it as a site value (`website.config.placeholders`).
2614
+ *
2615
+ * @param {string[]} names - the site's placeholder names, or none when the foundation resolves them
2616
+ * @param {Array<object>} pages - the collected pages
2617
+ */
2618
+ function warnUnresolvedPlaceholders(names, pages) {
2619
+ if (!names.length) return
2620
+ const escaped = names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
2621
+ const written = new RegExp(`\\{\\s*(${escaped.join('|')})(?=[\\s.}])`, 'g')
2622
+ const text = JSON.stringify(pages)
2623
+ const used = [...new Set([...text.matchAll(written)].map((m) => m[1]))]
2624
+ if (!used.length) return
2625
+ console.warn(
2626
+ `[uniweb] Pages write ${used.map((n) => `\`{${n}}\``).join(', ')}, which site.yml declares under \`placeholders:\`, ` +
2627
+ `but the foundation has no \`handlers.content\` to resolve them — those pages render the braces as text.\n` +
2628
+ `[uniweb] A foundation opts in with \`handlers: createLoomHandlers({ vars })\` from @uniweb/loom.`
2629
+ )
2630
+ }
2631
+
2610
2632
  /** What this process has said of a site's `blueprint.yml` (`collectSiteContent`). */
2611
2633
  const saidOfBlueprint = new Set()
2612
2634
 
@@ -2727,13 +2749,16 @@ export async function collectSiteContent(sitePath, options = {}) {
2727
2749
  // ⚖️ A WARNING, never an error: the site may be mid-migration, or the author
2728
2750
  // may be about to switch foundations, and a declared-but-unread value harms
2729
2751
  // nothing. Same rule as the retired-`fetcher:` keys above — warn once, carry on.
2730
- if (siteConfig.placeholders && !hasContentHandler) {
2731
- console.warn(
2732
- `[uniweb] site.yml declares \`placeholders:\` but the foundation has no \`handlers.content\`, ` +
2733
- `so nothing will resolve them — pages will render the literal \`{name}\` text.\n` +
2734
- `[uniweb] A foundation opts in with \`handlers: createLoomHandlers({ vars })\` from @uniweb/loom.`
2735
- )
2736
- }
2752
+ //
2753
+ // ⭐ ONLY WHEN A PAGE WRITES ONE (`warnUnresolvedPlaceholders`, once the pages are read). A
2754
+ // foundation's components may read a site's placeholders themselves
2755
+ // (`website.config.placeholders.currency`), with no content handler: a site value set once.
2756
+ // ⛔ Until 2026-11-11 the warning fired on any `placeholders:`, and told such a site its pages
2757
+ // would print `{name}` when none did.
2758
+ const placeholderNames =
2759
+ !hasContentHandler && siteConfig.placeholders && typeof siteConfig.placeholders === 'object' && !Array.isArray(siteConfig.placeholders)
2760
+ ? Object.keys(siteConfig.placeholders)
2761
+ : []
2737
2762
  // `base` reaches the theme because self-hosted font faces are authored
2738
2763
  // root-relative (`/fonts/x.woff2`) and the emitted @font-face lives in an
2739
2764
  // inline <style> — under a subdirectory deployment it must carry the base.
@@ -2798,6 +2823,8 @@ export async function collectSiteContent(sitePath, options = {}) {
2798
2823
  assetCollection = mergeAssetCollections(assetCollection, layoutAssets)
2799
2824
  iconCollection = mergeIconCollections(iconCollection, layoutIcons)
2800
2825
 
2826
+ warnUnresolvedPlaceholders(placeholderNames, pages)
2827
+
2801
2828
  // One manifest key per file: a co-located ref written the same way in two
2802
2829
  // folders (`./media/shot.png`) names two files, and would otherwise share one
2803
2830
  // entry — every page rendering the last one collected. Before the config
@@ -402,6 +402,16 @@ export function readEntityPoolSync(siteRoot, opts = {}) {
402
402
  if (!e.isFile()) continue
403
403
  // The folder's organization, not a record — see the header.
404
404
  if (dirs.length === 0 && e.name === FOLDER_YML) continue
405
+ // ⛔ A COMPANION SCHEMA IS RETIRED (2026-11-11): every record has a data schema, which says
406
+ // how it is translated, so `records/<query>.schema.js` is read by nothing and said so.
407
+ if (dirs.length === 0 && e.name.endsWith('.schema.js')) {
408
+ errors.push(
409
+ `${rel}/${e.name} is not read: a companion schema is retired. A record's data schema says ` +
410
+ `which of its fields are translated — define it in the foundation's schemas/ ` +
411
+ `(\`uniweb guide data\`), and delete this file.`
412
+ )
413
+ continue
414
+ }
405
415
  const ext = extname(e.name).toLowerCase()
406
416
  const fileRecord = isFileRecordDir(dirs)
407
417
  if (!fileRecord && !ENTITY_EXTENSIONS.has(ext)) continue
package/src/site/index.js CHANGED
@@ -51,7 +51,6 @@ export {
51
51
  processQueries,
52
52
  writeQueryFiles
53
53
  } from './query-processor.js'
54
- export { collectSchemalessData, collectSchemalessDataAssets, rewriteSchemalessDataAssets } from './schemaless-data.js'
55
54
  export {
56
55
  parseFetchConfig,
57
56
  executeFetch,
@@ -246,13 +246,14 @@ import { mountDevApi } from '../dev/api-mount.js'
246
246
  import { mountDevSubmit } from '../dev/submit-mount.js'
247
247
 
248
248
  /**
249
- * The pre-paint appearance script for a shell, the runtime's own (`@uniweb/runtime/ssr`, which a
250
- * prerendered page's seam writes too), or '' for a site with no dark scheme. Loaded once.
249
+ * A shell carrying the page's look by the runtime's own rule (`@uniweb/runtime/ssr`, which a
250
+ * prerendered page's seam writes too): the scheme class on its `<html>`, and the pre-paint script
251
+ * where the browser decides. Unchanged for a site with no dark scheme. Loaded once.
251
252
  */
252
- let bootScriptOf = null
253
- async function appearanceBootScript(appearance) {
254
- bootScriptOf ||= import('@uniweb/runtime/ssr').then((runtime) => runtime.renderAppearanceBootScript)
255
- return (await bootScriptOf)(appearance)
253
+ let writeAppearanceOf = null
254
+ async function writeShellAppearance(html, appearance) {
255
+ writeAppearanceOf ||= import('@uniweb/runtime/ssr').then((runtime) => runtime.writePageAppearance)
256
+ return (await writeAppearanceOf)(html, appearance)
256
257
  }
257
258
 
258
259
  /**
@@ -1165,14 +1166,6 @@ export function siteContentPlugin(options = {}) {
1165
1166
  headInjection += ` <style id="uniweb-theme">\n${contentToInject.theme.css}\n </style>\n`
1166
1167
  }
1167
1168
 
1168
- // ⭐ THE PRE-PAINT APPEARANCE SCRIPT, so a page the browser renders itself — every page under
1169
- // `uniweb dev`, and a build that doesn't prerender — shows the site's look before the bundle
1170
- // boots. A prerendered page keeps this one: its render adds none where the shell has it
1171
- // (`injectPageContent`). ⛔ Until 2026-11-11 only a prerendered page had it, so a dark site
1172
- // under `uniweb dev` painted light for about 0.4 s on every load.
1173
- const bootScript = await appearanceBootScript(contentToInject.theme?.appearance)
1174
- if (bootScript) headInjection += ` ${bootScript}\n`
1175
-
1176
1169
  // ⛔ No page's head tags — canonical, Open Graph, hreflang — go into the shell, which every
1177
1170
  // page is rendered into: the prerender writes each page's own (`injectPageContent`), and the
1178
1171
  // browser keeps them (`useHeadMeta`). Until 2026-10-25 the home page's were written here.
@@ -1211,11 +1204,18 @@ export function siteContentPlugin(options = {}) {
1211
1204
  result = result.replace(/<title>[\s\S]*?<\/title>/, () => `<title>${escapeHtml(siteName)}</title>`)
1212
1205
  }
1213
1206
 
1214
- if (!headInjection) return result
1215
-
1216
1207
  // Insert before </head>
1217
1208
  // A replacer function: `$$` or `$&` in the content, the theme or head.html is text, not a pattern.
1218
- return result.replace('</head>', () => headInjection + ' </head>')
1209
+ if (headInjection) result = result.replace('</head>', () => headInjection + ' </head>')
1210
+
1211
+ // ⭐ THE PAGE'S LOOK, so a page the browser renders itself — every page under `uniweb dev`, and
1212
+ // a build that doesn't prerender — shows the site's look before the bundle boots: the scheme
1213
+ // class on `<html>` where every first visit gets one look, and the pre-paint script where the
1214
+ // browser decides (`writePageAppearance`). A prerendered page is rendered into this shell and
1215
+ // keeps both; its render adds neither again. ⛔ Until 2026-11-11 the shell carried no class,
1216
+ // and at first no script either, so a dark site under `uniweb dev` painted light for about
1217
+ // 0.4 s on every load.
1218
+ return writeShellAppearance(result, contentToInject.theme?.appearance)
1219
1219
  },
1220
1220
 
1221
1221
  async generateBundle() {
@@ -43,6 +43,8 @@ import { readFile } from 'node:fs/promises'
43
43
  import yaml from 'js-yaml'
44
44
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
45
45
  import { dataKeyTypes } from '../uwx/data-key-types.js'
46
+ import { siteSelfScope } from '../uwx/self-scope.js'
47
+ import { qualifyRef } from '@uniweb/schemas/refs'
46
48
 
47
49
  // Read its own YAML rather than importing the site build's helper. That import
48
50
  // pointed the wrong way — a config resolver reaching into the collector that
@@ -403,33 +405,57 @@ export async function dataKeyTyping(siteRoot, declarations, opts = {}) {
403
405
  * built would compile its records in one shape under `pnpm dev` and another in
404
406
  * production — and a component reads them in exactly one.
405
407
  *
406
- * A `@/name` ref the foundation defines no schema for is absent without a word: a query
407
- * is named after no schema when its records have none. Any other ref that does not
408
- * resolve is absent too, and reported in `failures`. With no local foundation only
409
- * `@std/*` refs resolve — from the build's own copy of the standard schemas — and the
410
- * system Models a record may name (`@uniweb/link`), since nothing else is on disk.
408
+ * A `@/name` ref the foundation's own `schemas/` does not define is looked for under the
409
+ * foundation's scope (`@acme/name`), as a push names it — a library of that scope may define
410
+ * it. When neither does, it is in `missing`: a ref this build could check, and found nothing
411
+ * for, which a record cannot be of (`query-processor.js` refuses it). A ref of another scope
412
+ * found nowhere on disk is absent without a word, since it may be registered where this build
413
+ * cannot read; one that fails to load is reported in `failures`. With no local foundation only
414
+ * `@std/*` refs resolve — from the build's own copy of the standard schemas — and the system
415
+ * Models a record may name (`@uniweb/link`), since nothing else is on disk; nothing is `missing`
416
+ * then, as nothing could be checked.
411
417
  *
412
418
  * @param {string} siteRoot
413
419
  * @param {Iterable<string>} refs - the `schema:` refs of the site's queries
414
420
  * @param {{ siteYml?: object }} [opts] - an already-read site.yml
415
- * @returns {Promise<{ schemas: object, failures: Array<{ ref: string, message: string }> }>}
421
+ * @returns {Promise<{ schemas: object, failures: Array<{ ref: string, message: string }>, missing: string[] }>}
416
422
  */
417
423
  export async function resolveRecordSchemas(siteRoot, refs, opts = {}) {
418
424
  const wanted = [...new Set([...(refs || [])].filter((r) => typeof r === 'string' && r))]
419
425
  const schemas = {}
420
426
  const failures = []
421
- if (wanted.length === 0) return { schemas, failures }
427
+ const missing = []
428
+ if (wanted.length === 0) return { schemas, failures, missing }
422
429
  const siteYml = opts.siteYml || (await readYamlFile(join(siteRoot, 'site.yml')))
423
430
  const srcDir = localFoundationSrcDir(siteRoot, siteYml)
431
+ let scope // the foundation's, read once, when a foundation-relative ref needs it
424
432
  for (const ref of wanted) {
425
433
  if (!srcDir && !ref.startsWith('@std/') && !isSystemRecordRef(ref)) continue
426
434
  try {
427
435
  Object.assign(schemas, await buildDataSchemaMap([ref], { srcDir: srcDir ?? siteRoot }))
428
436
  } catch (err) {
429
- if (err?.code !== SCHEMA_NOT_FOUND) failures.push({ ref, message: err?.message || String(err) })
437
+ if (err?.code !== SCHEMA_NOT_FOUND) {
438
+ failures.push({ ref, message: err?.message || String(err) })
439
+ continue
440
+ }
441
+ if (!srcDir || !ref.startsWith('@/')) continue
442
+ if (scope === undefined) scope = (await siteSelfScope(siteRoot)) ?? null
443
+ const qualified = scope ? qualifyRef(ref, scope) : ref
444
+ if (qualified !== ref && (await definedOnDisk(qualified, srcDir))) continue
445
+ missing.push(ref)
430
446
  }
431
447
  }
432
- return { schemas, failures }
448
+ return { schemas, failures, missing }
449
+ }
450
+
451
+ /** Whether a scoped ref resolves on disk — a package of the foundation's workspace or a library. */
452
+ async function definedOnDisk(ref, srcDir) {
453
+ try {
454
+ await buildDataSchemaMap([ref], { srcDir })
455
+ return true
456
+ } catch (err) {
457
+ return err?.code !== SCHEMA_NOT_FOUND
458
+ }
433
459
  }
434
460
 
435
461
  /** The source directory of the site's foundation when it is local, else null. */
@@ -459,7 +485,9 @@ export async function foundationSections(siteRoot, siteYml = null) {
459
485
  const srcDir = localFoundationSrcDir(siteRoot, yml)
460
486
  if (srcDir) {
461
487
  try {
462
- return await buildSchema(srcDir)
488
+ // Not strict: a declaration the foundation's build stops on is warned of here, and read
489
+ // (`buildSchema`'s `strict`).
490
+ return await buildSchema(srcDir, undefined, null, { strict: false })
463
491
  } catch {
464
492
  // a foundation whose source does not read is reported by the build that builds it
465
493
  }
@@ -588,9 +588,10 @@ export const WHOLE_RECORD = Symbol.for('uniweb.query.whole')
588
588
  * `$name` is the record's handle, taken BEFORE the lift: a brief may declare a `slug`
589
589
  * field of its own (`@std/article`'s does), and the lift puts that one over the file's.
590
590
  *
591
- * A record whose query has no data schema (`resolveRecordSchemas`) is delivered as its
592
- * file holds it, a markdown body as `content`, which is what the static lane always did;
593
- * so is a body its schema has no field for — a push refuses that one. A markdown record
591
+ * A record whose data schema this build cannot read (`resolveRecordSchemas`: a foundation that
592
+ * is not local, a schema registered under another scope) is delivered as its file holds it, a
593
+ * markdown body as `content`; so is a body its schema has no field for — a push refuses that one.
594
+ * One whose schema the build can read and finds nothing for stops the build (`processQueries`). A markdown record
594
595
  * also gets `excerpt` and `image` where it states none, derived from its body: the
595
596
  * static lane's own, and not what a host adds.
596
597
  *
@@ -1203,9 +1204,20 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
1203
1204
  }
1204
1205
 
1205
1206
  // ⭐ THE DATA SCHEMA EACH QUERY'S RECORDS ARE DELIVERED IN (`deliverRecord`) — resolved
1206
- // from the foundation's source once for every query. A query with none compiles its
1207
- // records as their files hold them.
1208
- const dataSchemas = options.dataSchemas ?? (await querySchemas(siteDir, queriesConfig, typing))
1207
+ // from the foundation's source once for every query and every folder of records.
1208
+ //
1209
+ // ⭐ EVERY RECORD HAS A DATA SCHEMA [Diego, 2026-11-11]: a folder or a query whose schema the
1210
+ // build can check and finds nothing for stops it (`refuseRecordsWithoutSchema`), as a push
1211
+ // refuses it (`uwx/records.js`). One the build cannot check — a foundation that is not local,
1212
+ // a schema registered under another scope — compiles its records as their files hold them,
1213
+ // and the push checks it against the backend. ⛔ Until 2026-11-11 a folder with no schema was
1214
+ // "schema-less": compiled as files, which a publish uploaded in one language.
1215
+ let dataSchemas = options.dataSchemas
1216
+ if (!dataSchemas) {
1217
+ const resolved = await querySchemas(siteDir, queriesConfig, typing, poolBySchema)
1218
+ refuseRecordsWithoutSchema(resolved.missing, { dir: pool.dir, poolBySchema, queriesConfig })
1219
+ dataSchemas = resolved.schemas
1220
+ }
1209
1221
  const references = referenceHydrator({ poolBySchema, dataSchemas, siteDir, recordsRoot, basePath, includeDrafts })
1210
1222
 
1211
1223
  const results = {}
@@ -1243,26 +1255,58 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
1243
1255
  }
1244
1256
 
1245
1257
  /**
1246
- * The data schemas of the site's record queries, by ref (`resolveRecordSchemas`). A ref
1247
- * that is not a schema-less query's name and still does not resolve is warned about:
1248
- * its records are compiled as their files hold them, which is not the shape a
1249
- * component receives from a host.
1258
+ * The data schemas of the site's record queries and of its folders of records, by ref
1259
+ * (`resolveRecordSchemas`), and the refs it checked and found nothing for (`missing`). A ref of
1260
+ * another scope found nowhere on disk is left to the push, which may find it registered; one
1261
+ * that fails to load is warned about. Either way its records are compiled as their files hold
1262
+ * them, which is not the shape a component receives from a host.
1250
1263
  */
1251
- async function querySchemas(siteDir, queriesConfig, typing = new Map()) {
1264
+ async function querySchemas(siteDir, queriesConfig, typing = new Map(), poolBySchema = new Map()) {
1252
1265
  const refs = [...typing.values()]
1253
1266
  for (const config of Object.values(queriesConfig)) {
1254
1267
  if (config && typeof config === 'object' && config.url !== undefined) continue
1255
1268
  const ref = typeof config === 'string' ? config : config?.schema
1256
1269
  if (typeof ref === 'string' && !typing.has(ref)) refs.push(ref)
1257
1270
  }
1258
- const { schemas, failures } = await resolveRecordSchemas(siteDir, refs)
1271
+ // A folder no query reads is checked too, for a schema it names relative to the foundation —
1272
+ // the only kind this build can find missing; a scoped one is resolved where a query reads it.
1273
+ for (const ref of poolBySchema.keys()) if (ref.startsWith('@/')) refs.push(ref)
1274
+ const { schemas, failures, missing } = await resolveRecordSchemas(siteDir, refs)
1259
1275
  for (const { ref, message } of failures) {
1260
1276
  console.warn(
1261
1277
  `[query-processor] Data schema ${ref} did not resolve, so its records are compiled as ` +
1262
1278
  `their files hold them rather than as a component receives them: ${message}`
1263
1279
  )
1264
1280
  }
1265
- return schemas
1281
+ return { schemas, missing }
1282
+ }
1283
+
1284
+ /**
1285
+ * Stop the build for records whose data schema resolves to nothing, naming each folder and
1286
+ * query and what to write: every record has a data schema [Diego, 2026-11-11]. `missing` holds
1287
+ * only what the build could check (`resolveRecordSchemas`).
1288
+ *
1289
+ * @param {string[]} missing - foundation-relative refs no schema answers
1290
+ * @param {{ dir: string, poolBySchema: Map<string, Array>, queriesConfig: Object }} ctx
1291
+ */
1292
+ export function refuseRecordsWithoutSchema(missing, { dir, poolBySchema, queriesConfig }) {
1293
+ if (!missing?.length) return
1294
+ const lines = missing.map((ref) => {
1295
+ const readers = Object.entries(queriesConfig || {})
1296
+ .filter(([, c]) => (typeof c === 'string' ? c : c?.schema) === ref)
1297
+ .map(([name]) => `query "${name}"`)
1298
+ const held = poolBySchema.get(ref)
1299
+ const where = held?.length ? `${dir}/${held[0].dirs.join('/')}/` : readers.shift()
1300
+ return ` ${where} — ${ref}${readers.length ? `, read by ${readers.join(', ')}` : ''}`
1301
+ })
1302
+ const name = missing[0].replace(/^@\//, '')
1303
+ throw new Error(
1304
+ `[uniweb] Every record needs a data schema, and nothing defines ${missing.length === 1 ? 'this one' : 'these'}:\n` +
1305
+ `${lines.join('\n')}\n` +
1306
+ ` A folder's name is its records' data schema. Define it in the foundation, as schemas/${name}.yml ` +
1307
+ '(`uniweb guide data` shows one), or keep records of a data schema registered under another scope ' +
1308
+ 'in records/<scope>/<name>/.'
1309
+ )
1266
1310
  }
1267
1311
 
1268
1312
  /**
@@ -38,15 +38,19 @@ const TEAM_KEYS = Object.freeze(['label'])
38
38
  * An integration line, as a backend takes it. Refused here exactly as a backend refuses them, and no
39
39
  * more: a line this takes, a backend takes.
40
40
  */
41
- const INTEGRATION_KEYS = Object.freeze(['label', 'mapping', 'channel', 'trigger', 'filter', 'enabled'])
41
+ const INTEGRATION_KEYS = Object.freeze(['label', 'mapping', 'channel', 'trigger', 'filter', 'enabled', 'reply', 'reply_about'])
42
+ /** The one channel whose endpoint answers, so the one a `reply` mapping may sit on. */
43
+ const REPLYING = 'http'
44
+ /** `reply_about`: a field of the reply's type, `section.field`. */
45
+ const SECTION_FIELD = /^[^.\s]+\.[^.\s]+$/
42
46
  const CHANNELS = Object.freeze(['file', 'feed', 'email', 'http'])
43
- const TRIGGERS = Object.freeze(['manual', 'on_fetch', 'on_create', 'on_match'])
47
+ const TRIGGERS = Object.freeze(['manual', 'on_fetch', 'on_create', 'on_match', 'on_change'])
44
48
  /** Each channel → the triggers it pairs with. */
45
49
  const PAIRS = Object.freeze({
46
50
  file: ['manual'],
47
51
  feed: ['on_fetch'],
48
- email: ['on_create', 'on_match', 'manual'],
49
- http: ['on_create', 'on_match', 'manual'],
52
+ email: ['on_create', 'on_match', 'on_change', 'manual'],
53
+ http: ['on_create', 'on_match', 'on_change', 'manual'],
50
54
  })
51
55
  /** The channels a line may switch on with `enabled: true`. */
52
56
  const ENABLEABLE = Object.freeze(['file', 'feed'])
@@ -328,6 +332,20 @@ function integrationProblems(integrations) {
328
332
  if (channelOk && triggerOk && !PAIRS[line.channel].includes(line.trigger)) {
329
333
  found.push(`\`${at}\`: a \`${line.channel}\` integration's trigger is one of ${listed(PAIRS[line.channel])} — not \`${line.trigger}\`.`)
330
334
  }
335
+ if ('reply' in line) {
336
+ const name = refNameProblem(`${at}.reply`, line.reply, 'mapping')
337
+ if (name) found.push(name)
338
+ if (channelOk && line.channel !== REPLYING) {
339
+ found.push(`\`${at}.reply\`: only an \`${REPLYING}\` integration is answered, so only one takes a \`reply\` — not a \`${line.channel}\` one.`)
340
+ }
341
+ }
342
+ if ('reply_about' in line) {
343
+ if (!('reply' in line)) {
344
+ found.push(`\`${at}.reply_about\` names a field of the reply's type, so it goes with a \`reply\` mapping — the line has none.`)
345
+ } else if (typeof line.reply_about !== 'string' || !SECTION_FIELD.test(line.reply_about)) {
346
+ found.push(`\`${at}.reply_about\` is a field of the reply's type, \`section.field\` — \`identity.submission\` — not ${described(line.reply_about)}.`)
347
+ }
348
+ }
331
349
  if ('filter' in line && !isMap(line.filter)) {
332
350
  found.push(`\`${at}.filter\` is a map — \`filter: { where: { status: sold } }\` — not ${described(line.filter)}.`)
333
351
  }
@@ -26,8 +26,9 @@
26
26
  * full name for any other, as `data:` and `queries.yml` name types — and a push names each in full
27
27
  * by the rule every ref it sends follows (`qualifyRef`, with the scope `siteSelfScope` reads). The
28
28
  * backend never resolves an `@/x`. A pull writes `@/x` back, and keeps a name the file already
29
- * spells another way when it names the same type. An integration's `mapping:` — one of the
30
- * foundation's mappings (`src/mappings/`) — is named the same way; nothing in its `filter` is.
29
+ * spells another way when it names the same type. An integration's `mapping:` and `reply:` — each
30
+ * one of the foundation's mappings (`src/mappings/`) — are named the same way; its `reply_about`
31
+ * (a field) and nothing in its `filter` are.
31
32
  *
32
33
  * ⭐ ITS SHAPE IS THE BACKEND'S, AND THE BACKEND CHECKS IT AT EVERY DOOR THAT WRITES THE ROW. The
33
34
  * checks here come earlier — a build, a push, `uniweb doctor`, offline — and refuse no more than
@@ -97,12 +98,21 @@ export function blueprintForWire(blueprint, scope) {
97
98
  return out
98
99
  }
99
100
 
100
- /** Each integration line with its `mapping:` renamed by `rename`; nothing else in the line moves. */
101
+ /** The keys of an integration line that name a mapping. */
102
+ const MAPPING_KEYS = Object.freeze(['mapping', 'reply'])
103
+
104
+ /**
105
+ * Each integration line with the mappings it names (`mapping:`, `reply:`) renamed by `rename`;
106
+ * nothing else in the line moves — `reply_about` is a field, and a `filter` names fields.
107
+ */
101
108
  function mappingsNamed(integrations, rename) {
102
109
  return Object.fromEntries(
103
- Object.entries(integrations).map(([id, line]) =>
104
- isMap(line) && typeof line.mapping === 'string' ? [id, { ...line, mapping: rename(line.mapping) }] : [id, line]
105
- )
110
+ Object.entries(integrations).map(([id, line]) => {
111
+ if (!isMap(line)) return [id, line]
112
+ const out = { ...line }
113
+ for (const key of MAPPING_KEYS) if (typeof line[key] === 'string') out[key] = rename(line[key])
114
+ return [id, out]
115
+ })
106
116
  )
107
117
  }
108
118
 
@@ -175,7 +185,10 @@ export function blueprintFromWire(wire, { scope = null, own = null, local = null
175
185
  function mappingAsFileSpells(full, localIntegrations, scope) {
176
186
  if (isMap(localIntegrations)) {
177
187
  for (const line of Object.values(localIntegrations)) {
178
- if (isMap(line) && typeof line.mapping === 'string' && qualifyRef(line.mapping, scope) === full) return line.mapping
188
+ if (!isMap(line)) continue
189
+ for (const key of MAPPING_KEYS) {
190
+ if (typeof line[key] === 'string' && qualifyRef(line[key], scope) === full) return line[key]
191
+ }
179
192
  }
180
193
  }
181
194
  const org = bareOrg(scope)
@@ -310,22 +323,29 @@ export function blueprintWarnings(blueprint, { scope, declared, sending = false
310
323
  }
311
324
  }
312
325
  for (const [id, line] of Object.entries(isMap(blueprint.integrations) ? blueprint.integrations : {})) {
313
- const mapping = isMap(line) ? line.mapping : null
314
- if (typeof mapping !== 'string') continue
315
- const at = `integrations.${id}.mapping`
316
- if (!scoped && mapping.startsWith('@/') && sending) {
317
- out.push(
318
- `${BLUEPRINT_FILE}: \`${at}\` is the foundation's own mapping, and the foundation has no scope yet, ` +
319
- "so a push sends it as written — the backend never resolves an `@/x`. A foundation's scope is part " +
320
- "of its name — `name: '@org/<name>'` in its main.js, which `uniweb register` writes."
321
- )
322
- }
323
- if (declared?.mappings && !declared.mappings.has(qualifyRef(mapping, scope))) {
324
- out.push(
325
- `${BLUEPRINT_FILE}: \`${at}\` names a mapping none of this site's foundations declares, so a backend ` +
326
- `started from this site leaves the line out. Check the name against the foundation's src/mappings/.`
327
- )
328
- }
326
+ for (const key of MAPPING_KEYS) out.push(...mappingWarnings(line, id, key, { scoped, scope, declared, sending }))
327
+ }
328
+ return out
329
+ }
330
+
331
+ /** What one mapping an integration line names (`mapping:`, `reply:`) warns of. */
332
+ function mappingWarnings(line, id, key, { scoped, scope, declared, sending }) {
333
+ const mapping = isMap(line) ? line[key] : null
334
+ if (typeof mapping !== 'string') return []
335
+ const out = []
336
+ const at = `integrations.${id}.${key}`
337
+ if (!scoped && mapping.startsWith('@/') && sending) {
338
+ out.push(
339
+ `${BLUEPRINT_FILE}: \`${at}\` is the foundation's own mapping, and the foundation has no scope yet, ` +
340
+ "so a push sends it as written — the backend never resolves an `@/x`. A foundation's scope is part " +
341
+ "of its name — `name: '@org/<name>'` in its main.js, which `uniweb register` writes."
342
+ )
343
+ }
344
+ if (declared?.mappings && !declared.mappings.has(qualifyRef(mapping, scope))) {
345
+ out.push(
346
+ `${BLUEPRINT_FILE}: \`${at}\` names a mapping none of this site's foundations declares, so a backend ` +
347
+ `started from this site leaves the line out. Check the name against the foundation's src/mappings/.`
348
+ )
329
349
  }
330
350
  return out
331
351
  }