uniweb 0.13.5 → 0.13.7

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.
@@ -44,9 +55,18 @@
 import { writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { emitSyncPackages } from '@uniweb/build/uwx'
+import { uploadSiteMedia, isStorageRefusal } from '../backend/site-media.js'
 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 +97,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 +124,86 @@ 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.)
+  // Local media rides the SAME asset lane `publish` uses, and it rides it FIRST.
+  //
+  // Push is the collaboration verb: a teammate opens the site in the visual app
+  // right after it. Content that still points at `/images/hero.png` — bytes the
+  // backend never received — shows them a broken image, which is precisely what
+  // push exists to avoid. `publish` uploaded and rewrote; push dropped
+  // `localAssets` on the floor.
+  //
+  // Ordering is deliberate: BEFORE `ensureItemUuids`, which mints uuids on the
+  // backend. A refusal here then leaves nothing minted and nothing submitted.
+  //
+  // The probe emit runs WITHOUT `priorHashes`, so it surfaces every local ref
+  // rather than only the changed ones. That is not waste — the lane is
+  // content-addressed with a `present` skip-list, so unchanged bytes are a no-op
+  // PUT. It is also what makes the storage rule fall out of the mechanism instead
+  // of needing a special case: a content-only push presents the same plan as last
+  // time, every file is already present, zero new bytes are requested, and no
+  // quota check can refuse it. Only a push that genuinely ADDS bytes can be
+  // blocked.
+  //
+  // It also has to be this emit that carries `assetRewrite` below: the push cache
+  // stores hashes of the REWRITTEN content, so the emit compared against it must
+  // rewrite too, or every entity reads as changed forever.
+  let assetRewrite = null
+  if (!output && !dryRun) {
+    let mediaRefs = []
+    try {
+      const probe = await emitSyncPackages(siteDir, {
+        ...(foundationDir ? { foundationDir } : {}),
+        resolveModel: makeModelResolver({ client, offline: false }),
+      })
+      mediaRefs = probe.localAssets || []
+    } catch (err) {
+      error(`Could not scan the site for local media: ${err.message}`)
+      return { exitCode: 2 }
+    }
+    if (mediaRefs.length) {
+      info('Uploading media…')
+      try {
+        const { map, failed } = await uploadSiteMedia(client, siteDir, mediaRefs, {
+          onProgress: (m) => note(`  ${m}`),
+          warn: (m) => note(`! ${m}`),
+        })
+        // Bytes that did not land must not be pushed around: the content would go
+        // up still naming the local path, so the teammate sees the broken image
+        // this whole change exists to prevent, and the only trace is a warning. A
+        // missing FILE is a different thing — already broken before us, warned by
+        // the uploader, and not worth blocking a push over.
+        if (failed.length) {
+          error(`${failed.length} asset(s) failed to upload — nothing was pushed.`)
+          for (const f of failed) note(`  ${f.path} (HTTP ${f.status})`)
+          return { exitCode: 1 }
+        }
+        if (Object.keys(map).length) assetRewrite = map
+        note(`${Object.keys(map).length}/${mediaRefs.length} media ref(s) → serve URL`)
+      } catch (err) {
+        if (isStorageRefusal(err)) {
+          error('Storage quota reached — this push adds media that does not fit.')
+          note('  A push that changes only content costs no storage and still works.')
+          note('  Remove or shrink the new assets, or raise the plan limit, then re-run.')
+          note(`  ${err.message}`)
+          return { exitCode: 1 }
+        }
+        error(`Media upload failed: ${err.message}`)
+        return { exitCode: 1 }
+      }
+    }
+  }
+
+  const itemUuids = (output || dryRun)
+    ? readItemUuids(siteDir)
+    : await ensureItemUuids({ client, siteDir, note })
   let pkg
   try {
     pkg = await emitSyncPackages(siteDir, {
@@ -105,6 +211,11 @@ 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) }),
+      ...(assetRewrite ? { assetRewrite } : {}),
     })
   } catch (err) {
     error(`Could not build the sync package: ${err.message}`)

package/src/commands/refresh.js

@@ -0,0 +1,176 @@
+/**
+ * uniweb refresh — catch up with everything outside your working copy.
+ *
+ * A developer on a synced site has TWO independent external sources, and nothing
+ * in the tool used to connect them:
+ *
+ *   - the git remote — teammates' commits;
+ *   - the backend    — content authors' edits, made in the app.
+ *
+ * Someone who runs only `git pull` silently misses every app edit; someone who
+ * runs only `uniweb pull` misses their teammates. The person most likely to be
+ * caught out is exactly the one starting their day believing they are current.
+ * This is the one command for that: run it in the morning, or before a milestone.
+ *
+ * READ-ONLY, and that is the load-bearing decision. It never pushes. Because it
+ * cannot ship anything, it can be run reflexively without weighing consequences —
+ * which is the whole point of a start-of-day command. A version that also pushed
+ * would be one you had to think about first, and so one people would stop running.
+ *
+ * Order is deliberate: git first, then the backend. The three-way merge's common
+ * ancestor is the COMMITTED version of each file, so taking teammates' commits
+ * first makes that ancestor fresher and the merge more accurate. And if git itself
+ * conflicts, refresh stops there — one source of conflict at a time.
+ *
+ * Exits NON-ZERO when a merge left conflicts, the way a conflicted `git merge`
+ * does. That is what makes `uniweb refresh && uniweb push` correct by
+ * construction: without it, the obvious one-liner ships conflict markers into live
+ * content. If a `sync` verb is ever wanted, it is that chain.
+ *
+ * Usage:
+ *   uniweb refresh                 git pull, then merge the backend's content
+ *   uniweb refresh --no-git        skip the git remote; backend only
+ *   uniweb refresh --no-backend    skip the backend; git only
+ *   uniweb refresh --backend <url> Override the backend origin
+ */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+
+import { resolveSiteDir } from './deploy.js'
+import { isGitRepo, hasRemote, pullRemote, headProvenance } from '../utils/git.js'
+import { probeUnpushed } from '../backend/site-sync.js'
+
+const c = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  cyan: '\x1b[36m', green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m',
+}
+const say = {
+  ok: (m) => console.log(`${c.green}✓${c.reset} ${m}`),
+  info: (m) => console.log(`${c.cyan}→${c.reset} ${m}`),
+  warn: (m) => console.log(`${c.yellow}⚠${c.reset} ${m}`),
+  err: (m) => console.error(`${c.red}✗${c.reset} ${m}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`),
+}
+
+// Forward a flag AND its value to the delegated verb. `--backend http://x` is two
+// argv entries, so a naive filter passes the flag and drops the URL — leaving the
+// delegated pull pointed at the default backend while the user believes they
+// overrode it. `--backend=http://x` is one entry and passes through as-is.
+function collectPassthrough(args, names) {
+  const out = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    const name = names.find((n) => a === n || a.startsWith(`${n}=`))
+    if (!name) continue
+    out.push(a)
+    if (a === name && args[i + 1] && !args[i + 1].startsWith('-')) out.push(args[++i])
+  }
+  return out
+}
+
+// A site is backend-synced once it has an identity to pull by.
+function siteContentUuid(siteDir) {
+  try {
+    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
+    return typeof y?.$uuid === 'string' ? y.$uuid : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @param {string[]} args
+ * @param {object} [deps] - injectable seams for testing, mirroring pull.js:
+ *   `resolveSiteDir`, and `pull` (so the backend step can be driven without a
+ *   network or a real backend).
+ */
+export async function refresh(args = [], deps = {}) {
+  const skipGit = args.includes('--no-git')
+  const skipBackend = args.includes('--no-backend')
+  const resolveSite = deps.resolveSiteDir || resolveSiteDir
+  const siteDir = await resolveSite(args, 'refresh')
+
+  // Which sources this run actually consulted. Reported at the end, because
+  // "up to date" is a different claim from "up to date with the two things I
+  // happened to be able to check" — and the second is all we can ever honestly
+  // say. Silently skipping a source is how someone concludes they are current
+  // when they are not.
+  const consulted = []
+  const skipped = []
+  let conflicts = 0
+
+  // ── 1. the git remote ─────────────────────────────────────────────────────
+  if (skipGit) {
+    skipped.push('git (--no-git)')
+  } else if (!isGitRepo(siteDir)) {
+    skipped.push('git (not a repository)')
+  } else if (!hasRemote(siteDir)) {
+    skipped.push('git (no remote configured)')
+  } else {
+    say.info('Pulling from the git remote…')
+    const r = pullRemote(siteDir)
+    if (!r.ok) {
+      say.err('git pull failed — resolve this before continuing.')
+      for (const line of r.message.split('\n').slice(0, 6)) say.dim(line)
+      // Deliberately stop. Layering the backend's content on top of an unresolved
+      // git state gives the user two independent conflicts at once, and no clear
+      // order to address them in.
+      return { exitCode: 1 }
+    }
+    say.dim(r.changed ? 'Took new commits from the remote.' : 'Already up to date with the remote.')
+    consulted.push('git')
+  }
+
+  // ── 2. the backend ────────────────────────────────────────────────────────
+  if (skipBackend) {
+    skipped.push('backend (--no-backend)')
+  } else if (!siteContentUuid(siteDir)) {
+    skipped.push('backend (this site has never been synced)')
+  } else {
+    say.info("Merging the backend's content…")
+    const pull = deps.pull || (await import('./pull.js')).pull
+    // `--merge` rather than a plain pull: an author editing a different part of the
+    // same section is not a conflict, and should not be presented as one.
+    const passthrough = collectPassthrough(args, ['--backend', '--registry', '--token'])
+    const res = await pull(['--merge', ...passthrough])
+    conflicts = res?.merge?.conflicted?.length ?? 0
+    if (res?.exitCode && !conflicts) {
+      // Failed for a reason other than conflicts — say so plainly rather than
+      // reporting a clean refresh over a lane that never ran.
+      say.err('Could not merge the backend content.')
+      return { exitCode: res.exitCode }
+    }
+    consulted.push('backend')
+  }
+
+  // ── 3. where that leaves you ──────────────────────────────────────────────
+  console.log('')
+  if (consulted.length) say.dim(`Checked: ${consulted.join(', ')}`)
+  for (const s of skipped) say.dim(`Skipped: ${s}`)
+
+  const git = headProvenance(siteDir)
+  if (git) say.dim(`Commit : ${git.sha.slice(0, 8)}${git.dirty ? ' (working tree has changes)' : ''}`)
+
+  // What is still yours to send. The point of a milestone check is knowing both
+  // directions, not just that you took what was waiting.
+  if (!skipBackend && siteContentUuid(siteDir)) {
+    try {
+      const probe = await probeUnpushed(siteDir)
+      if (probe.changed) say.dim(`Unpushed: ${probe.changed} entit${probe.changed === 1 ? 'y' : 'ies'} changed locally`)
+    } catch {
+      /* the probe is a courtesy; never fail a refresh over it */
+    }
+  }
+
+  console.log('')
+  if (conflicts) {
+    say.err(`${conflicts} file(s) need you to resolve conflicts before pushing.`)
+    return { exitCode: 1 }
+  }
+  say.ok('Up to date.')
+  return { exitCode: 0 }
+}
+
+export default refresh

package/src/commands/sync.js

@@ -0,0 +1,75 @@
+/**
+ * uniweb sync — catch up, then share. `refresh` followed by `push`.
+ *
+ * The two halves already exist and already carry the safety:
+ *
+ *   - `refresh` takes teammates' commits and merges the backend's content, and
+ *     exits NON-ZERO when a merge left conflicts;
+ *   - `push` refuses when the backend has moved under you, and never overwrites
+ *     an author's work blind.
+ *
+ * So this verb adds no guarantees of its own — it composes two commands that
+ * already hold them. That is deliberate: a safety check you can only get by
+ * remembering to type `sync` is not a safety check, which is why the gate lives in
+ * `push` and the conflict stop lives in `refresh`. Anyone typing
+ * `uniweb refresh && uniweb push` gets the identical behaviour, and the exit codes
+ * are what make that chain correct rather than anything here.
+ *
+ * A THIN COMPOSITION, not a reimplementation. Both halves are called, never
+ * re-created. The `deploy`/`publish` split is the cautionary tale: two paths that
+ * did nearly the same thing drifted until one of them was quietly wrong.
+ *
+ * WHY IT STOPS ON CONFLICTS. Pushing after an unresolved merge would put conflict
+ * markers into content authors see. `refresh` reports them and exits non-zero; this
+ * stops there and says what is left to do.
+ *
+ * WHAT IT DOES NOT DO: publish. Sync brings the local copy and the backend DRAFT
+ * into agreement; going live stays a separate, deliberate act (`uniweb publish`).
+ * That separation is what keeps an unintended sync recoverable — the worst case is
+ * work-in-progress visible to authors in the app, not shipped to visitors.
+ *
+ * Reach for `refresh` when you only want to catch up — it cannot ship anything, so
+ * it is the one to run reflexively. Reach for `sync` when you also mean to share.
+ *
+ * Usage:
+ *   uniweb sync                    refresh, then push
+ *   uniweb sync --no-git           skip the git remote half of the refresh
+ *   uniweb sync --force            forwarded to push (overwrite upstream changes)
+ *   uniweb sync --backend <url>    override the backend origin
+ */
+
+const c = { reset: '\x1b[0m', dim: '\x1b[2m', cyan: '\x1b[36m', red: '\x1b[31m' }
+const say = {
+  info: (m) => console.log(`${c.cyan}→${c.reset} ${m}`),
+  err: (m) => console.error(`${c.red}✗${c.reset} ${m}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`),
+}
+
+/**
+ * @param {string[]} args
+ * @param {object} [deps] - injectable seams for testing: `refresh`, `push`.
+ */
+export async function sync(args = [], deps = {}) {
+  const refresh = deps.refresh || (await import('./refresh.js')).refresh
+  const push = deps.push || (await import('./push.js')).push
+
+  // `--force` means "overwrite upstream" and belongs to the push half only. Passing
+  // it to the refresh would ask pull to DISCARD the local work this command exists
+  // to send — the same word meaning opposite things on the two halves.
+  const refreshArgs = args.filter((a) => a !== '--force')
+
+  const r = await refresh(refreshArgs)
+  if (r?.exitCode) {
+    // refresh already explained itself — conflicts, or a git failure. Adding a
+    // second summary here would just bury it.
+    say.dim('Not pushing while that is unresolved.')
+    return { exitCode: r.exitCode }
+  }
+
+  console.log('')
+  say.info('Pushing your changes…')
+  const p = await push(args)
+  return { exitCode: p?.exitCode ?? 0 }
+}
+
+export default sync

package/src/framework-index.json

@@ -1,31 +1,32 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-25T20:40:37.933Z",
+  "generatedAt": "2026-07-27T11:29:06.768Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.15.5",
+      "version": "0.15.7",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
         "@uniweb/content-writer",
         "@uniweb/core",
+        "@uniweb/projections",
         "@uniweb/runtime",
         "@uniweb/schemas",
         "@uniweb/theming"
       ]
     },
     "@uniweb/content-reader": {
-      "version": "1.1.15",
+      "version": "1.1.17",
       "path": "framework/content-reader",
       "deps": []
     },
     "@uniweb/content-writer": {
-      "version": "0.2.7",
+      "version": "0.2.9",
       "path": "framework/content-writer",
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.7.29",
+      "version": "0.7.31",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -43,7 +44,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.9.37",
+      "version": "0.9.39",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -60,8 +61,16 @@
       "path": "framework/press",
       "deps": []
     },
+    "@uniweb/projections": {
+      "version": "0.1.2",
+      "path": "framework/projections",
+      "deps": [
+        "@uniweb/content-writer",
+        "@uniweb/core"
+      ]
+    },
     "@uniweb/runtime": {
-      "version": "0.8.36",
+      "version": "0.8.38",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -84,7 +93,7 @@
       "deps": []
     },
     "@uniweb/semantic-parser": {
-      "version": "1.1.18",
+      "version": "1.1.20",
       "path": "framework/semantic-parser",
       "deps": []
     },
@@ -99,7 +108,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.5.4",
+      "version": "0.5.6",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -622,6 +622,20 @@ async function main() {
     process.exit(result?.exitCode ?? 0)
   }
 
+  // Handle sync command (refresh + push; both halves imported, never reimplemented)
+  if (command === 'sync') {
+    const { sync } = await importProjectCommand('./commands/sync.js')
+    const result = await sync(args.slice(1))
+    process.exit(result?.exitCode ?? 0)
+  }
+
+  // Handle refresh command (dynamic import — depends on @uniweb/build via pull)
+  if (command === 'refresh') {
+    const { refresh } = await importProjectCommand('./commands/refresh.js')
+    const result = await refresh(args.slice(1))
+    process.exit(result?.exitCode ?? 0)
+  }
+
   // Handle status command (dynamic import — offline emit via @uniweb/build)
   if (command === 'status') {
     const { status } = await importProjectCommand('./commands/status.js')
@@ -1490,6 +1504,8 @@ ${colors.bright}Commands:${colors.reset}
   runtime register   Register an @uniweb/runtime version to the backend (@std only)
   push               Push a site's content to the backend
   pull               Pull a site's content from the backend
+  refresh            Catch up with the git remote AND the backend (never pushes)
+  sync               Catch up, then push (refresh + push)
   status             Show a site's sync state (unpushed content, foundation)
   inspect <path>     Inspect parsed content shape of a markdown file or folder
   docs               Generate component documentation