uniweb 0.13.5 → 0.13.6

package/src/commands/pull.js

@@ -12,9 +12,25 @@
  *     pages/**, layout/**), and
  *   - folder lane  → `collectionsToProject` (the folder + record files).
  *
- * Pull is git-pull-like: it reconciles the working tree to the backend, DELETING
- * pages/sections that no longer exist there (toggle off with `--no-delete`). The
- * deletion is guarded so an empty/partial payload never wipes the tree.
+ * Pull is a CHECKOUT, not a merge — the "git-pull-like" it used to claim here was
+ * misleading. It reconciles the working tree to the backend: section bodies are
+ * rewritten from the fetched document, and pages/sections the backend no longer has
+ * are DELETED (toggle off with `--no-delete`). The deletion is guarded so an
+ * empty/partial payload never wipes the tree.
+ *
+ * Because it overwrites rather than merges, it REFUSES when there is uncommitted
+ * work under the directories it owns — that was the one remaining way the CLI could
+ * destroy a user's work without them agreeing to it. Commit or stash first, or pass
+ * `--force`. Outside a git repository there is nothing to fall back on, so it asks
+ * instead (and refuses when it cannot).
+ *
+ * `--merge` is the third option, and usually the one you want after a refused push:
+ * three-way merge local work with what the backend sends, instead of choosing
+ * between them. Most "conflicts" are two people editing different paragraphs of one
+ * section, which merges silently; only genuine overlaps get conflict markers. The
+ * common ancestor is the COMMITTED version of each file — the backend keeps no
+ * per-version history and does not need to — so `--merge` requires a repo, and the
+ * merge itself is `git merge-file`.
  *
  * `uniweb login && uniweb pull`. Run from a site, or a workspace with one site.
  *
@@ -22,6 +38,8 @@
  *   uniweb pull                          GET both lanes, project to files, prune orphans
  *   uniweb pull --no-collections         Pull pages only; skip the folder (collections) lane
  *   uniweb pull --no-delete              Project, but keep files with no backend item
+ *   uniweb pull --merge                  Three-way merge local changes with the backend's
+ *   uniweb pull --force                  Pull over uncommitted local changes (discards them)
  *   uniweb pull --dry-run                Report what it would GET; write nothing
  *   uniweb pull --registry <url>         Override the backend origin
  *   uniweb pull --token <bearer>         Read with this bearer; skips `uniweb login`
@@ -38,16 +56,29 @@
  * against the playground backend, 2026-06-17.
  */
 
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
-import { join, dirname } from 'node:path'
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { createHash } from 'node:crypto'
+import { createInterface } from 'node:readline/promises'
+import { join, dirname, relative } from 'node:path'
 import yaml from 'js-yaml'
 import {
   siteContentDocumentToProject,
   collectionsToProject,
   resolveCollectionsConfig,
   readZip,
+  computeUnitHashes,
+  collectUnitUuids,
 } from '@uniweb/build/uwx'
 import { makeModelResolver } from './push.js'
+import {
+  mergeBaseVersions,
+  mergeItemBaseVersions,
+  writeUnitBases,
+  writeItemUuids,
+} from '../backend/site-sync.js'
+import { uncommittedUnder, siteContentRoots, showAtHead, mergeFile } from '../utils/git.js'
+import { isNonInteractive } from '../utils/interactive.js'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir as defaultResolveSiteDir, resolveSiteBackend } from './deploy.js'
 
@@ -167,11 +198,280 @@ export function readPullDocuments(buf) {
   return single ? [single] : []
 }
 
+// Read the per-entity optimistic-concurrency tokens out of a pull lane's manifest.
+// The backend stamps each entity entry with a top-level `version` (opaque RFC3339);
+// we cache it and echo it back as `base_version` on the next push, so a push
+// against a base the backend has moved past is refused instead of silently
+// overwriting. Returns a `{ <backend-uuid>: <version> }` map — empty for a JSON
+// fallback body (no manifest ⇒ no tokens ⇒ that lane simply stays unconditional).
+//
+// TOP-LEVEL on the entry. The backend's `Entry::extra` is `#[serde(flatten)]`, so
+// it never appears on the wire; reading `extra.version` finds nothing and silently
+// leaves the gate disarmed (which is exactly what it did before 2026-07-26).
+//
+// Keyed by `entries[].uuid`, which on a PULL manifest is the real backend uuid.
+// Note that is NOT symmetric with what we EMIT: on the push side that field is our
+// `$id` handle, and the backend correlates our `base_version` via the body's
+// `$uuid` instead. Same field name, different meaning by direction.
+//
+// This reads the SAME manifest.json that readPullDocuments deliberately skips:
+// there the entity files are the payload, here the manifest is the index we were
+// previously discarding.
+export function readPullVersions(buf) {
+  return readManifestTokens(buf).entity
+}
+
+/**
+ * Per-ITEM staleness tokens: `{ <record $uuid>: <opaque version> }`, from the
+ * entry's `item_versions`.
+ *
+ * The entity token can only say "something in this document moved"; these say
+ * which records did, which is what lets two people editing different sections
+ * both land instead of one being refused. Echoed back as `item_base_versions`.
+ *
+ * Keyed by record uuid rather than by our file path deliberately: the token then
+ * joins to the body by the same identity the backend's reconcile uses, and a file
+ * rename cannot silently re-target it. Absent for an entity with no items, and
+ * absent from an older backend — both mean "no per-item precondition", fall back
+ * to the entity grain.
+ */
+export function readPullItemVersions(buf) {
+  return readManifestTokens(buf).item
+}
+
+// One manifest read for both grains — they arrive on the same entry and must not
+// drift apart by being parsed in two places.
+function readManifestTokens(buf) {
+  const out = { entity: {}, item: {} }
+  if (!(buf.length >= 2 && buf[0] === 0x50 && buf[1] === 0x4b)) return out
+  for (const [name, data] of readZip(buf)) {
+    if (name !== 'manifest.json') continue
+    try {
+      const manifest = JSON.parse(data.toString('utf8'))
+      for (const entry of manifest?.entries || []) {
+        if (entry?.uuid && typeof entry.version === 'string') out.entity[entry.uuid] = entry.version
+        const items = entry?.item_versions
+        if (items && typeof items === 'object') {
+          for (const [uuid, v] of Object.entries(items)) {
+            if (typeof v === 'string') out.item[uuid] = v
+          }
+        }
+      }
+    } catch {
+      /* an unreadable manifest just means no tokens this pull */
+    }
+    break
+  }
+  return out
+}
+
 /**
  * @param {string[]} args
  * @param {object} [deps] - injectable seams for testing: `fetch` (default global
  *   fetch), `resolveSiteDir`, `getToken` (skip auth).
  */
+/**
+ * Refuse a pull that would overwrite unsaved work. Returns a result object to
+ * return from `pull`, or null to proceed.
+ *
+ * With a repo: uncommitted work under pull's roots blocks, naming the files.
+ * Without one: there is nothing standing behind the tree, so ask — and in a
+ * non-interactive context refuse rather than assume consent.
+ */
+async function checkWorkingTree(siteDir, args) {
+  const roots = siteContentRoots(siteDir)
+  let dirty = uncommittedUnder(siteDir, roots)
+
+  if (dirty === null) {
+    // Not a git work tree. Nothing to fall back on if this goes wrong.
+    if (isNonInteractive(args)) {
+      error('Refusing to pull: this site is not in a git repository.')
+      note('Pull rewrites pages, sections and layout from the backend and deletes what it no longer has.')
+      note('Without version control there is no way back, and this session cannot ask.')
+      note('Re-run with --force to accept that, or put the site under git first.')
+      return { exitCode: 1 }
+    }
+    const ok = await confirm(`Pull will overwrite ${roots.length} content location(s) and this site is not in git. Continue?`)
+    if (!ok) {
+      info('Nothing pulled.')
+      return { exitCode: 0 }
+    }
+    return null
+  }
+
+  const written = readWritten(siteDir)
+  dirty = dirty.filter((f) => !isPullOutput(siteDir, f, written))
+  if (!dirty.length) return null
+
+  error(`Refusing to pull: ${dirty.length} uncommitted change(s) under the files pull rewrites.`)
+  for (const f of dirty.slice(0, 12)) note(`  ${f}`)
+  if (dirty.length > 12) note(`  … and ${dirty.length - 12} more`)
+  note('Pull reconciles the working tree to the backend, so these would be overwritten or deleted.')
+  note('Commit or stash them first — then pull, and your work is still in git either way.')
+  note('To discard them and take the backend version, re-run with --force.')
+  return { exitCode: 1 }
+}
+
+// What the last pull wrote: `{ <repo-relative path>: <sha256 of the bytes it wrote> }`.
+//
+// Without this the guard cries wolf: pull rewrites the tree, so the very next pull
+// sees its OWN output as uncommitted work and refuses, listing files the user never
+// touched. A guard that fires on nothing teaches people to reach for --force, which
+// is the destructive option — the same failure mode as a gate that refuses disjoint
+// edits. A file still byte-identical to what pull last wrote is not user work.
+function writtenCachePath(siteDir) {
+  return join(siteDir, '.uniweb', 'pull-written.json')
+}
+function readWritten(siteDir) {
+  try {
+    const o = JSON.parse(readFileSync(writtenCachePath(siteDir), 'utf8'))
+    return {
+      files: o && typeof o.files === 'object' ? o.files : {},
+      deleted: Array.isArray(o?.deleted) ? o.deleted : [],
+    }
+  } catch {
+    return { files: {}, deleted: [] }
+  }
+}
+function recordWritten(siteDir, absPaths, deletedAbs = []) {
+  // MERGE, don't replace. A conditional pull that 304s writes nothing, and a
+  // partial pull writes only some lanes — in both cases the previous record is
+  // still "the last thing pull wrote there". Replacing would forget those paths and
+  // the next pull would see them as the user's work again, which is the false alarm
+  // this cache exists to prevent. A stale entry for a file that no longer exists is
+  // harmless: the hash read fails and it counts as a local change.
+  const prior = readWritten(siteDir)
+  const files = prior.files
+  for (const abs of absPaths) {
+    try {
+      files[relative(siteDir, abs)] = createHash('sha256').update(readFileSync(abs)).digest('hex')
+    } catch { /* deleted or unreadable — nothing to remember */ }
+  }
+  // Pull PRUNES too, and a deletion is a dirty path git reports just like an edit.
+  // Without recording them, pull's own pruning reads as the user having deleted
+  // files — the same false alarm as its writes, arriving by the other door.
+  const deleted = [...new Set([...prior.deleted, ...deletedAbs.map((a) => relative(siteDir, a))])]
+  try {
+    mkdirSync(dirname(writtenCachePath(siteDir)), { recursive: true })
+    writeFileSync(writtenCachePath(siteDir), JSON.stringify({ version: 1, files, deleted }, null, 2) + '\n')
+  } catch { /* best-effort: losing it only costs a spurious refusal */ }
+}
+// Is this dirty path just pull's own untouched output?
+function isPullOutput(siteDir, relPath, written) {
+  let exists = true
+  let hash = null
+  try {
+    hash = createHash('sha256').update(readFileSync(join(siteDir, relPath))).digest('hex')
+  } catch {
+    exists = false
+  }
+  // Absent because pull pruned it — not because the user deleted it.
+  if (!exists) return written.deleted.includes(relPath)
+  return written.files[relPath] === hash
+}
+
+/**
+ * `--merge`: keep local work instead of refusing, by three-way merging it with what
+ * the backend sends.
+ *
+ * Without this the recovery from a same-section conflict is commit → pull (which
+ * overwrites your version) → re-apply by hand → push. Yet most such "conflicts"
+ * aren't: two people edited different paragraphs of one section, and a real merge
+ * takes both. Only genuine overlaps need a human.
+ *
+ * Works by capturing local content BEFORE the projection overwrites it, then
+ * merging afterwards — so the projector stays a plain writer and needs no hook, and
+ * nothing is lost in between because "mine" is already in memory.
+ *
+ * Requires a repo, and that is not a mandate creeping in: the ancestor IS the
+ * committed version, and the merge is git's. There is nothing to merge against
+ * without one.
+ *
+ * @returns {Map<string, {content: Buffer, inHead: boolean}>|null} captured work, or
+ *   null when merging isn't possible here (the caller reports and stops).
+ */
+function captureLocalWork(siteDir) {
+  const dirty = uncommittedUnder(siteDir, siteContentRoots(siteDir))
+  if (dirty === null) return null
+  const written = readWritten(siteDir)
+  const out = new Map()
+  for (const rel of dirty) {
+    if (isPullOutput(siteDir, rel, written)) continue // pull's own output, not work
+    try {
+      out.set(rel, { content: readFileSync(join(siteDir, rel)), inHead: showAtHead(siteDir, rel) !== null })
+    } catch {
+      // Locally deleted. Pull will restore the backend's copy, which is the
+      // sensible reading of "I removed this and then asked for their version".
+    }
+  }
+  return out
+}
+
+// Merge captured work back over what the projection just wrote. Returns a report.
+function mergeLocalWork(siteDir, captured) {
+  const clean = []
+  const conflicted = []
+  const kept = []
+  for (const [rel, { content: mine, inHead }] of captured) {
+    const abs = join(siteDir, rel)
+    let theirs = null
+    try { theirs = readFileSync(abs) } catch { /* pruned by the pull */ }
+
+    if (theirs === null) {
+      // The backend no longer has it, but we changed it. Restoring is the
+      // non-destructive reading; the alternative silently discards local work to
+      // honour a deletion the user never saw.
+      mkdirSync(dirname(abs), { recursive: true })
+      writeFileSync(abs, mine)
+      kept.push(`${rel} (removed upstream, kept yours)`)
+      continue
+    }
+    if (theirs.equals(mine)) continue // both sides agree already
+
+    const base = inHead ? showAtHead(siteDir, rel) : null
+    if (!base) {
+      // No committed ancestor — a file added locally and never committed. There is
+      // no third input, so a three-way merge is not defined. Keep ours rather than
+      // guess, and say so.
+      writeFileSync(abs, mine)
+      kept.push(`${rel} (no committed ancestor, kept yours)`)
+      continue
+    }
+
+    const dir = mkdtempSync(join(tmpdir(), 'uniweb-merge-'))
+    try {
+      const basePath = join(dir, 'base')
+      const theirsPath = join(dir, 'theirs')
+      writeFileSync(basePath, base)
+      writeFileSync(theirsPath, theirs)
+      writeFileSync(abs, mine) // merge-file rewrites this in place
+      const r = mergeFile(siteDir, abs, basePath, theirsPath)
+      if (!r.merged) {
+        writeFileSync(abs, mine) // merge couldn't run — never leave a half-state
+        kept.push(`${rel} (merge unavailable, kept yours)`)
+      } else if (r.conflicted) {
+        conflicted.push(rel)
+      } else {
+        clean.push(rel)
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  }
+  return { clean, conflicted, kept }
+}
+
+// Minimal yes/no prompt; defaults to no, because the default must not destroy.
+async function confirm(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const a = (await rl.question(`${question} [y/N] `)).trim().toLowerCase()
+    return a === 'y' || a === 'yes'
+  } finally {
+    rl.close()
+  }
+}
+
 export async function pull(args = [], deps = {}) {
   const resolveSiteDir = deps.resolveSiteDir || defaultResolveSiteDir
 
@@ -179,8 +479,36 @@ export async function pull(args = [], deps = {}) {
   const tokenFlag = flagValue(args, '--token')
   const prune = !(args.includes('--no-delete') || args.includes('--no-prune')) // git-like by default
   const noCollections = args.includes('--no-collections') || args.includes('--content-only')
+  const force = args.includes('--force')
+  const mergeMode = args.includes('--merge')
 
   const siteDir = await resolveSiteDir(args, 'pull')
+
+  // Don't overwrite work that isn't saved anywhere. Pull reconciles the working
+  // tree to the backend — it rewrites section bodies from the fetched document and
+  // prunes what the backend doesn't have — so uncommitted work under the
+  // directories it owns is destroyed with no way back. That is the one place the
+  // CLI could still lose a user's work without them agreeing to it.
+  //
+  // Checked coarsely, by root, on purpose: pull rewrites essentially every file
+  // under those roots, so an exact per-file intersection would refuse the same
+  // cases while being able to miss one.
+  // `--merge` keeps local work instead of refusing it: capture what is dirty now,
+  // let the projection write the backend's version, then merge ours back over it.
+  let captured = null
+  let mergeReport = null
+  if (!dryRun && mergeMode) {
+    captured = captureLocalWork(siteDir)
+    if (captured === null) {
+      error('Cannot merge: this site is not in a git repository.')
+      note('The common ancestor a merge needs is the committed version of each file.')
+      note('Without a repo there is nothing to merge against — use `uniweb pull --force` to take the backend version.')
+      return { exitCode: 1 }
+    }
+  } else if (!dryRun && !force) {
+    const blocked = await checkWorkingTree(siteDir, args)
+    if (blocked) return blocked
+  }
   const siteBackend = await resolveSiteBackend(siteDir)
   const client = new BackendClient({
     originFlag: flagValue(args, '--backend') || flagValue(args, '--registry'),
@@ -236,7 +564,13 @@ export async function pull(args = [], deps = {}) {
     }
     try {
       const etag = res.headers?.get?.('etag') ?? null
-      const docs = readPullDocuments(Buffer.from(await res.arrayBuffer()))
+      const buf = Buffer.from(await res.arrayBuffer())
+      const docs = readPullDocuments(buf)
+      // Bank the per-entity staleness tokens this lane carried, so the next push
+      // is gated against the state we just took. A 304 skips this — correctly:
+      // unchanged upstream means the token we already hold is still current.
+      mergeBaseVersions(siteDir, readPullVersions(buf))
+      mergeItemBaseVersions(siteDir, readPullItemVersions(buf))
       return { docs, etag }
     } catch (err) {
       error(`Could not read the ${label} response: ${err.message}`)
@@ -244,6 +578,10 @@ export async function pull(args = [], deps = {}) {
     }
   }
 
+  // Every file the projection writes, so the next pull can tell its own output
+  // apart from the user's work (see readWritten).
+  const wrote = []
+  const removed = []
   let pages = 0
   let sections = 0
   let records = 0
@@ -261,7 +599,20 @@ export async function pull(args = [], deps = {}) {
   if (content && !content.notModified) {
     const siteDoc = content.docs && (content.docs.find((d) => d?.info || d?.$model) || content.docs[0] || null)
     if (siteDoc) {
+      // Re-base the page attribution. The pulled document IS the backend's own
+      // representation, so it becomes the remote base directly. We deliberately
+      // CLEAR the local base rather than reuse it: our source files were just
+      // rewritten from this document, and what we would emit from them is not
+      // byte-identical to it, so the old local base no longer describes anything.
+      // The next push re-establishes it; until then our side reports as unknown,
+      // which is honest rather than wrong.
+      writeUnitBases(siteDir, { remote: computeUnitHashes(siteDoc), local: {} })
+      // Per-item identity for the next push. Without it the backend reads our
+      // records as new and re-mints every page and section row.
+      writeItemUuids(siteDir, collectUnitUuids(siteDoc))
       const report = siteContentDocumentToProject({ document: siteDoc, siteRoot: siteDir, prune })
+      wrote.push(...report.pages, ...report.sections, ...report.layout)
+      removed.push(...(report.deleted || []), ...(report.renamed || []).map((r) => r.from))
       pages += report.pages.length
       sections += report.sections.length
       deleted += report.deleted.length
@@ -302,9 +653,38 @@ export async function pull(args = [], deps = {}) {
 
   // Persist the ETags so the next pull is conditional (304 when unchanged).
   writePullCache(siteDir, { content: etagContent, folder: etagFolder })
+  // Config files are rewritten every pull whether or not they changed; include the
+  // ones the projector owns so a pull-then-pull doesn't trip on them either.
+  // Merge captured local work back over what the projection just wrote. Runs after
+  // BOTH lanes, so a file either lane produced is merged the same way.
+  if (captured && captured.size) {
+    mergeReport = mergeLocalWork(siteDir, captured)
+    const r = mergeReport
+    if (r.clean.length) {
+      info(`Merged your changes into ${r.clean.length} file(s):`)
+      for (const f of r.clean) note(`  ${f}`)
+    }
+    for (const f of r.kept) note(`\u21b7 ${f}`)
+    if (r.conflicted.length) {
+      error(`${r.conflicted.length} file(s) have conflicts to resolve:`)
+      for (const f of r.conflicted) note(`  ${f}`)
+      note('Conflict markers are in place. Resolve them, then commit and push.')
+    }
+  }
+
+  recordWritten(
+    siteDir,
+    [...wrote, ...['site.yml', 'theme.yml', 'head.html', 'collections.yml'].map((f) => join(siteDir, f))],
+    removed
+  )
 
   success(
     `Pulled — ${pages} page(s), ${sections} section(s), ${records} record(s)` + (deleted ? `, ${deleted} deleted` : '')
   )
-  return { exitCode: 0 }
+  // Unresolved conflicts are a non-zero exit, the way a conflicted `git merge` is.
+  // The pull itself worked; there is work left for a human. This is what makes a
+  // chained `uniweb pull --merge && uniweb push` safe by construction — without it,
+  // the obvious one-liner pushes conflict markers into live content.
+  const conflicts = mergeReport?.conflicted?.length ?? 0
+  return { exitCode: conflicts ? 1 : 0, merge: mergeReport }
 }

package/src/commands/push.js

@@ -12,8 +12,11 @@
  * UPDATE by that uuid. The folder lane is keyed by the SAME site-content uuid —
  * the backend owns the site's `@uniweb/folder`, so the framework never holds a
  * folder uuid. Records still round-trip their own `$uuid`
- * (back-filled into their source files). site-content is pushed wholesale (no per-item
- * uuids on the wire). Push-only, last-push-wins (`collision=force`) in v1.
+ * (back-filled into their source files). site-content items carry a per-item `$uuid`
+ * too, stamped at emit from the identity cache rather than from author files — without
+ * it the backend reads every record as new and recreates every page and section row.
+ * Push-only, and gated on the backend's per-entity `version`
+ * (see "Pushes are GATED by default" below); `--force` restores last-push-wins.
  *
  * Order: content first (CREATE or UPDATE — the site must exist before its folder),
  * then the folder, keyed by the site's uuid. On a brand-new site the backend creates
@@ -30,6 +33,14 @@
  *   uniweb push --token <bearer>         Submit with this bearer; skips `uniweb login`
  *   uniweb push --foundation <dir>       Use this local foundation for the Model schema
  *   uniweb push --all                    Send every record (bypass the changed-only cache)
+ *   uniweb push --force                  Overwrite upstream changes (drop the staleness gate)
+ *
+ * Pushes are GATED by default: each entity carries the backend `version` this clone
+ * last saw (a top-level `base_version` on the manifest entry), and the backend refuses the whole package
+ * atomically — before any write — if its stored version has moved. That prevents a
+ * developer who hasn't pulled from silently destroying an app author's edits (the
+ * backend's reconcile deletes items absent from the package, so an author's NEW page
+ * would be hard-deleted). `--force` omits the token and restores last-push-wins.
  *
  * Backend: via BackendClient (the content + folder sync lanes). Origin from
  *   --registry  >  UNIWEB_REGISTER_URL  >  the local default.
@@ -46,7 +57,15 @@ import { resolve } from 'node:path'
 import { emitSyncPackages } from '@uniweb/build/uwx'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
-import { makeModelResolver, readSyncCache, pushSyncPackages } from '../backend/site-sync.js'
+import {
+  makeModelResolver,
+  readSyncCache,
+  readBaseVersions,
+  readItemBaseVersions,
+  readItemUuids,
+  ensureItemUuids,
+  pushSyncPackages,
+} from '../backend/site-sync.js'
 
 // Re-exported for downstream importers (pull.js, push.test.js) that read these
 // helpers from this module — their canonical home is now ../backend/site-sync.js.
@@ -77,6 +96,12 @@ export async function push(args = []) {
   const asOrg = flagValue(args, '--as-org')
   const foundationDir = flagValue(args, '--foundation')
   const sendAll = args.includes('--all') // bypass the send-only-changed cache
+  // --force drops the optimistic-concurrency precondition, making the push
+  // unconditional (the backend then falls back to its `collision` policy). It is
+  // deliberately NOT "send collision=force": when a base_version is present the
+  // backend consults it and never looks at `collision`, so forcing has to mean
+  // OMITTING the token — the HTTP If-Match idiom.
+  const force = args.includes('--force')
 
   const siteDir = await resolveSiteDir(args, 'push')
   const siteBackend = await resolveSiteBackend(siteDir)
@@ -98,6 +123,17 @@ export async function push(args = []) {
   // position. Non-local Models are fetched from the registry on demand. `priorHashes`
   // (the .uniweb push-cache) drives "send only changed" across both lanes; --all bypasses.
   const priorHashes = readSyncCache(siteDir)
+  // Per-item identity, without which the backend reads every record as new and
+  // recreates every page and section row.
+  //
+  // An offline preview (`-o` / `--dry-run`) still stamps from the CACHE — that is a
+  // local file read, so it stays offline, and it keeps the emitted `.uwx` faithful
+  // to what a real push would send. Only the network RECOVERY is skipped, so a
+  // preview never reaches the backend. (Emitting `{}` here instead would make the
+  // preview quietly unrepresentative, which is the one thing `-o` exists to avoid.)
+  const itemUuids = (output || dryRun)
+    ? readItemUuids(siteDir)
+    : await ensureItemUuids({ client, siteDir, note })
   let pkg
   try {
     pkg = await emitSyncPackages(siteDir, {
@@ -105,6 +141,10 @@ export async function push(args = []) {
       resolveModel: makeModelResolver({ client, offline: Boolean(output) || dryRun }),
       priorHashes,
       sendAll,
+      itemUuids,
+      // Both grains are dropped together by --force: one flag, one meaning,
+      // no partial-force mode.
+      ...(force ? {} : { baseVersions: readBaseVersions(siteDir), itemBaseVersions: readItemBaseVersions(siteDir) }),
     })
   } catch (err) {
     error(`Could not build the sync package: ${err.message}`)