uniweb 0.65.0 → 0.67.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.65.0",
+  "version": "0.67.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -44,12 +44,12 @@
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/core": "^0.29.8",
     "@uniweb/kit": "^0.19.4",
+    "@uniweb/schemas": "^0.6.0",
     "@uniweb/runtime": "^0.27.4",
-    "@uniweb/schemas": "^0.4.0",
     "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.59.1",
+    "@uniweb/build": "^0.61.0",
     "@uniweb/content-reader": "^1.2.5",
     "@uniweb/semantic-parser": "^1.4.1"
   },

package/partials/agents.md

@@ -1870,7 +1870,7 @@ fetch:
 
 **Component-side fetching.** When a component genuinely needs to fetch on its own (a search box, "load more", a lazy popover), use the kit hooks — `useFetched`, `useCacheEntry`, `useWholeRecord`. They share the framework's cache and dispatcher with declarative fetches; same-key requests dedupe automatically.
 
-**Validate before shipping.** `uniweb validate` checks file-based data against your declared schemas — missing required fields, type/enum/format mismatches, nested fields. Warns by default; `--strict` for a non-zero CI exit. Distinct from `uniweb doctor` (project structure): `validate` checks your *data* against the schemas you *declared*. External queries (`url:`), `ref`/`options`, and rich `sections`-form inputs are reported deferred.
+**Validate before shipping.** `uniweb validate` checks file-based data against your declared schemas — missing required fields, type/enum/format mismatches, nested fields. A violation fails it (`--lax` only reports); it checks every record file in `records/`, and `push` / `publish` refuse the same findings before sending anything. Distinct from `uniweb doctor` (project structure): `validate` checks your *data* against the schemas you *declared*. External queries (`url:`) are reported as deferred — their data isn't in the project; the value of a `ref`/`options` field is not checked against the entity it names.
 
 ### Fetching from other sources (`fetcher:`)
 
@@ -2539,7 +2539,7 @@ uniweb i18n init-freeform / update-hash / move / rename / prune --freeform
 
 uniweb -v                         # Installed CLI version — and whether a newer one exists
 uniweb doctor                     # Diagnose project configuration (--fix to auto-repair)
-uniweb validate                   # Check file-based data against declared schemas (--strict for CI)
+uniweb validate                   # Check file-based data against declared schemas (fails on a violation; --lax)
 npx uniweb@latest update          # Align @uniweb/* deps + AGENTS.md (--dry-run, --yes)
                                   #   bare `uniweb update` aligns to the CLI you ALREADY have
 uniweb inspect <path>             # Show parsed content for a section or page (--raw for the AST)
@@ -2609,7 +2609,7 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 
 Either side can publish. Nothing about this changes how you build: the same foundation and the same site run under `uniweb dev`, `uniweb export`, or a CI deploy with no account at all.
 
-**Publishing vs registering.** Foundations on Uniweb Cloud live in the catalog as `@org/name@version` — `name` from the foundation's `main.js`. When a foundation powers a single site, **don't run `uniweb register` yourself** — `uniweb publish` from the site directory releases the local foundation to the catalog (when its code changed) and goes live in one step. Register deliberately only when the foundation is a product meant for multiple sites; consuming sites then pin `foundation: '@org/name@1.2.3'`. **The catalog is private and access-segregated, not a public package registry** — people see only the foundations licensed to sites they own or edit. The *site* carries the license, and it rides along with site ownership when a developer hands a site to a client. Don't describe publishing as making a foundation publicly discoverable. Schemas can also be registered on their own from a schemas-only package (`@uniweb/schemas`, any `@org/schemas`, or a bare folder of `schemas/*.{yml,json,js}`) — that's how `@std` schemas are published. Auth via `uniweb login` (`uniweb login --backend <url> --token <bearer>` without a terminal) or `UNIWEB_TOKEN`; preview with `--dry-run`.
+**Publishing vs registering.** Foundations on Uniweb Cloud live in the catalog as `@org/name@version` — `name` from the foundation's `main.js`. When a foundation powers a single site, **don't run `uniweb register` yourself** — `uniweb publish` from the site directory releases the local foundation to the catalog (when its code changed) and goes live in one step. A registered version is immutable, so when the foundation's code changed under a version already registered, `push` and `publish` release the change under the next version and write it into the foundation's `package.json` — commit that file (`--no-release` sends the content without the code). The version it picks is always the next patch: for a change that is not backwards compatible, set a higher minor or major version in the foundation's `package.json` yourself before you push. They stop when the registry holds a version newer than yours, released from another copy: pull that change first, or pass `--bump` to release yours above it. Register deliberately only when the foundation is a product meant for multiple sites; consuming sites then pin `foundation: '@org/name@1.2.3'`. **The catalog is private and access-segregated, not a public package registry** — people see only the foundations licensed to sites they own or edit. The *site* carries the license, and it rides along with site ownership when a developer hands a site to a client. Don't describe publishing as making a foundation publicly discoverable. Schemas can also be registered on their own from a schemas-only package (`@uniweb/schemas`, any `@org/schemas`, or a bare folder of `schemas/*.{yml,json,js}`) — that's how `@std` schemas are published. Auth via `uniweb login` (`uniweb login --backend <url> --token <bearer>` without a terminal) or `UNIWEB_TOKEN`; preview with `--dry-run`.
 
 ### Staying current
 

package/src/backend/foundation-bring-along.js

@@ -5,11 +5,30 @@
  * A publish must never ship a site pointing at stale or missing foundation code
  * (the footgun: a site goes live referencing a version the catalog doesn't
  * have). So when the site references a LOCAL foundation, the verb fingerprints it
- * and reconciles with the catalog. Three cases (§4):
+ * and reconciles with the catalog (§4):
  *
- *   | version not yet registered    | release it, then publish        |
- *   | registered, code unchanged    | skip the release (digest match) |
- *   | registered, code CHANGED      | warn / prompt — never silent    |
+ *   | version not yet registered      | release it                            |
+ *   | registered, code unchanged      | skip the release (digest match)       |
+ *   | registered, code CHANGED        | release it under the next version     |
+ *   | a NEWER version is registered   | stop — `--bump` releases above it     |
+ *
+ * ⭐ **Changed code is released by default** *[Diego, 2026-09-24]*. A site whose project
+ * holds its own foundation is a content+code bundle — *"a developer is used to code
+ * going with the site, so they don't think of bumping the code of a site"* — and the
+ * version there decides nothing: the only site reading it is the one being pushed.
+ * Since a registered version is immutable, the change goes under the next version
+ * above the registered one, written into the package's `package.json` first. ⛔ This
+ * reverses the version-bump release gate of 2026-06-23, whose reasoning — a deliberate,
+ * npm-style release — fits a foundation other sites use as a product; those sites pin
+ * a catalog ref and never reach this code. Its author's demo site, which names it by
+ * path, does — and gets the same default, by ruling [Diego, 2026-09-24]. The release is
+ * always the next patch, so a change that is not backwards compatible needs a higher
+ * version set in `package.json` by hand.
+ *
+ * ⛔ **A NEWER registered version still stops it.** It was released from another copy
+ * of the project, whose code this one may not have, and releasing above it would make
+ * the older code the newest — the code twin of push's content staleness gate. `--bump`
+ * releases above it anyway; `--no-release` ships the content bound to it.
  *
  * The freshness signal is the backend-stored, framework-computed digest (§4.1):
  * no local state, multi-machine-safe. When the site references a published
@@ -44,7 +63,11 @@ import {
 } from '@uniweb/build'
 import { computeFoundationDigest } from '../utils/code-upload.js'
 import { isNonInteractive } from '../utils/interactive.js'
-import { compareSemverPrecedence } from '../utils/semver-precedence.js'
+import { writeJsonPreservingStyle } from '../utils/json-file.js'
+import {
+  compareSemverPrecedence,
+  nextVersionAbove
+} from '../utils/semver-precedence.js'
 
 /**
  * Resolve the site's LOCAL foundation — the one publish should bring along — or
@@ -160,6 +183,14 @@ function readPkgField(dir, field) {
   }
 }
 
+// Set the package's version, changing nothing else in the file — its key order,
+// indentation and trailing newline stay as they were, so the diff is one line.
+function writePkgVersion(dir, version) {
+  const path = join(dir, 'package.json')
+  const src = readFileSync(path, 'utf8')
+  writeJsonPreservingStyle(path, { ...JSON.parse(src), version }, src)
+}
+
 // What travels to the spawned `uniweb register` / `build` on the command line: only
 // --non-interactive. The BACKEND travels in the child's environment
 // (releaseFoundation), and the SESSION is the shared session file — or UNIWEB_TOKEN,
@@ -232,7 +263,9 @@ export async function bringFoundationAlong({
  * @param {object} o
  * @param {{dir: string, version: string|null}} o.local
  * @param {'foundation'|'extension'} o.kind
- * @returns {Promise<{ released: boolean, proceed: boolean, ref: string|null }>}
+ * @returns {Promise<{ released: boolean, proceed: boolean, ref: string|null, bumped?: string }>}
+ *   `bumped` is the version written into package.json when changed code was released
+ *   under the next version.
  */
 async function bringLocalCodeAlong({
   client,
@@ -271,6 +304,19 @@ async function bringLocalCodeAlong({
   // says (see the `!reg` branch).
   const noRelease = args.includes('--no-release')
 
+  // `--bump`: when the registry holds a version NEWER than the local one, release the
+  // local code above it instead of stopping. That is all it does — changed code under
+  // the registered version is released without it, and unchanged code never is — so a
+  // script can pass it on every run.
+  const bump = args.includes('--bump')
+
+  if (bump && noRelease) {
+    say.err(
+      '`--bump` releases your local changes and `--no-release` ships without them — pass one of the two.'
+    )
+    return { released: false, proceed: false, refused: true, ref: null }
+  }
+
   // The pinned ref to stamp on the pushed site — read at RETURN time (after any
   // release), so it reflects the released version, the scope register derived and
   // the name it asked for. null when no scoped ref can be formed (then the site.yml
@@ -336,6 +382,36 @@ async function bringLocalCodeAlong({
     }
   }
 
+  // The next version above the registered one — what changed code is released under
+  // when the local version is taken. Null when the registered version is not SemVer,
+  // and then there is nothing to count up from.
+  const bumpTo = nextVersionAbove(reg.latest_version)
+
+  // Write it into package.json, then release. `register` rebuilds on its own when the
+  // built schema's version no longer matches package.json, so the release carries it.
+  // `optOut` names `--no-release` for a release nobody asked for by flag.
+  //
+  // ⚖️ A failed release leaves the new version in the file, and that is the useful
+  // state: the next run finds a local version above the registered one and releases
+  // it, with nothing to redo.
+  const releaseAsNext = async (why, { optOut = false } = {}) => {
+    if (!bumpTo) {
+      say.err(
+        `Cannot release ${label} under a new version: the registered ${reg.latest_version} is not a SemVer version.`
+      )
+      say.dim(
+        `Nothing was sent. Set a version above it in the ${kind}'s package.json, then re-run \`uniweb ${verb}\`; or \`uniweb ${verb} --no-release\` sends content bound to the released ${reg.latest_version}.`
+      )
+      return { released: false, proceed: false, refused: true, ref: null }
+    }
+    writePkgVersion(local.dir, bumpTo)
+    say.info(`Releasing the ${kind} ${scopedName || kind} as ${bumpTo} — ${why}…`)
+    const released = releaseFoundation(local, args, cliBin, say, client?.origin)
+    say.dim(`The ${kind}'s package.json now says ${bumpTo} — commit it.`)
+    if (optOut) say.dim('To send content without releasing code, pass `--no-release`.')
+    return { released, proceed: true, bumped: bumpTo, ref: await pinnedRef() }
+  }
+
   // Registered — fingerprint the local build and compare. Build first so the
   // digest reflects current source (idempotent: a no-op when already fresh).
   buildFoundation(local, cliBin)
@@ -348,38 +424,70 @@ async function bringLocalCodeAlong({
     return { released: false, proceed: true, ref: await pinnedRef() }
   }
 
-  // A different version locally → a new version to release.
+  // A different version locally.
   if (local.version && local.version !== reg.latest_version) {
-    if (noRelease) {
-      // ⚠️ Bind to the REGISTERED version, not the local one. `pinnedRef()` would
-      // return the bumped-but-unreleased `local.version` here — a ref no deployment
-      // can serve, which is the very failure this flag must not create.
+    const order = compareSemverPrecedence(local.version, reg.latest_version)
+    // Equal in precedence (build metadata apart) is the registered version itself, and
+    // is treated as it, below.
+    if (order !== 0) {
+      if (noRelease) {
+        // ⚠️ Bind to the REGISTERED version, not the local one. `pinnedRef()` would
+        // return the bumped-but-unreleased `local.version` here — a ref no deployment
+        // can serve, which is the very failure this flag must not create.
+        say.info(
+          `Keeping the released ${kind} ${reg.latest_version} — local ${local.version} not released (\`--no-release\`).`
+        )
+        return { released: false, proceed: true, ref: registeredRef(reg) }
+      }
+
+      // ⛔ OLDER than the registered latest: that version was released from another
+      // copy of the project, and this one may not have its code. Releasing above it
+      // would make this code the newest and bind the site to it — a teammate's release
+      // undone by a push that never saw it. So it stops, and names the ways on.
+      //
+      // Until 2026-09-24 it was submitted, the registry deciding: it took a version it
+      // already held with this very code (a resume), and refused anything else. Only
+      // the latest version's digest is readable, and the digest folds in the version,
+      // so "this code, under an older version" cannot be told apart from here.
+      if (order === -1) {
+        if (bump) {
+          say.warn(
+            `The registry holds ${reg.latest_version}, newer than your ${label} — releasing your code above it (\`--bump\`). If ${reg.latest_version} is someone else's release, its changes are not in yours.`
+          )
+          return releaseAsNext(`above the registered ${reg.latest_version}`)
+        }
+        say.err(
+          `The registry holds ${kind} ${scopedName || kind} ${reg.latest_version}, newer than your ${local.version} — a release this copy does not have.`
+        )
+        say.dim(
+          `Nothing was sent. Pull the change that released it, then re-run \`uniweb ${verb}\`; or:`
+        )
+        if (bumpTo) {
+          say.dim(`  • \`uniweb ${verb} --bump\` — releases your code as ${bumpTo}, above it`)
+        }
+        say.dim(
+          `  • \`uniweb ${verb} --no-release\` — sends content bound to the released ${reg.latest_version}`
+        )
+        return { released: false, proceed: false, refused: true, ref: null }
+      }
+
+      // Newer than anything registered — a new version, released as it stands. Not
+      // SemVer (`order === null`) — nothing to compare, so the same, and the registry
+      // decides; `register` prints its answer if it is a no.
       say.info(
-        `Keeping the released ${kind} ${reg.latest_version} — local ${local.version} not released (\`--no-release\`).`
+        order === 1
+          ? `Releasing the ${kind} ${label} (new version; registered latest is ${reg.latest_version})…`
+          : `Releasing the ${kind} ${label} (registered latest is ${reg.latest_version})…`
       )
-      return { released: false, proceed: true, ref: registeredRef(reg) }
-    }
-    // ⚖️ The registry takes a NEW version only when it is greater than every one
-    // it holds — but an older local version may be one it already has, and
-    // re-registering that resumes. The CLI cannot tell which from here, so it
-    // does not refuse: it submits, says what will decide, and `register` prints
-    // the registry's answer if it is a no.
-    const order = compareSemverPrecedence(local.version, reg.latest_version)
-    say.info(
-      order === 1
-        ? `Releasing the ${kind} ${label} (new version; registered latest is ${reg.latest_version})…`
-        : order === null
-          ? `Releasing the ${kind} ${label} (registered latest is ${reg.latest_version})…`
-          : `Releasing the ${kind} ${label} — not newer than the registered latest ${reg.latest_version}, so the registry takes it only if ${local.version} is already registered with this code…`
-    )
-    return {
-      released: releaseFoundation(local, args, cliBin, say, client?.origin),
-      proceed: true,
-      ref: await pinnedRef()
+      return {
+        released: releaseFoundation(local, args, cliBin, say, client?.origin),
+        proceed: true,
+        ref: await pinnedRef()
+      }
     }
   }
 
-  // Same version, but the digest differs or the backend can't confirm it.
+  // The registered version — but the digest differs, or the backend can't confirm it.
   if (!reg.digest) {
     // Degrade: the backend doesn't return the stored digest yet, so we can't
     // be sure the registered version matches local. Offer to re-deliver.
@@ -393,8 +501,10 @@ async function bringLocalCodeAlong({
       `Can't verify the registered ${label} matches your local copy (backend returned no digest).`
     )
     if (skipPrompts || isNonInteractive(args)) {
+      // ⚖️ Not released: nothing says the code changed, and releasing on no evidence
+      // would mint a version on every push against such a backend.
       say.dim(
-        'Proceeding without re-releasing — pass nothing to re-deliver, or bump the version to release a change.'
+        `Proceeding without re-releasing — to release a change, set a higher version in the ${kind}'s package.json.`
       )
       return { released: false, proceed: true, ref: await pinnedRef() }
     }
@@ -411,10 +521,8 @@ async function bringLocalCodeAlong({
     return { released: false, proceed: true, ref: await pinnedRef() }
   }
 
-  // Case 3 (§4): the code was edited but the version wasn't bumped. The
-  // registered version is immutable, so we never silently ship the old code —
-  // the deliberate release gate is a version bump (§3.1).
-  // Asked for explicitly: the case this flag exists to name.
+  // The code changed and the version did not. A registered version is immutable, so
+  // the change is released under the next one.
   if (noRelease) {
     say.info(
       `Keeping the released ${kind} ${reg.latest_version} — your local changes are not released (\`--no-release\`).`
@@ -422,67 +530,17 @@ async function bringLocalCodeAlong({
     return { released: false, proceed: true, ref: registeredRef(reg) }
   }
 
-  // ⭐ THREE OUTCOMES, NOT TWO — `--yes` and "no TTY" are not the same answer.
+  // ⭐ RELEASED BY DEFAULT — for a person and an agent alike, with no question.
   //
-  // They were one condition until 2026-08-19, and conflating them meant the only
-  // party that never got asked was the one that most needed asking. A `--yes` is a
-  // decision someone made in advance; an absent TTY is the ABSENCE of a decision,
-  // and absence is not consent.
-  //
-  // ⚖️ Which flips the safe default by caller, for a reason particular to this
-  // situation: proceeding here ships a site bound to code that is NOT the code in
-  // the working tree. A human is at a terminal, reads the warning, and decides. An
-  // agent re-runs commands for free and reports "pushed" on exit 0 — so for it the
-  // cheap outcome is one more cycle and the expensive one is a silent wrong success
-  // it will not look at again. Refusing costs an agent a retry; proceeding costs it
-  // a false completion report and a live site nobody notices is stale.
-
-  // 1. Explicit consent — proceed, but at WARN. `dim` is what we print for things
-  //    nobody needs to read, and "your changes are not live" is not that.
-  if (skipPrompts) {
-    say.warn(
-      `Local ${label} differs from the registered ${reg.latest_version} and the version wasn't bumped — ` +
-        `shipping against the registered code. Your local changes will NOT be live.`
-    )
-    return { released: false, proceed: true, ref: await pinnedRef() }
-  }
-
-  // 2. Nobody to ask. Refuse, and name both real options as runnable commands so
-  //    the caller's next step needs no interpretation. `refused` marks this as a
-  //    hard stop rather than a human's "no", which callers map to different exits.
-  if (isNonInteractive(args)) {
-    say.err(
-      `Local ${kind} ${label} differs from the registered ${reg.latest_version}, and the version wasn't bumped.`
-    )
-    say.dim(`Nothing was sent. Either release the change, or ship without it:`)
-    say.dim(`  • bump the ${kind}'s version in package.json, then re-run \`uniweb ${verb}\``)
-    // Teach the flag that NAMES this, not `--yes`. Both work, but `--yes` means "do
-    // not ask me" and only does this as a side effect — pointing a stuck user at it
-    // teaches a blunt instrument for a precise job.
-    say.dim(
-      `  • \`uniweb ${verb} --no-release\` — sends content bound to the released ${reg.latest_version}`
-    )
-    return { released: false, proceed: false, refused: true, ref: null }
-  }
-
-  // 3. A human is here. State it, then ask.
-  say.warn(
-    `Your local ${label} differs from the registered version ${reg.latest_version}, but the version wasn't bumped.`
-  )
-  say.dim(
-    `A registered version is immutable — bump the ${kind}'s version to release the change.`
-  )
-  const proceed = await confirm(
-    `Continue with the already-registered ${reg.latest_version} anyway?`,
-    false
-  )
-  if (!proceed) {
-    say.info(
-      `Aborted — nothing was sent. Bump the ${kind} version, then re-run \`uniweb ${verb}\`.`
-    )
-    return { released: false, proceed: false, ref: null }
-  }
-  return { released: false, proceed: true, ref: await pinnedRef() }
+  // Until 2026-09-24 this stopped: a terminal was asked, a run without one refused, and
+  // `--yes` shipped the REGISTERED code. That guarded against a site bound to code that
+  // was not the working tree's — which is exactly what releasing prevents: the site is
+  // bound to the code just released, as it is to the content pushed with it. `--yes`
+  // has nothing left to consent to here, and a question whose answer is nearly always
+  // yes teaches people to stop reading it.
+  return releaseAsNext(`its code changed since ${reg.latest_version} was registered`, {
+    optOut: true
+  })
 }
 
 // Build the foundation so its dist/ can be fingerprinted. Idempotent — the