@uniweb/build 0.77.0 → 0.79.0

package/src/uwx/sync-package.js

@@ -28,6 +28,7 @@ import { siteProjectToDocument } from './site.js'
 import { siteSelfScope, refuseOrgOption } from './self-scope.js'
 import { stampUnitUuids, collectUnitUuids } from './site-diff.js'
 import { emitEntitySyncPackage } from './entity-document.js'
+import { recordQueriesShown } from './shown-records.js'
 import { isLocalAssetPath } from '../site/assets.js'
 
 const SITE_MODEL_NAME = '@uniweb/site-content'
@@ -42,17 +43,28 @@ const cacheKey = (entity) => `${entity.model} ${entity.id}`
 // uuid→version map (the sync-cache); an entity the map doesn't know is left
 // unconditional rather than guessed at. See entity-document.js for what the
 // token means on the wire.
-const withBaseVersion = (baseVersions, itemBaseVersions) => (entity) => {
+const withBaseVersion = (baseVersions, itemBaseVersions, { every = false } = {}) => (entity) => {
   const uuid = entity?.document?.$uuid
   const v = uuid ? baseVersions[uuid] : null
-  // Per-item preconditions, narrowed to the records THIS package actually carries.
-  // The cache spans the whole site, but a package holds only what changed; sending
-  // tokens for absent records would bloat the manifest and assert preconditions on
-  // items we are not touching.
+  // Per-item preconditions.
+  //
+  // ⭐ THE SITE-CONTENT ENTITY SENDS EVERY VERSION THIS COPY HOLDS (`every`), for items
+  // present AND for items the files dropped. A push deletes only the items it holds a
+  // version for, and only while the site left them unchanged — so a dropped item's
+  // version is what makes leaving it out a deletion, and without it the item is kept
+  // [Diego, 2026-10-07; backend's gate, kb/framework/plans/services-exchange.md]. The
+  // caller holds a version only for an item it has seen (`heldTokens`, cli), so none is
+  // ever sent for an item the backend holds and this copy does not.
+  // ⛔ Until then this narrowed to the units the document carried: a dropped page was
+  // deleted by today's rule anyway, and nothing else was sent a version.
+  //
+  // Any other entity: narrowed to the units it carries, as before — the records lane
+  // is gated by its entity version, and sends none.
   let items = null
   if (itemBaseVersions && Object.keys(itemBaseVersions).length) {
     items = {}
-    for (const itemUuid of Object.values(collectUnitUuids(entity.document))) {
+    const uuids = every ? Object.keys(itemBaseVersions) : Object.values(collectUnitUuids(entity.document))
+    for (const itemUuid of uuids) {
       const t = itemBaseVersions[itemUuid]
       if (t) items[itemUuid] = t
     }
@@ -215,8 +227,6 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  * @param {string} [opts.sourceLocale]    - localized-field wrap locale
  * @param {Object<string,string>} [opts.priorHashes] - sync-cache (send-only-changed)
  * @param {boolean} [opts.sendAll]        - bypass the prior-hash filter
- * @param {object[]} [opts.serviceRows]   - the `services` Section to send, as the
- *                                          caller decided it (site.js `requestedServices`)
  * @param {Object<string,string>} [opts.itemUuids] - unit path → backend `$uuid`,
  *        stamped onto the site-content document so the backend matches our items
  *        instead of re-minting them (which deletes and recreates every page and
@@ -225,11 +235,12 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  *        identity of its list items, as a previous push or pull banked it
  *        (`record-items.js`); stamped onto each record the backend holds, so a re-sent
  *        record updates its items instead of replacing them.
- * @param {Object<string,string>} [opts.itemBaseVersions] - record `$uuid` → opaque
- *        per-ITEM `version`. Narrowed at emit to the records the package carries and
- *        sent as `entries[].item_base_versions`, so the backend can refuse only the
- *        records that genuinely moved instead of the whole document. Omit to push
- *        those records unconditionally.
+ * @param {Object<string,string>} [opts.itemBaseVersions] - item `$uuid` → opaque
+ *        per-ITEM `version`, for every site-content item this copy has seen. Sent
+ *        whole on the site-content entity as `entries[].item_base_versions` — items
+ *        present and items the files dropped — so the backend refuses only the items
+ *        that genuinely moved, and deletes only what this copy saw (`withBaseVersion`).
+ *        Omit to push unconditionally.
  * @param {Object<string,string>} [opts.baseVersions] - backend-uuid → opaque
  *        `version` token, the push gate's optimistic-concurrency precondition.
  *        Each sent entity whose `$uuid` the map knows carries it as a top-level
@@ -292,6 +303,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const priorHashes = opts.priorHashes || {}
   const sendAll = !!opts.sendAll
   const stamp = withBaseVersion(opts.baseVersions || {}, opts.itemBaseVersions || {})
+  const stampSite = withBaseVersion(opts.baseVersions || {}, opts.itemBaseVersions || {}, { every: true })
   const exporter = opts.exporter
   const exportedAt = opts.exportedAt
   refuseOrgOption(opts, 'emitSyncPackages')
@@ -376,13 +388,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
         // and the page and `settings` keys that carry Open Graph texts per language.
         ...(Array.isArray(opts.queryFields) ? { queryFields: opts.queryFields } : {}),
         ...(Array.isArray(opts.pageFields) ? { pageFields: opts.pageFields } : {}),
-        ...(Array.isArray(opts.settingsFields) ? { settingsFields: opts.settingsFields } : {}),
-        // The `services` Section as the caller decided it — the site's rows with the
-        // owner's changed asks applied — or the Sections withheld. Passed through
-        // rather than decided here: the site's rows and the last agreement are what
-        // the CLI reads. See site.js at `requestedServices`.
-        ...(Array.isArray(opts.serviceRows) ? { serviceRows: opts.serviceRows } : {}),
-        ...(opts.declareServices === false ? { declareServices: false } : {})
+        ...(Array.isArray(opts.settingsFields) ? { settingsFields: opts.settingsFields } : {})
       })
     : null
   // Deploy-derived `info` fields are stamped here — NOT authored in site.yml, so they
@@ -584,7 +590,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   // --- site-content lane -------------------------------------------------------
   let siteContent = null
   if (siteEntity && changed(siteEntity)) {
-    siteContent = { ...emitLane([stamp(siteEntity)], exporter, exportedAt), index: [{ kind: 'site' }] }
+    siteContent = { ...emitLane([stampSite(siteEntity)], exporter, exportedAt), index: [{ kind: 'site' }] }
   }
 
   // The site's current uuid (from site.yml): the verb keys the folder push route on
@@ -636,5 +642,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     // records this package SENDS that the backend holds with list items and no bank entry
     // (their uuids) — sent as they are, the backend refuses each one (`identity_required`).
     recordItemIdentity,
+    // The queries whose records the site's pages show live — what the `records` service
+    // delivers on a published site (`shown-records.js`). Whether it changed or not.
+    recordsShown: siteDoc ? recordQueriesShown(siteDoc) : [],
   }
 }

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,

package/src/uwx/yaml-upsert.js

@@ -1,79 +0,0 @@
-// Surgical, comment-preserving upsert of a TOP-LEVEL scalar key in a YAML file.
-//
-// `site.yml` and `collections.yml` are hand-authored — they carry comments and an
-// author-chosen key order. Round-tripping them through js-yaml (load → dump) would
-// discard every comment and re-flow the file. The sync back-fill only ever needs to
-// write ONE machine-owned scalar (the entity `$uuid`) into such a file, so we edit
-// the single line in place and leave the rest byte-for-byte.
-//
-// Scope, stated: top-level (column-0) scalar keys only — which is all `$uuid` ever
-// is. Not a general YAML writer; do not reach for it to set nested or list values.
-
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
-import { dirname } from 'node:path'
-
-// A top-level `key:` line (column 0, no leading space), capturing any inline value.
-function topLevelKeyLine(key) {
-  // Escape regex metachars in the key (`$uuid` contains `$`).
-  const esc = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-  return new RegExp(`^${esc}:[^\\n]*$`, 'm')
-}
-
-/**
- * Set `key: value` at the top level of the YAML file at `filePath`, preserving all
- * other lines (comments included). If the key already exists at column 0, its line
- * is replaced; otherwise a new line is prepended (machine-owned identity reads
- * cleanest at the top). The file (and its directory) is created if absent.
- *
- * @param {string} filePath
- * @param {string} key    - a top-level scalar key (e.g. `$uuid`)
- * @param {string} value  - the scalar value, written verbatim (uuids need no quoting)
- * @returns {boolean} true if the file changed
- */
-export function upsertYamlScalar(filePath, key, value) {
-  const line = `${key}: ${value}`
-  let text = ''
-  if (existsSync(filePath)) text = readFileSync(filePath, 'utf8')
-
-  const re = topLevelKeyLine(key)
-  let next
-  if (re.test(text)) {
-    next = text.replace(re, line)
-  } else if (text.length === 0) {
-    next = line + '\n'
-  } else {
-    // Prepend, keeping the rest intact (and a trailing newline if the file lacked one).
-    const body = text.endsWith('\n') ? text : text + '\n'
-    next = line + '\n' + body
-  }
-  if (next === text) return false
-  mkdirSync(dirname(filePath), { recursive: true })
-  writeFileSync(filePath, next)
-  return true
-}
-
-/**
- * Remove a TOP-LEVEL scalar key from the YAML file at `filePath`, preserving every
- * other line (comments included) — the inverse of `upsertYamlScalar`, with the same
- * scope: one `key: value` line at column 0. A key followed by indented lines, or
- * opening a block scalar (`|` / `>`), is not a one-line scalar and is left alone
- * rather than half-removed.
- *
- * @param {string} filePath
- * @param {string} key - a top-level scalar key (e.g. `preview`)
- * @returns {boolean} true if the file changed
- */
-export function removeYamlScalar(filePath, key) {
-  if (!existsSync(filePath)) return false
-  const lines = readFileSync(filePath, 'utf8').split('\n')
-  const esc = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-  const re = new RegExp(`^${esc}:(.*)$`)
-  const at = lines.findIndex((l) => re.test(l))
-  if (at === -1) return false
-  const inline = lines[at].replace(re, '$1').trim()
-  const continues = at + 1 < lines.length && /^[ \t]+\S/.test(lines[at + 1])
-  if (continues || /^[|>]/.test(inline)) return false
-  lines.splice(at, 1)
-  writeFileSync(filePath, lines.join('\n'))
-  return true
-}