@uniweb/build 0.25.1 → 0.25.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.25.1",
+  "version": "0.25.3",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,17 +59,17 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/schemas": "^0.2.10",
+    "@uniweb/semantic-parser": "^1.3.0",
     "@uniweb/theming": "^0.1.15",
-    "@uniweb/projections": "^0.3.4",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/semantic-parser": "^1.3.0"
+    "@uniweb/projections": "^0.3.4",
+    "@uniweb/schemas": "^0.2.10"
   },
   "optionalDependencies": {
     "@uniweb/semantic-parser": "^1.3.0",
+    "@uniweb/content-reader": "^1.2.4",
     "@uniweb/schemas": "^0.2.10",
-    "@uniweb/runtime": "^0.12.9",
-    "@uniweb/content-reader": "^1.2.4"
+    "@uniweb/runtime": "^0.12.9"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -78,7 +78,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.11.2"
+    "@uniweb/core": "^0.11.3"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/schema.js

@@ -156,6 +156,24 @@ const DEFAULT_ONLY_CAPABILITIES = [
  * every `[#id]` rendered as its own literal text — indistinguishable from a
  * foundation that had never opted in. Found only by reading generate-entry.js.
  *
+ * ⚠️ THAT DIAGNOSIS WAS CORRECT AND INCOMPLETE, and the rest took three weeks
+ * to find (2026-08-23). The same commit that moved those keys onto the default
+ * export also added `import … from '@uniweb/kit/xref'`, whose graph reaches
+ * `Ref.jsx`. `loadFoundationConfig` could not parse that, so the config never
+ * loaded at all — the identical symptom, from an unrelated cause, arriving on
+ * the same day the correct fix was applied. The fix looked inert because it
+ * was: where the keys sat could not matter while nothing was read.
+ *
+ * ⛔ AND IT DISABLED THIS WARNING. `warnMisplacedCapabilities` runs AFTER the
+ * import; a config that throws never reaches it. The guard added to catch that
+ * incident was, from that day, unable to fire on the project it was written
+ * for. A check downstream of the thing most likely to fail is not a check.
+ *
+ * To tell the two apart: a misplaced named export loses only that capability.
+ * A config that fails to load loses everything the file declares — `vars`
+ * included, so the site also renders with no theme variables at all. If the
+ * theme is gone too, stop looking at export placement.
+ *
  * A warning rather than an error: a foundation may legitimately export a name
  * that collides for its own use, and failing someone's build over a naming
  * coincidence is worse than telling them what we ignored.

package/src/site/collection-processor.js

@@ -134,12 +134,38 @@ function parseCollectionConfig(name, config) {
 }
 
 /**
- * Parse YAML frontmatter from markdown content
+ * Parse YAML frontmatter from markdown content.
+ *
+ * Two cases, and keeping them apart is the whole point:
+ *
+ *   NO frontmatter — the file does not open with `---`, or never closes the
+ *   block. Legitimate: a record can be pure body. Returns {}.
+ *
+ *   DECLARED frontmatter that does not parse — an error, because every field
+ *   is gone at once. Not just the one with the typo: title, slug, date, image,
+ *   category, all of it. The record still builds, still ships, and lands at a
+ *   filename-derived slug with no title and no cover.
+ *
+ * ⛔ THIS USED TO WARN AND CONTINUE, and the warning could not be found.
+ * Measured 2026-08-24 on a real post: an unquoted colon inside a description
+ * ("...on a website framework: everything hard about docs...") voided six
+ * fields and moved the page from /blog/docs-sites to /blog/11_docs_sites. The
+ * only trace was
+ *
+ *   [collection-processor] YAML parse error: bad indentation of a mapping entry (4:72)
+ *
+ * on line 16 of 857 lines of build output, naming no file, nine lines above
+ * "Processed articles: 6 items" — a success line that reads as everything
+ * being fine. The build exited 0 and the broken record shipped.
+ *
+ * A parse error now names the file and says what it costs, because "which of
+ * my 200 records is (4:72) in?" is the question the old message left you with.
  *
  * @param {string} raw - Raw file content
+ * @param {string} [filepath] - Path to the file, for the error message
  * @returns {{ frontmatter: Object, body: string }}
  */
-function parseFrontmatter(raw) {
+function parseFrontmatter(raw, filepath) {
   if (!raw.trim().startsWith('---')) {
     return { frontmatter: {}, body: raw }
   }
@@ -154,8 +180,18 @@ function parseFrontmatter(raw) {
     const body = parts.slice(2).join('---\n')
     return { frontmatter, body }
   } catch (err) {
-    console.warn('[collection-processor] YAML parse error:', err.message)
-    return { frontmatter: {}, body: raw }
+    const where = filepath ? `${filepath}: ` : ''
+    throw new Error(
+      `${where}frontmatter is not valid YAML — ${err.message}\n` +
+        `  The file opens with \`---\`, so it is declaring frontmatter. Since the block does not\n` +
+        `  parse, EVERY field in it is lost — title, slug, date, image, category — and the record\n` +
+        `  would build as an untitled entry at a slug derived from its filename.\n` +
+        `  A common cause is an unquoted value containing a colon followed by a space:\n` +
+        `    description: Building on a framework: everything hard is a website problem\n` +
+        `  Quote the value and it parses:\n` +
+        `    description: "Building on a framework: everything hard is a website problem"`,
+      { cause: err },
+    )
   }
 }
 
@@ -508,7 +544,7 @@ async function processContentItem(dir, filename, config, siteRoot, basePath) {
   const slug = basename(filename, extname(filename))
 
   // Parse frontmatter and body
-  const { frontmatter, body } = parseFrontmatter(raw)
+  const { frontmatter, body } = parseFrontmatter(raw, filepath)
 
   // Skip unpublished items by default
   if (frontmatter.published === false) {

package/src/site/deploy-config-writer.js

@@ -26,10 +26,31 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { Document, parseDocument, isMap } from 'yaml'
 
+// The header every generated deploy.yml carries. It has to answer the question
+// a reader has while looking AT the file — who wrote this, and may I edit it —
+// because that is where the question gets asked, not in the docs.
+//
+// The previous wording opened "operational config ... edit `targets:` freely",
+// which reads as a file you are expected to author with one auto-managed block
+// inside it. It cost a real reader an afternoon: they went looking for what to
+// write under `targets:` for a site that had never deployed, when the answer is
+// that the first deploy writes it.
 const SCAFFOLD_HEADER = [
-  ' deploy.yml — operational config and last-deploy memory for this site.',
-  ' Safe to commit. The `lastDeploy:` block is auto-managed by `uniweb deploy`;',
-  ' edit `targets:` freely.',
+  ' deploy.yml — written by `uniweb deploy` / `uniweb publish`.',
+  '',
+  ' You do not create this file. The first successful deploy does, recording the',
+  ' target you picked and what happened. Later deploys rewrite only `lastDeploy:`',
+  ' and leave the rest — including your comments — alone.',
+  '',
+  ' Safe to commit; no credentials live here. Host credentials come from the',
+  ' environment.',
+  '',
+  '   default:     which target is used when none is named',
+  '   targets:     where this site ships. Edit to change the destination, or add',
+  '                a target and pick it with `--target <name>`',
+  '   autoSave:    `lastDeploy` to keep the record below, `off` to stop writing it',
+  '   lastDeploy:  what the last deploy did. A record, not a setting — nothing',
+  '                reads it back, so a stale one is safe to delete',
 ].join('\n')
 
 /**

package/src/uwx/index.js

@@ -44,6 +44,7 @@ export {
   emitSiteSyncPackage,
   writeSiteEntityUuid,
   writeSiteOrg,
+  writeSiteBackend,
   extensionDeclaration,
   isExtensionUrl,
   isSiteRelativeExtensionUrl,

package/src/uwx/site.js

@@ -947,3 +947,42 @@ export function writeSiteEntityUuid(siteRoot, uuid) {
 export function writeSiteOrg(siteRoot, handle) {
   return upsertYamlScalar(join(siteRoot, 'site.yml'), '$org', handle)
 }
+
+/**
+ * Record the backend this project SYNCS WITH (`site.yml::$backend`), beside `$uuid`/`$org`.
+ *
+ * ⭐ It is not a tag on the site uuid — it is the project's **sync scope**. Four surfaces
+ * hold backend-minted identity, and this one fact is what makes all of them meaningful:
+ * `site.yml::$uuid`, every collection record's `$uuid` in its own source file,
+ * `assets.json`, and `.uniweb/sync-cache.json`. Change the backend and every one of them
+ * is foreign at once — which is why a mismatch is a stop, not a fallback
+ * (`assertSiteBackendScope` in the CLI).
+ *
+ * ⛔ **Written ONLY for a non-default backend.** The 98% case stays out of the file, and an
+ * absent value reads as the default — correct both for a project written before this key
+ * existed and for one synced against the default. Callers decide; this writer does not know
+ * the CLI's default. See `recordSiteBackend` (cli/src/backend/site-sync.js), which is where
+ * the "is it the default?" test lives.
+ *
+ * ⚠️ **The name is load-bearing. Five alternatives were considered and rejected (2026-08-24);
+ * do not re-propose one.** `origin` is wrong twice over — a site HAS an origin (its own
+ * served domain), and this lane is git-modeled, where `origin` names a remote rather than a
+ * URL. `remote` implies a multiplicity this design closes. `hosting` and `platform` name the
+ * hosting edge, which this package has no client for. `host` collides with
+ * `deploy.yml::targets.<n>.host` (the deploy adapter). A `uuid: <id>@<backend>` suffix was
+ * rejected too: it would make "this never reaches the backend" a discipline at every read
+ * site instead of a property, and `siteProjectToDocument` assigns `$uuid` straight onto the
+ * wire document.
+ *
+ * Safe as a plain YAML scalar: a URL's `:` is followed by `/` or a digit, never a space, so
+ * it needs no quoting (verified against js-yaml for apex, `localhost:8080` and host:port+path
+ * forms, 2026-08-24). This is the same class of hazard as `$org`'s leading `@`, which is
+ * stripped for exactly that reason — but it lands on the safe side.
+ *
+ * @param {string} siteRoot
+ * @param {string} origin - a bare origin, no trailing slash
+ * @returns {boolean} true if site.yml changed
+ */
+export function writeSiteBackend(siteRoot, origin) {
+  return upsertYamlScalar(join(siteRoot, 'site.yml'), '$backend', origin)
+}