uniweb 0.65.0 → 0.66.0

package/src/backend/site-sync.js

@@ -15,6 +15,7 @@ import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync } from '
 import { join, dirname, relative, isAbsolute } from 'node:path'
 import yaml from 'js-yaml'
 import { hasUncommittedContent } from '../utils/git.js'
+import { recordWritten } from '../utils/pull-written.js'
 import { humanBytes } from '../utils/bytes.js'
 import { isAuthoredPreview } from '../utils/preview.js'
 import {
@@ -33,6 +34,7 @@ import {
   diffSiteUnits,
   describeSiteDiff,
   computeUnitHashes,
+  collectSiteUnits,
   collectUnitUuids,
   collectFolderItemUuids,
   collectQueryUuids,
@@ -91,6 +93,141 @@ async function explainStaleSiteContent({ client, siteDir, localBuffer, uuid }) {
   }
 }
 
+// A unit in the form it is compared in across the two representations: keys sorted,
+// `$`-keys dropped (`$uuid`, `$id` — identity and payload handles, not content).
+const canonicalUnit = (v) =>
+  Array.isArray(v)
+    ? v.map(canonicalUnit)
+    : v && typeof v === 'object'
+      ? Object.fromEntries(
+          Object.keys(v)
+            .filter((k) => !k.startsWith('$'))
+            .sort()
+            .map((k) => [k, canonicalUnit(v[k])])
+        )
+      : v
+
+/**
+ * Whether the backend's post-write copy of a unit is the content we sent.
+ *
+ * Compared on OUR keys only. The two are not byte-comparable — the backend's copy
+ * carries fields we don't emit (`params`, `theme_override`, its own `$uuid`) and
+ * orders keys its own way, which is why `site-diff.js` never hashes one side against
+ * the other — but what we emit, it stores verbatim: measured 2026-09-23 against a
+ * live `uniwebd`, 15 of 15 units equal on our keys after a push.
+ */
+function writtenAsSent(sent, written) {
+  if (!sent || !written) return false
+  const onOurKeys = {}
+  for (const k of Object.keys(sent)) if (!k.startsWith('$')) onOurKeys[k] = written[k]
+  return JSON.stringify(canonicalUnit(sent)) === JSON.stringify(canonicalUnit(onOurKeys))
+}
+
+/**
+ * The post-write tokens a site-content push may bank: only those that describe
+ * content this copy HOLDS.
+ *
+ * ⛔ BANKING EVERY RETURNED TOKEN LOST OTHER WRITERS' WORK — measured 2026-09-23 on a
+ * live `uniwebd`, two copies of one site:
+ *
+ *   1. B edits section X and pushes.
+ *   2. A, which has not pulled, pushes an edit to section Y. The per-item gate reads
+ *      A's X as untouched (`pkg == base`) and keeps B's X — correct. But the response
+ *      carries X's token for B's content, and A banked it.
+ *   3. A's next push of X then reads as "only you changed it" (`host == base`) and
+ *      overwrites B's edit, with no refusal.
+ *
+ * The entity token did the same to ADDITIONS: a section B added survived A's first
+ * push (created after A's base ⇒ KEEP), A banked a base newer than it, and A's next
+ * push deleted it (created at-or-before the base ⇒ "you dropped it").
+ *
+ * So a unit's token is banked only when its post-write copy is what we sent — our own
+ * write, or a unit nobody touched. A unit the backend kept for someone else keeps the
+ * token we already hold, which is the one for OUR content, so the next push that
+ * changes it is `pkg != base, host != base` and refused. And while the backend holds
+ * units we don't, the entity token stays where it was, so the next push keeps them.
+ *
+ * With either document missing there is nothing to compare, and the tokens are banked
+ * as the backend sent them — the contract is that `finalized[].document` is always
+ * there.
+ *
+ * @returns {{ version: string|null, itemVersions: Object<string,string>|null,
+ *   held: string[], kept: string[], foreign: string[] }} `held`: units the backend
+ *   holds as we sent them; `kept`: units it kept someone else's content for;
+ *   `foreign`: units it holds that we did not send. All paths.
+ */
+export function heldTokens({ sent, written, version = null, itemVersions = null }) {
+  if (!sent || !written) return { version, itemVersions, held: [], kept: [], foreign: [] }
+  const ours = collectSiteUnits(sent)
+  const theirs = collectSiteUnits(written)
+  const uuidAt = collectUnitUuids(written)
+  const units = new Set(Object.values(uuidAt))
+  const held = []
+  const kept = []
+  const foreign = []
+  const items = {}
+  for (const [path, uuid] of Object.entries(uuidAt)) {
+    if (!ours.has(path)) {
+      foreign.push(path)
+      continue
+    }
+    if (!writtenAsSent(ours.get(path), theirs.get(path))) {
+      kept.push(path)
+      continue
+    }
+    held.push(path)
+    if (itemVersions?.[uuid]) items[uuid] = itemVersions[uuid]
+  }
+  // A token for an item that is not a unit (a `queries` declaration) is never sent
+  // back — the emit narrows preconditions to units (`withBaseVersion`) — so it is
+  // banked as before: it can neither arm nor disarm anything.
+  for (const [uuid, token] of Object.entries(itemVersions || {})) {
+    if (!units.has(uuid)) items[uuid] = token
+  }
+  return {
+    version: foreign.length ? null : version,
+    itemVersions: itemVersions ? items : null,
+    held: held.sort(),
+    kept: kept.sort(),
+    foreign: foreign.sort()
+  }
+}
+
+// The files a unit projects to, under the site's own roots — `site.yml::paths` can
+// relocate `pages` and `layout`. `site.yml` stands for the `info` unit, which projects
+// to three files.
+function unitFilesOf(siteDir, unitPath) {
+  if (unitPath === 'site.yml') return ['site.yml', 'theme.yml', 'head.html']
+  let paths = {}
+  try {
+    paths = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))?.paths || {}
+  } catch {
+    /* no or unreadable site.yml — the defaults are right */
+  }
+  for (const root of ['pages', 'layout']) {
+    if (unitPath.startsWith(`${root}/`)) return [`${paths[root] || root}${unitPath.slice(root.length)}`]
+  }
+  return []
+}
+
+/**
+ * Record, as synced, the files of the units a push left on the backend as we sent them.
+ *
+ * ⭐ WHAT A PUSH DELIVERED IS THE NEXT MERGE'S ANCESTOR. `pull --merge` finds the
+ * version a file last synced at by the hash in `pull-written.json`. A pull records what
+ * it wrote; this records what a push delivered — the units `heldTokens` says the
+ * backend holds as ours, never one it kept for someone else. Without it, after a merge
+ * and a push the ancestor was the pull's raw output, which nobody commits: the next
+ * merge found no common version and put both whole files under conflict markers, for
+ * edits on different lines (measured 2026-09-23).
+ */
+function recordPushedUnits(siteDir, unitPaths) {
+  const files = new Set()
+  for (const p of unitPaths) for (const f of unitFilesOf(siteDir, p)) files.add(f)
+  const present = [...files].map((f) => join(siteDir, f)).filter((abs) => existsSync(abs))
+  if (present.length) recordWritten(siteDir, present)
+}
+
 // Pull the finalized entities out of the restore response. The backend returns
 // `{ report: { finalized: [ { index, uuid, changed, document }, … ] } }` — each entry
 // carries its position in the SUBMITTED sequence (`index`, the correlation key — `$id`
@@ -112,10 +249,10 @@ export function extractFinalized(payload) {
       uuid: d?.uuid ?? d?.document?.$uuid ?? null,
       changed: d?.changed,
       // Post-write optimistic-concurrency token, read back from the stored row.
-      // Cache it UNCONDITIONALLY — do not branch on `changed` and do not infer:
-      // the backend pins "zero-write ⇒ version unmoved" with a test, so a no-op
-      // resubmit returns the value we already hold, and anything else is theirs
-      // to report, not ours to derive.
+      // Do not branch on `changed`: the backend pins "zero-write ⇒ version unmoved"
+      // with a test, so a no-op resubmit returns the value we already hold. ⛔ But a
+      // site-content push banks it only while the stored document holds nothing we
+      // don't — see `heldTokens`, and what banking it unconditionally deleted.
       version: typeof d?.version === 'string' ? d.version : null,
       // Per-item post-write tokens, `{ recordUuid: <opaque> }` (backend `d7e46335`).
       // Same map shape and same key name the PULL manifest entry stamps, deliberately
@@ -548,8 +685,12 @@ export function readItemBaseVersions(siteDir, backend) {
 }
 export function mergeItemBaseVersions(siteDir, backend, versions) {
   if (!versions || !Object.keys(versions).length) return
+  // ⛔ The read names the backend. Without it the read keyed nothing, came back `{}`,
+  // and this "merge" replaced the map with the last response — dropping the token
+  // `heldTokens` withholds for a unit the backend kept for someone else, and with it
+  // the precondition that refuses the next push of that unit (2026-09-23).
   updateSyncCache(siteDir, backend, {
-    itemBaseVersions: { ...readItemBaseVersions(siteDir), ...versions }
+    itemBaseVersions: { ...readItemBaseVersions(siteDir, backend), ...versions }
   })
 }
 export function mergeBaseVersions(siteDir, backend, versions) {
@@ -935,6 +1076,31 @@ async function recordAndDescribeOwner({ client, siteDir, payload, note }) {
   return org
 }
 
+/**
+ * Stop a push or publish before it sends anything, when a record cannot be sent as
+ * written — the emit's `refusals` (`@uniweb/build`'s `recordsToEntities`).
+ *
+ * ⛔ Checked BEFORE the site is created or a byte uploaded, not only before the send:
+ * both are writes of their own, which a refused records lane does not undo. (The lane
+ * itself is one transaction on the backend since 2026-09-24, so a refusal there writes
+ * nothing. Before that, a refused lane left the folder's entries and entities with no
+ * data behind, and every later push of the site's records was refused — measured
+ * 2026-09-23, from one record written by section.)
+ *
+ * @param {string[]|undefined} refusals
+ * @param {{ error: (m: string) => void, note: (m: string) => void }} report
+ * @returns {boolean} true when the caller must stop
+ */
+export function refuseUnsendableRecords(refusals, { error, note }) {
+  if (!refusals?.length) return false
+  const n = refusals.length
+  error(
+    `${n === 1 ? 'A record' : `${n} records`} cannot be pushed as written — no content was sent.`
+  )
+  for (const r of refusals) note(`  ${r}`)
+  return true
+}
+
 /**
  * Guarantee we have per-item identity before an identity-bearing push.
  *
@@ -1440,11 +1606,11 @@ export async function pushSyncPackages({
   const harvest = (finalized) => {
     for (const f of finalized || []) {
       if (f.uuid && f.version) newVersions[f.uuid] = f.version
-      // Unconditionally, and NOT gated on `changed` — same rule as the entity
-      // token: the backend pins "zero-write ⇒ version unmoved", so a no-op
-      // resubmit hands back the value we already hold. An older backend omits the
-      // field entirely, which leaves the cached tokens alone and degrades to the
-      // entity grain, exactly as before.
+      // NOT gated on `changed` — same rule as the entity token: the backend pins
+      // "zero-write ⇒ version unmoved", so a no-op resubmit hands back the value we
+      // already hold. (The site-content lane filters first, `harvestSiteContent`.)
+      // An older backend omits the field entirely, which leaves the cached tokens
+      // alone and degrades to the entity grain, exactly as before.
       if (f.itemVersions) Object.assign(newItemVersions, f.itemVersions)
     }
   }
@@ -1453,6 +1619,27 @@ export async function pushSyncPackages({
     mergeBaseVersions(siteDir, client.origin, newVersions)
     mergeItemBaseVersions(siteDir, client.origin, newItemVersions)
   }
+  // ⛔ The site-content lane banks only the tokens for content this copy holds — the
+  // document we sent against the one the backend stored (`heldTokens`, and the two
+  // losses banking everything caused). What the backend kept for someone else is
+  // collected here, to re-base attribution and to say so.
+  const sentSiteDoc = siteContent ? entityDocFromUwx(siteContent.buffer) : null
+  const notHeld = { kept: [], foreign: [] }
+  const heldUnits = []
+  const harvestSiteContent = (finalized) => {
+    for (const f of finalized || []) {
+      const held = heldTokens({
+        sent: sentSiteDoc,
+        written: f.document,
+        version: f.version,
+        itemVersions: f.itemVersions
+      })
+      harvest([{ ...f, version: held.version, itemVersions: held.itemVersions }])
+      heldUnits.push(...held.held)
+      notHeld.kept.push(...held.kept)
+      notHeld.foreign.push(...held.foreign)
+    }
+  }
   // The backend's post-write copy of the site-content document, kept for the
   // remote-side unit base (see writeUnitBases).
   let siteFinalizedDoc = null
@@ -1475,7 +1662,7 @@ export async function pushSyncPackages({
         mergeHarvested()
         return { exitCode: 1, finalizedTotal, wrote }
       }
-      harvest(finalized)
+      harvestSiteContent(finalized)
       siteFinalizedDoc = finalized[0]?.document || null
       // ⭐ BANK COLLECTION-DECLARATION IDENTITY, the sibling of the folder's
       // placements below. These items have no file to back-fill into — they all
@@ -1519,7 +1706,7 @@ export async function pushSyncPackages({
       if (createdOrg)
         wrote.push(`recorded its owner (${createdOrg}) in sync.json`)
       const createdFinalized = extractFinalized(payload)
-      harvest(createdFinalized)
+      harvestSiteContent(createdFinalized)
       siteFinalizedDoc = createdFinalized?.[0]?.document || null
       finalizedTotal += createdFinalized?.length ?? 1
     }
@@ -1589,12 +1776,21 @@ export async function pushSyncPackages({
   // actually shipped — a push that skipped it left that state where it was.
   if (siteContent) {
     const patch = {}
-    const ours = entityDocFromUwx(siteContent.buffer)
+    const ours = sentSiteDoc
     if (ours) patch.local = computeUnitHashes(ours)
     // `finalized[].document` is the backend's own representation, read back from
     // the stored row — the only remote-side base a push can produce.
     const theirs = siteFinalizedDoc?.pages ? siteFinalizedDoc : null
-    if (theirs) patch.remote = computeUnitHashes(theirs)
+    if (theirs) {
+      patch.remote = computeUnitHashes(theirs)
+      // A unit the backend kept for someone else is not agreed state: its remote base
+      // stays where it was, so a refusal names it as changed upstream.
+      const before = readUnitBases(siteDir, client.origin).remote
+      for (const path of notHeld.kept) {
+        if (before[path]) patch.remote[path] = before[path]
+        else delete patch.remote[path]
+      }
+    }
     if (Object.keys(patch).length) writeUnitBases(siteDir, client.origin, patch)
     // The backend's post-write document carries `$uuid` per item at every nesting
     // level, so the push that just landed also re-arms identity for the next one.
@@ -1622,6 +1818,16 @@ export async function pushSyncPackages({
       )
     }
   }
+  // The files of the units the backend now holds as ours are the synced version — the
+  // ancestor the next `pull --merge` merges from.
+  if (heldUnits.length) recordPushedUnits(siteDir, heldUnits)
+  // What the backend holds that this copy doesn't. None of it was overwritten, and no
+  // later push will overwrite it — but the files are behind until a pull.
+  if (notHeld.kept.length || notHeld.foreign.length) {
+    const paths = [...new Set([...notHeld.kept, ...notHeld.foreign])].sort()
+    note(`Changed on the backend by someone else, not in your files yet: ${paths.join(', ')}`)
+    note('Take them with `uniweb refresh` (or `uniweb pull --merge`). Until then, pushing leaves them as they are.')
+  }
   // ⛔ A DRAFT THE BACKEND STORED ENABLED FAILS THE PUSH, and only here, after every
   // piece of sync state above is banked: the push itself happened, and the next one must
   // see it. What must not happen is a publish that goes live on top of it, which is why

package/src/commands/clone.js

@@ -102,7 +102,7 @@ function slugify(s) {
 // than imported because pull.js statically imports @uniweb/build).
 export function extractDocument(payload) {
   if (!payload || typeof payload !== 'object') return null
-  if (payload.$model || payload.$id || payload.info) return payload
+  if (payload.$schema || payload.$uuid || payload.$id || payload.info) return payload
   return payload.document || payload.entity || null
 }
 

package/src/commands/deploy.js

@@ -93,10 +93,6 @@ export async function deploy(args = []) {
   const dryRun = args.includes('--dry-run')
   const siteDir = await resolveSiteDir(args)
 
-  // Advisory only — warns and ships. See utils/conformance.js for why this
-  // is not a gate.
-  await warnIfContentDoesNotConform(siteDir, { args, warn: say.warn, dim: say.dim })
-
   // Host dispatch. Resolution order:
   //   1. --target <name> picks a target from deploy.yml
   //   2. deploy.yml's `default:` target when no flag is given
@@ -184,6 +180,13 @@ export async function deploy(args = []) {
     }
   }
 
+  // A static host: advisory — warns and ships (utils/conformance.js). Uniweb Cloud is
+  // `publish`, below, which refuses content that does not conform: there the backend
+  // enforces the schemas, so the check is a gate, not advice (2026-09-24).
+  if (plan.kind !== 'uniweb') {
+    await warnIfContentDoesNotConform(siteDir, { args, warn: say.warn, dim: say.dim })
+  }
+
   // Uniweb Cloud is `publish`'s flow — delegate so deploy.yml stays one
   // actionable record and there's a single implementation of go-live.
   if (plan.kind === 'uniweb') {
@@ -224,9 +227,8 @@ export async function deploy(args = []) {
     // publish ignores deploy's --host/--target; --dry-run/--no-save pass straight
     // through.
     const { publish } = await import('./publish.js')
-    // Conformance was already reported above, and publish runs the same check
-    // — without this the user reads one warning twice and learns to skim it.
-    const result = await publish([...args, '--no-validate'])
+    // publish runs the conformance gate itself; deploy checked nothing for this host.
+    const result = await publish(args)
     process.exit(result?.exitCode ?? 0)
   }
 

package/src/commands/publish.js

@@ -68,7 +68,7 @@ import {
 } from '../backend/client.js'
 import { DEFAULT_BACKEND_ORIGIN } from '../utils/config.js'
 import { resolveSiteDir } from './deploy.js'
-import { warnIfContentDoesNotConform } from '../utils/conformance.js'
+import { refuseIfContentDoesNotConform } from '../utils/conformance.js'
 import { readFlagValue } from '../utils/args.js'
 import { checkFlags } from '../utils/flag-guard.js'
 import {
@@ -87,6 +87,7 @@ import {
   ensureItemUuids,
   readFolderItemUuids,
   ensureSiteExists,
+  refuseUnsendableRecords,
   clearRemoteSyncStateIfUnbound,
   dropSiteBoundValues,
   pushSyncPackages
@@ -255,9 +256,11 @@ export async function publish(args = []) {
 
   const siteDir = await resolveSiteDir(args, 'publish')
 
-  // Advisory only — warns and ships. See utils/conformance.js for why this
-  // is not a gate.
-  await warnIfContentDoesNotConform(siteDir, { args })
+  // ⭐ A GATE, before anything is sent — the backend checks these records against the
+  // schemas this publish registers. See utils/conformance.js.
+  if (await refuseIfContentDoesNotConform(siteDir, { args, error: say.err, warn: say.warn, dim: say.dim })) {
+    return { exitCode: 1 }
+  }
   const siteYml = readSiteYml(join(siteDir, 'site.yml'))
   // ⭐ THE BACKEND YOU ARE LOGGED IN TO is where this goes *[Diego, 2026-09-21]*, for every
   // backend verb (resolveBackendOrigin). Only UNIWEB_REGISTER_URL — the automation
@@ -568,6 +571,11 @@ export async function publish(args = []) {
     say.err(`Could not build the sync package: ${err.message}`)
     return { exitCode: 1 }
   }
+  // A record the backend would refuse stops the publish HERE — before the site is
+  // created or a byte uploaded, not merely before the send (`refuseUnsendableRecords`).
+  if (refuseUnsendableRecords(probe.refusals, { error: say.err, note: say.dim })) {
+    return { exitCode: 1 }
+  }
   const schemalessNames = (probe.schemaless || []).map((col) => col.name)
   // A product decision the author is usually making unknowingly — say it at warn
   // level, not dim among everything else. See the helper for what the old
@@ -964,6 +972,9 @@ export async function publish(args = []) {
     return { exitCode: 1 }
   }
   for (const w of pkg.warnings) say.dim(`! ${w}`)
+  if (refuseUnsendableRecords(pkg.refusals, { error: say.err, note: say.dim })) {
+    return { exitCode: 1 }
+  }
   const report = {
     info: (m) => say.info(m),
     note: (m) => say.dim(m),