@uniweb/build 0.30.0 → 0.30.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.30.0",
+  "version": "0.30.2",
   "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/theming": "^0.1.15",
-    "@uniweb/semantic-parser": "^1.3.1",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.5.2",
-    "@uniweb/schemas": "^0.2.11"
+    "@uniweb/schemas": "^0.2.12",
+    "@uniweb/semantic-parser": "^1.3.1",
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/content-writer": "^0.3.4"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.13.2"
+    "@uniweb/runtime": "^0.13.3"
   },
   "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.0"
+    "@uniweb/core": "^0.14.1"
   },
   "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/content-collector.js

@@ -2396,6 +2396,16 @@ export async function collectSiteContent(sitePath, options = {}) {
   // consumer and never ships in a payload (the visitor runtime is
   // list-unaware; the sync lane reads site.yml directly, not this output).
   const { publishLanguages: _publishLanguages, ...runtimeSiteConfig } = siteConfig
+  // ⛔ `$`-prefixed keys are the project's BACKEND-SCOPED state — `$uuid`, `$org`,
+  // `$backend`, `$services`, `$secrets` — and this payload is a PUBLISHED artifact
+  // that a visitor can fetch. They have no runtime reader (nothing in core, runtime
+  // or kit reads a `config.$*` key), so this removes noise for four of them and a
+  // real disclosure for the fifth: `$secrets` carries no values, but its entries
+  // name every secret the site has, and an inventory of credential names is not
+  // something an `export` should publish.
+  for (const key of Object.keys(runtimeSiteConfig)) {
+    if (key.startsWith('$')) delete runtimeSiteConfig[key]
+  }
 
   return {
     config: {

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/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
 }

package/src/uwx/folder.js

@@ -187,10 +187,17 @@ export function buildFolderEntity({ recordEntities, folderNodes = [], declared,
 
   const missing = []
   const contents = contentsFromNodes(folderNodes, byEntityId, missing)
+  // ⚠️ `id` IS THE ENTITY'S POOL PATH, NOT A FOLDER PATH — say so, because the two
+  // read identically and a reader who takes it for a placement concludes the
+  // emitter is dropping a branch it never had. *(Measured 2026-08-31: the backend
+  // lane read `folder: "articles/outdoor-hygge"` as a placement under an
+  // `articles` branch and opened a channel about a missing branch node; the string
+  // was naming `entities/articles/outdoor-hygge.md`.)*
   const warnings = missing.map(
     (id) =>
-      `folder: "${id}" is placed in records.yml but produced no record entity — ` +
-      `the placement was dropped rather than sent pointing at nothing.`
+      `records.yml: "${id}" — a path under entities/ — is listed, but no record ` +
+      `entity was produced for it (check that its schema resolves). The placement ` +
+      `was dropped rather than sent pointing at nothing.`
   )
 
   const document = {

package/src/uwx/site-project.js

@@ -153,7 +153,6 @@ const INFO_TO_SITE_YML = {
   data: 'data',
   template: 'template',
   seo: 'seo',
-  app: 'app', // deployment's @uniweb/app-spec ref (bare uuid; deployment-local)
 }
 
 /**
@@ -208,6 +207,32 @@ export function siteInfoToConfig({ document, siteRoot, sourceLocale = LOCALIZED_
     : []
   if (extensions.length > 0) siteChanges.extensions = extensions
 
+  // services[] → site.yml::$services · secrets[] → site.yml::$secrets.
+  //
+  // ⭐ The `$` prefix, and not the bare name, for the reason spelled out in
+  // `uwx/site.js`: `site.yml::services` already means "pretend a host offers these"
+  // on the bundle lane, and one key cannot mean two things.
+  //
+  // ⭐ `$id` is DROPPED — it is derived (a service's `name`; a secret's
+  // `service:name` pair), so writing it back would put a redundant handle in the
+  // author's file and invite them to edit the one field that must not drift from
+  // the fields it is derived from. Same call as `extensions` above.
+  //
+  // ⛔ Everything else rides VERBATIM, `config` included: it is opaque, per-service
+  // and will grow, so projecting a known subset would quietly drop whatever the
+  // service gained since this line was written — and the next push would then send
+  // the truncated version back as authoritative.
+  //
+  // ⚠️ An EMPTY section is written as an empty list, not skipped. `[]` is a real
+  // state — "this site has no service rows" — and it is the state a `pull` must be
+  // able to deliver after the last one was removed. Skipping would leave a stale
+  // `$services` on disk that the next push would resurrect.
+  for (const [section, ymlKey] of [['services', '$services'], ['secrets', '$secrets']]) {
+    const records = document?.[section]
+    if (!Array.isArray(records)) continue
+    siteChanges[ymlKey] = records.map(({ $id: _id, ...fields }) => fields)
+  }
+
   const result = { siteConfig: writeSiteConfig(siteRoot, siteChanges) }
 
   // theme (whole object) → theme.yml.

package/src/uwx/site.js

@@ -809,6 +809,121 @@ function queriesNested(declarations, uuids = null) {
   return out
 }
 
+// ── `services` + `secrets` — a site's own service records ─────────────────────
+//
+// ⭐ THE FILE KEYS ARE `$services` / `$secrets`, NOT `services` / `secrets`, and the
+// `$` is load-bearing rather than decorative. `site.yml::services` is ALREADY TAKEN,
+// on the other lane: the bundle lane spreads site.yml whole into the payload, so a
+// `services:` block there lands at `config.services` — the HOST tier — which is the
+// documented way to simulate a host locally (`kit/src/utils/submitTarget.js`).
+// Reusing the name would give one key two meanings that differ per lane, which is
+// the shape of bug nobody finds.
+//
+// `$` already means "backend-scoped, round-tripped, not hand-authored" in this file
+// (`$uuid`, `$org`, `$backend`), and that is exactly what these are: a service's
+// config is bound where the service is provisioned, and arrives here by `pull`.
+//
+// ⚖️ WHAT THESE ARE NOT. A site's OWN service declarations — `search:`, `submit:`,
+// `assistant:`, `tracking:` — stay top-level `info.*` keys and are untouched. Those
+// are authored, they resolve at the SITE tier (`config.<name>`, first choice in
+// `@uniweb/core`'s `resolveService`), and moving them here would flip them to the
+// host tier, where a block's mere presence declines every service it does not name.
+// These Sections carry the services a site is PROVISIONED with — `api` above all,
+// which has no file-authored form because it is bought, not declared.
+//
+// ⛔ ABSENT IS NOT EMPTY, and the difference is destructive. The Section is
+// REPLACED by what we send, so `[]` means "drop every stored config row" while a
+// missing key means "I am not telling you about this". A project that has never
+// pulled has no `$services`, and its ordinary push must not read as a request to
+// wipe a service the operator configured in the app. So: emit the Section only when
+// the file declares the key. Clearing is available and explicit — `$services: []`.
+//
+// ⚠️ The push gate is NOT what makes this safe, though it usually catches it: its
+// tokens live in a gitignored per-clone cache, so a fresh clone pushes
+// unconditionally. Correctness has to sit here.
+
+/**
+ * `$services` / `$secrets` → Section records, or undefined when the key is absent.
+ *
+ * ⭐ PASSTHROUGH, NOT AN ALLOWLIST — the same rule and the same reason as
+ * `queriesNested` above. The field set belongs to the backend's Model, a service's
+ * `config` is opaque and per-service, and reconcile replaces `data` wholesale — so
+ * enumerating keys here would not merely fail to send a field we do not know, it
+ * would DESTROY whatever is stored under it on every push. Framework can enumerate
+ * its own vocabulary and cannot enumerate theirs; withhold ours, forward the rest.
+ *
+ * @param {*} declared - the raw `$services` / `$secrets` value from site.yml
+ * @param {(entry: object) => string|null} identify - the record's stable `$id`
+ * @param {string} label - the key name, for the one warning below
+ * @returns {object[]|undefined}
+ */
+function serviceRecords(declared, identify, label) {
+  if (declared === undefined || declared === null) return undefined
+  if (!Array.isArray(declared)) {
+    console.warn(
+      `uwx/site: \`${label}:\` must be a list of entries — ignoring a ${typeof declared}.`
+    )
+    return undefined
+  }
+  const out = []
+  for (const entry of declared) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue
+    const id = identify(entry)
+    // ⚠️ `name` is OUR OWN declared-required field, so a warning here is honest —
+    // unlike an unrecognized key, which only the server can judge. And the loss is
+    // otherwise invisible: on a replaced Section a dropped entry reads as a
+    // deliberate removal of its config row.
+    if (!id) {
+      console.warn(
+        `uwx/site: \`${label}:\` has an entry with no \`name\` — skipping it. On a replaced ` +
+          'section a dropped entry reads as a deliberate removal of its config.'
+      )
+      continue
+    }
+    const data = {}
+    for (const [key, value] of Object.entries(entry)) {
+      if (value === undefined) continue
+      data[key] = value
+    }
+    out.push(withIdentity(id, data))
+  }
+  return out
+}
+
+/** One service per `name` — the same keyspace `config.services` uses at runtime. */
+function servicesNested(siteYml) {
+  return serviceRecords(
+    siteYml.$services,
+    (e) => (typeof e.name === 'string' && e.name ? e.name : null),
+    '$services'
+  )
+}
+
+/**
+ * One secret per `(service, name)` — the pair the backend merges on. A site-level
+ * secret belongs to no service, so `service` is optional and the handle degrades to
+ * the bare name.
+ *
+ * ⛔ `value` IS FORWARDED VERBATIM, INCLUDING A LITERAL. A pulled secret carries the
+ * marker `#ref` meaning "a secret is set", never the value, and pushing the marker
+ * back means "leave it alone" — so the ordinary round trip sends nothing sensitive.
+ * A literal typed into the file is refused by the server, which is where that
+ * judgement belongs; framework does not strip it, because silently dropping a value
+ * an author typed would leave them believing a secret was set.
+ */
+function secretsNested(siteYml) {
+  return serviceRecords(
+    siteYml.$secrets,
+    (e) => {
+      if (typeof e.name !== 'string' || !e.name) return null
+      return typeof e.service === 'string' && e.service
+        ? `${e.service}:${e.name}`
+        : e.name
+    },
+    '$secrets'
+  )
+}
+
 /**
  * Map a file site project to the nested `@uniweb/site-content` `$`-document
  * (see the lane header above). PURE — reads the project, never mints, never writes.
@@ -957,13 +1072,38 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // secret store is the only right home either way.
 
   setIf(info, 'tracking', stripCredentials(siteYml.tracking, 'tracking'))
+  // ⛔ `api` IS DELIBERATELY NOT HERE, and this note exists because every comment
+  // above it argues the opposite — three services are on this allowlist precisely so
+  // an authored block cannot work on a static host and vanish on the synced one.
+  // Without this paragraph the next reader adds the missing fourth line and calls it
+  // a bug fix.
+  //
+  // ⭐ `api` is the one service a site does not AUTHOR. It is a real backend that is
+  // provisioned and paid for, so its address is the host's to supply — it arrives as
+  // `config.services.api` and `@uniweb/api` reads it there (`resolveBase`). An
+  // authored `api:` is the SITE tier, which outranks the host permanently.
+  //
+  // ⇒ Carrying it would turn a local-dev override into a production one the moment
+  // someone pushed: the host would store `info.api` and serve it back as `config.api`,
+  // which wins over the address of the backend the site actually has. The vanish on
+  // this lane is the correct behaviour, not the bug the comments above describe —
+  // there, a dropped block leaves a site with NO endpoint; here it leaves the site
+  // with the RIGHT one.
+  //
+  // The provisioned record rides the `$services` section instead (see servicesNested).
   setIf(info, 'paths', siteYml.paths)
   setIf(info, 'data', siteYml.data ?? siteYml.fetch)
-  // `app` — the deployment's `@uniweb/app-spec` reference (a bare uuid string),
-  // bound when the site is hosted as a composite. Authored config that round-trips
-  // verbatim/opaque (like `foundation`), so a pull→edit→push preserves it; it is
-  // deployment-LOCAL (not portable across deployments). (uwx-format.md → info.app.)
-  setIf(info, 'app', siteYml.app)
+  // ⛔ `app` IS RETIRED — do not reintroduce it, in either direction. It carried an
+  // opaque uuid naming a separate entity a host bound to the site; that entity is
+  // gone, a site's services belong to the site itself, and NOTHING replaces the key.
+  //
+  // ⚠️ Removing the emit is the FIRST of two steps and the order is forced: a host
+  // refuses a key it does not declare, so the producer stops sending before the
+  // declaration is dropped. The reverse order fails every push in between.
+  //
+  // ✅ Unobservable, because nothing ever originated the key — no template writes
+  // `site.yml::app`. The line round-tripped a value that was never set.
+  // (uwx-format.md → info.app.)
   // `template: true` designates this site as a clonable SITE-TEMPLATE: on push the
   // backend applies a clonability designation to this site-content entity (it is
   // NOT a registry artifact). Verbatim; absent → a normal (non-template) site.
@@ -1017,6 +1157,13 @@ 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)
+  // 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.
+  const services = servicesNested(siteYml)
+  if (services) doc.services = services
+  const secrets = secretsNested(siteYml)
+  if (secrets) doc.secrets = secrets
   return doc
 }