@uniweb/build 0.37.1 → 0.39.0

package/src/uwx/records.js

@@ -2,7 +2,7 @@
 // referenced BY NAME, on the entity-content SYNC lane.
 //
 // Each record becomes a section-keyed `$`-document (docs/reference/entity-content.md):
-// `$id` (the slug — the producer-local handle), `$model` (the Model by name), and
+// `$id` (the producer-local handle), `$model` (the Model by name), and
 // each SINGLE section keyed by its name — the brief plus any sibling singles, not
 // the brief alone. The backend MINTS `$uuid` on first sync and
 // returns it in the finalized response; the verb back-fills it into the source
@@ -91,8 +91,9 @@ function stripSigils(value) {
     // ⛔ A `@uniweb/folder` REF LEAF ENCODES ONE REFERENCE TWO WAYS, and hashing the
     // encoding rather than the reference made the folder's hash unreproducible.
     //
-    // `refLeaf` (uwx/folder.js) emits `$ref: "<collection>/<slug>"` while the record
-    // is brand-new and `entry: { model, entity: <uuid> }` once it has been minted.
+    // `refLeaf` (uwx/folder.js) emits `$ref: <the record's $id>` — the pool position
+    // `<dirs>/<slug>` — while the record is brand-new, and `entry: { model, entity:
+    // <uuid> }` once it has been minted.
     // Both denote the same record. A push hashes the folder BEFORE submitting, then
     // back-fills the minted `$uuid` into every record's source file — so the very
     // next emit builds the OTHER encoding, and the hash the push just banked can
@@ -103,14 +104,14 @@ function stripSigils(value) {
     //
     // ⭐ Neither encoding is content. What the folder SAYS is "this branch contains
     // this record, here, in this order" — and that is already hashed: a leaf carries
-    // `path_segment` (the record's slug) inside a branch carrying the collection's.
+    // `name` (the record's handle) inside a branch carrying the collection's.
     // A `folders:` branch's entries are COLLECTION names, so every leaf under one
     // comes from a single collection, where a slug is unique. Position plus segment
     // therefore identify the record on their own; `$ref` adds a payload-local handle
     // and `entry` adds identity, and both are exactly what `$uuid` is stripped for.
     //
     // ⚖️ The previous rule kept `$ref` "so a reference change is visible". It still
-    // is: point a leaf at a different record and its `path_segment` moves with it.
+    // is: point a leaf at a different record and its `name` moves with it.
     const isFolderRefLeaf = value.kind === 'ref'
     const out = {}
     for (const [k, v] of Object.entries(value)) {
@@ -181,7 +182,7 @@ function encodeFieldValue(value, field, sourceLocale, translations) {
  * already carries `$uuid` (back-filled from a prior sync) round-trips it.
  *
  * @param {object} params
- * @param {string} params.queryName  - the site.yml collection name
+ * @param {string} params.queryName  - the query's name in site.yml
  * @param {object[]} params.records        - [{ slug, ...fields }]
  * @param {object} params.declaration      - the `@uniweb/data-schema` declaration
  *        (from toDataSchemaDeclaration): `{ name, brief, sections }`
@@ -272,9 +273,22 @@ export function recordsToEntities({
       warnings.push(`${queryName}: a record without a slug was skipped`)
       continue
     }
-    // `$id` is the payload-local handle = the record's path under collections/
-    // (`<collection>/<slug>`), globally unique within one sync so the @uniweb/folder
-    // entity can point a leaf at it via `$ref`. An explicit frontmatter `$id` wins.
+    // ⛔ `$id` IS NOT THE SLUG. It is the payload-local, PATH-QUALIFIED handle, so
+    // the @uniweb/folder entity can point a leaf at it via `$ref`. An explicit
+    // frontmatter `$id` wins.
+    //
+    // ⚠️ The authoritative value is the record's POOL POSITION — `<dirs>/<slug>` —
+    // and it is set upstream, at the pool walk; see the ⭐ comment there, which is
+    // where the reasoning lives. `<query>/<slug>` below is only the fallback for a
+    // record that did not arrive through the pool, and it is explicitly NOT the
+    // shape identity is meant to take: two queries over one Model would mint two
+    // identities for one file.
+    //
+    // The qualification is a CONSTRAINT, not a style: the sync response is keyed per
+    // (`$model`, `$id`), so a bare slug would collide whenever two queries over the
+    // same Model reuse one (see the duplicate check below). ⇒ Do not describe this
+    // value as "the slug" — the folder leaf's `name` is the bare segment, and
+    // conflating the two has already misdirected a naming decision.
     const id = record.$id || `${queryName}/${slug}`
     const uuid = record.$uuid || null
     const hasBody = typeof record.$body === 'string' && record.$body.trim() !== ''
@@ -631,7 +645,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   // statically (the "data ball") instead, so the caller can route them there.
   const schemaless = []
   // The sync response is keyed per ($model, $id), so the pair must be unique
-  // within one submission (two collections on the same Model could otherwise
+  // within one submission (two queries over the same Model could otherwise
   // reuse a slug).
   const seen = new Set()
   for (const { name, decl } of mapped) {

package/src/uwx/registry-package.js

@@ -159,6 +159,11 @@ function buildInfo(self, org, digest, runtime) {
   // be satisfied. Same lift as `digest`: stated by the producer, opaque to the
   // backend, acted on by whoever resolves a whole site.
   if (runtime) info.runtime = runtime
+  // The host services this foundation is BUILT AGAINST, from package.json's
+  // `uniweb.supports`. `Array.isArray` and not truthiness: `[]` is an explicit
+  // "none" and must survive as one, while an ABSENT key means UNKNOWN — the
+  // same three-state rule `runtime` states above, for the same reason.
+  if (Array.isArray(self.supports)) info.supports = self.supports
   return info
 }
 
@@ -166,7 +171,11 @@ function buildInfo(self, org, digest, runtime) {
 // as one opaque object the backend never reads into (custodian).
 function buildSchemaBlob(schema) {
   const { dataSchemas: _ds, ...rest } = schema
-  const { name: _n, version: _v, description: _d, role: _r, ...selfConfig } = rest._self || {}
+  // Every key hoisted into `info` is stripped here, so the wire carries each
+  // fact ONCE. Two copies of one fact is a drift liability, and the copy inside
+  // an opaque blob is the one nobody would think to update.
+  const { name: _n, version: _v, description: _d, role: _r, supports: _s, ...selfConfig } =
+    rest._self || {}
   return { ...rest, _self: selfConfig }
 }
 

package/src/uwx/site-project.js

@@ -513,7 +513,12 @@ function projectPages(pages, pagesDir, sourceLocale, report, prune, ctx) {
 // is already a plain string.
 export function pageDirName(record, sourceLocale) {
   const slug = unwrapLocalized(record.slug, sourceLocale)
-  return record.is_dynamic ? `[${record.param_name || slug}]` : slug
+  if (!record.is_dynamic) return slug
+  // The multi-segment folder rides the wire as slug `...path` with
+  // `param_name: slug` (the handle it delivers by); it comes back as the one
+  // fixed spelling, never as `[slug]`.
+  if (slug === '...path') return '[...path]'
+  return `[${record.param_name || slug}]`
 }
 
 // Pass 1 — write + relocate every page dir, its page.yml/folder.yml, and its

package/src/uwx/site.js

@@ -334,6 +334,12 @@ async function orderedSubfolders(dirPath, inheritedMode, parentConfig) {
 }
 
 const DYNAMIC_RE = /^\[(.+)\]$/
+// The multi-segment route folder, one fixed spelling (`content-collector.js`).
+// On the wire its page `slug` is the marker itself (`...path`) and its
+// `param_name` is `slug`: the record is delivered by its handle, the last
+// segment, exactly as under `[slug]`. ⚠️ What a consumer's projector emits as
+// the page ROUTE for it is that consumer's; framework expects `/…/:path*`.
+const CATCH_ALL_MARKER = '...path'
 
 // ===========================================================================
 // NESTED ($-document) lane — Phase 0 de-flatten (bidirectional-sync §8).
@@ -545,7 +551,7 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
       slug,
       mode,
       isDynamic: !!dyn,
-      paramName: dyn ? dyn[1] : undefined,
+      paramName: dyn ? (dyn[1] === CATCH_ALL_MARKER ? 'slug' : dyn[1]) : undefined,
       isRoot,
       siteIndex,
       sourceLocale,
@@ -684,7 +690,7 @@ export function isSiteRelativeExtensionUrl(decl) {
  * 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.
+ * every push after it was refused. Measured 2026-08-29; collab framework↔backend.
  *
  * ⭐ `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
@@ -724,8 +730,6 @@ export function isSiteRelativeExtensionUrl(decl) {
  * `site.yml collections.<name>.label`; no such field has ever existed, and they have
  * corrected it.
  *
- * ⇒ Full record, including what is established vs merely claimed:
- * `kb/framework/build/collections-decl-open-questions.md`.
  *
  * @param {object} declarations resolved collection declarations, keyed by name
  * @param {Object<string,string>} [uuids] `name` → backend `$uuid`, from a push

package/src/uwx/sync-package.js

@@ -276,6 +276,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   // are complete — new records by `$ref`, already-minted ones by `entry: <uuid>`.
   const folder = buildFolderEntity({
     recordEntities: col.entities,
+    ...(sourceLocale ? { sourceLocale } : {}),
     // ⭐ AUTHORED, from `records.yml`. It used to be derived — one branch per
     // collection — which made the folder a shadow of a directory layout rather
     // than something the author states.

package/src/dev-backend.js

@@ -1,247 +0,0 @@
-#!/usr/bin/env node
-/**
- * Dev backend for testing Uniweb sites with `supports: [where, limit, sort]`.
- *
- * Reads a directory of YAML recordsByQuery (each subfolder is a collection,
- * each .yml file inside is a record) and exposes them via HTTP. Evaluates
- * where-objects on the server side using @uniweb/core's matchWhere — the
- * exact same evaluator the runtime uses as a fallback. This lets you
- * develop a site against a "real" backend without standing up a database.
- *
- * Wire format matches the framework default fetcher's pushdown conventions
- * (see framework/runtime/src/default-fetcher.js):
- *
- *   GET  /api/{collection}                        — all records
- *   GET  /api/{collection}?_where=<JSON>          — filtered by where-object
- *   GET  /api/{collection}?_limit=N               — first N records
- *   GET  /api/{collection}?_sort=field:dir        — sorted
- *   POST /api/{collection}  body: { where, ... } — operators in body
- *   GET  /api/{collection}/{slug}                 — single record
- *
- * Usage:
- *   node scripts/framework/dev-backend.js --recordsByQuery <path> [--port N]
- *
- * Example (academic-metrics):
- *   node scripts/framework/dev-backend.js \
- *     --recordsByQuery framework/templates/academic-metrics/site/recordsByQuery \
- *     --port 8080
- *
- * Then in the site's site.yml:
- *   fetcher:
- *     baseUrl: http://localhost:8080
- *     supports: [where, limit, sort]
- *
- * And rewrite collection refs to URLs, e.g.:
- *   fetch: { url: /api/members, schema: members }
- */
-
-import { createServer } from 'node:http'
-import { readFile, readdir, stat } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
-import { resolve, join, basename, extname } from 'node:path'
-import { parseArgs } from 'node:util'
-import yaml from 'js-yaml'
-import { matchWhere } from '@uniweb/core'
-
-const { values } = parseArgs({
-  options: {
-    entities: { type: 'string', short: 'e' },
-    port: { type: 'string', short: 'p', default: '8080' },
-  },
-})
-
-if (!values.entities) {
-  console.error('Usage: dev-backend.js --entities <path> [--port N]')
-  process.exit(1)
-}
-
-const ENTITIES_ROOT = resolve(values.entities)
-const PORT = Number(values.port)
-
-if (!existsSync(ENTITIES_ROOT)) {
-  console.error(`Entities directory not found: ${ENTITIES_ROOT}`)
-  process.exit(1)
-}
-
-// ─── Load recordsByQuery from disk ─────────────────────────────────────────────
-
-async function loadRecords(dir) {
-  const files = await readdir(dir)
-  const items = []
-  for (const file of files) {
-    const ext = extname(file).toLowerCase()
-    if (!['.yml', '.yaml', '.json'].includes(ext)) continue
-    const filepath = join(dir, file)
-    const content = await readFile(filepath, 'utf8')
-    let data
-    try {
-      data = ext === '.json' ? JSON.parse(content) : yaml.load(content)
-    } catch (err) {
-      console.warn(`[dev-backend] Failed to parse ${filepath}: ${err.message}`)
-      continue
-    }
-    if (data == null) continue
-    const slug = basename(file, ext)
-    if (Array.isArray(data)) {
-      // Array-form file: each element is a record.
-      for (const record of data) {
-        if (record && typeof record === 'object') items.push(record)
-      }
-    } else if (typeof data === 'object') {
-      items.push({ slug, ...data })
-    }
-  }
-  return items
-}
-
-async function loadAllRecords() {
-  const entries = await readdir(ENTITIES_ROOT)
-  const recordsByQuery = {}
-  for (const name of entries) {
-    const fullPath = join(ENTITIES_ROOT, name)
-    const s = await stat(fullPath)
-    if (!s.isDirectory()) continue
-    recordsByQuery[name] = await loadRecords(fullPath)
-    console.log(`[dev-backend] Loaded ${recordsByQuery[name].length} items from "${name}"`)
-  }
-  return recordsByQuery
-}
-
-// ─── Operator handling (mirrors default-fetcher pushdown wire format) ───────
-
-function applyOperators(items, operators) {
-  let result = items
-  if (operators.where) {
-    result = matchWhere(operators.where, result)
-  }
-  if (operators.sort) {
-    result = applySort(result, operators.sort)
-  }
-  if (typeof operators.limit === 'number' && operators.limit > 0) {
-    result = result.slice(0, operators.limit)
-  }
-  return result
-}
-
-function applySort(items, sortExpr) {
-  const sorts = String(sortExpr).split(',').map((s) => {
-    const [field, dir = 'asc'] = s.trim().split(/\s+/)
-    return { field, desc: dir.toLowerCase() === 'desc' }
-  })
-  return [...items].sort((a, b) => {
-    for (const { field, desc } of sorts) {
-      const av = a?.[field] ?? ''
-      const bv = b?.[field] ?? ''
-      if (av < bv) return desc ? 1 : -1
-      if (av > bv) return desc ? -1 : 1
-    }
-    return 0
-  })
-}
-
-function parseOperatorsFromQuery(searchParams) {
-  const out = {}
-  if (searchParams.has('_where')) {
-    try {
-      out.where = JSON.parse(searchParams.get('_where'))
-    } catch (err) {
-      throw new Error(`Invalid _where JSON: ${err.message}`)
-    }
-  }
-  if (searchParams.has('_limit')) {
-    out.limit = Number(searchParams.get('_limit'))
-  }
-  if (searchParams.has('_sort')) {
-    out.sort = searchParams.get('_sort')
-  }
-  return out
-}
-
-async function readJsonBody(req) {
-  return new Promise((resolve, reject) => {
-    let body = ''
-    req.on('data', (chunk) => { body += chunk })
-    req.on('end', () => {
-      if (!body) return resolve({})
-      try { resolve(JSON.parse(body)) }
-      catch (err) { reject(new Error(`Invalid JSON body: ${err.message}`)) }
-    })
-    req.on('error', reject)
-  })
-}
-
-// ─── HTTP server ────────────────────────────────────────────────────────────
-
-function send(res, status, body) {
-  res.writeHead(status, {
-    'Content-Type': 'application/json',
-    'Access-Control-Allow-Origin': '*',
-    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-    'Access-Control-Allow-Headers': 'Content-Type',
-  })
-  res.end(typeof body === 'string' ? body : JSON.stringify(body))
-}
-
-async function handleRequest(req, res, recordsByQuery) {
-  if (req.method === 'OPTIONS') return send(res, 204, '')
-
-  const url = new URL(req.url, `http://${req.headers.host}`)
-  const match = url.pathname.match(/^\/api\/([^/]+)(?:\/([^/]+))?$/)
-  if (!match) return send(res, 404, { error: 'Not found' })
-
-  const [, queryName, slug] = match
-  const items = recordsByQuery[queryName]
-  if (!items) return send(res, 404, { error: `Unknown query: ${queryName}` })
-
-  // Single record by slug.
-  if (slug) {
-    const item = items.find((r) => r?.slug === slug)
-    if (!item) return send(res, 404, { error: `No record with slug "${slug}"` })
-    return send(res, 200, item)
-  }
-
-  // Collection — apply operators from query string (GET) or body (POST).
-  let operators
-  try {
-    operators = req.method === 'POST'
-      ? await readJsonBody(req)
-      : parseOperatorsFromQuery(url.searchParams)
-  } catch (err) {
-    return send(res, 400, { error: err.message })
-  }
-
-  let result
-  try {
-    result = applyOperators(items, operators)
-  } catch (err) {
-    return send(res, 400, { error: `Operator evaluation failed: ${err.message}` })
-  }
-  return send(res, 200, result)
-}
-
-// ─── Boot ───────────────────────────────────────────────────────────────────
-
-const recordsByQuery = await loadAllRecords()
-const knownQueries = Object.keys(recordsByQuery)
-if (knownQueries.length === 0) {
-  console.warn('[dev-backend] No recordsByQuery found.')
-}
-
-const server = createServer((req, res) => {
-  handleRequest(req, res, recordsByQuery).catch((err) => {
-    console.error('[dev-backend] Request handler threw:', err)
-    send(res, 500, { error: 'Internal server error' })
-  })
-})
-
-server.listen(PORT, () => {
-  console.log(`[dev-backend] Listening on http://localhost:${PORT}`)
-  console.log(`[dev-backend] Queries: ${knownQueries.join(', ') || '(none)'}`)
-  console.log('[dev-backend] Endpoints:')
-  for (const name of knownQueries) {
-    console.log(`  GET  /api/${name}                  — all records`)
-    console.log(`  GET  /api/${name}?_where=<JSON>    — filtered`)
-    console.log(`  GET  /api/${name}/{slug}            — single record`)
-    console.log(`  POST /api/${name}  body: { where } — operators in body`)
-  }
-})