@uniweb/build 0.64.1 → 0.65.0

package/src/site/preview.js

@@ -0,0 +1,84 @@
+/**
+ * A PREVIEW OF A SITE A BACKEND HOLDS — what `uniweb dev` read from that backend, handed to the one
+ * dev server it starts.
+ *
+ * A clone names its foundation by catalog ref (`@acme/fnd@1.2.0`) and keeps the media URLs the
+ * backend serves, so two things its dev server needs are the backend's to say. `uniweb dev` asks the
+ * backend the site is on, through the site, and passes what it learned in `UNIWEB_PREVIEW`, as JSON:
+ *
+ *   { backend: 'https://…',                              the backend the site is on
+ *     foundation: { ref, url, cssUrl } }                 where it serves the version site.yml names
+ *
+ * ⭐ It resolves the declared foundation; it never substitutes one. The answer names the ref it is
+ * for, and `detectFoundationType` honors it for that ref alone — which is what separates it from the
+ * `UNIWEB_FOUNDATION_REF` override `config.js` retired, a way for a site to be rendered by code its
+ * own `site.yml` did not name.
+ *
+ * ⭐ And a media URL the clone kept is the backend's own. A pull keeps any serve URL it cannot map
+ * back to an author's file (`uwx/asset-map.js::restoreAssetRefs`, *"the URL that works"*), and a
+ * root-relative one works on the origin that served the document holding it. So the dev server
+ * fetches from `backend` what the content names and the site does not have (`config.js`) — it
+ * resolves the URL it was given against the origin it came from, and composes no route.
+ *
+ * ⛔ Nothing keeps it. A serve location is decided at publish and read from the response that
+ * carries it, so it lives as long as the process that asked: `site.yml` keeps the ref, and no push,
+ * pull or build sees a URL from here. A build handed one refuses it (`config.js`), so a preview's
+ * answer never reaches a built artifact.
+ *
+ * ⚠️ And it may not be known. Whether a backend tells the CLI where a version is served is the
+ * backend's to decide; `uniweb dev` says so and starts nothing when it is not told.
+ */
+
+/** The variable `uniweb dev` sets for the dev server it starts. */
+export const PREVIEW_ENV = 'UNIWEB_PREVIEW'
+
+/**
+ * The variable's value.
+ *
+ * @param {{ backend: string, foundation: { ref: string, url: string, cssUrl?: string|null } }} preview
+ * @returns {string}
+ */
+export function encodePreview({ backend, foundation }) {
+  const { ref, url, cssUrl = null } = foundation
+  return JSON.stringify({ backend, foundation: { ref, url, cssUrl: cssUrl || null } })
+}
+
+/**
+ * What a dev server was handed, or null when it was handed nothing.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {{ backend: string, foundation: { ref: string, url: string, cssUrl: string|null } }|null}
+ * @throws {Error} when the variable is set and says nothing usable — a preview that cannot read its
+ *   answer must not start as if it had none
+ */
+export function readPreview(env = process.env) {
+  const raw = env[PREVIEW_ENV]
+  if (!raw) return null
+  let given = null
+  try {
+    given = JSON.parse(raw)
+  } catch {
+    // reported below
+  }
+  const f = given?.foundation
+  if (!isHttpOrigin(given?.backend) || typeof f?.ref !== 'string' || typeof f.url !== 'string' || !f.url) {
+    throw new Error(
+      `${PREVIEW_ENV} holds no preview (${JSON.stringify(raw).slice(0, 120)}). ` +
+        'It is set by `uniweb dev`; run that rather than setting it.'
+    )
+  }
+  return {
+    backend: new URL(given.backend).origin,
+    foundation: { ref: f.ref, url: f.url, cssUrl: typeof f.cssUrl === 'string' ? f.cssUrl : null }
+  }
+}
+
+// ⛔ `new URL('localhost:8080')` parses — as the scheme `localhost:` — and its origin is the string
+// "null". An origin is http(s), or it is nothing.
+function isHttpOrigin(value) {
+  try {
+    return /^https?:$/.test(new URL(value).protocol)
+  } catch {
+    return false
+  }
+}

package/src/site/queries-config.js

@@ -35,6 +35,7 @@ import { detectFoundationType, parseCatalogRef } from './foundation-ref.js'
 import { readRegisteredFoundation } from './registered-foundation.js'
 import { buildDataSchemaMap, SCHEMA_NOT_FOUND } from '../resolve-data-schema.js'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
+import { buildSchema } from '../schema.js'
 import { refuseQueryRoute, refuseLimit } from './data-fetcher.js'
 import { readFile } from 'node:fs/promises'
 import yaml from 'js-yaml'
@@ -174,8 +175,6 @@ export async function resolveQueriesConfig(siteRoot, opts = {}) {
     }
   }
 
-  await deriveDeferredFromSchemas(siteRoot, siteYml, declarations)
-
   // ⛔ `folderSync` AND `folders` WERE DELETED HERE, 2026-09-06. Both were
   // `collections.yml` survivors kept "for one step" while `records.yml` took
   // over, and both had become literals — `true` and `null` — that no longer
@@ -194,7 +193,7 @@ export async function resolveQueriesConfig(siteRoot, opts = {}) {
 }
 
 /** What a query over the site's records declares, which an external query cannot. */
-const SITE_RECORDS_ONLY = ['schema', 'model', 'scope', 'deferred', 'excerpt', 'path']
+const SITE_RECORDS_ONLY = ['schema', 'model', 'scope', 'excerpt', 'path']
 /** The keys of an external query's `record:` request. */
 const RECORD_KEYS = ['url', 'method', 'body', 'transform']
 
@@ -207,7 +206,7 @@ const RECORD_KEYS = ['url', 'method', 'body', 'transform']
  * `transform` (a dot-path to its records), `where` / `sort` / `limit` evaluated over
  * them, and `record:` — `{ url, method, body, transform }` — for one record on a
  * parametric page. What describes the site's records — `schema`, `scope`,
- * `deferred`, `excerpt` — is refused beside `url:`. ⛔ `detailUrl:` and `detail:` are
+ * `excerpt` — is refused beside `url:`. ⛔ `detailUrl:` and `detail:` are
  * retired everywhere: their one real case is `record.url`. ⛔ And `limit:` is a whole
  * number, 0 or more (`refuseLimit`).
  *
@@ -235,6 +234,17 @@ export function refuseQueryDeclaration(decl) {
         `on an external query — one with \`url:\`.`
     )
   }
+  // ⛔ `deferred:` IS RETIRED (2026-09-27 [Diego]: "the `deferred:` concept keeps getting in the way
+  // and doesn't match a hosted lane"). A list carries each record's brief, on every site, so a
+  // field a list should leave out belongs in a section of its own, outside the brief — where a
+  // host leaves it out too. `deferred:` only made a static site's lists differ from a hosted one's.
+  if (decl.deferred !== undefined) {
+    throw new Error(
+      `[uniweb] ${where}: \`deferred:\` is retired. A list carries each record's brief — the fields ` +
+        `of its schema's brief section — so a field a list should leave out belongs in a section of ` +
+        `its own, outside the brief. Remove the key.`
+    )
+  }
   refuseQueryRoute(decl, where)
   refuseLimit(decl.limit, where)
   // ⛔ `sync:` IS RETIRED (2026-09-21). `sync: false` kept a query's records off a
@@ -303,6 +313,11 @@ function refuseMethod(method, where) {
  * downstream. It is stripped here rather than at each consumer, so the payload
  * has one shape and no consumer has to know the field existed.
  *
+ * ⛔ `name` too: a declaration carries its query's name for the build's own messages, and
+ * `config.queries` is keyed by it — repeated inside, it was a second copy nothing read, and it
+ * held a key a declaration may want for something else [Diego, 2026-09-27]. Until then every
+ * query on the payload read `{ name: 'articles', … }` under `articles`.
+ *
  * Returns undefined for a site with no queries, so `config.queries`
  * stays absent rather than becoming an empty object — an empty object reads as
  * "declared, and empty" to anything checking for presence.
@@ -311,90 +326,14 @@ export function toConfigQueries(declarations) {
   const names = Object.keys(declarations || {})
   if (names.length === 0) return undefined
   const out = {}
-  for (const name of names) {
-    const { schemaExplicit, ...rest } = declarations[name]
-    out[name] = rest
+  for (const key of names) {
+    const { schemaExplicit, name, ...rest } = declarations[key]
+    out[key] = rest
   }
   return out
 }
 
 
-/**
- * Fill in `deferred:` from each collection's own data schema.
- *
- * ⭐ A schema's **brief** section already states what a record's summary is — the
- * card, the row, the thing a list shows. Everything else is wanted only when one
- * record is the focus. That is exactly what `deferred:` says, so an author with a
- * schema should not have to say it twice, in a second vocabulary, with nothing
- * checking the two against each other.
- *
- * ⇒ `deferred` = every top-level section of the schema other than its brief — the keys
- * a delivered record holds them under (`article_body` for `@std/article`), which is
- * exactly what a host's records service leaves out of a list and adds for `whole`.
- * ⛔ It was the flat form's fields minus the brief's until 2026-09-24; a delivered
- * record carries those under their section, so stripping them by name stripped nothing.
- *
- * Derived from the SCHEMA, never from a record. That is what keeps the
- * build-derived keys safe without a reserved list: `slug`, `route`, `path`,
- * `excerpt`, `image` and `lastModified` are not sections, so they are never
- * stripped. A markdown body goes where its content field is — inside `article_body`,
- * say — so it is deferred with that section.
- *
- * ⛔ Silent on every path that cannot answer, because none of them is an error:
- *
- *   - an author-declared `deferred:` wins outright — this never overrides one;
- *   - no local foundation (a linked or cataloged one), or it is unbuilt → nothing
- *     to read, and a site must still build;
- *   - the schema is not in the foundation's built map → the same soft-skip the
- *     sync lane already applies. `dist/meta/schema.json` carries the schemas
- *     COMPONENTS reference, so a collection whose schema no component binds is
- *     simply not there;
- *   - the schema has no brief, or only one section (`recordLayout`) → there is no
- *     lean shape to honour, so records stay whole.
- *
- * The last two are why this reads the built artifact rather than resolving
- * schemas itself: it is the same input the sync lane uses, so both lanes agree
- * about which schemas exist.
- */
-async function deriveDeferredFromSchemas(siteRoot, siteYml, declarations) {
-  const pending = Object.values(declarations).filter(
-    (d) => d.schema && !Array.isArray(d.deferred)
-  )
-  if (pending.length === 0) return
-
-  const dataSchemas = foundationDataSchemas(siteRoot, siteYml)
-  if (!dataSchemas) return
-
-  for (const decl of pending) {
-    const heavy = deferredFromSchema(dataSchemas[decl.schema])
-    if (heavy) decl.deferred = heavy
-  }
-}
-
-/**
- * The `deferred:` a schema implies — every top-level section but its **brief**, by name.
- *
- * ⛔ ONE IMPLEMENTATION, TWO CALLERS, and that is the point. `deriveDeferredFromSchemas`
- * above uses it to FILL an unstated `deferred:`; `uwx/records-project.js` uses it to
- * RECOGNIZE a derived value on the way back in, so a pull does not write a derivation
- * into the author's file as though they had typed it.
- *
- * ⚠️ A second copy would drift, and the drift would be invisible: the deriver and the
- * inverter would simply stop agreeing about which values are "the derived one", and the
- * pull would start persisting values it was written to drop.
- *
- * @param {object|undefined} schema a data schema, or undefined when it does not resolve
- * @returns {string[]|null} the implied deferred list, or null when the schema states no
- *   brief (a root list, say) or implies nothing heavy — in both cases there is no
- *   derivation to recognize
- */
-export function deferredFromSchema(schema) {
-  const layout = schema ? recordLayout(schema) : null
-  if (!layout || layout.flat || !layout.brief) return null
-  const heavy = layout.sections.map(([name]) => name).filter((name) => name !== layout.brief)
-  return heavy.length ? heavy : null
-}
-
 /**
  * The data schemas a site's records are shaped by, keyed by ref — each resolved from
  * the LOCAL foundation's SOURCE by the resolver its build uses (`buildDataSchemaMap`),
@@ -446,6 +385,30 @@ function localFoundationSrcDir(siteRoot, siteYml) {
   }
 }
 
+/**
+ * A site's foundation's section types, each with its `data:` — what types a query named for a data
+ * key (`uwx/data-key-types.js`). Read from the foundation's SOURCE when it is local, as
+ * `resolveRecordSchemas` reads its data schemas, so `pnpm dev` without a built foundation types a
+ * query as a production build does; else from its built or registered `schema.json`
+ * (`foundationSchemaJson`). Null when there is neither.
+ *
+ * @param {string} siteRoot
+ * @param {object} [siteYml] - an already-read site.yml
+ * @returns {Promise<object|null>}
+ */
+export async function foundationSections(siteRoot, siteYml = null) {
+  const yml = siteYml || (await readYamlFile(join(siteRoot, 'site.yml')))
+  const srcDir = localFoundationSrcDir(siteRoot, yml)
+  if (srcDir) {
+    try {
+      return await buildSchema(srcDir)
+    } catch {
+      // a foundation whose source does not read is reported by the build that builds it
+    }
+  }
+  return foundationSchemaJson(siteRoot, yml)
+}
+
 /** The data schemas a site's foundation declares, or null when unresolvable. */
 export function foundationDataSchemas(siteRoot, siteYml) {
   return foundationSchemaJson(siteRoot, siteYml)?.dataSchemas || null