@uniweb/build 0.44.4 → 0.45.0

package/src/uwx/self-scope.js

@@ -0,0 +1,78 @@
+// `@/x` — a Model ref in the site's own foundation scope — and its qualified form.
+//
+// `@/member` names a data schema in the foundation's own `schemas/`. It is
+// AUTHORING shorthand: a backend resolves Models by name and never mints one, so a
+// ref that leaves the CLI must be the name the Model was stored under,
+// `@<org>/member`. Everything that reads a ref off the wire matches it exactly —
+// the entity store at restore, and a records service answering a hosted page's
+// query.
+//
+// ⭐ ONE RULE FOR EVERY PATH THAT SHIPS A REF FROM ONE PUBLISH, and its inverse:
+//
+//   - a record's `$model`             `records.js::buildRecordEntities`
+//   - a query's `schema`              `site.js::queriesNested` (the `queries` Section)
+//   - the author's spelling, on pull  `records-project.js` (placement and declarations)
+//
+// ⛔ They must agree on one alias. When the query path shipped `@/member` verbatim
+// while the records beside it were qualified, the query named a Model its own
+// records were not stored under: a hosted page's question named a Model that does
+// not exist, the records service refused that key, and the section rendered
+// nothing — the key absent from `content.data`, the reason only on
+// `block.dataError`, the console clean. Nothing on either side was malformed; the
+// two paths disagreed.
+//
+// Registering a foundation qualifies its declarations separately, from the
+// foundation's publish scope (`registry-package.js`). That is a different input
+// (the foundation's scope, not the site's publish org) and stays there.
+
+/**
+ * An org handle as `--org` or `site.yml::$org` gives it — `@acme`, `acme`, or
+ * `@acme/…` — reduced to the bare handle, or `''`.
+ *
+ * @param {unknown} org
+ * @returns {string}
+ */
+export function bareOrg(org) {
+  return typeof org === 'string' ? org.replace(/^@/, '').replace(/\/.*$/, '') : ''
+}
+
+/**
+ * `@/x` → `@<org>/x`. Any other ref (`@std/x`, `@acme/x`) passes through, and so
+ * does `@/x` when no org is known — callers that ship an unresolved alias say so
+ * themselves (`buildRecordEntities` warns per query).
+ *
+ * @param {unknown} ref
+ * @param {unknown} org
+ * @returns {unknown}
+ */
+export function resolveSelfScope(ref, org) {
+  const handle = bareOrg(org)
+  return typeof ref === 'string' && ref.startsWith('@/') && handle
+    ? `@${handle}/${ref.slice(2)}`
+    : ref
+}
+
+/**
+ * The inverse, for a pull: `@<org>/x` → `@/x` for the site's own org.
+ *
+ * ⛔ WITHOUT THIS THE ROUND TRIP IS NOT A FIXED POINT, and the failure is silent
+ * on both ends. A record authored under `entities/article/` comes back as
+ * `@acme/article` and, placed literally, lands under `entities/acme/article/` — a
+ * different schema folder, which the next build reads as a different schema. A
+ * query declared `schema: '@/member'` comes back as `@acme/member`, and one that
+ * relied on the query-name default comes back with an explicit schema it never
+ * had.
+ *
+ * ⭐ The site records its own org at create (`site.yml::$org` — "whose this is"),
+ * which is exactly the inverse. A model scoped to ANOTHER org is left alone: it
+ * genuinely is that org's, and `@/` would be a lie.
+ *
+ * @param {unknown} ref
+ * @param {unknown} org
+ * @returns {unknown}
+ */
+export function unresolveSelfScope(ref, org) {
+  const handle = bareOrg(org)
+  if (typeof ref !== 'string' || !handle) return ref
+  return ref.startsWith(`@${handle}/`) ? `@/${ref.slice(handle.length + 2)}` : ref
+}

package/src/uwx/site-project.js

@@ -144,11 +144,19 @@ const INFO_TO_SITE_YML = {
   // ⭐ `tags` — authored, non-localized tokens; the filter facet for a list of site
   // cards. Round-trips verbatim like any authored list.
   tags: 'tags',
-  // ⛔ `url` and `preview_image` ARE DELIBERATELY ABSENT and must stay absent. Both are
-  // BACKEND-STAMPED — a site's live address and its card image URL are assigned by
-  // the host — so writing either into `site.yml` would launder a deploy-derived value
-  // into authored config, which is the hazard `submit` / `assistant` / `tracking` are
-  // annotated against above. Framework emits neither and must project neither.
+  // ⭐ `preview` — the card image, verbatim: the app's timestamp, an author's URL, or
+  // the path an author wrote for an image in the project, which `restoreAssetRefs`
+  // has already put back by recognizing the serve URL the push recorded in
+  // `assets.json` (asset-map.js). [Diego, 2026-09-10]
+  preview: 'preview',
+  // ⭐ `url` — where the site is live → `site.yml::$url`. The backend records it at
+  // every publish, and pull is its only way onto disk; recorded rather than authored,
+  // so it lands under the `$` like `$uuid`.
+  //
+  // ⚠️ Both were listed here as "DELIBERATELY ABSENT… BACKEND-STAMPED" until
+  // 2026-09-10. Leaving an app-written field out of this map is what lets the next
+  // push destroy it, since `info` is replaced whole.
+  url: '$url',
 }
 
 // ── `settings` Section → site.yml ─────────────────────────────────────────────

package/src/uwx/site.js

@@ -53,7 +53,9 @@ import {
   applyWildcardOrder,
   processMarkdownFile,
   fetchFromDataShorthand,
+  assertRouteFolder,
 } from '../site/content-collector.js'
+import { refuseUnder } from '../site/data-fetcher.js'
 import { normalizeHideIn } from '../site/nav-visibility.js'
 import { resolveDefaultLocale, validateLanguageConfig, queryDataUrl } from '@uniweb/core'
 import { emitEntitySyncPackage } from './entity-document.js'
@@ -62,6 +64,7 @@ import { unwrapLocalized } from './backfill.js'
 import { loadFreeformTranslation } from '../i18n/freeform.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveQueriesConfig } from './queries-config.js'
+import { resolveSelfScope } from './self-scope.js'
 
 const SITE_ENTITY_KEY = 'site-content' // one content entity per site project
 
@@ -69,6 +72,16 @@ function setIf(obj, key, value) {
   if (value !== undefined) obj[key] = value
 }
 
+// A YAML scalar the author may have written unquoted: `20260910` loads as a number
+// and `2026-09-10` as a Date. Carry either as the string it stands for; anything
+// else that is not a string is not a value a string field can hold.
+function scalarString(value) {
+  if (typeof value === 'string') return value
+  if (typeof value === 'number') return String(value)
+  if (value instanceof Date) return value.toISOString()
+  return undefined
+}
+
 // Credential-shaped keys, mirroring the set the delivery edge strips on the
 // reading side. Deliberately the SAME list rather than a stricter one, so the
 // two guards are visibly twins and a key added to one is obviously owed to the
@@ -225,6 +238,10 @@ function buildPageData(config, ctx) {
   // 2026-09-02 this kept `[0]` and dropped the rest silently, so the wire
   // carried one dataset for a page that asked for several.
   let fetch = config.fetch ?? fetchFromDataShorthand(config.data)
+  // `where: { path: { under } }` is refused here as the build refuses it
+  // (`parseFetchConfig`): a site that cannot build must not sync either. A
+  // section's fetch is refused where the collector parses it.
+  for (const one of [fetch].flat()) refuseUnder(one?.where, 'fetch')
   // Resolve the authored `query:` shorthand to the runtime-fetchable
   // `path: /data/<name>.json` (the static convention the default-fetcher uses).
   // A shell/backend-hosted site renders client-side with NO prerender, so the
@@ -537,8 +554,13 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
   const { siteRoot, siteIndex, sourceLocale, translations } = ctx
   const folders = await orderedSubfolders(dirPath, inheritedMode, parentConfig)
   const out = []
+  // A folder inside a `[...path]` folder can never be reached, and `[dir]` /
+  // `[path]` would name a route variable — refused here as the collector refuses
+  // them, so a site that cannot build cannot sync either (ruled 2026-09-11).
+  const insideCatchAll = (parentSlugPath || '').split('/').includes(CATCH_ALL_MARKER)
   for (let i = 0; i < folders.length; i++) {
     const f = folders[i]
+    assertRouteFolder(f.dirName, insideCatchAll ? '/:path*' : '/')
     const dyn = f.dirName.match(DYNAMIC_RE)
     const slug = dyn ? dyn[1] : f.name
     const mode = f.source === 'folder.yml' ? 'folder' : 'page'
@@ -731,6 +753,9 @@ export function isSiteRelativeExtensionUrl(decl) {
  * @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.
+ * @param {string} [org] the publish org. A foundation-relative `schema` (`@/x`)
+ *        is qualified with it (`./self-scope.js`), exactly as the records' `$model`
+ *        is — see the note at the `schema` line below.
  */
 // ⛔ KEYS THAT MUST NOT REACH THE WIRE. Everything else on an authored declaration
 // is emitted, including fields this build does not model — see the note in
@@ -786,13 +811,20 @@ const DECL_NOT_ON_WIRE = new Set([
   'filter'
 ])
 
-function queriesNested(declarations, uuids = null) {
+function queriesNested(declarations, uuids = null, org = null) {
   const out = []
   for (const [name, d] of Object.entries(declarations)) {
+    refuseUnder(d.where, `queries.${name}`)
     const data = {}
     const source = d.path ? { path: d.path } : d.url ? { url: d.url } : d.source
     setIf(data, 'source', source)
-    setIf(data, 'schema', d.schema)
+    // ⛔ QUALIFIED, WITH THE SAME RULE AND THE SAME ORG AS THE RECORDS' `$model`
+    // (`records.js::buildRecordEntities`). A consumer answers a query by matching
+    // this name against the Models its records were stored under, so a verbatim
+    // `@/member` beside records stored as `@org/member` names nothing: the query
+    // resolves no Model and the page that binds it renders empty. The pull puts the
+    // author's `@/` back (`records-project.js::declarationsToQueriesYml`).
+    setIf(data, 'schema', resolveSelfScope(d.schema, org))
     setIf(data, 'sort', d.sort)
     // Legacy `filter:` is not synced — it is translated to `where` upstream
     // (the canonical predicate). No legacy fields on the wire.
@@ -1021,7 +1053,7 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
   // `ogTitle`, `ogDescription`, `noindex`, `canonical`, `changefreq`, `priority`
   // (`core/src/seo.js`). Two of those are literally sitemap.xml columns. It only
   // ever passed the card test because `image` was inside it; the card's picture is
-  // `info.preview_image` now.
+  // `info.preview` now.
   setIf(settings, 'seo', siteYml.seo)
   // ⭐ `keywords` IS seo by function — it renders into `<meta name="keywords">`
   // (`runtime/src/ssr-renderer.js`). It is top-level in site.yml for authoring
@@ -1051,6 +1083,10 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
   // ⭐ The site-level fetch, DESUGARED and under its real name. `data:` is the
   // authoring shorthand for `fetch:` and every other tier already calls the wire
   // field `fetch`; the site tier called it `data` until 2026-09-09.
+  // `under` is refused as the build refuses it; the `data:` shorthand carries no
+  // `where`. ⚠️ The source expression stays inside `setIf`: `gen-emit-surface.mjs`
+  // reads the published key's sources off it.
+  for (const one of [siteYml.fetch].flat()) refuseUnder(one?.where, 'site.yml fetch')
   setIf(settings, 'fetch', siteYml.fetch ?? fetchFromDataShorthand(siteYml.data))
 
   // ⭐ The SITE TIER of framework's own `{name, hide, params}` layout object, which
@@ -1076,6 +1112,9 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
  * @param {string} [opts.sourceLocale] - localized-field wrap locale. Defaults to
  *        the site's effective default locale (`defaultLanguage || languages[0] ||
  *        'en'` — the shared `resolveDefaultLocale` rule), NOT a bare 'en'.
+ * @param {string} [opts.org] - the publish org, which qualifies a query's
+ *        foundation-relative `schema` (`@/x` → `@org/x`). Pass the same org the
+ *        records are emitted with; absent, `@/x` ships as written.
  * @returns {Promise<object>} the section-keyed `$`-document:
  *        `{ $uuid?, $id, $model, info, pages, layout_sections, extensions, queries }`
  */
@@ -1271,11 +1310,28 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // over an already-fetched list and never asks the database, while a DB-filterable
   // facet is separately useful — only the second needs a predicable brief field.
   setIf(info, 'tags', siteYml.tags)
-  // ⛔ `url` and `preview_image` are BACKEND-STAMPED and framework emits NEITHER.
-  // A site's live address is assigned at publish and its card image needs a servable
-  // URL; a serve location is a per-response answer the host owns — read, never
-  // constructed. `site-project.js` must also never write them into `site.yml`, or a
-  // pull launders a deploy-derived value into authored config.
+  // ⭐ `preview` — the site card's image. ONE field, TWO writers, and it round-trips
+  // whichever wrote it [Diego, 2026-09-10]:
+  //   · the APP, when it generates a card image — a timestamp, carried verbatim;
+  //   · an AUTHOR, deliberately — typically a template site's custom image: a URL, or
+  //     a site-root path to an image in the project, which push uploads like any
+  //     content image and sends as its serve URL, and which pull puts back as the
+  //     path the author wrote (`restoreAssetRefs` recognizes the URL by the
+  //     fingerprint `assets.json` recorded for it).
+  // The app leaves an author's value alone.
+  //
+  // ⚠️ This read "`url` and `preview_image` are BACKEND-STAMPED and framework emits
+  // NEITHER" until 2026-09-10. Neither half held: nothing stamped `url`, and leaving
+  // an app-written field off an allowlist destroys it on every push, because `info`
+  // is replaced whole.
+  setIf(info, 'preview', scalarString(siteYml.preview))
+  // ⭐ `url` — where the site is live, so a site card can link to it without opening
+  // the editor. The backend records it at every publish (stated by backend,
+  // 2026-09-10) and pull brings it into `site.yml::$url`; nothing in framework writes
+  // it. The `$` marks it as recorded rather than authored, like `$uuid` — and keeps it
+  // out of the rendered payload, where a bare `url:` would sit beside `seo.baseUrl`,
+  // the authored canonical address.
+  setIf(info, 'url', siteYml.$url)
 
   const ctx = { siteRoot, siteIndex: siteYml.index, sourceLocale, translations }
   const pagesPath = siteYml.paths?.pages
@@ -1327,7 +1383,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   //
   // ⚠️ `queriesNested` keeps its name. §2's rule: rename what an author or a
   // consumer sees, leave the identifier alone.
-  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids)
+  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids, opts.org)
   // Emitted ONLY when the file declares the key — see the header above
   // `serviceRecords`: on a replaced Section, absent and empty are different
   // requests and one of them is destructive.

package/src/uwx/sync-package.js

@@ -126,10 +126,13 @@ function walkEntityAssets(node, visitor) {
 //
 //     ⚠️ **This bullet used to justify itself with "no deployment emits
 //     `config.assets.url` yet". FALSIFIED 2026-08-18** by the backend lane:
-//     `serve` publishes the pattern **unconditionally**, falling back to the
-//     direct form, so a deployment with no asset storage emits the honest
-//     `/gateway/asset/dist/{id}/base.{ext}` rather than nothing (measured by
-//     them on a running daemon, not read off a type). ⛔ Scoped to deployments
+//     `serve` publishes the pattern **unconditionally**, falling back to a
+//     direct form, so a deployment with no asset storage emits a pattern rather
+//     than nothing (measured by them on a running daemon, not read off a type).
+//     ⛔ This named that direct form `/gateway/asset/dist/{id}/base.{ext}` until
+//     2026-09-10, and there is no such route [Diego] — the name had spread into
+//     tests and kb as if it were THE serve URL. A serve URL is whatever the host
+//     returns; nothing here depends on its shape. ⛔ Scoped to deployments
 //     running code from 2026-08-17 or later; an older one emits nothing, and
 //     absent stays absent. A present-tense negative about someone else's
 //     deployments is the claim nothing in this repo can ever contradict — it
@@ -157,19 +160,22 @@ function walkEntityAssets(node, visitor) {
 // ProseMirror image node's attrs (`{src, alt, …}`) and a section background's
 // media object (`{image: {src}}`) with one rule — the two shapes framework
 // resolves, reached through the same walk.
-function rewriteEntityAssets(node, map, ids) {
+//
+// `noStamp` is the one object that must get NO identity attrs even when a slot
+// matches — the site's `info`, whose fields the host declares (see the call site).
+function rewriteEntityAssets(node, map, ids, noStamp = null) {
   if (Array.isArray(node)) {
     for (let i = 0; i < node.length; i++) {
       const v = node[i]
       if (typeof v === 'string') { if (map[v]) node[i] = map[v] }
-      else rewriteEntityAssets(v, map, ids)
+      else rewriteEntityAssets(v, map, ids, noStamp)
     }
     return node
   }
   if (node && typeof node === 'object') {
     // Stamp BEFORE the string swap below, while the reference is still the
     // local ref the ids map is keyed by.
-    if (ids) {
+    if (ids && node !== noStamp) {
       // Every asset slot, not just the primary: a video's `poster` and a
       // document's `preview` are assets like any other, and each has identity
       // attrs naming which reference they belong to (ASSET_SLOTS).
@@ -187,7 +193,7 @@ function rewriteEntityAssets(node, map, ids) {
     for (const key of Object.keys(node)) {
       const v = node[key]
       if (typeof v === 'string') { if (map[v]) node[key] = map[v] }
-      else rewriteEntityAssets(v, map, ids)
+      else rewriteEntityAssets(v, map, ids, noStamp)
     }
   }
   return node
@@ -311,6 +317,10 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     ? await siteProjectToDocument(siteRoot, {
         sourceLocale,
         ...(opts.queryUuids ? { queryUuids: opts.queryUuids } : {}),
+        // ⛔ THE SAME ORG `buildRecordEntities` WAS GIVEN ABOVE. A query's `schema`
+        // must name the Model its records are stored under, and both are qualified
+        // from one `@/x` by one rule (`./self-scope.js`) — so they take one org.
+        ...(opts.org ? { org: opts.org } : {}),
         // Withhold the `$services`/`$secrets` Sections when the caller has
         // determined the file is not asking for anything new by them. Passed
         // through rather than decided here: the last-agreed state is project
@@ -387,7 +397,12 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const assetIds =
     opts.assetIds && typeof opts.assetIds === 'object' ? opts.assetIds : null
   if (assetRewrite) {
-    if (siteDoc) rewriteEntityAssets(siteDoc, assetRewrite, assetIds)
+    // ⛔ No identity attrs on `info`: it is a Section whose fields the host declares,
+    // and `preview` is a real ASSET_SLOTS slot, so stamping would add
+    // `previewAssetId`/`previewAssetExt` — fields the host refuses. Its bare strings
+    // are still swapped for their serve URLs, which `assets.json` recognizes on pull
+    // by fingerprint (asset-map.js → `servedFingerprint`).
+    if (siteDoc) rewriteEntityAssets(siteDoc, assetRewrite, assetIds, siteDoc.info)
     for (const e of col.entities) rewriteEntityAssets(e.document, assetRewrite, assetIds)
   }
   // Collect the site-root local refs the deploy must upload (`/images/x.png`).

package/src/uwx/yaml-upsert.js

@@ -51,3 +51,29 @@ export function upsertYamlScalar(filePath, key, value) {
   writeFileSync(filePath, next)
   return true
 }
+
+/**
+ * Remove a TOP-LEVEL scalar key from the YAML file at `filePath`, preserving every
+ * other line (comments included) — the inverse of `upsertYamlScalar`, with the same
+ * scope: one `key: value` line at column 0. A key followed by indented lines, or
+ * opening a block scalar (`|` / `>`), is not a one-line scalar and is left alone
+ * rather than half-removed.
+ *
+ * @param {string} filePath
+ * @param {string} key - a top-level scalar key (e.g. `$url`)
+ * @returns {boolean} true if the file changed
+ */
+export function removeYamlScalar(filePath, key) {
+  if (!existsSync(filePath)) return false
+  const lines = readFileSync(filePath, 'utf8').split('\n')
+  const esc = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const re = new RegExp(`^${esc}:(.*)$`)
+  const at = lines.findIndex((l) => re.test(l))
+  if (at === -1) return false
+  const inline = lines[at].replace(re, '$1').trim()
+  const continues = at + 1 < lines.length && /^[ \t]+\S/.test(lines[at + 1])
+  if (continues || /^[|>]/.test(inline)) return false
+  lines.splice(at, 1)
+  writeFileSync(filePath, lines.join('\n'))
+  return true
+}