uniweb 0.56.9 → 0.56.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.56.9",
+  "version": "0.56.11",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,11 +41,11 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
+    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/core": "^0.29.4",
     "@uniweb/runtime": "^0.26.4",
+    "@uniweb/schemas": "^0.3.3",
     "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/schemas": "^0.3.2",
-    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/kit": "^0.19.3"
   },
   "peerDependencies": {

package/src/backend/foundation-bring-along.js

@@ -40,6 +40,7 @@ import { detectFoundationType, isExtensionUrl } from '@uniweb/build'
 import { computeFoundationDigest } from '../utils/code-upload.js'
 import { readFlagValue } from '../utils/args.js'
 import { isNonInteractive } from '../utils/interactive.js'
+import { compareSemverPrecedence } from '../utils/semver-precedence.js'
 
 /**
  * Resolve the site's LOCAL foundation — the one publish should bring along — or
@@ -117,13 +118,19 @@ export function resolveLocalExtensions(siteDir, siteYml) {
 }
 
 // The foundation's scoped catalog name (`@org/name`) from its package.json — an
-// already-scoped `name`, else `uniweb.scope` + a bare `name`. Null when neither
+// already-scoped name, else `uniweb.scope` + a bare one. Null when neither
 // yields a scoped name (then we can't look up the registered version, so the
 // caller treats the foundation as "release it and let register pick the scope").
+//
+// ⛔ The name is `uniweb.id` when set, exactly as the build reads it for the
+// schema that `register` submits (`build/src/schema.js`). Reading `name` alone —
+// as this did until 2026-09-17 — looked a `uniweb.id` foundation up under a name
+// the catalog does not have, so every push re-released it, and pinned the site
+// to that same wrong name.
 function foundationScopedName(dir) {
   try {
     const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
-    const name = pkg?.name
+    const name = pkg?.uniweb?.id || pkg?.name
     if (typeof name === 'string' && name.startsWith('@')) return name
     const scope = pkg?.uniweb?.scope
     if (scope && name) return `${String(scope).replace(/\/+$/, '')}/${name}`
@@ -344,8 +351,18 @@ async function bringLocalCodeAlong({
       )
       return { released: false, proceed: true, ref: registeredRef(reg) }
     }
+    // ⚖️ The registry takes a NEW version only when it is greater than every one
+    // it holds — but an older local version may be one it already has, and
+    // re-registering that resumes. The CLI cannot tell which from here, so it
+    // does not refuse: it submits, says what will decide, and `register` prints
+    // the registry's answer if it is a no.
+    const order = compareSemverPrecedence(local.version, reg.latest_version)
     say.info(
-      `Releasing the ${kind} ${label} (new version; registered latest is ${reg.latest_version})…`
+      order === 1
+        ? `Releasing the ${kind} ${label} (new version; registered latest is ${reg.latest_version})…`
+        : order === null
+          ? `Releasing the ${kind} ${label} (registered latest is ${reg.latest_version})…`
+          : `Releasing the ${kind} ${label} — not newer than the registered latest ${reg.latest_version}, so the registry takes it only if ${local.version} is already registered with this code…`
     )
     return {
       released: releaseFoundation(local, args, cliBin, say),

package/src/commands/register.js

@@ -633,8 +633,8 @@ async function runRegister(args = []) {
     // Resume path: a registered version is immutable, so re-running after a
     // partial code delivery hits the duplicate rejection here — a STRUCTURED
     // 409 (problem+json, title "Conflict") — and proceeds to phase 2 (the
-    // code-uploads plan authorizes against the REGISTERED version; completed
-    // files are idempotent no-ops).
+    // code-uploads plan authorizes against the REGISTERED version; files it
+    // already stores come back `present` and are skipped).
     const isDuplicate = !standalone && res.status === 409
     if (isDuplicate) {
       alreadyRegistered = true
@@ -712,14 +712,18 @@ async function runRegister(args = []) {
           )
         }
         log(
-          `  ${colors.dim}Re-run \`uniweb register\` to resume — completed files are safe no-ops.${colors.reset}`
+          `  ${colors.dim}Re-run \`uniweb register\` to resume — files already stored are skipped.${colors.reset}`
         )
         return { exitCode: 1 }
       }
+      // "4 files" on a first upload; "1 uploaded, 3 already stored" on a resume.
+      const delivered = result.stored?.length
+        ? `${result.uploaded.length} uploaded, ${result.stored.length} already stored`
+        : `${result.uploaded.length} files`
       if (result.verified === true) {
         // serveBase is guaranteed here — it is what gated the check.
         success(
-          `Code delivered (${result.uploaded.length} files) — entry verified live at ${colors.dim}${result.serveBase}${colors.reset}`
+          `Code delivered (${delivered}) — entry verified live at ${colors.dim}${result.serveBase}${colors.reset}`
         )
       } else if (result.verified === false) {
         error(
@@ -727,9 +731,7 @@ async function runRegister(args = []) {
         )
         return { exitCode: 1 }
       } else {
-        success(
-          `Code delivered (${result.uploaded.length} files, ${result.mode} mode)`
-        )
+        success(`Code delivered (${delivered}, ${result.mode} mode)`)
         // Say WHY nothing was checked, rather than skipping in silence. The CLI
         // never reconstructs a serve URL (see utils/code-upload.js), so a plan
         // without `serve_base` means the location is not ours to know — name it
@@ -741,6 +743,16 @@ async function runRegister(args = []) {
         }
       }
     } catch (err) {
+      // ⚖️ A 4xx is the registry REFUSING the plan — e.g. a stored file
+      // declared at a different size (`version_content_changed`). Running the
+      // same command again gets the same answer, so do not suggest it: print
+      // the refusal's own sentence, which says what does help.
+      if (err.status >= 400 && err.status < 500 && err.detail) {
+        error(`Code delivery refused: HTTP ${err.status}`)
+        log(`  ${err.detail}`)
+        if (err.code) log(`  ${colors.dim}(${err.code})${colors.reset}`)
+        return { exitCode: 1 }
+      }
       error(`Code delivery failed: ${err.message}`)
       log(
         `  ${colors.dim}The schema registration above succeeded; re-run \`uniweb register\` to deliver the code.${colors.reset}`

package/src/commands/rename.js

@@ -60,6 +60,7 @@ import { writeJsonPreservingStyleAsync } from '../utils/json-file.js'
 import { getExistingPackageNames, validatePackageName } from '../utils/names.js'
 import { detectPackageManager, installCmd } from '../utils/pm.js'
 import { getCliPrefix } from '../utils/interactive.js'
+import { replaceInTopLevelList, setTopLevelScalar } from '../utils/yaml-edit.js'
 
 const colors = {
   reset: '\x1b[0m',
@@ -208,6 +209,24 @@ async function rewritePackageJsonName(pkgPath, newName) {
   await writeJsonPreservingStyleAsync(pkgPath, pkg, src)
 }
 
+/**
+ * Stop, before any file moves, when a site's `site.yml` names the package in a
+ * form the in-place edit cannot reach. The alternative is rewriting the whole
+ * file, which loses the author's comments and formatting — so we refuse and say
+ * how to write it instead.
+ */
+function refuseUneditableSiteYml(sitePaths, key, hint) {
+  if (sitePaths.length === 0) return
+  for (const path of sitePaths) {
+    error(
+      `Cannot rename: ${colors.bright}${path}/site.yml${colors.reset} writes \`${key}:\` in a form this command cannot edit without rewriting the file.`
+    )
+  }
+  log(`Nothing was changed. ${hint}`)
+  log('Then run the rename again.')
+  process.exit(1)
+}
+
 // ─── Foundation rename ───────────────────────────────────────────
 
 async function renameFoundation(rootDir, oldName, newName, prefix) {
@@ -262,7 +281,7 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
   for (const site of sites) {
     const sitePkgPath = join(rootDir, site.path, 'package.json')
     const siteYmlPath = join(rootDir, site.path, 'site.yml')
-    let pkg, pkgSrc, ymlData
+    let pkg, pkgSrc, ymlText, ymlData
     try {
       pkgSrc = await readFile(sitePkgPath, 'utf-8')
       pkg = JSON.parse(pkgSrc)
@@ -271,7 +290,8 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
       pkgSrc = null
     }
     try {
-      ymlData = yaml.load(await readFile(siteYmlPath, 'utf-8')) || {}
+      ymlText = await readFile(siteYmlPath, 'utf-8')
+      ymlData = yaml.load(ymlText) || {}
     } catch {
       ymlData = null
     }
@@ -285,12 +305,19 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
         pkgSrc,
         sitePkgPath,
         siteYmlPath,
-        ymlData,
+        // Edited in place — see utils/yaml-edit.js — and computed HERE, before
+        // anything moves, so a file it cannot edit stops the rename cleanly.
+        newYmlText: ymlMatches ? setTopLevelScalar(ymlText, 'foundation', newName) : null,
         hasDep,
         ymlMatches
       })
     }
   }
+  refuseUneditableSiteYml(
+    affectedSites.filter((s) => s.ymlMatches && s.newYmlText === null).map((s) => s.path),
+    'foundation',
+    `Write it on one line: \`foundation: ${oldName}\`.`
+  )
 
   // ─── Print plan, then execute ────────────────────────────────
 
@@ -333,11 +360,7 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
       await writeJsonPreservingStyleAsync(s.sitePkgPath, s.pkg, s.pkgSrc)
     }
     if (s.ymlMatches) {
-      const newYmlData = { ...s.ymlData, foundation: newName }
-      await writeFile(
-        s.siteYmlPath,
-        yaml.dump(newYmlData, { flowLevel: -1, quotingType: "'" })
-      )
+      await writeFile(s.siteYmlPath, s.newYmlText)
     }
   }
 
@@ -485,9 +508,10 @@ async function renameExtension(rootDir, oldName, newName, prefix) {
   const affectedSites = []
   for (const site of sites) {
     const siteYmlPath = join(rootDir, site.path, 'site.yml')
-    let ymlData
+    let ymlText, ymlData
     try {
-      ymlData = yaml.load(await readFile(siteYmlPath, 'utf-8')) || {}
+      ymlText = await readFile(siteYmlPath, 'utf-8')
+      ymlData = yaml.load(ymlText) || {}
     } catch {
       continue
     }
@@ -496,9 +520,23 @@ async function renameExtension(rootDir, oldName, newName, prefix) {
       (e) => typeof e === 'string' && e.startsWith(oldUrlPrefix)
     )
     if (hits.length > 0) {
-      affectedSites.push({ site, ymlData, siteYmlPath, hits })
+      const replacements = new Map(
+        hits.map((e) => [e, newUrlPrefix + e.slice(oldUrlPrefix.length)])
+      )
+      affectedSites.push({
+        site,
+        siteYmlPath,
+        hits,
+        // Edited in place, and computed before anything moves — as for foundations.
+        newYmlText: replaceInTopLevelList(ymlText, 'extensions', replacements)
+      })
     }
   }
+  refuseUneditableSiteYml(
+    affectedSites.filter((a) => a.newYmlText === null).map((a) => a.site.path),
+    'extensions',
+    `Write each entry on a line of its own, e.g. \`- ${oldUrlPrefix}dist/entry.js\`.`
+  )
 
   log('')
   log(
@@ -531,16 +569,7 @@ async function renameExtension(rootDir, oldName, newName, prefix) {
   await rewritePackageJsonName(join(newExtDir, 'package.json'), newName)
 
   for (const a of affectedSites) {
-    const newExts = (a.ymlData.extensions || []).map((e) =>
-      typeof e === 'string' && e.startsWith(oldUrlPrefix)
-        ? newUrlPrefix + e.slice(oldUrlPrefix.length)
-        : e
-    )
-    const newYmlData = { ...a.ymlData, extensions: newExts }
-    await writeFile(
-      a.siteYmlPath,
-      yaml.dump(newYmlData, { flowLevel: -1, quotingType: "'" })
-    )
+    await writeFile(a.siteYmlPath, a.newYmlText)
   }
 
   if (folderWillRename) {

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-17T03:24:18.741Z",
+  "generatedAt": "2026-09-17T03:53:59.364Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.3.6",
@@ -96,7 +96,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.3.2",
+      "version": "0.3.3",
       "path": "framework/schemas",
       "deps": []
     },
@@ -116,7 +116,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.14.7",
+      "version": "0.14.8",
       "path": "framework/templates",
       "deps": []
     },

package/src/utils/code-upload.js

@@ -7,10 +7,12 @@
  *
  *   1. PLAN   — POST {apiBase}/dev/registry/code-uploads with the file list
  *               ({ path, content_type, size, sha256? }). The response carries
- *               one upload target per file ({ path, method, url, headers })
- *               plus mode: 'direct' (dev — URLs point back at the backend) or
- *               'presigned' (prod — storage PUTs; bytes never transit the
- *               backend). The CLI never branches on the mode.
+ *               one entry per file: `present: true` for a file the backend
+ *               already stores for this version (no URL — it is skipped), or an
+ *               upload target ({ path, method, url, headers }). Plus mode:
+ *               'direct' (dev — URLs point back at the backend) or 'presigned'
+ *               (prod — storage PUTs; bytes never transit the backend). The CLI
+ *               never branches on the mode.
  *   2. UPLOAD — PUT each file's raw bytes to its URL with the given headers.
  *               The ENTRY uploads LAST: a partial upload never yields a
  *               loadable version (practical atomicity — there is no server
@@ -35,7 +37,8 @@
  *     plan step's per-version file cap — the cap is an abuse guard, the maps
  *     simply don't belong on the CDN.)
  *   - a registered version is immutable, code included — changed bytes mean
- *     a new version (re-PUTting identical bytes is a safe no-op)
+ *     a new version. A stored file is never re-sent (the plan marks it
+ *     `present`), and one declared at a different size is refused (422)
  */
 
 import { createHash } from 'node:crypto'
@@ -215,7 +218,10 @@ export function computeFoundationDigest(distDir) {
  * @param {string} opts.distDir  - the built dist/ directory
  * @param {Array}  [opts.files]  - pre-collected file list (default: collect)
  * @param {(msg: string) => void} [opts.onProgress]
- * @returns {Promise<{ mode: string, uploaded: string[], failed: Array<{path, status, detail}>, verified: boolean|null, serveBase: string|null }>}
+ * @returns {Promise<{ mode: string, uploaded: string[], stored: string[], failed: Array<{path, status, detail}>, verified: boolean|null, serveBase: string|null }>}
+ *   `stored` — files the plan reported as already stored (`present: true`), not re-sent.
+ * @throws {Error} when the plan is refused — with `status`, and the problem+json
+ *   `detail` and `code` when the body carries them
  */
 export async function uploadFoundationCode({
   apiBase,
@@ -259,10 +265,22 @@ export async function uploadFoundationCode({
   })
   if (!planRes.ok) {
     const body = await planRes.text().catch(() => '')
+    // A refusal is problem+json, and its `detail` is a sentence written for the
+    // person reading — for a changed file it says what to do. Carry it (and the
+    // `code`) instead of a raw body the reader has to dig the sentence out of.
+    let problem = null
+    try {
+      problem = JSON.parse(body)
+    } catch {
+      problem = null
+    }
+    const detail = typeof problem?.detail === 'string' ? problem.detail : null
     const err = new Error(
-      `code-uploads plan rejected: HTTP ${planRes.status}${body ? ` — ${body.slice(0, 300)}` : ''}`
+      `code-uploads plan rejected: HTTP ${planRes.status}${detail ? ` — ${detail}` : body ? ` — ${body.slice(0, 300)}` : ''}`
     )
     err.status = planRes.status
+    err.detail = detail
+    err.code = typeof problem?.code === 'string' ? problem.code : null
     throw err
   }
   const plan = await planRes.json()
@@ -275,6 +293,7 @@ export async function uploadFoundationCode({
     plan.mode === 'direct' ? { Authorization: `Bearer ${token}` } : {}
 
   const uploaded = []
+  const stored = []
   const failed = []
   for (const file of uploadOrder(list)) {
     const target = targets.get(file.path)
@@ -286,6 +305,27 @@ export async function uploadFoundationCode({
       })
       continue
     }
+    // ⭐ A file the backend already stores for this version comes back
+    // `present: true`, with no URL — a stored file of a registered version is
+    // never overwritten. Skip it. This is what lets an interrupted upload
+    // resume, and a re-run on a fully uploaded version pass.
+    //
+    // ⛔ Before this branch existed, a present entry was PUT to
+    // `new URL(undefined, origin)`, which does not throw — it resolves to
+    // `<origin>/undefined` — and came back as a failed upload.
+    if (target.present === true) {
+      stored.push(file.path)
+      onProgress(`${file.path} (already stored)`)
+      continue
+    }
+    if (!target.url) {
+      failed.push({
+        path: file.path,
+        status: 0,
+        detail: 'the plan gave no upload URL'
+      })
+      continue
+    }
     const bytes = readFileSync(join(distDir, file.path))
     try {
       // ⭐ **Retried.** A single connection-level failure used to fail the whole
@@ -350,5 +390,5 @@ export async function uploadFoundationCode({
     }
   }
 
-  return { mode: plan.mode || 'direct', uploaded, failed, verified, serveBase }
+  return { mode: plan.mode || 'direct', uploaded, stored, failed, verified, serveBase }
 }

package/src/utils/semver-precedence.js

@@ -0,0 +1,57 @@
+/**
+ * SemVer 2.0.0 precedence — how a registry orders a foundation's versions.
+ *
+ * A pre-release sorts below its release (`1.0.0-rc.1` < `1.0.0`), and build
+ * metadata carries no order (`1.2.0+b` equals `1.2.0`).
+ *
+ * ⚖️ Not `compareSemver` in `dep-survey.js`: that one reads dependency specs
+ * (`^1.2.3`) for `uniweb update` and compares major.minor.patch only. This one
+ * is strict — anything that is not a SemVer version is `null`, never a guess.
+ */
+
+// The regex published with the SemVer 2.0.0 specification (semver.org, §FAQ).
+const SEMVER =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/
+
+/**
+ * @param {unknown} version
+ * @returns {{ major: number, minor: number, patch: number, pre: string[] }|null}
+ */
+export function parseSemver(version) {
+  if (typeof version !== 'string') return null
+  const m = SEMVER.exec(version)
+  if (!m) return null
+  return { major: +m[1], minor: +m[2], patch: +m[3], pre: m[4] ? m[4].split('.') : [] }
+}
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1|0|1|null} how `a` sorts against `b`; null when either is not SemVer
+ */
+export function compareSemverPrecedence(a, b) {
+  const x = parseSemver(a)
+  const y = parseSemver(b)
+  if (!x || !y) return null
+  for (const part of ['major', 'minor', 'patch']) {
+    if (x[part] !== y[part]) return x[part] > y[part] ? 1 : -1
+  }
+  // A version with a pre-release sorts below the same version without one.
+  if (!x.pre.length || !y.pre.length) {
+    return x.pre.length === y.pre.length ? 0 : x.pre.length ? -1 : 1
+  }
+  for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+    const p = x.pre[i]
+    const q = y.pre[i]
+    if (p === undefined) return -1
+    if (q === undefined) return 1
+    if (p === q) continue
+    const pNum = /^\d+$/.test(p)
+    const qNum = /^\d+$/.test(q)
+    // Numeric identifiers compare numerically and sort below alphanumeric ones.
+    if (pNum && qNum) return BigInt(p) > BigInt(q) ? 1 : -1
+    if (pNum !== qNum) return pNum ? -1 : 1
+    return p > q ? 1 : -1
+  }
+  return 0
+}

package/src/utils/yaml-edit.js

@@ -0,0 +1,115 @@
+/**
+ * In-place edits to a YAML file a person wrote (`site.yml`), for a command that
+ * must change one value and leave everything else as it was: comments, key
+ * order, blank lines, quoting, a flow list written on one line.
+ *
+ * ⛔ Never load a hand-written file and dump it back. js-yaml's `dump` drops every
+ * comment and re-flows lists and long strings — `scaffold.js` records what that
+ * did to the templates whose comments are the point of them.
+ *
+ * ⭐ Every edit is VERIFIED: the edited text must parse to exactly the old data
+ * with that one value changed. A value written in a form the line-level edit
+ * cannot reach (a block scalar, an entry split across lines) returns null
+ * rather than a guess, so the caller can refuse before it changes anything.
+ */
+
+import { isDeepStrictEqual } from 'node:util'
+import yaml from 'js-yaml'
+
+const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** A scalar as written after `key: `, quoted only when YAML needs it (`@scope/name` does). */
+const scalar = (value) => yaml.dump(value, { lineWidth: -1 }).trim()
+
+/**
+ * Where a trailing ` # comment` begins in the text after `key:`, outside quotes,
+ * including the whitespace before it. -1 when the line has none.
+ */
+function commentStart(rest) {
+  let quote = null
+  for (let i = 0; i < rest.length; i++) {
+    const ch = rest[i]
+    if (quote) {
+      if (ch === quote) quote = null
+    } else if (ch === '"' || ch === "'") {
+      quote = ch
+    } else if (ch === '#' && i > 0 && /\s/.test(rest[i - 1])) {
+      let start = i
+      while (start > 0 && /\s/.test(rest[start - 1])) start--
+      return start
+    }
+  }
+  return -1
+}
+
+/** The edited text when it parses to `expected`, else null. */
+function verified(after, expected) {
+  try {
+    return isDeepStrictEqual(yaml.load(after) ?? {}, expected) ? after : null
+  } catch {
+    return null
+  }
+}
+
+function load(text) {
+  try {
+    const data = yaml.load(text) ?? {}
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Set a top-level, one-line scalar `key` to `value`, keeping the line's inline
+ * comment and every other line as it was.
+ *
+ * @param {string} text - the file's contents
+ * @param {string} key - a top-level key, e.g. `foundation`
+ * @param {string} value
+ * @returns {string|null} the new contents, or null when the edit cannot be made in place
+ */
+export function setTopLevelScalar(text, key, value) {
+  const data = load(text)
+  if (!data) return null
+  const match = new RegExp(`^${escapeRegex(key)}:([^\\n]*)$`, 'm').exec(text)
+  if (!match) return null
+  const at = commentStart(match[1])
+  const comment = at === -1 ? '' : match[1].slice(at)
+  const line = `${key}: ${scalar(value)}${comment}`
+  const after = text.slice(0, match.index) + line + text.slice(match.index + match[0].length)
+  return verified(after, { ...data, [key]: value })
+}
+
+/**
+ * Replace entries of a top-level list `key` — each `from` value becomes its `to`
+ * — wherever an entry is written on a line of its own or inside a one-line flow
+ * list, plain or quoted. A value that only CONTAINS `from` is left alone, and so
+ * is a comment line.
+ *
+ * @param {string} text - the file's contents
+ * @param {string} key - a top-level list key, e.g. `extensions`
+ * @param {Map<string, string>} replacements - old entry → new entry
+ * @returns {string|null} the new contents, or null when the edit cannot be made in place
+ */
+export function replaceInTopLevelList(text, key, replacements) {
+  const data = load(text)
+  if (!data || !Array.isArray(data[key])) return null
+  const expected = { ...data, [key]: data[key].map((v) => (replacements.has(v) ? replacements.get(v) : v)) }
+
+  const after = text
+    .split('\n')
+    .map((line) => {
+      if (/^\s*#/.test(line)) return line
+      for (const [from, to] of replacements) {
+        const f = escapeRegex(from)
+        line = line
+          .replace(new RegExp(`'${f}'`, 'g'), () => `'${to.replace(/'/g, "''")}'`)
+          .replace(new RegExp(`"${f}"`, 'g'), () => JSON.stringify(to))
+          .replace(new RegExp(`(^|[\\s\\[,])${f}(?=$|[\\s,\\]])`, 'g'), (_, lead) => lead + to)
+      }
+      return line
+    })
+    .join('\n')
+  return verified(after, expected)
+}