@uniweb/build 0.78.0 → 0.79.0

package/src/uwx/services-request.js

@@ -8,7 +8,7 @@
  *     exclude: { routes: [/legal] }           # an option the site's runtime reads
  *   submit: https://forms.example.com/f/abc   # an address: a provider the site brings
  *   tracking: { consent: required }
- *   api: { grade: pro }                       # a setting for the host's service
+ *   backend: { grade: pro }                   # a setting for the host's service
  * ```
  *
  * ⭐ ONE PLACE [Diego, 2026-10-06]. Until then the site's own provider and options
@@ -19,8 +19,8 @@
  * Each entry goes ONE place per lane, decided here and nowhere else:
  *
  *   - **a built site** reads it as its own config (`config.<name>` in the payload) —
- *     the switch, an address, the options. ⛔ For `api` only its switch and address:
- *     its settings are for the host that provisions it. Never a credential.
+ *     the switch, an address, the options. ⛔ For `backend` only its switch and
+ *     address: its settings are for the host that provisions it. Never a credential.
  *   - **a push** sends it as the request: ONE row per entry in the `services` Section,
  *     `{ name, enabled?: false, config? }`, whose `config` is the whole entry — an
  *     address, the options, the host's settings — never a credential. What reaches a
@@ -65,9 +65,27 @@ export const RUNTIME_KEYS = Object.freeze({
   submit: Object.freeze(['enabled', 'endpoint']),
   assistant: Object.freeze(['enabled', 'endpoint']),
   tracking: Object.freeze(['enabled', 'endpoint', 'emit', 'consent', 'scripts', 'flushIntervalMs', 'debug']),
-  api: Object.freeze(['enabled', 'endpoint'])
+  backend: Object.freeze(['enabled', 'endpoint'])
 })
 
+/**
+ * Services renamed, by their old name. The old name is refused wherever a service is
+ * named — an entry here, and a foundation's `uniweb.supports` — naming the new one.
+ *
+ * ⛔ No alias, and the reason is the runtime: a name no host offers resolves to
+ * nothing, so a site or a foundation still saying `api` would simply lose the service
+ * on every page, with nothing anywhere saying why. Here it stops where it is written.
+ *
+ * ⭐ `api` → `backend`, 2026-10-07 [Diego: "name the actual service, and not the
+ * interface of the service, which is a route named /api"]. The site's own backend is
+ * named for what it is; `/_api` stays the route it answers on, and `@uniweb/api` is
+ * named for that interface.
+ */
+export const RENAMED_SERVICES = Object.freeze({ api: 'backend' })
+
+/** `site.yml` keys renamed with a service — refused by the old name, like the services. */
+const RENAMED_SITE_KEYS = Object.freeze({ $devApi: '$devBackend' })
+
 /**
  * Services only a host provides, which a site never answers itself: no address, no
  * runtime part. A site does not declare its own record provider — a third-party
@@ -92,6 +110,106 @@ function stable(value) {
   )
 }
 
+/**
+ * YAML 1.1's words for a switch, which js-yaml — YAML 1.2 — reads as TEXT, and `true` /
+ * `false` written in quotes. ⛔ As text, `search: yes` was an address: the site's own
+ * search provider at `yes`, with the host's search asked OFF, while the CLI said
+ * "site.yml turns on search" (measured on 0.85.0, 2026-10-07 — F14).
+ */
+const SWITCH_WORDS = /^(y|yes|on|true|n|no|off|false)$/i
+const ON_WORDS = /^(y|yes|on|true)$/i
+
+/** What a value is, in words — for a message that says what was found. */
+function described(value) {
+  if (value === null || value === undefined) return 'empty'
+  if (Array.isArray(value)) return 'a list'
+  if (typeof value === 'string') return value.trim() ? `the text \`${value}\`` : 'empty'
+  return `\`${JSON.stringify(value)}\``
+}
+
+/** A switch written as a word: what it says, and what to write instead. */
+function switchWord(path, key, value) {
+  const on = ON_WORDS.test(value.trim())
+  return (
+    `\`${path}\` is the text \`${value}\`, not a switch — YAML reads yes, no, on and off as words. ` +
+    `Write \`${key}: ${on}\` to turn it ${on ? 'on' : 'off'}.`
+  )
+}
+
+/**
+ * What is wrong with one entry, or null when it is `true`, `false`, an address or a map —
+ * the one judgement both `readServicesRequest` and `refuseUnreadableServices` make.
+ */
+function entryProblem(name, value) {
+  if (RENAMED_SERVICES[name]) {
+    const now = RENAMED_SERVICES[name]
+    return (
+      `\`services.${name}\` is now \`services.${now}\` — the site's own backend is the \`${now}\` service. ` +
+      `Rename the entry; what it says stays. On a site you push, \`uniweb pull\` brings it renamed.`
+    )
+  }
+  if (typeof value === 'boolean') return null
+  if (typeof value === 'string') {
+    if (SWITCH_WORDS.test(value.trim())) return switchWord(`services.${name}`, name, value)
+    if (!value.trim()) return `\`services.${name}\` is empty — write true, false, an address, or a map.`
+    if (HOST_ONLY.has(name)) return `\`services.${name}\` has no address of its own — your host provides it. Write \`${name}: true\`.`
+    return null
+  }
+  if (!isMap(value)) return `\`services.${name}\` is true, false, an address, or a map — not ${described(value)}.`
+  if (value.enabled !== undefined && typeof value.enabled !== 'boolean') {
+    return typeof value.enabled === 'string' && SWITCH_WORDS.test(value.enabled.trim())
+      ? switchWord(`services.${name}.enabled`, 'enabled', value.enabled)
+      : `\`services.${name}.enabled\` is true or false — not ${described(value.enabled)}.`
+  }
+  if (typeof value.endpoint === 'string' && SWITCH_WORDS.test(value.endpoint.trim())) {
+    return `\`services.${name}.endpoint\` is the text \`${value.endpoint}\`, not an address — an address is a URL or a path. To turn the service on, leave \`endpoint\` out.`
+  }
+  if (HOST_ONLY.has(name) && addressOf(value)) {
+    return `\`services.${name}\` has no address of its own — your host provides it. Remove \`endpoint\`.`
+  }
+  return null
+}
+
+/**
+ * Every entry of `site.yml::services` that neither a build nor a push can read, each said
+ * with its fix — [] when there is none.
+ *
+ * @param {*} declared - the raw `services:` value
+ * @returns {string[]}
+ */
+export function unreadableServices(declared) {
+  if (declared === undefined || declared === null) return []
+  if (!isMap(declared)) return ['`services:` is a map of service names — `services: { search: true }`.']
+  return Object.entries(declared)
+    .map(([name, value]) => entryProblem(name, value))
+    .filter(Boolean)
+}
+
+/**
+ * Stop on a `services:` entry neither lane can read — beside `refuseRetiredServiceKeys`,
+ * in the static build and in the push.
+ *
+ * ⛔ NOT "warn and ignore it". A push states every service the file lists and OFF for each
+ * one this copy holds that it does not (`statedServices`), so an entry it skipped turned
+ * that service off — `search: 7`, or `records: /_query`, switched off on the site under a
+ * warning that said "Ignoring it" (until 2026-10-07). And a word for a switch was not
+ * skipped but read as an address, which asks the host to leave its own off (F14).
+ *
+ * @param {object} siteYml
+ * @param {string} [where]
+ * @throws {Error} naming each entry and what to write
+ */
+export function refuseUnreadableServices(siteYml, where = 'site.yml') {
+  if (!isMap(siteYml)) return
+  const found = unreadableServices(siteYml.services)
+  if (!found.length) return
+  throw new Error(
+    found.length === 1
+      ? `[uniweb] ${where}: ${found[0]}`
+      : `[uniweb] ${where}: \`services:\` has entries that cannot be read:\n${found.map((f) => `  - ${f}`).join('\n')}`
+  )
+}
+
 /** The address an entry names, or null — a string, or a map's `endpoint`. */
 function addressOf(value) {
   if (typeof value === 'string') return value.trim() || null
@@ -132,12 +250,20 @@ function sayCredentials(name, found, warn) {
  */
 export function refuseRetiredServiceKeys(siteYml, where = 'site.yml') {
   if (!isMap(siteYml)) return
+  const renamed = Object.keys(RENAMED_SITE_KEYS).filter((k) => siteYml[k] !== undefined)
+  if (renamed.length) {
+    throw new Error(
+      `[uniweb] ${where}: ${renamed.map((k) => `\`${k}:\` is now \`${RENAMED_SITE_KEYS[k]}:\``).join(', ')} — ` +
+        "it names what answers the site's `backend` service in `uniweb dev`. Rename the key; its value stays."
+    )
+  }
   const found = RETIRED_SERVICE_KEYS.filter((k) => siteYml[k] !== undefined)
   if (!found.length) return
-  const lines = found.map((k) => `  ${k}: …`).join('\n')
+  // The block to move them into names each service as `services:` does now.
+  const lines = found.map((k) => `  ${RENAMED_SERVICES[k] || k}: …`).join('\n')
   const api = found.includes('api')
-    ? '\n  `api:` named the address a local mock answered on — in `uniweb dev`, `$devApi` now ' +
-      'supplies it. Asking your host for an app backend is `api: true` under `services:`.'
+    ? '\n  `api:` named the address a local mock answered on — in `uniweb dev`, `$devBackend` now ' +
+      "supplies it. Asking your host for the site's own backend is `backend: true` under `services:`."
     : ''
   throw new Error(
     `[uniweb] ${where}: ${found.map((k) => `\`${k}:\``).join(', ')} ` +
@@ -148,10 +274,10 @@ export function refuseRetiredServiceKeys(siteYml, where = 'site.yml') {
 
 /**
  * Services whose settings are never published: only the switch and the address reach
- * the site's config. `api`'s settings are for the host that provisions it (a grade,
+ * the site's config. `backend`'s settings are for the host that provisions it (a grade,
  * sign-in providers, billing) and no page reads them.
  */
-const UNPUBLISHED_SETTINGS = new Set(['api'])
+const UNPUBLISHED_SETTINGS = new Set(['backend'])
 
 /**
  * One entry → what the site's config carries: `false`, an address, or the entry's
@@ -217,6 +343,14 @@ export function readServicesRequest(declared, { warn = () => {} } = {}) {
   }
   const asks = []
   for (const [name, value] of Object.entries(declared)) {
+    // ⚠️ Skipped here for a caller that only reads; the build and the push stop on it
+    // first (`refuseUnreadableServices`), since a push would state a skipped one off.
+    // First, so a renamed service is skipped whatever its value — `true` included.
+    const problem = entryProblem(name, value)
+    if (problem) {
+      warn(`${problem} Ignoring \`${name}\`.`)
+      continue
+    }
     if (value === true) {
       asks.push({ name })
       continue
@@ -225,31 +359,18 @@ export function readServicesRequest(declared, { warn = () => {} } = {}) {
       asks.push({ name, enabled: false })
       continue
     }
-    if (typeof value !== 'string' && !isMap(value)) {
-      warn(`\`services.${name}\` is true, false, an address, or a map. Ignoring it.`)
-      continue
-    }
-    if (isMap(value) && value.enabled !== undefined && typeof value.enabled !== 'boolean') {
-      warn(`\`services.${name}.enabled\` is true or false. Ignoring \`${name}\`.`)
-      continue
-    }
     const address = addressOf(value)
-    if (typeof value === 'string' && !address) continue // an empty string asks nothing
-    if (address && HOST_ONLY.has(name)) {
-      warn(`\`services.${name}\` has no address of its own — your host provides it. Ignoring \`${name}\`.`)
-      continue
-    }
     const { enabled, ...entry } = isMap(value) ? value : { endpoint: address }
     const { value: config, found } = withoutCredentials(entry)
     sayCredentials(name, found, warn)
     if (address) {
       config.endpoint = address
-      // ⚠️ Said for `api` because its old spelling invites it: `api: /_api` was where a
-      // local mock answered, and under `services:` an address turns the host's off.
-      if (name === 'api') {
+      // ⚠️ Said for `backend` because its old spelling invites it: `api: /_api` was where
+      // a local mock answered, and under `services:` an address turns the host's off.
+      if (name === 'backend') {
         warn(
-          "`services.api` is an address: it asks your host to leave its own `api` off, so the site uses yours. " +
-            "For your host's, write `api: true`; in `uniweb dev`, `$devApi` answers it."
+          "`services.backend` is an address: it asks your host to leave its own `backend` off, so the site uses yours. " +
+            "For your host's, write `backend: true`; in `uniweb dev`, `$devBackend` answers it."
         )
       }
     }

package/src/uwx/site-project.js

@@ -56,7 +56,6 @@ import { siteContentDirs } from './site-dirs.js'
 import { layoutAreaRoute } from '../site/layout-folder.js'
 import { orderFolders, rootOrderConfig, parseNumericPrefix, parseWildcardArray, composeLocalizedRoute, stripAtPrefix, compareFilenames } from '../site/content-collector.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
-import { upsertYamlScalar } from './yaml-upsert.js'
 
 // The pull-side identity index: a per-clone, GITIGNORED `uuid → relative path`
 // map under `.uniweb/`, the home for the backend's per-item identity so that
@@ -1155,7 +1154,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
       const listed = Array.isArray(root.pages) ? parseWildcardArray(root.pages) : null
       // A list that names the homepage first beats `index:`, so it opens with `...` instead.
       if (listed && listed.before.length > 0) root.write(['...', ...root.pages.filter((e) => e !== '...')])
-      upsertYamlScalar(join(siteRoot, 'site.yml'), 'index', ctx.homepage)
+      writeSiteConfig(siteRoot, { index: ctx.homepage })
     }
   }
   projectLayout(document?.layout_sections, layoutBaseDir, report, prune, ctx)

package/src/uwx/site.js

@@ -83,9 +83,9 @@ import { updateBackendState, readBackendState } from './sync-store.js'
 import {
   readServicesRequest,
   statedServices,
-  refuseRetiredServiceKeys
+  refuseRetiredServiceKeys,
+  refuseUnreadableServices
 } from './services-request.js'
-import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveQueriesConfig } from './queries-config.js'
 import { resolveSelfScope, siteSelfScope, refuseOrgOption } from './self-scope.js'
 import { siteContentDirs } from './site-dirs.js'
@@ -1372,6 +1372,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   refuseOrgOption(opts, 'uwx/site')
   const siteYml = await readYamlFile(join(siteRoot, 'site.yml'))
   refuseRetiredServiceKeys(siteYml)
+  refuseUnreadableServices(siteYml)
   const sourceLocale = opts.sourceLocale || resolveDefaultLocale(siteYml)
   if (!siteYml.name) {
     throw new Error('uwx/site: site.yml::name is required')
@@ -1477,12 +1478,13 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // KEYED FIELD: one embedded in an endpoint URL (`https://collector/e?key=…`) is
   // invisible there and is disclosed. The host's secret store is the only right home.
   //
-  // ⛔ `api`'S ADDRESS IS THE HOST'S TO SUPPLY — `config.services.api`, read by
-  // `@uniweb/api` (`resolveBase`). Asking for it is `services: { api: true }`, or a map
-  // of the host's settings; an address of the site's own asks the host to leave its own
-  // off, and `readServicesRequest` says so, because `api: /_api` — where a local mock
-  // used to answer — reads that way. In `uniweb dev`, `$devApi` supplies the mock's
-  // address (`dev/api-mount.js`).
+  // ⛔ `backend`'S ADDRESS IS THE HOST'S TO SUPPLY — `config.services.backend`, read by
+  // `@uniweb/api` (`resolveBase`). Asking for it is `services: { backend: true }`, or a
+  // map of the host's settings; an address of the site's own asks the host to leave its
+  // own off, and `readServicesRequest` says so, because `/_api` — where a local mock
+  // used to answer — reads that way. In `uniweb dev`, `$devBackend` supplies the mock's
+  // address (`dev/api-mount.js`). *(The service was `api` until 2026-10-07; that name is
+  // refused — `RENAMED_SERVICES`.)*
   // ⛔ THE CONFIGURATION KEYS ARE NOT HERE — they ride the `settings` Section
   // (`settingsNested` above). `info` is the BRIEF: what a card or a select dropdown
   // renders, plus what a listing can filter on. Eighteen keys moved off it on

package/src/uwx/yaml-edit.js

@@ -0,0 +1,288 @@
+// Edits to a YAML file an author wrote — ONE engine, `editYamlText`, for everything
+// in the framework that changes such a file.
+//
+// `site.yml`, `theme.yml`, `page.yml`, `queries.yml` are hand-authored — they carry
+// comments, blank lines and an author-chosen layout. Round-tripping them through
+// js-yaml (load → dump) discards every comment and re-flows the file. So nothing
+// writes one whole: the engine rewrites only the entries that change.
+//
+//   - `editYamlText(text, before, after)` — the engine: text in, text out.
+//   - `setYamlKey` / `replaceInYamlList` — the two edits a command decides on before
+//     it writes anything (`uniweb rename`), as text, so a file it cannot edit stops
+//     the command while nothing has moved.
+//   - Writing a file goes through `project-writer.js` (`writeSiteConfig`,
+//     `writeThemeFile`, …), which reads it, merges, and hands the engine both values.
+//
+// ⛔ *Until 2026-10-07 there were three: this module's line-level `upsertYamlScalar`
+// and `removeYamlScalar` (one top-level scalar line), the CLI's `utils/yaml-edit.js`
+// (`setTopLevelScalar`, `replaceInTopLevelList`), and the engine. The two line-level
+// ones refused or misplaced what the engine edits — a block scalar, a list entry
+// beside a comment, a new key PREPENDED above a file's header comments.*
+
+import yaml from 'js-yaml'
+import { parseDocument, isMap, isSeq, isScalar, Scalar, visit } from 'yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+
+/** js-yaml's options for every value the framework writes into YAML, so output is byte-stable. */
+export const YAML_DUMP_OPTS = { lineWidth: -1, quotingType: "'", forceQuotes: false, noRefs: true }
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+/** Deep equality of two values read from YAML: sorted-key JSON. */
+const sameValue = (a, b) => {
+  const canonical = (v) =>
+    JSON.stringify(v, (_k, x) => (isPlainObject(x) ? Object.fromEntries(Object.keys(x).sort().map((k) => [k, x[k]])) : x))
+  return canonical(a) === canonical(b)
+}
+
+/** Offset of the start of the line holding `pos`. */
+const lineStart = (text, pos) => text.lastIndexOf('\n', pos - 1) + 1
+
+/** The column a block map's key starts at — null when anything but spaces precedes it (`- key:`). */
+function columnOf(text, key) {
+  const start = lineStart(text, key.range[0])
+  const lead = text.slice(start, key.range[0])
+  return /^ *$/.test(lead) ? lead.length : null
+}
+
+/** Where a pair's text ends: after its value, its trailing comment and its newline. */
+function pairEnd(text, pair) {
+  let end = (pair.value ?? pair.key).range[2]
+  if (text[end - 1] !== '\n') {
+    const nl = text.indexOf('\n', end)
+    const rest = nl === -1 ? text.slice(end) : text.slice(end, nl)
+    if (/^\s*(#.*)?$/.test(rest)) end = nl === -1 ? text.length : nl + 1
+  }
+  return end
+}
+
+/** Every line but the first — or every line, for text that starts a line — indented to `col`. */
+function indented(text, col, first) {
+  if (!col) return text
+  const pad = ' '.repeat(col)
+  return text
+    .split('\n')
+    .map((line, i) => (line && (i > 0 || first) ? pad + line : line))
+    .join('\n')
+}
+
+/** An alias or a `<<` merge key: one edit could change what another place says. */
+function usesReferences(doc) {
+  let found = false
+  visit(doc, {
+    Alias() {
+      found = true
+      return visit.BREAK
+    },
+    Pair(_, pair) {
+      if (isScalar(pair.key) && pair.key.value === '<<') {
+        found = true
+        return visit.BREAK
+      }
+    }
+  })
+  return found
+}
+
+/**
+ * A scalar written where `node` stood — in the node's quotes when it was quoted and the
+ * new value is text (`"…"` stays `"…"`), else as js-yaml writes it; inside a flow
+ * collection, in a form that cannot run into the next entry. Null when it does not fit
+ * on one line, or `node` spans lines.
+ */
+function scalarText(text, node, value, dump, inFlow) {
+  if (!node.range || node.range[1] <= node.range[0]) return null
+  if (text.slice(node.range[0], node.range[1]).includes('\n')) return null
+  if (value !== null && typeof value === 'object') return null
+  let out
+  if (typeof value === 'string' && node.type === Scalar.QUOTE_DOUBLE) out = JSON.stringify(value)
+  else if (typeof value === 'string' && node.type === Scalar.QUOTE_SINGLE) out = `'${value.replace(/'/g, "''")}'`
+  else if (inFlow) {
+    const list = dump([value], { flowLevel: 0 }).trim()
+    if (!list.startsWith('[') || !list.endsWith(']')) return null
+    out = list.slice(1, -1)
+  } else out = dump(value).replace(/\n$/, '')
+  return out.includes('\n') ? null : out
+}
+
+/**
+ * Make one list say `after` — `before` is what it says now, the same length — by
+ * rewriting each changed entry where it stands. False for anything else (a list that
+ * grew or shrank, an entry that is not a one-line scalar): the caller writes it whole.
+ */
+function editSeq(text, seq, before, after, edits, dump) {
+  if (seq.items.length !== before.length || before.length !== after.length) return false
+  const inner = []
+  for (let i = 0; i < after.length; i++) {
+    if (sameValue(before[i], after[i])) continue
+    const node = seq.items[i]
+    const now = isScalar(node) ? scalarText(text, node, after[i], dump, seq.flow) : null
+    if (now === null) return false
+    inner.push({ start: node.range[0], end: node.range[1], text: now })
+  }
+  edits.push(...inner)
+  return true
+}
+
+/**
+ * Make one block map say `after` — `before` is what it says now — by edits to its own
+ * entries: a removed key's lines go, a changed scalar is rewritten where it stands, a
+ * changed map or same-length list is edited the same way one level down, anything else
+ * is written whole in its place, and a new key goes after the last one. False when the
+ * map is not one this can edit (a key that is not a plain scalar, or not first on its line).
+ */
+function editMap(text, map, before, after, edits, dump) {
+  if (!map.items.length || !map.items[0].key?.range) return false
+  const col = columnOf(text, map.items[0].key)
+  if (col === null) return false
+  const seen = new Set()
+  let end = 0
+  for (const pair of map.items) {
+    if (!isScalar(pair.key) || !pair.key.range || columnOf(text, pair.key) !== col) return false
+    const key = String(pair.key.value)
+    if (seen.has(key)) return false
+    seen.add(key)
+    const value = pair.value
+    const stop = pairEnd(text, pair)
+    end = Math.max(end, stop)
+    if (!Object.hasOwn(after, key) || after[key] === undefined) {
+      edits.push({ start: lineStart(text, pair.key.range[0]), end: stop, text: '' })
+      continue
+    }
+    if (Object.hasOwn(before, key) && sameValue(before[key], after[key])) continue
+    const next = after[key]
+    const inner = []
+    if (isMap(value) && !value.flow && isPlainObject(before[key]) && isPlainObject(next)) {
+      if (editMap(text, value, before[key], next, inner, dump)) {
+        edits.push(...inner)
+        continue
+      }
+    } else if (isSeq(value) && Array.isArray(before[key]) && Array.isArray(next)) {
+      if (editSeq(text, value, before[key], next, inner, dump)) {
+        edits.push(...inner)
+        continue
+      }
+    } else if (isScalar(value)) {
+      const now = scalarText(text, value, next, dump, false)
+      if (now !== null) {
+        edits.push({ start: value.range[0], end: value.range[1], text: now })
+        continue
+      }
+    }
+    // Written whole — in flow style when the author wrote it that way (`tags: [a, b]`).
+    const flow = (isMap(value) || isSeq(value)) && value.flow
+    edits.push({
+      start: pair.key.range[0],
+      end: stop,
+      text: indented(dump({ [key]: next }, flow ? { flowLevel: 1 } : {}), col, false)
+    })
+  }
+  for (const key of Object.keys(after)) {
+    if (seen.has(key) || after[key] === undefined) continue
+    const lead = end > 0 && text[end - 1] !== '\n' ? '\n' : ''
+    edits.push({ start: end, end, text: lead + indented(dump({ [key]: after[key] }), col, true) })
+  }
+  return true
+}
+
+/**
+ * Edit the YAML `text` so it says `after` — `before` is what it says now, as the build
+ * reads it — changing only the entries that differ, and leaving every other byte as its
+ * author wrote it: comments, blank lines, key order, quoting, a list written on one line.
+ *
+ * ⭐ `yaml` LOCATES, js-yaml WRITES AND READS. The comment-preserving library parses the
+ * text for where each entry sits; a changed entry is rendered by js-yaml, as the writers
+ * render a whole file — keeping the quotes it had, where it had them; and the result is
+ * read back by the build's own reader, and kept only if it says exactly `after`. ⛔ Not
+ * `yaml`'s Document API, edited and printed: it prints the WHOLE file again, and with no
+ * edit at all it changed 16 of the 17 template `site.yml` files — long lines folded,
+ * `[a, b]` padded to `[ a, b ]` — and with the best options still 4 of 17, comments moved
+ * onto a key's line or indented under the map before them (measured 2026-10-07). Every
+ * such line is one a pull did not change, and a conflict waiting in a merge.
+ *
+ * ⛔ *Until 2026-10-07 the writers dumped the whole file, and a pull that changed one key
+ * of `site.yml` left the Starter template's 93 lines as 10 — every comment gone — and a
+ * `pull --merge` then conflicted on the whole commented header (F1, F12).*
+ *
+ * @param {string} text - the file as it is
+ * @param {object} before - what it says, read by the build's reader
+ * @param {object} after - what it must say
+ * @param {object} [dumpOptions] - js-yaml's, for what is written
+ * @returns {string|null} the edited text; null when the file cannot be edited in place —
+ *   not a map, an alias or merge key, a parse error, or a result that reads differently
+ */
+export function editYamlText(text, before, after, dumpOptions = YAML_DUMP_OPTS) {
+  if (typeof text !== 'string' || !isPlainObject(before) || !isPlainObject(after)) return null
+  let doc
+  try {
+    doc = parseDocument(text)
+  } catch {
+    return null
+  }
+  if (doc.errors.length || usesReferences(doc)) return null
+  const dump = (value, extra = {}) => yaml.dump(value, { ...dumpOptions, ...extra })
+  const edits = []
+  if (doc.contents === null || doc.contents === undefined) {
+    // Comments and nothing else: what the file says goes after them.
+    const lead = text && !text.endsWith('\n') ? '\n' : ''
+    edits.push({ start: text.length, end: text.length, text: lead + dump(after) })
+  } else if (!isMap(doc.contents) || doc.contents.flow || !editMap(text, doc.contents, before, after, edits, dump)) {
+    return null
+  }
+  // Last first, so an offset is never moved by an edit before it. At one offset: a removal
+  // before an insertion, and the outer map's new keys before the inner map's, so the inner
+  // map's land first in the text.
+  const order = edits.map((e, i) => ({ ...e, i })).sort((a, b) => b.start - a.start || b.end - a.end || b.i - a.i)
+  let out = text
+  for (const e of order) out = out.slice(0, e.start) + e.text + out.slice(e.end)
+  let read
+  try {
+    read = yaml.load(out, YAML_OPTIONS) ?? {}
+  } catch {
+    return null
+  }
+  return sameValue(read, after) ? out : null
+}
+
+/** What `text` says, as the build reads it — null when it is not YAML, or not a map. */
+function readMap(text) {
+  try {
+    const data = yaml.load(text, YAML_OPTIONS) ?? {}
+    return isPlainObject(data) ? data : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Set top-level `key` to `value` in `text` — added after the last key when it is not
+ * there — editing nothing else.
+ *
+ * @param {string} text - the file's contents
+ * @param {string} key - a top-level key, e.g. `foundation`
+ * @param {*} value
+ * @returns {string|null} the new contents; null when the text cannot be edited in place
+ *   (`editYamlText`) — a caller deciding before it writes refuses then
+ */
+export function setYamlKey(text, key, value) {
+  const before = readMap(text)
+  return before ? editYamlText(text, before, { ...before, [key]: value }) : null
+}
+
+/**
+ * Replace entries of the top-level list `key` — each `from` entry becomes its `to` — where
+ * they stand, in the quotes they were written in. An entry that only CONTAINS `from` is
+ * left alone, and so is everything else in the file.
+ *
+ * @param {string} text - the file's contents
+ * @param {string} key - a top-level list key, e.g. `extensions`
+ * @param {Map<*, *>} replacements - old entry → new entry
+ * @returns {string|null} the new contents; null when `key` is not a list, or the text
+ *   cannot be edited in place
+ */
+export function replaceInYamlList(text, key, replacements) {
+  const before = readMap(text)
+  if (!before || !Array.isArray(before[key])) return null
+  const list = before[key].map((v) => (replacements.has(v) ? replacements.get(v) : v))
+  return editYamlText(text, before, { ...before, [key]: list })
+}

package/src/validate-data.js

@@ -31,7 +31,7 @@ import { YAML_OPTIONS } from './utils/yaml-schema.js'
 import { queryNameFromUrl, declaredKeys, fillDeclaredKeys, fetchLevels, pageRouteQuery } from '@uniweb/core'
 import { parentRouteOf } from '@uniweb/core/route-match'
 
-import { validateItem, validateRecordFile, validateBound, contentBodyField, rootListSection, referencesOf } from '@uniweb/schemas/conform'
+import { validateItem, validateRecordFile, validateBound, validateKeyValue, contentBodyField, rootListSection, referencesOf } from '@uniweb/schemas/conform'
 import { isUuid } from './uwx/uuid.js'
 import { validateAndNormalizeSchema, buildDataSchemaMap } from './resolve-data-schema.js'
 
@@ -147,6 +147,10 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
       // `@uniweb/core/page-data`) — ⛔ it wrote its own list until 2026-09-19, which read only
       // the declared parent and had no route binding for a nested page.
       const declared = declaredKeys(bindings)
+      // Each key's schema ref as the runtime reads it — never the raw value, whose spelling varies
+      // (⛔ until 2026-10-07 a `'…/*'` value was looked up whole here, matched no schema, and its
+      // key was never checked).
+      const refOf = new Map(declared.map(([key, ref]) => [key, ref]))
       const levels = fetchLevels({ own: section.fetch, page: page.fetch, parent, route, site: config.fetch })
       const inputs = collectInputs(levels)
       const held = nodesOfType(section.content, 'dataBlock').map((node) => node.attrs?.tag).filter(Boolean)
@@ -194,8 +198,7 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
         }
         if (!input.path) continue
 
-        const binding = bindings?.[key]
-        const ref = typeof binding === 'string' ? binding : binding?.schema
+        const ref = refOf.get(key)
         if (!ref) continue // ungoverned key — no schema declared for it
 
         const schema = dataSchemas[ref]
@@ -480,9 +483,12 @@ function nodesOfType(doc, type) {
  * becomes one (it falls back to `codeBlock`), so a malformed block cannot reach
  * here and be misreported as a schema violation.
  *
- * Uses `validateBound` rather than `validateItem` because a block's value may be
- * a record OR a list — ```` ```yaml:nav ```` is a bare array. That dispatch is the
- * reason root-list conformance had to land first.
+ * ⭐ A block holds what its key DECLARES (ruled 2026-10-07 [Diego]): a list of records, or one
+ * with `single: true`; each its brief, or as stored with `whole: true`; a list schema's list either
+ * way — `validateKeyValue`, the one rule for a key's value. ⛔ Until 2026-10-07 the schema's root
+ * alone decided (`validateBound`), so a block under a key typed by a record schema had to hold ONE
+ * record while a query under the same key delivered a list — and a key declared `'…/*'` was looked
+ * up with its suffix, matched no schema, and was never checked.
  *
  * @param {Object} site - collected site content
  * @param {Object} foundation - the built foundation schema (type → { data })
@@ -501,16 +507,17 @@ export function validateTaggedDataBlocks(site, foundation, dataSchemas) {
       const bindings = type && foundation?.[type]?.data
       if (!bindings || typeof bindings !== 'object') return
 
+      const declared = new Map(declaredKeys(bindings).map(([key, ref, whole, single]) => [key, { ref, whole, single }]))
       for (const node of nodesOfType(section.content, 'dataBlock')) {
         const tag = node.attrs?.tag
         if (!tag) continue
 
-        const binding = bindings[tag]
-        if (binding === undefined) continue // this key is not governed — say nothing
+        const declaration = declared.get(tag)
+        if (declaration === undefined) continue // this key is not governed — say nothing
 
-        // A binding is a named ref, or an inline schema. Only a ref resolves to a
+        // A key is typed by a named ref, or by an inline schema. Only a ref resolves to a
         // normalized schema here; an inline one is reported rather than guessed at.
-        const ref = typeof binding === 'string' ? binding : binding?.schema
+        const { ref, whole, single } = declaration
         if (typeof ref !== 'string') {
           deferred.push({ route: page.route, section: type, key: tag, reason: 'inline schema on the binding' })
           continue
@@ -520,7 +527,7 @@ export function validateTaggedDataBlocks(site, foundation, dataSchemas) {
 
         schemas.add(ref)
         checked++
-        for (const finding of validateBound(schema, node.attrs?.data)) {
+        for (const finding of validateKeyValue(schema, node.attrs?.data, { whole, single })) {
           violations.push({
             file: `${page.route || '/'} › ${type} › ${node.attrs?.language || 'yaml'}:${tag}`,
             schema: ref,