uniweb 0.68.0 → 0.69.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/core": "^0.29.8",
     "@uniweb/runtime": "^0.27.4",
+    "@uniweb/core": "^0.29.8",
     "@uniweb/kit": "^0.19.4",
+    "@uniweb/semantic-parser": "^1.4.1",
     "@uniweb/schemas": "^0.7.0",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/content-writer": "^0.3.4"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.62.0",
+    "@uniweb/build": "^0.63.0",
     "@uniweb/content-reader": "^1.2.5",
     "@uniweb/semantic-parser": "^1.4.1"
   },

package/partials/agents.md

@@ -896,7 +896,7 @@ The body — the value of the schema's content field, `article_body.content`.
 
 **A component receives it differently from how the file writes it**, the same way on a static site and a hosted one: the brief's fields at the top (`article.title`), every other section under its name (`article.article_body.content`, `article.article_body.author`), and `$name`, the handle. Lists carry the brief alone unless the query says otherwise (`deferred:`, below). Full rules: `reference/entity-content.md`.
 
-**A reference names the record it points at.** A `{ ref: '@/speaker' }` field is written as that record's name — `speaker: ada` for `records/speaker/ada.yml` (its file's name, or its `slug:`) — and a `many` one as a list of names. A component receives `{ entity, brief }`: the record reduced to its brief, so `talk.speaker.brief.name`. `uniweb validate` and a push report a name that matches no record; a push sends each reference to the record it names (a second pass when that record is new too), and a pull writes the name back.
+**A reference names the record it points at.** A `{ ref: '@/speaker' }` field is written as that record's name — `speaker: ada` for `records/speaker/ada.yml` (its file's name, or its `slug:`) — and a `many` one as a list of names. A component receives `{ entity, brief }`: the record reduced to its brief, so `talk.speaker.brief.name`. `uniweb validate` and a push report a name that matches no record; a push sends each reference to the record it names (in the same push when that record is new too), and a pull writes the name back.
 
 **`records/folder.yml` — optional, and only for folders.** It is the one file in `records/` that is not a record, it moves with the directory (`paths.records`), and like a pages folder's `folder.yml` it describes the folder it sits in. Every record sits at the top of the site's records folder unless `folder.yml` places it in a sub-folder. Add one only when a query needs to ask for a *slice* of the records rather than all of them — most sites never do:
 

package/src/backend/site-sync.js

@@ -1186,12 +1186,9 @@ export async function probeUnpushed(siteDir, { backend = null, sendAll = false }
   // ⚠️ Until 2026-09-23 this said the site's recorded ORG resolves it and must be
   // passed in — true before 2026-09-22, and read as a reason to pass it.
   const pkg = await comparisonEmit(siteDir, { backend, priorHashes, sendAll })
-  // A record held back for a reference (`pushInPasses`) is not in either lane, and is
-  // still unpushed.
   const changed =
     (pkg.siteContent?.entityCount || 0) +
-    (pkg.records?.entityCount || 0) +
-    (pkg.waiting || []).filter((w) => w.held).length
+    (pkg.records?.entityCount || 0)
   return { changed, unchanged: pkg.skipped || 0, warnings: pkg.warnings || [] }
 }
 
@@ -1270,6 +1267,28 @@ export async function rebankSyncHashes(siteDir, backend = null) {
   return Object.keys(pkg.hashes || {}).length
 }
 
+/**
+ * Re-bank the hashes of the records a push sent naming a record it created — `keys`,
+ * the emit's `namesNew` — as the next push will hash them.
+ *
+ * ⭐ Such a record names its new record by `$ref`, and the backend stores the uuid it
+ * mints. The next push names it by that uuid: the same reference, and another hash — so
+ * the hash the push banked describes a document no later emit builds, and the next push
+ * would send every one of these records again. Re-sending is not harmless: a record's
+ * list-section items go without the identity a re-send needs (`identity_required`).
+ *
+ * ⚖️ Only these keys, over the hashes the push just banked: the site-content lane and
+ * the folder are banked as that push sent them, and a caller's own emit options (a
+ * publish that does not declare services) are not the comparison emit's.
+ */
+export async function rebankRecordHashes(siteDir, backend, keys) {
+  if (!keys?.length) return
+  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true })
+  const hashes = { ...readSyncCache(siteDir, backend) }
+  for (const key of keys) if (pkg.hashes?.[key]) hashes[key] = pkg.hashes[key]
+  writeSyncCache(siteDir, backend, hashes, readAppliedInjections(siteDir, backend))
+}
+
 /**
  * What a push did with the site's `template:` intent — read from the backend's own
  * reply, never inferred from what we sent.
@@ -1774,6 +1793,15 @@ export async function pushSyncPackages({
   // Entities absent from finalized[] (skipped, or not editable) keep their cached
   // value — absence is not invalidation.
   writeSyncCache(siteDir, client.origin, hashes, applied)
+  // A record that named a record this push created is banked as the next push will send
+  // it — by that record's uuid, which the back-fill above just recorded.
+  if (records && pkg.namesNew?.length) {
+    try {
+      await rebankRecordHashes(siteDir, client.origin, pkg.namesNew)
+    } catch (err) {
+      note(`! Could not re-bank ${pkg.namesNew.length} record(s) that name a new record: ${err.message}. The next push sends them again.`)
+    }
+  }
   mergeHarvested()
   // Re-base the page attribution: our emitted document and the backend's post-write
   // copy of it are the two sides' new agreed state. Only when the site-content lane
@@ -1850,78 +1878,3 @@ export async function pushSyncPackages({
   }
   return { exitCode: 0, boundSiteUuid, finalizedTotal, wrote }
 }
-
-/**
- * Push, then push again while records WAIT for a reference's record — the verbs' way to
- * send a package (`push`, `publish`).
- *
- * ⭐ A reference is sent as the uuid the backend minted for the record it names, so a
- * record that points at one created by the same push cannot be completed in that push
- * (`@uniweb/build`'s `emitSyncPackages` → `waiting`). The first pass creates what it can —
- * records whose waiting references are not required go without them — and each further
- * pass, emitted afresh from the state the last one banked, sends what has become
- * nameable. A chain of required references takes one pass per link; two records that
- * each require the other can never be completed, and the push stops, naming them.
- *
- * @param {object} params
- * @param {object} params.pkg - the first pass's package (`emitSyncPackages`)
- * @param {() => Promise<object>} params.reemit - the next pass's package, emitted afresh
- * @param {Function} [params.push] - sends one package; `pushSyncPackages` (a test's seam)
- * @returns {Promise<{ exitCode: number, boundSiteUuid?: string, finalizedTotal: number, wrote: string[], passes: number }>}
- */
-export async function pushInPasses({ client, siteDir, pkg, report, reemit, maxPasses = 12, push = pushSyncPackages }) {
-  const { note, error } = report
-  let current = pkg
-  let passes = 1
-  let result = await push({ client, siteDir, pkg: current, report })
-  let finalizedTotal = result.finalizedTotal || 0
-  const wrote = [...(result.wrote || [])]
-  while (result.exitCode === 0 && current.waiting?.length) {
-    const n = current.waiting.length
-    note(
-      `${n} record${n === 1 ? '' : 's'} name${n === 1 ? 's' : ''} a record this push created — ` +
-        `pushing again to complete ${n === 1 ? 'its references' : 'their references'}.`
-    )
-    let next
-    try {
-      next = await reemit()
-    } catch (err) {
-      error(`Could not build the next pass: ${err.message}`)
-      return { ...result, exitCode: 1, finalizedTotal, wrote, passes }
-    }
-    if (refuseUnsendableRecords(next.refusals, report)) {
-      return { ...result, exitCode: 1, finalizedTotal, wrote, passes }
-    }
-    // Nothing became nameable: every record still waiting waits on one that waits too.
-    if (waitingKey(next.waiting) === waitingKey(current.waiting) || passes >= maxPasses) {
-      error(
-        'These records could not be completed — each requires a reference to a record that ' +
-          'is itself waiting to be created:'
-      )
-      for (const w of next.waiting || []) {
-        const refs = w.pending.map((p) => `${p.path} → "${p.name}"`).join(', ')
-        note(`  ${w.id} (${w.model}): ${refs}`)
-      }
-      note(
-        'Push one of them without that reference first — or make it optional in the schema — ' +
-          'then add it back and push again.'
-      )
-      return { ...result, exitCode: 1, finalizedTotal, wrote, passes }
-    }
-    current = next
-    passes++
-    result = await push({ client, siteDir, pkg: current, report })
-    finalizedTotal += result.finalizedTotal || 0
-    for (const w of result.wrote || []) if (!wrote.includes(w)) wrote.push(w)
-  }
-  return { ...result, finalizedTotal, wrote, passes }
-}
-
-// Which records wait, and on what — two passes that leave it the same made no progress.
-function waitingKey(waiting) {
-  return JSON.stringify(
-    (waiting || [])
-      .map((w) => [w.model, w.id, w.pending.map((p) => `${p.path}:${p.name}`).sort()])
-      .sort()
-  )
-}

package/src/commands/publish.js

@@ -90,8 +90,7 @@ import {
   refuseUnsendableRecords,
   clearRemoteSyncStateIfUnbound,
   dropSiteBoundValues,
-  readItemUuids,
-  pushInPasses
+  pushSyncPackages
 } from '../backend/site-sync.js'
 import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
@@ -943,14 +942,13 @@ export async function publish(args = []) {
     say.dim('Services unchanged.')
   }
 
-  // The emit's options, read afresh for each pass (`pushInPasses`): a pass banks
-  // hashes, identity and base versions that the next one must build on.
-  //
   // publish rides the same gated push as `uniweb push`: if an app author has
   // edited since this clone last synced, the push is refused rather than
   // overwriting them, and nothing goes live. `--force` drops the precondition.
   const forced = args.includes('--force')
-  const emitOptions = ({ priorHashes, itemUuids }) => ({
+  let pkg
+  try {
+    pkg = await emitSyncPackages(siteDir, {
       backend: client.origin,
       ...(declaration.declare ? {} : { declareServices: false }),
       // Placement identity for the folder — see writeFolderItemUuids.
@@ -969,10 +967,7 @@ export async function publish(args = []) {
       ...(Object.keys(ext.pins).length ? { injectExtensions: ext.pins } : {}),
       ...(assetRewrite ? { assetRewrite } : {}),
       ...(assetIds ? { assetIds } : {})
-  })
-  let pkg
-  try {
-    pkg = await emitSyncPackages(siteDir, emitOptions({ priorHashes, itemUuids }))
+    })
   } catch (err) {
     say.err(`Could not build the sync package: ${err.message}`)
     return { exitCode: 1 }
@@ -987,19 +982,11 @@ export async function publish(args = []) {
     error: (m) => say.err(m),
     dim: (s) => `${c.dim}${s}${c.reset}`
   }
-  const pushResult = await pushInPasses({
+  const pushResult = await pushSyncPackages({
     client,
     siteDir,
     pkg,
-    report,
-    reemit: () =>
-      emitSyncPackages(
-        siteDir,
-        emitOptions({
-          priorHashes: readSyncCache(siteDir, client.origin),
-          itemUuids: readItemUuids(siteDir, client.origin)
-        })
-      )
+    report
   })
   if (pushResult.exitCode !== 0) return { exitCode: pushResult.exitCode }
   const siteUuid = pushResult.boundSiteUuid

package/src/commands/push.js

@@ -87,7 +87,7 @@ import {
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
   dropSiteBoundValues,
-  pushInPasses
+  pushSyncPackages
 } from '../backend/site-sync.js'
 import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
 
@@ -496,9 +496,9 @@ export async function push(args = [], deps = {}) {
     output || dryRun
       ? readItemUuids(siteDir, client.origin)
       : await ensureItemUuids({ client, siteDir, note })
-  // The emit's options, read afresh for each pass (`pushInPasses`): a pass banks
-  // hashes, identity and base versions that the next one must build on.
-  const emitOptions = ({ priorHashes, sendAll, itemUuids }) => ({
+  let pkg
+  try {
+    pkg = await emitSyncPackages(siteDir, {
       backend: client.origin,
       // Placement identity for the folder — see writeFolderItemUuids.
       folderItemUuids: readFolderItemUuids(siteDir, client.origin),
@@ -529,10 +529,7 @@ export async function push(args = [], deps = {}) {
           }),
       ...(assetRewrite ? { assetRewrite } : {}),
       ...(assetIds ? { assetIds } : {})
-  })
-  let pkg
-  try {
-    pkg = await emitSyncPackages(siteDir, emitOptions({ priorHashes, sendAll, itemUuids }))
+    })
   } catch (err) {
     error(`Could not build the sync package: ${err.message}`)
     return { exitCode: 2 }
@@ -598,9 +595,8 @@ export async function push(args = [], deps = {}) {
   }
 
   // Submit both lanes, back-fill the minted uuids, and persist the send-only-changed
-  // cache — again for any record whose reference names a record this push created.
-  // Shared with `uniweb publish` via ../backend/site-sync.js.
-  const result = await pushInPasses({
+  // cache. Shared with `uniweb publish` via ../backend/site-sync.js.
+  const result = await pushSyncPackages({
     client,
     siteDir,
     pkg,
@@ -609,16 +605,7 @@ export async function push(args = [], deps = {}) {
       note,
       error,
       dim: (s) => `${colors.dim}${s}${colors.reset}`
-    },
-    reemit: () =>
-      emitSyncPackages(
-        siteDir,
-        emitOptions({
-          priorHashes: readSyncCache(siteDir, client.origin),
-          sendAll: false,
-          itemUuids: readItemUuids(siteDir, client.origin)
-        })
-      )
+    }
   })
   if (result.exitCode !== 0) return { exitCode: result.exitCode }
   success(

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-24T21:52:18.260Z",
+  "generatedAt": "2026-09-25T11:51:15.075Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.6.2",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.62.0",
+      "version": "0.63.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -126,7 +126,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.10.5",
+      "version": "0.10.6",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",