@uniweb/build 0.78.0 → 0.80.0

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
@@ -588,7 +587,7 @@ function listedNames(list) {
 //
 // ⛔ A top-level section never takes an `@` file: that is a child's name, and the build renders an
 // `@` file no `nest:` claims only as an orphan appended at the end — listed by name, it is not rendered.
-function existingSectionFile(pageDir, fileBase, stableId, { child = false } = {}) {
+export function existingSectionFile(pageDir, fileBase, stableId, { child = false } = {}) {
   if (!existsSync(pageDir)) return null
   const entries = readdirSync(pageDir).filter((e) => isMarkdownFile(e) && (child || !e.startsWith('@')))
   const found =
@@ -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,

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
-}