@uniweb/build 0.55.0 → 0.56.0

package/src/uwx/site.js

@@ -67,6 +67,7 @@ import { emitEntitySyncPackage } from './entity-document.js'
 import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent } from './locale-sync.js'
 import { unwrapLocalized } from './backfill.js'
 import { loadFreeformTranslation } from '../i18n/freeform.js'
+import { updateBackendState, readBackendState } from './sync-store.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveQueriesConfig } from './queries-config.js'
 import { resolveSelfScope } from './self-scope.js'
@@ -974,8 +975,14 @@ function queriesNested(declarations, uuids = null, org = null) {
 
 // ── `services` + `secrets` — a site's own service records ─────────────────────
 //
-// ⭐ THE FILE KEYS ARE `$services` / `$secrets`, NOT `services` / `secrets`, and the
-// `$` is load-bearing rather than decorative. `site.yml::services` is ALREADY TAKEN,
+// ⚠️ THESE WERE `site.yml::$services` / `$secrets` UNTIL 2026-09-20. They now live in
+// `sync.json::backends.<origin>.{services,secrets}`, because what a site is PROVISIONED
+// with is a fact about one backend — a service is bought on the backend that sold it.
+// The `$` prefix existed to keep them off `site.yml::services`, which means something
+// else on the bundle lane (the HOST tier); out of `site.yml` entirely, that collision
+// is gone too.
+//
+// The original note, kept because it explains why the names could not simply be reused: `site.yml::services` is ALREADY TAKEN,
 // on the other lane: the bundle lane spreads site.yml whole into the payload, so a
 // `services:` block there lands at `config.services` — the HOST tier — which is the
 // documented way to simulate a host locally (`kit/src/utils/submitTarget.js`).
@@ -1056,9 +1063,9 @@ function serviceRecords(declared, identify, label) {
 }
 
 /** One service per `name` — the same keyspace `config.services` uses at runtime. */
-function servicesNested(siteYml) {
+function servicesNested(provisioned) {
   return serviceRecords(
-    siteYml.$services,
+    provisioned?.services,
     (e) => (typeof e.name === 'string' && e.name ? e.name : null),
     '$services'
   )
@@ -1076,9 +1083,9 @@ function servicesNested(siteYml) {
  * judgement belongs; framework does not strip it, because silently dropping a value
  * an author typed would leave them believing a secret was set.
  */
-function secretsNested(siteYml) {
+function secretsNested(provisioned) {
   return serviceRecords(
-    siteYml.$secrets,
+    provisioned?.secrets,
     (e) => {
       if (typeof e.name !== 'string' || !e.name) return null
       return typeof e.service === 'string' && e.service
@@ -1212,6 +1219,7 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
  *
  * @param {string} siteRoot - directory containing site.yml
  * @param {object} [opts]
+ * @param {string} [opts.backend] - whose `$uuid` to put on the wire (sync.json)
  * @param {string} [opts.entityUuid] - override the entity `$uuid` (tests); default
  *        is `site.yml::$uuid` (absent on first sync — `$id`-only document).
  * @param {string} [opts.sourceLocale] - localized-field wrap locale. Defaults to
@@ -1497,8 +1505,13 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // `$uuid?` then `$id` `$model`, then sections in Model-declared order. The entity
   // `$uuid` lives in site.yml (back-filled after first sync); absent on first sync.
   const doc = {}
+  // ⭐ From `sync.json`, keyed by the backend this document is being produced FOR.
+  // It was `site.yml::$uuid` — one scalar with no way to say which backend minted it.
+  // A producer with no backend emits no `$uuid`, which is exactly right: the wire
+  // value is that backend's name for this site, and there is no such name yet.
   const entityUuid =
-    opts.entityUuid || (typeof siteYml.$uuid === 'string' ? siteYml.$uuid : undefined)
+    opts.entityUuid ||
+    (opts.backend ? readBackendState(siteRoot, opts.backend).site?.uuid : undefined)
   if (entityUuid) doc.$uuid = entityUuid
   doc.$id = SITE_ENTITY_KEY // one site-content entity per project (stable handle)
   doc.$model = SITE_MODEL_NAME
@@ -1537,9 +1550,13 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // ⚖️ Default is to declare, so every existing caller is unchanged and the
   // withholding is opt-in.
   const declare = opts.declareServices !== false
-  const services = declare ? servicesNested(siteYml) : undefined
+  // ⭐ Provisioned per backend — a service is bought on the backend that sold it,
+  // so which rows exist is a question about ONE backend. They were `site.yml::$services`
+  // / `$secrets`, a single copy that could only ever describe one.
+  const provisioned = opts.backend ? readBackendState(siteRoot, opts.backend) : null
+  const services = declare ? servicesNested(provisioned) : undefined
   if (services) doc.services = services
-  const secrets = declare ? secretsNested(siteYml) : undefined
+  const secrets = declare ? secretsNested(provisioned) : undefined
   if (secrets) doc.secrets = secrets
   return doc
 }
@@ -1589,8 +1606,8 @@ export async function emitSiteSyncPackage(siteRoot, opts = {}) {
  * @param {string} uuid - the entity uuid the backend minted/echoed
  * @returns {boolean} true if site.yml changed
  */
-export function writeSiteEntityUuid(siteRoot, uuid) {
-  return upsertYamlScalar(join(siteRoot, 'site.yml'), '$uuid', uuid)
+export function writeSiteEntityUuid(siteRoot, backend, uuid) {
+  return updateBackendState(siteRoot, backend, { site: { uuid } })
 }
 
 /**
@@ -1639,45 +1656,12 @@ export function writeSiteEntityUuid(siteRoot, uuid) {
  * @param {string} handle - the bare org handle (no leading `@`)
  * @returns {boolean} true if site.yml changed
  */
-export function writeSiteOrg(siteRoot, handle) {
-  return upsertYamlScalar(join(siteRoot, 'site.yml'), '$org', handle)
+export function writeSiteOrg(siteRoot, backend, handle) {
+  return updateBackendState(siteRoot, backend, { site: { org: handle } })
 }
 
-/**
- * Record the backend this project SYNCS WITH (`site.yml::$backend`), beside `$uuid`/`$org`.
- *
- * ⭐ It is not a tag on the site uuid — it is the project's **sync scope**. Four surfaces
- * hold backend-minted identity, and this one fact is what makes all of them meaningful:
- * `site.yml::$uuid`, every collection record's `$uuid` in its own source file,
- * `assets.json`, and `.uniweb/sync-cache.json`. Change the backend and every one of them
- * is foreign at once — which is why a mismatch is a stop, not a fallback
- * (`assertSiteBackendScope` in the CLI).
- *
- * ⛔ **Written ONLY for a non-default backend.** The 98% case stays out of the file, and an
- * absent value reads as the default — correct both for a project written before this key
- * existed and for one synced against the default. Callers decide; this writer does not know
- * the CLI's default. See `recordSiteBackend` (cli/src/backend/site-sync.js), which is where
- * the "is it the default?" test lives.
- *
- * ⚠️ **The name is load-bearing. Five alternatives were considered and rejected (2026-08-24);
- * do not re-propose one.** `origin` is wrong twice over — a site HAS an origin (its own
- * served domain), and this lane is git-modeled, where `origin` names a remote rather than a
- * URL. `remote` implies a multiplicity this design closes. `hosting` and `platform` name the
- * hosting edge, which this package has no client for. `host` collides with
- * `deploy.yml::targets.<n>.host` (the deploy adapter). A `uuid: <id>@<backend>` suffix was
- * rejected too: it would make "this never reaches the backend" a discipline at every read
- * site instead of a property, and `siteProjectToDocument` assigns `$uuid` straight onto the
- * wire document.
- *
- * Safe as a plain YAML scalar: a URL's `:` is followed by `/` or a digit, never a space, so
- * it needs no quoting (verified against js-yaml for apex, `localhost:8080` and host:port+path
- * forms, 2026-08-24). This is the same class of hazard as `$org`'s leading `@`, which is
- * stripped for exactly that reason — but it lands on the safe side.
- *
- * @param {string} siteRoot
- * @param {string} origin - a bare origin, no trailing slash
- * @returns {boolean} true if site.yml changed
- */
-export function writeSiteBackend(siteRoot, origin) {
-  return upsertYamlScalar(join(siteRoot, 'site.yml'), '$backend', origin)
-}
+// ⛔ `writeSiteBackend` and `site.yml::$backend` are GONE (2026-09-20). The scope is
+// no longer a value recorded beside the uuid — it is the KEY the identity is stored
+// under (`sync.json::backends.<origin>`), so there is nothing to record and nothing
+// that can disagree with it. `kb/framework/reference/sync-json.md`.
+

package/src/uwx/sync-package.js

@@ -273,6 +273,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const exportedAt = opts.exportedAt
 
   const col = await buildRecordEntities(siteRoot, {
+    // Which backend's record uuids go on the wire (sync.json) — see records.js.
+    ...(opts.backend ? { backend: opts.backend } : {}),
     ...(opts.foundationDir ? { foundationDir: opts.foundationDir } : {}),
     ...(opts.resolveModel ? { resolveModel: opts.resolveModel } : {}),
     ...(sourceLocale ? { sourceLocale } : {}),
@@ -316,6 +318,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const siteDoc = includeSite
     ? await siteProjectToDocument(siteRoot, {
         sourceLocale,
+        // Whose $uuid belongs on this wire document — see siteProjectToDocument.
+        ...(opts.backend ? { backend: opts.backend } : {}),
         ...(opts.queryUuids ? { queryUuids: opts.queryUuids } : {}),
         // ⛔ THE SAME ORG `buildRecordEntities` WAS GIVEN ABOVE. A query's `schema`
         // must name the Model its records are stored under, and both are qualified

package/src/uwx/sync-store.js

@@ -0,0 +1,351 @@
+/**
+ * `sync.json` — what each backend minted, keyed by origin.
+ *
+ * ## What it is
+ *
+ * Every id in this file was assigned by a backend and is meaningless against any
+ * other one: a site uuid, a record's uuid, an asset's content-addressed id. The
+ * file is **committed**, because a teammate who clones the project otherwise holds
+ * content with no way to say which site on which backend it is.
+ *
+ * ⭐ **If it changed, something got synced.** Nothing else writes it — which is the
+ * whole reason it is separate from `deploy.yml`, whose diff means "a target changed".
+ *
+ * Spec: `kb/framework/reference/sync-json.md`. Why it exists at all:
+ * `kb/framework/plans/backend-scoped-project-state.md`.
+ *
+ * ## Why it is keyed by ORIGIN, all the way down
+ *
+ * A project may sync with any number of backends. Nothing can be shared between
+ * them, so nothing is: each origin gets its own section and they never merge.
+ *
+ * ⭐ **The payoff is a guard that stops existing.** Identity used to sit in
+ * `site.yml` as a single `$uuid`, with `$backend` recording which backend it came
+ * from and `assertSiteBackendScope` refusing a command whose origin disagreed.
+ * Here there is no configuration in which backend A's ids can reach B — you read
+ * A's section for A — so there is no mismatch to detect.
+ *
+ * ## ⛔ No dependencies, by requirement
+ *
+ * `clone` writes a site's identity BEFORE `pnpm install` has run, so the writer has
+ * to work with nothing installed. `site.yml`'s equivalent needed a hand-rolled
+ * dependency-free fallback for exactly this (`cli/utils/site-identity.js`); JSON
+ * needs no parser, so this module uses `node:fs` and nothing else.
+ *
+ * @module
+ */
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+export const SYNC_STORE_FILE = 'sync.json'
+
+/** Current on-disk shape. Bumped only for a breaking layout change. */
+const VERSION = 1
+
+/** Map sections — merged entry by entry. Anything else in a patch replaces. */
+const MAP_SECTIONS = new Set(['records', 'items', 'queries', 'folders', 'assets'])
+
+const storePath = (siteDir) => join(siteDir, SYNC_STORE_FILE)
+
+/**
+ * A bare origin with no trailing slash, or null when unparseable.
+ *
+ * Callers may pass a whole endpoint URL — `http://localhost:8080/dev/site/…` and
+ * `http://localhost:8080` address the same backend. `https://x` and `http://x` do
+ * not: a scheme change is a different backend, not the same one reached differently.
+ */
+export function normalizeOrigin(value) {
+  if (typeof value !== 'string' || !value.trim()) return null
+  try {
+    // ⛔ http(s) only: `new URL('localhost:8080')` PARSES — as the scheme `localhost:` —
+    // and its origin is the string "null". Keyed by that, a mistyped backend would get a
+    // section of its own.
+    const u = new URL(value)
+    return u.protocol === 'http:' || u.protocol === 'https:' ? u.origin : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The whole file, normalized. A missing, unreadable or malformed file reads as
+ * empty rather than throwing: this is a record, and a corrupt one must never be the
+ * reason a push fails. The next write repairs it.
+ *
+ * @param {string} siteDir
+ * @returns {{ version: number, backends: Record<string, object> }}
+ */
+export function readSyncStore(siteDir) {
+  const empty = { version: VERSION, backends: {} }
+  const p = storePath(siteDir)
+  if (!existsSync(p)) return empty
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8'))
+    const backends = parsed?.backends
+    if (!backends || typeof backends !== 'object' || Array.isArray(backends)) return empty
+    const out = {}
+    for (const [origin, state] of Object.entries(backends)) {
+      const key = normalizeOrigin(origin)
+      if (key && state && typeof state === 'object' && !Array.isArray(state)) out[key] = state
+    }
+    return { version: VERSION, backends: out }
+  } catch {
+    return empty
+  }
+}
+
+/**
+ * One backend's section, or `{}` when this project has never synced with it.
+ *
+ * ⛔ Returns a COPY at the top level, so a caller mutating it cannot write through
+ * to the next read. The maps inside are shared — treat the whole thing as read-only
+ * and go through `updateBackendMap` to change anything.
+ *
+ * @param {string} siteDir
+ * @param {string} origin
+ * @returns {object}
+ */
+export function readBackendState(siteDir, origin) {
+  const key = normalizeOrigin(origin)
+  if (!key) return {}
+  const found = readSyncStore(siteDir).backends[key]
+  return found ? { ...found } : {}
+}
+
+/** Every origin this project has synced with, sorted. */
+export function listSyncedBackends(siteDir) {
+  return Object.keys(readSyncStore(siteDir).backends).sort()
+}
+
+/**
+ * Write the store, with every level sorted.
+ *
+ * ⛔ **Sorting is not tidiness.** A committed file that reorders itself produces a
+ * diff on every push and teaches people to stop reading it — at which point a real
+ * change to what a site is bound to passes unnoticed. Same rule, and the same
+ * reason, as `assets.json`, which this file absorbs.
+ */
+function writeStore(siteDir, backends) {
+  const sortedBackends = {}
+  for (const origin of Object.keys(backends).sort()) {
+    const state = backends[origin]
+    const sortedState = {}
+    for (const section of Object.keys(state).sort()) {
+      const value = state[section]
+      if (MAP_SECTIONS.has(section) && value && typeof value === 'object' && !Array.isArray(value)) {
+        const sortedMap = {}
+        for (const k of Object.keys(value).sort()) sortedMap[k] = value[k]
+        sortedState[section] = sortedMap
+      } else {
+        sortedState[section] = value
+      }
+    }
+    sortedBackends[origin] = sortedState
+  }
+  const text = JSON.stringify({ version: VERSION, backends: sortedBackends }, null, 2) + '\n'
+  const p = storePath(siteDir)
+  // A no-op write is worse than useless: it dirties `git status` on a push that
+  // changed nothing, which is the other half of the diff-stability rule above.
+  if (existsSync(p)) {
+    try {
+      if (readFileSync(p, 'utf8') === text) return false
+    } catch {
+      /* unreadable — fall through and replace it */
+    }
+  }
+  mkdirSync(dirname(p), { recursive: true })
+  writeFileSync(p, text)
+  return true
+}
+
+/**
+ * Merge `patch` into one backend's section.
+ *
+ * **Map sections merge entry by entry; everything else replaces.** A push carries
+ * only what that run touched, so replacing a map would drop every entry it happened
+ * not to mention — which is most of them on a partial push. `services` and
+ * `secrets` are arrays and a whole projection from the backend, so replacing is
+ * right for those.
+ *
+ * @param {string} siteDir
+ * @param {string} origin
+ * @param {object} patch - e.g. `{ site: { uuid }, records: { 'a.md': 'uuid' } }`
+ * @returns {boolean} whether the file changed
+ */
+export function updateBackendState(siteDir, origin, patch) {
+  const key = normalizeOrigin(origin)
+  if (!key || !patch || typeof patch !== 'object') return false
+  const { backends } = readSyncStore(siteDir)
+  const prior = backends[key] || {}
+  const next = { ...prior }
+
+  for (const [section, value] of Object.entries(patch)) {
+    if (value === undefined) continue
+    if (MAP_SECTIONS.has(section) && value && typeof value === 'object' && !Array.isArray(value)) {
+      next[section] = { ...(prior[section] || {}), ...value }
+    } else if (section === 'site' && value && typeof value === 'object') {
+      // The identity object merges too: a create knows the uuid, the org prompt
+      // that follows knows the handle, and neither should erase the other.
+      next[section] = { ...(prior[section] || {}), ...value }
+    } else {
+      next[section] = value
+    }
+  }
+
+  backends[key] = next
+  return writeStore(siteDir, backends)
+}
+
+/**
+ * Merge entries into one map section, with an optional per-entry rule.
+ *
+ * `merge(next, prior)` decides what an entry becomes when one already exists, and
+ * returns `undefined` to leave the stored one alone. Without it, the incoming entry
+ * wins. Assets use it to carry a `served` fingerprint forward across a push that
+ * learned an id without learning an address.
+ *
+ * @param {string} siteDir
+ * @param {string} origin
+ * @param {string} section - one of `records` `items` `queries` `folders` `assets`
+ * @param {Record<string, *>} entries
+ * @param {(next: *, prior: *) => *} [merge]
+ * @returns {{ added: string[], changed: string[], written: boolean }}
+ */
+export function updateBackendMap(siteDir, origin, section, entries, merge) {
+  const key = normalizeOrigin(origin)
+  const added = []
+  const changed = []
+  if (!key || !MAP_SECTIONS.has(section) || !entries || typeof entries !== 'object') {
+    return { added, changed, written: false }
+  }
+
+  const { backends } = readSyncStore(siteDir)
+  const prior = backends[key] || {}
+  const map = { ...(prior[section] || {}) }
+
+  for (const [k, incoming] of Object.entries(entries)) {
+    if (incoming === undefined || incoming === null) continue
+    const was = map[k]
+    const value = was !== undefined && merge ? merge(incoming, was) : incoming
+    if (value === undefined) continue
+    if (was === undefined) added.push(k)
+    else if (JSON.stringify(was) !== JSON.stringify(value)) changed.push(k)
+    else continue
+    map[k] = value
+  }
+
+  if (!added.length && !changed.length) return { added, changed, written: false }
+  backends[key] = { ...prior, [section]: map }
+  return { added, changed, written: writeStore(siteDir, backends) }
+}
+
+/**
+ * The merge rule for the `assets` section — pass it to `updateBackendMap`.
+ *
+ * ⭐ **One definition, because three callers need it.** A push learns an id; only an
+ * UPLOAD learns the address the host serves it at. So a push that re-records the same
+ * bytes must not erase the `served` fingerprint an earlier one recorded, and a push
+ * whose bytes changed must drop it — the old address no longer describes them.
+ * Hand-rolled at each call site this is three chances to forget the second half.
+ *
+ * @param {{id: string, ext?: string, served?: string}} next
+ * @param {{id: string, ext?: string, served?: string}} prior
+ */
+export function carryServed(next, prior) {
+  if (next?.served || !prior || prior.id !== next?.id) return next
+  return prior.served ? { ...next, served: prior.served } : next
+}
+
+/**
+ * Empty named sections of one backend's state.
+ *
+ * ⛔ **`updateBackendState` cannot express this**: map sections MERGE, so passing
+ * `{ items: {} }` is a no-op. Clearing needs its own verb, and the absence of one is
+ * how a caller ends up reaching into the file by hand.
+ *
+ * @param {string} siteDir
+ * @param {string} origin
+ * @param {string[]} sections
+ * @returns {string[]} the sections that actually held something
+ */
+export function clearBackendSections(siteDir, origin, sections) {
+  const key = normalizeOrigin(origin)
+  if (!key || !Array.isArray(sections)) return []
+  const { backends } = readSyncStore(siteDir)
+  const prior = backends[key]
+  if (!prior) return []
+  const cleared = []
+  const next = { ...prior }
+  for (const section of sections) {
+    const v = prior[section]
+    if (v && typeof v === 'object' && Object.keys(v).length) {
+      cleared.push(section)
+      next[section] = {}
+    }
+  }
+  if (!cleared.length) return []
+  backends[key] = next
+  writeStore(siteDir, backends)
+  return cleared
+}
+
+/**
+ * Forget one backend entirely. Every other backend is untouched — which is the
+ * point of the keying, and the reason this is safe in a way clearing the old
+ * single-valued identity never was.
+ *
+ * @returns {boolean} whether anything was removed
+ */
+export function clearBackend(siteDir, origin) {
+  const key = normalizeOrigin(origin)
+  if (!key) return false
+  const { backends } = readSyncStore(siteDir)
+  if (!backends[key]) return false
+  delete backends[key]
+  // ⭐ The last backend gone ⇒ the FILE goes. An empty ledger reads exactly like no
+  // ledger, and leaving one behind is an untracked file in `git status` — a trace
+  // of the very sync the caller asked to forget (the throwaway dev-server lane).
+  if (!Object.keys(backends).length) {
+    unlinkSync(storePath(siteDir))
+    return true
+  }
+  writeStore(siteDir, backends)
+  return true
+}
+
+/**
+ * Delete `sync.json` outright — `uniweb forget --all`, which turns a COPY of a
+ * project into a new one.
+ *
+ * Every id in this file belongs to the project it was copied from, and keeping any
+ * of them is how a copy's push updates the original's site. There is no partial
+ * version of that: a copy owns none of these sites.
+ *
+ * @param {string} siteDir
+ * @returns {string[]|null} the origins it held, or null when there was no file. A
+ *   file that does not parse is removed all the same — it is still the original's —
+ *   and reports `[]`.
+ */
+export function forgetSyncStore(siteDir) {
+  const p = storePath(siteDir)
+  if (!existsSync(p)) return null
+  const origins = Object.keys(readSyncStore(siteDir).backends).sort()
+  unlinkSync(p)
+  return origins
+}
+
+/**
+ * The local ref a given asset id is known at for one backend, or null.
+ *
+ * Exists for `pull`, which meets stored content carrying an id and has to put the
+ * file back at the path its author wrote rather than inventing one.
+ */
+export function refForAssetId(siteDir, origin, id) {
+  if (!id) return null
+  const assets = readBackendState(siteDir, origin).assets || {}
+  for (const [ref, v] of Object.entries(assets)) {
+    if (v && v.id === id) return ref
+  }
+  return null
+}