uniweb 0.64.1 → 0.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.64.1",
+  "version": "0.66.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,17 +41,17 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
+    "@uniweb/kit": "^0.19.4",
     "@uniweb/runtime": "^0.27.4",
-    "@uniweb/schemas": "^0.4.0",
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/schemas": "^0.5.0",
     "@uniweb/core": "^0.29.8",
-    "@uniweb/kit": "^0.19.4",
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/content-writer": "^0.3.4"
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependencies": {
-    "@uniweb/semantic-parser": "^1.4.1",
     "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/build": "^0.59.1"
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/build": "^0.60.0"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

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:`), `ref`/`options`, and rich `sections`-form inputs are reported deferred.
 
 ### Fetching from other sources (`fetcher:`)
 
@@ -2527,9 +2527,9 @@ uniweb add ci --target foundation # Publish a foundation for free at permanent v
 
 uniweb push / pull / clone / status   # Git-style content sync with the Uniweb backend
 uniweb refresh / sync                 # Catch up (git + backend, never pushes) / catch up, then push
-uniweb push --org @acme               # First push/publish of a site: who owns it (see below)
+uniweb login --org @acme              # The workspace you work in — new sites are created there (see below)
 uniweb register [--scope @scope]      # Register a foundation + its data schemas to the registry
-uniweb login / logout                 # One backend at a time: log in (--backend <url>) or out
+uniweb login / logout                 # One backend, one workspace at a time: log in (--backend, --org) or out
 uniweb org list / create <handle>     # Your personal scope, and the orgs you belong to
 uniweb content export [dir]           # Package a site (or a built foundation's schema) as .uwx
 
@@ -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)
@@ -2573,24 +2573,24 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 
 **Content authors work visually in the Uniweb App.** They compose the same extended markdown and set the same component params you defined, through a visual editor — never touching code, git, or the CLI. They see exactly the section types your foundation offers and exactly the knobs each one exposes, because **every `meta.js` is registered as the foundation's schema** when you publish. Your `meta.js` is the app's UI (see *meta.js* in Part 4).
 
-> ⚠️ **The FIRST push or publish of a site asks who owns it — and refuses if it cannot ask.**
-> That create decides which organization owns the site (and whose storage its assets are billed
-> to), it is the only moment the choice is made, and there is no CLI command to change it
-> afterwards. At a terminal you get a picker. **Without a terminal — CI, a script, or you, an
-> agent — the command exits non-zero instead of choosing**, and `--yes` refuses too, because
-> guessing an owner is not an answer. Name it and it never asks again:
+> ⚠️ **Every push, pull and publish works in ONE workspace — the one chosen at `uniweb login`.**
+> A workspace is your personal one or an organization's. A site a push or publish **creates** is
+> created — owned, and its storage billed — there, and there is no CLI command to move it
+> afterwards. A site the backend keeps in **another** workspace stops the command, which says how
+> to switch. With no organization, the login works in your personal workspace; with
+> organizations, the login asks, or you name it:
 >
 > ```bash
-> uniweb publish --org @acme     # an organization
-> uniweb publish --personal      # your personal account, deliberately
+> uniweb login --org @acme      # work in an organization
+> uniweb login --personal       # work in your personal workspace
+> uniweb push --org @acme       # this command only
 > ```
 >
-> The answer is recorded in `sync.json` and committed, so it is a one-time choice per site,
-> not per machine. **Ask the human which one to use** rather than picking for them — a site in
-> the wrong org cannot be moved from here. Sites that already exist are unaffected: their
-> ownership is settled, so nothing is asked. After the create, every command names the
-> recorded org for you; an `--org` that disagrees with where the backend keeps the site
-> **stops the command** rather than acting in another org.
+> Already logged in, `uniweb login --org @other` switches without logging in again. **Without a
+> terminal — you, an agent — a login with organizations refuses until one is named**, and so
+> does a command when none was. A process logged in with `UNIWEB_TOKEN` names its workspace with
+> `UNIWEB_WORKSPACE=@acme` (or `personal`). **Ask the human which workspace to use** rather than
+> picking for them — a site created in the wrong one cannot be moved from here.
 >
 > Relatedly: these commands now **reject flags they do not recognize** instead of ignoring them.
 > If you get `Unknown flag`, read the suggestion — it is usually a near miss.
@@ -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). 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/client.js

@@ -148,6 +148,15 @@ export function workspaceHandle(value) {
 
 const UNIT_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
+/**
+ * A workspace as a sentence names it: `@acme`, `the unit <uuid>`, or `your personal
+ * workspace` — for null, and for a login's stored `personal`.
+ */
+export function describeWorkspace(workspace) {
+  if (!workspace || workspace === 'personal') return 'your personal workspace'
+  return workspace.startsWith('@') ? workspace : `the unit ${workspace}`
+}
+
 /**
  * A workspace as the header names it — `@handle`, or a unit's bare uuid when the unit
  * has no handle — or null for none.
@@ -155,7 +164,7 @@ const UNIT_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}
  * ⚠️ A bare value is taken for a uuid only when it is shaped like one, and our own
  * handle grammar admits uuid-shaped handles (3–39 lowercase letters, digits, hyphens).
  * So a HANDLE reaches this already dressed — `--org` through `workspaceHandle`, a
- * record through `readSiteWorkspace` — and a bare uuid here is a unit.
+ * login's choice as stored — and a bare uuid here is a unit.
  *
  * @param {unknown} value
  * @returns {string|null}
@@ -167,34 +176,45 @@ export function workspaceHeader(value) {
 }
 
 /**
- * The request named its workspace EXPLICITLY — `--org`, `--personal`, a choice made at
- * create — and the backend works on the site from another.
+ * The site is in another workspace than the one this command works in.
  *
- * ⛔ Stopping is the point. It is the mismatch check [Diego, 2026-09-22: "there is no org
- * mismatch when the site is set for an org and the user tries a different one"], and it
- * is the backend's `409` that decides it, never a handle comparison here: a site in
- * `@acme/labs` is legitimately worked on from `@acme`. Adopting the answer would override
- * a choice the user made.
+ * ⛔ **Stopping is the point, and nothing is adopted.** A command works in ONE workspace —
+ * the one chosen with the login (`workspace.js`) — and a site outside it is refused, not
+ * worked on anyway *[Diego, 2026-09-23: "that's the intent of the workspace concept"]*.
+ * It is the backend's `409` that decides it, never a handle comparison here: a site in
+ * `@acme/labs` is legitimately worked on from `@acme`. ⚠️ *Until 2026-09-23 a workspace
+ * nobody had named was adopted from the `409` and the request retried.*
  */
 export class WorkspaceMismatchError extends Error {
   /**
-   * @param {{ named: string|null, answer: string|null }} p - the workspace the request
-   *   named, and the one the backend named (`@handle`, null for personal)
+   * @param {{ named: string|null, answer: string|null, source?: string }} p - the
+   *   workspace the request named and the one the backend named (`@handle`, a unit's
+   *   uuid, null for personal), and where the named one came from (`workspace.js`)
    */
-  constructor({ named, answer }) {
+  constructor({ named, answer, source = 'login' }) {
     const where = (w) =>
       !w ? 'your personal workspace' : w.startsWith('@') ? w : `the unit ${w}`
-    const flag = named ? '--org' : '--personal'
-    super(
-      `The backend works on this site from ${where(answer)}, not ${where(named)} ` +
-        `(${named ? `--org ${named}` : flag}). ` +
-        // `--org` takes a handle; a unit without one is reached by naming nothing.
-        (answer?.startsWith('@') ? `Pass --org ${answer}, or drop ${flag}.` : `Drop ${flag}.`)
-    )
+    // How to work in the site's workspace, said for the way this one was chosen.
+    const switchTo = !answer
+      ? { flag: 'pass --personal', env: 'set UNIWEB_WORKSPACE=personal' }
+      : answer.startsWith('@')
+        ? { flag: `pass --org ${answer}`, env: `set UNIWEB_WORKSPACE=${answer}` }
+        : null
+    const login = !answer ? 'uniweb login --personal' : answer.startsWith('@') ? `uniweb login --org ${answer}` : null
+    const fix = !switchTo
+      ? 'It has no handle, so the CLI cannot work in it.'
+      : source === 'flag'
+        ? `To work on it, ${switchTo.flag}.`
+        : source === 'env'
+          ? `To work on it, ${switchTo.env}.`
+          : `To work on it: ${login}`
+    const why = source === 'flag' ? ' (named on this command)' : source === 'env' ? ' (UNIWEB_WORKSPACE)' : ''
+    super(`This site is in ${where(answer)}, and you are working in ${where(named)}${why}. ${fix}`)
     this.name = 'WorkspaceMismatchError'
     this.status = 409
     this.named = named
     this.answer = answer
+    this.source = source
   }
 }
 
@@ -270,8 +290,7 @@ export class BackendClient {
     this._fetch = fetchImpl || ((url, init) => globalThis.fetch(url, init))
     this._discovery = null
     this._workspace = null
-    this._workspaceExplicit = false
-    this._onWorkspaceAdopted = null
+    this._workspaceSource = 'login'
   }
 
   /** The workspace this client's requests name — `@handle`, or null (none named). */
@@ -280,23 +299,19 @@ export class BackendClient {
   }
 
   /**
-   * Name the workspace every request from here on works in (`x-uniweb-workspace`).
+   * Name the workspace every site request from here on works in (`x-uniweb-workspace`)
+   * — the one `resolveWorkspace` answered for this command.
    *
-   * @param {string|null} value - `@acme` / `acme`, a handle-less unit's uuid, or null to
-   *   name none (`workspaceHeader`)
+   * @param {string|null} value - `@acme` / `acme`, a handle-less unit's uuid, or null for
+   *   the personal workspace (`workspaceHeader`)
    * @param {object} [opts]
-   * @param {boolean} [opts.explicit=false] - the user named it (`--org`, `--personal`,
-   *   the create picker). A `409 wrong_workspace` then STOPS the command
-   *   (`WorkspaceMismatchError`) instead of adopting the backend's answer.
-   * @param {(handle: string|null) => void|Promise<void>} [opts.onAdopted] - called when a
-   *   request that named nothing, or a stale workspace, adopts the one the backend named;
-   *   the caller records it (sync.json) and says so
+   * @param {string} [opts.source='login'] - where it came from (`workspace.js`), so a
+   *   refusal says how to switch
    * @returns {this}
    */
-  setWorkspace(value, { explicit = false, onAdopted = null } = {}) {
+  setWorkspace(value, { source = 'login' } = {}) {
     this._workspace = workspaceHeader(value)
-    this._workspaceExplicit = Boolean(explicit)
-    this._onWorkspaceAdopted = onAdopted || null
+    this._workspaceSource = source
     return this
   }
 
@@ -332,9 +347,8 @@ export class BackendClient {
    * applies query params, and infers a content-type from the body when unset
    * (string → application/json, Buffer/Uint8Array → application/zip). Returns
    * the raw Response so callers branch on status themselves (409 resume,
-   * 404 → null, 401/403 messaging, …) — except a `409 wrong_workspace`, which is
-   * answered here: adopted and retried once when the workspace was not named, and
-   * thrown as `WorkspaceMismatchError` when it was (see the body).
+   * 404 → null, 401/403 messaging, …) — except a `409 wrong_workspace`, thrown as
+   * `WorkspaceMismatchError`: the site is in another workspace than this command's.
    *
    * @param {string} path - leading-slash path, e.g. '/dev/site/content'
    * @param {object} [opts]
@@ -349,13 +363,10 @@ export class BackendClient {
     const res = await this._send(path, opts)
     if (res?.status !== 409) return res
 
-    // ⭐ THE WORKSPACE A REQUEST NAMES IS CHECKED BY THE BACKEND, NOT HERE. A request that
-    // names the wrong one for an existing site is refused with `409 wrong_workspace`,
-    // naming a workspace the caller CAN open that contains the site — its own unit, or a
-    // parent the caller belongs to. Two answers, and which one depends on the user:
-    //   - they named it (`--org`, `--personal`) → stop and say so: the mismatch check;
-    //   - they named nothing, or a stale one → adopt the backend's answer, let the caller
-    //     record it, and retry ONCE.
+    // ⭐ THE WORKSPACE A REQUEST NAMES IS CHECKED BY THE BACKEND, NOT HERE. A request whose
+    // workspace does not contain the site is refused with `409 wrong_workspace`, naming a
+    // workspace the caller CAN open that does — the site's own unit, or a parent. The
+    // command works in one workspace, so this stops it (`WorkspaceMismatchError`).
     // ⛔ No handle comparison anywhere: a site in `@acme/labs` is worked on from `@acme`.
     const problem =
       typeof res.clone === 'function' ? await res.clone().json().catch(() => null) : null
@@ -367,15 +378,14 @@ export class BackendClient {
       : typeof where.unit_uuid === 'string' && where.unit_uuid
         ? where.unit_uuid
         : null
-    // Naming what the backend names and still refused: nothing to adopt, or to report
-    // as a mismatch. The caller reads the 409 like any other.
+    // Refused while naming what the backend names: nothing to switch to; the caller reads
+    // the 409 like any other.
     if (answer === this._workspace) return res
-    if (this._workspaceExplicit) {
-      throw new WorkspaceMismatchError({ named: this._workspace, answer })
-    }
-    this._workspace = answer
-    if (this._onWorkspaceAdopted) await this._onWorkspaceAdopted(answer)
-    return this._send(path, opts)
+    throw new WorkspaceMismatchError({
+      named: this._workspace,
+      answer,
+      source: this._workspaceSource
+    })
   }
 
   /** One request, as `request` documents it — naming the client's workspace on a site route. */
@@ -571,7 +581,7 @@ export class BackendClient {
 
   /** GET /dev/orgs → { account_handle, orgs[] }. */
   async fetchOrgs() {
-    return fetchOrgsImpl({ apiBase: this.origin, token: await this.token() })
+    return fetchOrgsImpl({ apiBase: this.origin, token: await this.token(), fetchImpl: this._fetch })
   }
 
   /** POST /dev/orgs { handle } → { handle, uuid, is_primary }. Throws with the server's detail on 409/422. */