@uniweb/build 0.29.0 → 0.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.29.0",
+  "version": "0.29.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -60,10 +60,10 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/semantic-parser": "^1.3.1",
-    "@uniweb/projections": "^0.5.1",
-    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/schemas": "^0.2.11",
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/projections": "^0.5.1",
+    "@uniweb/semantic-parser": "^1.3.1",
     "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {

package/src/site/fetch-shapes.js

@@ -0,0 +1,70 @@
+// What shape a `fetch:` declaration is, and what a PROJECTION may write back.
+//
+// ⛔ WHY THIS EXISTS. A `fetch:` declaration has three shapes, and the keys each one
+// accepts differ (`data-fetcher.js` RECOGNIZED_FETCH_KEYS):
+//
+//   refine      refine · inherit · detail · limit · sort · where · filter
+//   collection  collection · schema · … — and NOT `path`/`url`
+//   source      path · url · schema · …
+//
+// The build RESOLVES a `collection:` shorthand into a concrete location, so the
+// declaration that rides the sync wire carries BOTH the authored `collection` and
+// the derived `path`. Projecting that back verbatim writes a file that is neither
+// shape cleanly: `collection` wins the classification, and the `path` beside it is
+// then an unrecognized key on its own declaration.
+//
+// ⚠️ Measured on matinee 2026-08-29 — `push → pull → push`, where the third step is
+// rejected by our OWN validator against a file our OWN projector had just written:
+//
+//   fetch:
+//     path: /data/members.json     ← derived; also a build artifact path
+//     schema: members
+//     collection: members          ← what the author actually wrote
+//
+//   [uniweb] fetch: unrecognized key "path" was ignored. Keys recognized on this
+//   declaration: collection, detailPage, filter, limit, merge, prerender, schema,
+//   sort, transform, where.
+//
+// ⭐ The round trip has to invert the resolution, not copy it. `/data/<name>.json`
+// is a materialization of a collection, never its definition — so it is precisely
+// the thing an authored file should not contain.
+//
+// ⚖️ DROPS ONLY WHAT IS DERIVABLE, not everything unrecognized. A key we do not know
+// might be one a newer producer authored, and silently discarding it on every pull
+// would make the round trip lossy in a way nothing reports. `path` and `url` beside
+// a `collection` are recoverable from the collection itself; anything else survives
+// and the validator's warning stays the honest signal.
+
+/** Which of the three shapes a declaration is — the same order `data-fetcher` uses. */
+export function fetchShapeOf(fetch) {
+  if (!fetch || typeof fetch !== 'object') return null
+  if (fetch.refine === true || fetch.inherit === true) return 'refine'
+  if (fetch.collection) return 'collection'
+  return 'source'
+}
+
+/** Keys a shape derives rather than the author writing them. */
+const DERIVED_BY_SHAPE = {
+  collection: ['path', 'url'],
+  refine: [],
+  source: []
+}
+
+/**
+ * The declaration as an author would have written it — the wire's resolved form
+ * minus what the build derived.
+ *
+ * @param {object} fetch a `fetch:` declaration off the sync wire
+ * @returns {object} the same declaration, safe to write into authored config
+ */
+export function authorableFetch(fetch) {
+  const shape = fetchShapeOf(fetch)
+  const derived = DERIVED_BY_SHAPE[shape]
+  if (!derived || derived.length === 0) return fetch
+  const out = {}
+  for (const [k, v] of Object.entries(fetch)) {
+    if (derived.includes(k)) continue
+    out[k] = v
+  }
+  return out
+}

package/src/uwx/index.js

@@ -90,6 +90,7 @@ export {
   collectSiteUnits,
   walkSiteUnits,
   collectUnitUuids,
+  collectCollectionUuids,
   stampUnitUuids,
 } from './site-diff.js'
 export {

package/src/uwx/site-diff.js

@@ -292,3 +292,26 @@ export function describeSiteDiff(diff, { limit = 8 } = {}) {
   }
   return lines
 }
+
+
+/**
+ * Collection-declaration identity from a document the BACKEND produced (a pull, or a
+ * push response's `finalized[].document`): `{ <collection name>: <$uuid> }`.
+ *
+ * ⛔ The sibling of collectFolderItemUuids, and it exists for the same reason: these
+ * items have no file of their own, so nothing in a path-keyed map can hold their
+ * identity, and a push that omits it re-sends the whole section uuid-less. The
+ * backend refuses that rather than deleting every stored row — see collectionsNested.
+ *
+ * Keyed by `name`, which the backend enforces unique within the section. `$id` is
+ * deliberately not consulted: it is a payload-local handle the backend never stores.
+ */
+export function collectCollectionUuids(doc) {
+  const out = {}
+  for (const item of doc?.collections || []) {
+    const name = item?.name
+    const uuid = item?.$uuid
+    if (typeof name === 'string' && typeof uuid === 'string' && name && uuid) out[name] = uuid
+  }
+  return out
+}

package/src/uwx/site-project.js

@@ -39,6 +39,7 @@ import { createHash } from 'node:crypto'
 import yaml from 'js-yaml'
 import { writeSiteConfig, writeThemeFile, writeIfChanged, writeSectionFile, writeMergedYaml } from './project-writer.js'
 import { declarationsToCollectionsYml } from './collections-project.js'
+import { authorableFetch } from '../site/fetch-shapes.js'
 import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, unwrapLocalizedContent } from './locale-sync.js'
 import { buildFreeformPath } from '../i18n/freeform.js'
 import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
@@ -303,7 +304,8 @@ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED
   if (theme_override !== undefined) frontmatter.theme = theme_override
   if (preset !== undefined) frontmatter.preset = preset
   if (input !== undefined) frontmatter.input = input
-  if (fetch !== undefined) frontmatter.fetch = fetch
+  // Invert the build's resolution rather than copy it — see fetch-shapes.js.
+  if (fetch !== undefined) frontmatter.fetch = authorableFetch(fetch)
   if (stable_id !== undefined) frontmatter.id = stable_id
 
   const body = insets ? reinlineInsets(sourceContent, insets) : sourceContent
@@ -424,7 +426,8 @@ function pageRecordToYml(record, sectionsArray, sourceLocale) {
   if (record.rewrite !== undefined) y.rewrite = record.rewrite
   if (record.layout !== undefined) y.layout = record.layout
   if (record.seo !== undefined) y.seo = record.seo
-  if (record.fetch !== undefined) y.fetch = record.fetch
+  // Invert the build's resolution rather than copy it — see fetch-shapes.js.
+  if (record.fetch !== undefined) y.fetch = authorableFetch(record.fetch)
   // `sections:` exists to preserve ORDER and NESTING, which the projected filenames
   // can't carry (they're `<stableId>.md`, with no numeric prefix). It must not also
   // decide MEMBERSHIP — and a bare list does: the collector reads a list without

package/src/uwx/site.js

@@ -639,7 +639,39 @@ export function isSiteRelativeExtensionUrl(decl) {
 // The collection DECLARATIONS carried inside site-content `info`-adjacent metadata.
 // Merges the co-located `collections.yml` (the home for file-based decls) over the
 // legacy `site.yml::collections` (kept for remote `url:` sources + back-compat).
-function collectionsNested(declarations) {
+/**
+ * The site's collection DECLARATIONS as `$`-records.
+ *
+ * ⛔ IDENTITY IS KEYED BY `name`, AND IT HAS TO BE.
+ *
+ * Every other item on this entity gets its `$uuid` from a map keyed by the file it
+ * was projected to — but a collection declaration has no file of its own: they all
+ * come from one `collections/collections.yml`. So a path-keyed map has no shape a
+ * declaration could occupy, nothing is ever recorded for one, and every push re-sent
+ * this whole section uuid-less. The backend refuses that (an all-blank section over
+ * stored items would delete every stored row), which is why `push` worked once and
+ * every push after it was refused. Measured 2026-08-29; collab framework-backend-812b.
+ *
+ * ⭐ `name` is the right key and not merely the available one — the backend enforces
+ * `unique_field(name, scope: section)` on this section, and it is the join key its
+ * `resolve_collection_model` matches and the `/data/{name}.json` serve segment. An
+ * author-facing rename is `label`, so the key does not move under either lane.
+ *
+ * ⛔ NOT `$id`, though it happens to hold the same string. `$id` is a payload-local
+ * handle the backend skips on parse and never stores, correlated by submission index
+ * rather than by value — keying on it would key on something that exists only inside
+ * our own outgoing document.
+ *
+ * ⚠️ Because `name` IS the identity, renaming a collection is by design
+ * indistinguishable from delete-plus-create. Rename one of two and the mix passes;
+ * rename every collection at once and the section goes all-blank and is refused.
+ * That is the semantics, not a defect.
+ *
+ * @param {object} declarations resolved collection declarations, keyed by name
+ * @param {Object<string,string>} [uuids] `name` → backend `$uuid`, from a push
+ *        response or a pull. Absent on a first sync, where minting is correct.
+ */
+function collectionsNested(declarations, uuids = null) {
   const out = []
   for (const [name, d] of Object.entries(declarations)) {
     const data = {}
@@ -655,7 +687,10 @@ function collectionsNested(declarations) {
     setIf(data, 'deferred', d.deferred)
     setIf(data, 'detail_url', d.detailUrl)
     setIf(data, 'queryable', d.queryable)
-    out.push(withIdentity(name, { name, ...data }))
+    const rec = withIdentity(name, { name, ...data })
+    const uuid = uuids?.[name]
+    if (typeof uuid === 'string' && uuid) rec.$uuid = uuid
+    out.push(rec)
   }
   return out
 }
@@ -860,7 +895,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   doc.pages = pages
   doc.layout_sections = layoutSections
   doc.extensions = extensionsNested(siteYml)
-  doc.collections = collectionsNested(colConfig.declarations)
+  doc.collections = collectionsNested(colConfig.declarations, opts.collectionUuids)
   return doc
 }
 

package/src/uwx/sync-package.js

@@ -285,7 +285,14 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     ...(opts.folderItemUuids ? { itemUuids: opts.folderItemUuids } : {}),
   })
 
-  const siteDoc = includeSite ? await siteProjectToDocument(siteRoot, { sourceLocale }) : null
+  // `collectionUuids` — identity for the `collections` section, keyed by collection
+  // NAME because a declaration has no file of its own (see collectionsNested).
+  const siteDoc = includeSite
+    ? await siteProjectToDocument(siteRoot, {
+        sourceLocale,
+        ...(opts.collectionUuids ? { collectionUuids: opts.collectionUuids } : {})
+      })
+    : null
   // Deploy-derived `info` fields (e.g. `data_bundle`, the static-data ball URL) are
   // stamped here — NOT authored in site.yml, so they ride the wire but never project
   // back on pull (the `info.assets` precedent). They are part of the hashed content,