@uniweb/build 0.30.1 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,15 +59,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
+    "@uniweb/schemas": "^0.2.13",
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/projections": "^0.5.2",
-    "@uniweb/semantic-parser": "^1.3.1",
-    "@uniweb/schemas": "^0.2.11",
-    "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/projections": "^0.5.3",
+    "@uniweb/content-writer": "^0.3.4"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.13.3"
+    "@uniweb/runtime": "^0.13.4"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -76,7 +76,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.14.1"
+    "@uniweb/core": "^0.15.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/dev/api-mount.js

@@ -0,0 +1,142 @@
+import { readFileSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import yaml from 'js-yaml'
+
+/**
+ * Mount a site's own request handler in the dev server.
+ *
+ * A site that talks to a backend needs one running to be developed against, and
+ * making that a live deployment is slow, costs money, and puts a shared database
+ * behind a developer's experiments. So a site may name a **local handler** and the
+ * dev server mounts it at the site's own service address:
+ *
+ * ```yaml
+ * # site.yml
+ * api: /_api                 # where the site's app backend answers
+ * devApi: ./mock/api.js      # what answers it, in development only
+ * ```
+ *
+ * ```js
+ * // mock/api.js — default-export a fetch handler
+ * export default (request) => new Response('{}', { headers: { 'content-type': 'application/json' } })
+ * ```
+ *
+ * ## ⭐ The framework mounts; the site supplies
+ *
+ * This knows nothing about what it is mounting — not the routes, not the shapes,
+ * not which backend is being imitated. It takes a `Request` handler and puts it on
+ * a path. ⛔ **That is deliberate and load-bearing:** the moment the framework
+ * knows what a "mock backend" is, it has a favourite one, and a site talking to
+ * something else is a second-class citizen in its own dev server. A handler is the
+ * whole contract, and anything that can produce one — a hand-written stub, a
+ * recorded fixture, someone's real service in a function — mounts the same way.
+ *
+ * ## ⛔ Development only, and it cannot leak
+ *
+ * `devApi` is read by the dev plugin and by nothing else: no build reads it, no
+ * `info` key carries it, and nothing writes it into a payload. A site's *address*
+ * (`api:`) is authored config and travels; what answers that address locally is a
+ * fact about one machine.
+ *
+ * ⚠️ **Same-origin on purpose.** Mounting inside the dev server means cookies and
+ * `credentials: 'same-origin'` behave as they do in production, where a site's app
+ * backend answers on the site's own origin. A handler on another port would work
+ * too, and would exercise CORS and third-party-cookie rules that production does
+ * not have — so a problem found that way might not be a real one.
+ *
+ * ## ⛔ Registered SYNCHRONOUSLY, and that is not a style choice
+ *
+ * Vite adds middleware registered during `configureServer` BEFORE its own — but
+ * only what is registered before that hook returns. An `await` first, and the
+ * middleware lands after the SPA fallback, which answers every path with
+ * `index.html`: the API returns a 200 of HTML, the client fails to parse it, and
+ * nothing in the log says why. So the config is read with `readFileSync` and the
+ * middleware goes on the stack immediately; only the module load is deferred, and
+ * the middleware awaits it on the first request.
+ *
+ * @param {import('vite').ViteDevServer} server
+ * @param {object} options
+ * @param {string} options.root - the site directory
+ * @returns {boolean} whether a handler was mounted
+ */
+export function mountDevApi(server, { root }) {
+  // ⛔ Read from the RAW site.yml, never from the collected `config`. `$`-prefixed
+  // keys are stripped from the payload precisely because they are local to a
+  // checkout — so the one place that needs this one goes to the file. That is the
+  // rule working: if it were readable from `config`, it would also be published.
+  let site
+  try {
+    site = yaml.load(readFileSync(join(root, 'site.yml'), 'utf8')) || {}
+  } catch {
+    return false
+  }
+
+  const spec = site.$devApi
+  if (!spec) return false
+
+  const declared = site.api
+  const mount = typeof declared === 'string' ? declared : declared?.endpoint
+  if (!mount) {
+    console.error("[dev-api] `$devApi` needs an `api:` address to answer on — add `api: /_api` to site.yml.")
+    return false
+  }
+
+  // Loaded once, lazily, and awaited by the middleware. ⚠️ Loud and specific on
+  // failure: a dev API that silently fails to load looks exactly like a backend
+  // refusing every request, and a developer debugs their own client for an hour
+  // before finding a typo in a path.
+  let loading = null
+  const getHandler = () => {
+    if (!loading) {
+      loading = server
+        .ssrLoadModule(pathToFileURL(resolve(root, spec)).href)
+        .then((loaded) => {
+          const handler = loaded?.default ?? loaded?.fetch
+          if (typeof handler !== 'function') {
+            throw new Error(`'${spec}' must default-export a function (request) => Response`)
+          }
+          return handler
+        })
+        .catch((err) => {
+          console.error(`[dev-api] could not load '${spec}': ${err.message}`)
+          throw err
+        })
+    }
+    return loading
+  }
+
+  const prefix = mount.endsWith('/') ? mount.slice(0, -1) : mount
+
+  server.middlewares.use(async (req, res, next) => {
+    if (!req.url || (req.url !== prefix && !req.url.startsWith(`${prefix}/`))) return next()
+
+    // The handler sees the path WITHOUT the mount point: where a site chooses to
+    // expose its backend is the site's business, and a handler written against one
+    // deployment's prefix would not survive another's.
+    const inner = req.url.slice(prefix.length) || '/'
+    const origin = `http://${req.headers.host || 'localhost'}`
+    const init = { method: req.method, headers: req.headers }
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      const chunks = []
+      for await (const chunk of req) chunks.push(chunk)
+      if (chunks.length) init.body = Buffer.concat(chunks)
+    }
+
+    try {
+      const handler = await getHandler()
+      const response = await handler(new Request(new URL(inner, origin), init))
+      res.statusCode = response.status
+      response.headers.forEach((value, key) => res.setHeader(key, value))
+      const text = await response.text()
+      res.end(text || undefined)
+    } catch (err) {
+      res.statusCode = 500
+      res.setHeader('content-type', 'application/json')
+      res.end(JSON.stringify({ status: 500, title: 'DevApiFailure', detail: err?.message }))
+    }
+  })
+
+  console.log(`[dev-api] '${spec}' answering ${prefix}/*`)
+  return true
+}

package/src/site/config.js

@@ -31,6 +31,7 @@ import {
 import { importMapPlugin } from '../import-map-plugin.js'
 import { resolveModuleUrl, resolveExtensionUrls } from './extension-urls.js'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
+import { checkFoundationResolution } from '../utils/foundation-resolution-check.js'
 import { detectFoundationType } from './foundation-ref.js'
 
 /**
@@ -191,7 +192,7 @@ export async function defineSiteConfig(options = {}) {
   // Plugin to ensure foundation entry file exists (for bundled mode with local foundation)
   const ensureFoundationEntryPlugin = !isRuntimeMode && foundationInfo.type === 'local' ? {
     name: 'uniweb:ensure-foundation-entry',
-    async config() {
+    async config(_config, env) {
       const srcDir = resolveFoundationSrcPath(foundationInfo.path)
       const entryPath = join(srcDir, '_entry.generated.js')
 
@@ -202,8 +203,50 @@ export async function defineSiteConfig(options = {}) {
         try {
           await generateEntryPoint(srcDir, entryPath)
         } catch (err) {
-          console.warn('[site] Failed to generate foundation entry:', err.message)
+          // ⛔ **Swallowing this on a BUILD is how you get vite's opaque
+          // `Failed to resolve entry for package "<name>"` 50ms later**: we
+          // decline to write the entry, say so in a `console.warn` that scrolls
+          // past, and hand vite a package whose `main` points at a file nobody
+          // created. The message naming the actual cause is the one we printed
+          // and discarded.
+          //
+          // ⚖️ **But only when there is no entry to fall back on.** If a previous
+          // build left one, it is stale rather than absent and the build can
+          // still complete — turning that into a hard failure would break a
+          // build that works today, which is a worse trade than a loud warning.
+          // Dev keeps warning either way: a transient error mid-session must not
+          // kill a running server.
+          const haveFallback = existsSync(entryPath)
+          if (env?.command === 'build' && !haveFallback) {
+            throw new Error(
+              `[site] Could not generate the foundation entry for "${foundationInfo.name}".\n` +
+                `  ${err.message}\n\n` +
+                `  ${entryPath} does not exist, so the build cannot resolve the\n` +
+                `  foundation. Fixing the error above is the fix; vite's next\n` +
+                `  message about resolving package "${foundationInfo.name}" is a\n` +
+                `  symptom of this one.`,
+              { cause: err }
+            )
+          }
+          console.warn(
+            `[site] ⛔ Failed to generate foundation entry: ${err.message}` +
+              (haveFallback
+                ? `\n[site]    Continuing with the EXISTING ${entryPath}, which is now STALE.`
+                : '')
+          )
         }
+
+        // Do we and vite agree on which directory that was? Two resolutions run
+        // here — ours by path, vite's by the bare specifier below
+        // (`alias['#foundation'] = foundationInfo.name`) — and when they diverge
+        // the quiet outcome is worse than the loud one: a stale entry in vite's
+        // directory builds the WRONG foundation and reports success.
+        const agreement = checkFoundationResolution({
+          name: foundationInfo.name,
+          generatedInto: srcDir,
+          siteRoot,
+        })
+        if (!agreement.ok) console.warn(`\n${agreement.message}\n`)
       }
     },
 

package/src/site/plugin.js

@@ -200,6 +200,7 @@ async function processDevSectionFetches(sections, fetchOptions) {
 }
 import { generateSearchIndex, isSearchEnabled, getSearchIndexFilename } from '../search/index.js'
 import { mergeTranslations } from '../i18n/merge.js'
+import { mountDevApi } from '../dev/api-mount.js'
 
 /*
  * `applyRouteTranslation` now comes from `@uniweb/projections` (imported
@@ -879,6 +880,18 @@ export function siteContentPlugin(options = {}) {
     configureServer(devServer) {
       server = devServer
 
+      // A site's own backend, answered locally in development. `site.yml::$devApi`
+      // names a module that default-exports a fetch handler, mounted at the site's
+      // own `api:` address so the address is identical in dev and in production.
+      // ⚠️ Synchronous on purpose — see mountDevApi. An await here and the
+      // middleware lands after Vite's SPA fallback, which answers the API with
+      // index.html and says nothing about why.
+      try {
+        mountDevApi(devServer, { root: resolvedSitePath })
+      } catch (err) {
+        console.error(`[dev-api] ${err.message}`)
+      }
+
       // Watch for content changes in dev mode
       if (shouldWatch) {
         const siteYmlPath = resolve(resolvedSitePath, 'site.yml')

package/src/utils/foundation-resolution-check.js

@@ -0,0 +1,142 @@
+/**
+ * Do WE and VITE agree on where the foundation is?
+ *
+ * ## The bug this exists for
+ *
+ * A site build resolves its foundation **twice, by two different mechanisms**,
+ * and until 2026-09-01 nothing checked that they agreed:
+ *
+ *   1. **We resolve a PATH.** `detectFoundationType('src', siteRoot)` returns
+ *      `{ type: 'local', path: <siteRoot>/../src }`, and the
+ *      `uniweb:ensure-foundation-entry` plugin generates `_entry.generated.js`
+ *      into exactly that directory.
+ *   2. **Vite resolves a NAME.** `site/config.js` sets
+ *      `alias['#foundation'] = foundationInfo.name` — the bare specifier — so
+ *      Vite runs its own node_modules lookup and reads that package's `main`.
+ *
+ * Those name the same directory only because a package manager linked
+ * `node_modules/<name>` to the foundation. Nothing enforces it, and when it does
+ * not hold we generate into one directory while Vite reads another.
+ *
+ * ## ⛔ The failure is worse when it does NOT fail
+ *
+ * If the directory Vite reaches has no `_entry.generated.js`, the build dies with
+ * vite's `[commonjs--resolver] Failed to resolve entry for package "<name>"` —
+ * opaque, but loud.
+ *
+ * **If it has a STALE one, nothing fails at all.** The site builds against a
+ * different foundation than the one on disk, and reports success. A developer
+ * editing `src/` sees their change generated into `src/_entry.generated.js` and
+ * simply not take effect. *(Measured by the `flows` lane 2026-09-01: their
+ * harness minted fixtures under a `node_modules` that was itself a symlink to a
+ * seed tree, so a relative `../../src` link resolved into the seed. Every run
+ * that mutated its foundation and then built a site had been silently building
+ * the seed's copy — and presenting as green — for as long as the harness had
+ * existed. The red they opened a channel about was the harmless half.)*
+ *
+ * ⇒ **This check is about the silent case.** An error message can only reach the
+ * loud one; comparing the two answers reaches both.
+ *
+ * ## Why it compares REALPATHS and not link text
+ *
+ * `readlink node_modules/<name>` returning `../../src` looks healthy and proves
+ * nothing: **a relative symlink resolves against the link's target, not its
+ * location**, so with `node_modules` itself a link, `../../src` lands in a
+ * different tree. Only the resolved physical path answers the question vite
+ * actually asks. *(This module's first draft compared link text. It reported
+ * healthy on the one tree that was broken.)*
+ *
+ * ## Why it does its own node_modules walk
+ *
+ * `createRequire(...).resolve(name)` cannot be used: in the failure case `main`
+ * points at the missing entry, so it throws rather than telling us where it
+ * looked. `require.resolve(name + '/package.json')` cannot either — a foundation
+ * declares `exports: { ".": "./_entry.generated.js" }`, which gates every other
+ * subpath, so that lookup fails on a *healthy* package.
+ *
+ * So we walk `node_modules` upward for the package directory, which is the part
+ * of node resolution that locates a package before `exports` or `main` is
+ * consulted. That is the step whose answer we need.
+ */
+
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, join, parse } from 'node:path'
+
+/**
+ * The directory a bare specifier's package lives in, by node's own
+ * node_modules walk — the step that runs before `exports`/`main` are read.
+ *
+ * @param {string} name - the bare specifier (a foundation's package name)
+ * @param {string} fromDir - the directory resolution starts in (the site root)
+ * @returns {string|null} the package directory, or null if no node_modules
+ *   anywhere up the tree holds it
+ */
+export function findPackageDir(name, fromDir) {
+  let dir = fromDir
+  const { root } = parse(fromDir)
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const candidate = join(dir, 'node_modules', name)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+    if (dir === root) return null
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/**
+ * Compare where we generated the foundation entry against where vite will look.
+ *
+ * ⭐ **Silence is deliberate when the package is not found at all.** Not every
+ * supported layout puts the foundation in the site's `node_modules` — a
+ * `foundations/<name>/` multi-site project may not — and a warning that fires on
+ * a healthy project is worse than no warning, because the next person learns to
+ * ignore it. A package we cannot locate is also a case vite will fail on by
+ * itself, loudly. **We report only a disagreement we can actually prove**, which
+ * makes a false positive impossible by construction.
+ *
+ * @param {Object} args
+ * @param {string} args.name - the foundation's declared name (the bare specifier)
+ * @param {string} args.generatedInto - the directory we wrote `_entry.generated.js` to
+ * @param {string} args.siteRoot - where vite resolves the bare specifier from
+ * @returns {{ ok: true } | { ok: false, ours: string, theirs: string, message: string }}
+ */
+export function checkFoundationResolution({ name, generatedInto, siteRoot }) {
+  const theirsRaw = findPackageDir(name, siteRoot)
+  if (!theirsRaw) return { ok: true }
+
+  let ours, theirs
+  try {
+    ours = realpathSync(generatedInto)
+    theirs = realpathSync(theirsRaw)
+  } catch {
+    // A path vanished between the walk and the realpath. Not a disagreement we
+    // can prove, so it is not one we report.
+    return { ok: true }
+  }
+
+  if (ours === theirs) return { ok: true }
+
+  return {
+    ok: false,
+    ours,
+    theirs,
+    message: [
+      `[site] ⛔ Foundation "${name}" resolves to two different directories.`,
+      ``,
+      `  we generated its entry into : ${ours}`,
+      `  vite will import it from    : ${theirs}`,
+      ``,
+      `  Your site build will use the SECOND one, so edits to the first do not`,
+      `  take effect — and if that directory carries a stale _entry.generated.js`,
+      `  the build SUCCEEDS against the wrong foundation.`,
+      ``,
+      `  This means node_modules/${name} under ${siteRoot} is not the foundation`,
+      `  directory. Re-run your package manager's install. If you copied or moved`,
+      `  this project, check whether node_modules (or a parent of it) is a symlink`,
+      `  into another tree — a relative link inside one resolves against the link's`,
+      `  target, so it can point outside this project while looking correct.`,
+    ].join('\n'),
+  }
+}

package/src/uwx/data-schema.js

@@ -78,7 +78,8 @@ export function isContentBodyField(field) {
  * @param {(ref: string) => string} [opts.resolveOptions] - maps an `options`
  *   (item_ref) ref to its full `@org/model/<section>` path. Falls back to
  *   `resolveName` (model only) when not supplied.
- * @returns {Object} the declaration (`{ name, description?, linkable?, sections }`).
+ * @returns {Object} the declaration (`{ name, label?, description?, source_locale?,
+ *          creatable_by?, linkable?, sections }`).
  */
 export function toDataSchemaDeclaration(normalized, { name, resolveName, resolveOptions } = {}) {
   if (!name) throw new Error('toDataSchemaDeclaration: a registry name is required')
@@ -100,10 +101,40 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
   }
 
   const decl = { name }
+  if (normalized.label) decl.label = normalized.label
   if (normalized.description) decl.description = normalized.description
-  // A brief-less model has no card to hydrate as an entity_ref target, so it is
-  // not linkable; a model with a brief defaults to linkable (omit ⇒ true).
-  if (!brief) decl.linkable = false
+  if (normalized.sourceLocale) decl.source_locale = normalized.sourceLocale
+  // `creatable_by` — who may instantiate this Model. Omitted when the author
+  // declares nothing, because the registry's own default (open) is the absent
+  // meaning; sending it explicitly would state a policy the author did not.
+  if (normalized.creatableBy) decl.creatable_by = normalized.creatableBy
+
+  // `linkable` — DERIVED AND AUTHORED, and the two compose in one direction only.
+  //
+  // A brief-less model has no card to hydrate as an `entity_ref` target, so it
+  // cannot be linkable whatever it says; a model with a brief is linkable by
+  // default (omit ⇒ true). ⇒ **The derivation is a ceiling and the authored value
+  // may only lower it.** An author may say `linkable: false` on a model with a
+  // brief — a real choice, "do not let other models point at this" — and that is
+  // honoured.
+  //
+  // ⛔ The contradiction is refused rather than silently resolved: `linkable: true`
+  // on a brief-less model asks for something that cannot exist, and quietly
+  // ignoring it is how an author comes to believe a ref target works. Naming it
+  // costs one line and the message says which half to change.
+  if (!brief) {
+    if (normalized.linkable === true) {
+      throw new Error(
+        `Data schema '${name}': 'linkable: true' needs a brief section — a model with no brief ` +
+          `has no card to hydrate when another model references it. Mark a section 'brief: true', ` +
+          `or drop 'linkable'.`
+      )
+    }
+    decl.linkable = false
+  } else if (normalized.linkable === false) {
+    decl.linkable = false
+  }
+
   decl.sections = sections
   return decl
 }