uniweb 0.62.0 → 0.63.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.62.0",
+  "version": "0.63.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/core": "^0.29.8",
-    "@uniweb/schemas": "^0.3.3",
-    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/kit": "^0.19.4",
+    "@uniweb/core": "^0.29.8",
     "@uniweb/runtime": "^0.27.4",
-    "@uniweb/content-writer": "^0.3.4"
+    "@uniweb/schemas": "^0.3.4",
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependencies": {
+    "@uniweb/build": "^0.59.0",
     "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/build": "^0.58.0"
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -2575,7 +2575,9 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 > 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.
+> 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.
 >
 > 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.
@@ -2630,10 +2632,9 @@ Platform-specific configuration that doesn't belong in npm-standard fields. All
 
 | Field | Where used | Default | Purpose |
 |---|---|---|---|
-| `scope` | `uniweb register` | derived from your login, then saved here | The org the foundation registers under (`@acme`, or `acme`): a bare `main.js` name `marketing` registers as `@acme/marketing`. `--scope @org` overrides it for one run. |
 | `runtimePolicy` | `dist/runtime-pin.json` | unset | Declares how far past the recorded runtime version a host may move a site. |
 
-**The foundation's name is not here — it is `name` in `main.js`** (else `package.json`'s `name`). ⛔ `uniweb.id` is no longer read: `uniweb register` refuses it and prints the `main.js` line to write instead.
+**The foundation's name is not here — it is `name` in `main.js`** (else `package.json`'s `name`), **and so is the org it registers under: the scope is part of the name**, `name: '@acme/marketing'`. A name with no scope has not been registered yet: the first `uniweb register` takes `--scope @org` (else one of your orgs) and writes it into the name, and a `--scope` naming another org than the name's is refused. The foundation's own data schemas register under the same scope (`@/article` → `@acme/article`). ⛔ `uniweb.id` and `uniweb.scope` are no longer read for a foundation: `uniweb register` refuses them and prints the `main.js` line to write instead. (A schemas-only package has no `main.js`, and still records its scope in `uniweb.scope`.)
 
 **Runtime updates — handled for you.** Your foundation's code links against the runtime: it externalizes `react`, `react-dom`, `react-dom/server`, both JSX runtimes and `@uniweb/core`, and the runtime supplies all of them at load time. So a build is bound to *that* React and *that* core API.
 

package/src/backend/client.js

@@ -105,6 +105,141 @@ export function resolveBackendOrigin() {
  */
 export const DISCOVERY_DEFAULTS = {}
 
+/**
+ * The header a request names its WORKSPACE with — the unit it works in.
+ *
+ * ⭐ `@<handle>`, the `@` required: a bare value is read as a unit's uuid — the spelling
+ * for a workspace with no handle — so the two can never be mistaken for each other.
+ * Every `/dev` route accepts it; the client names it on the site routes, the ones that
+ * work in a workspace (`namesWorkspace`). ⛔ It replaced `?as_org=` (2026-09-23), which
+ * only routes that declared it accepted — the rest answered `400`.
+ */
+export const WORKSPACE_HEADER = 'x-uniweb-workspace'
+
+/**
+ * Whether a request works IN a workspace — a site route, `/dev/site…`.
+ *
+ * Only those name one. Every `/dev` route accepts the header, but registration reads
+ * none (the `@scope` in the name decides, membership-gated), `/dev/assets` reads none
+ * (a charge lands on the entity's own workspace), and auth, orgs and config are about
+ * the account. Naming the site's workspace there would be harmless and meaningless —
+ * and a workspace that is refused (`400`/`403`) would then fail a registration that
+ * never involved it.
+ *
+ * @param {string} path - leading-slash path
+ * @returns {boolean}
+ */
+export function namesWorkspace(path) {
+  return /^\/dev\/site(\/|$)/.test(String(path))
+}
+
+/**
+ * A workspace as it may be written — `@acme`, `acme`, `@acme/…` — as the header's
+ * `@acme`; null for none (the personal workspace, which a request names by omission).
+ *
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function workspaceHandle(value) {
+  const h =
+    typeof value === 'string' ? value.trim().replace(/^@/, '').replace(/\/.*$/, '') : ''
+  return h ? `@${h}` : null
+}
+
+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 the header names it — `@handle`, or a unit's bare uuid when the unit
+ * has no handle — or null for none.
+ *
+ * ⚠️ 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.
+ *
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function workspaceHeader(value) {
+  if (typeof value !== 'string' || !value.trim()) return null
+  const v = value.trim()
+  return !v.startsWith('@') && UNIT_UUID.test(v) ? v : workspaceHandle(v)
+}
+
+/**
+ * The request named its workspace EXPLICITLY — `--org`, `--personal`, a choice made at
+ * create — and the backend works on the site from another.
+ *
+ * ⛔ 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.
+ */
+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)
+   */
+  constructor({ named, answer }) {
+    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}.`)
+    )
+    this.name = 'WorkspaceMismatchError'
+    this.status = 409
+    this.named = named
+    this.answer = answer
+  }
+}
+
+/**
+ * The line to print when a request THREW rather than answered.
+ *
+ * A `WorkspaceMismatchError` is the backend's answer, not a transport failure, so it is
+ * printed as itself: "Could not reach the backend" in front of it would send the user
+ * to check their network over a choice they made on the command line.
+ *
+ * @param {unknown} err
+ * @param {string} origin
+ * @returns {string}
+ */
+export function describeRequestError(err, origin) {
+  if (err instanceof WorkspaceMismatchError) return err.message
+  return `Could not reach the backend at ${origin}: ${err?.message ?? err}`
+}
+
+/**
+ * The sentence a refusal carries — a problem document's `detail`, else its `title`, else
+ * the start of a prose body — or null. Consumes the body. For the surfaces that would
+ * otherwise print a status line alone, so a refusal the backend explains is shown as it
+ * is: a deployment with one workspace answers a request naming another with a plain
+ * `409 Conflict` whose `detail` names the one there is.
+ *
+ * @param {Response} res
+ * @returns {Promise<string|null>}
+ */
+export async function refusalDetail(res) {
+  let body = ''
+  try {
+    body = await res.text()
+  } catch {
+    return null
+  }
+  try {
+    const problem = JSON.parse(body)
+    const line = problem?.detail || problem?.title
+    return typeof line === 'string' && line ? line : null
+  } catch {
+    return body ? body.slice(0, 300) : null
+  }
+}
+
 export class BackendClient {
   /**
    * @param {object} [opts]
@@ -134,6 +269,35 @@ export class BackendClient {
     this._command = command
     this._fetch = fetchImpl || ((url, init) => globalThis.fetch(url, init))
     this._discovery = null
+    this._workspace = null
+    this._workspaceExplicit = false
+    this._onWorkspaceAdopted = null
+  }
+
+  /** The workspace this client's requests name — `@handle`, or null (none named). */
+  get workspace() {
+    return this._workspace
+  }
+
+  /**
+   * Name the workspace every request from here on works in (`x-uniweb-workspace`).
+   *
+   * @param {string|null} value - `@acme` / `acme`, a handle-less unit's uuid, or null to
+   *   name none (`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
+   * @returns {this}
+   */
+  setWorkspace(value, { explicit = false, onAdopted = null } = {}) {
+    this._workspace = workspaceHeader(value)
+    this._workspaceExplicit = Boolean(explicit)
+    this._onWorkspaceAdopted = onAdopted || null
+    return this
   }
 
   /**
@@ -168,7 +332,9 @@ 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, …).
+   * 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).
    *
    * @param {string} path - leading-slash path, e.g. '/dev/site/content'
    * @param {object} [opts]
@@ -179,10 +345,41 @@ export class BackendClient {
    * @param {boolean} [opts.auth=true]
    * @returns {Promise<Response>}
    */
-  async request(
-    path,
-    { method = 'GET', body, headers = {}, query, auth = true } = {}
-  ) {
+  async request(path, opts = {}) {
+    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.
+    // ⛔ 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
+    if (problem?.reason !== 'wrong_workspace') return res
+    const where = problem.workspace || {}
+    // A unit with no handle is named by its uuid, bare — the header takes either.
+    const answer = where.handle
+      ? workspaceHandle(where.handle)
+      : 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.
+    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)
+  }
+
+  /** One request, as `request` documents it — naming the client's workspace on a site route. */
+  async _send(path, { method = 'GET', body, headers = {}, query, auth = true } = {}) {
     const url = new URL(path, this.origin)
     if (query) {
       for (const [k, v] of Object.entries(query)) {
@@ -191,6 +388,7 @@ export class BackendClient {
     }
     const h = { ...headers }
     if (auth) h.Authorization = `Bearer ${await this.token()}`
+    if (this._workspace && namesWorkspace(path)) h[WORKSPACE_HEADER] = this._workspace
     if (body != null && h['Content-Type'] == null) {
       if (typeof body === 'string') h['Content-Type'] = 'application/json'
       else if (body instanceof Uint8Array || Buffer.isBuffer(body))
@@ -405,10 +603,13 @@ export class BackendClient {
    * design). Callers must guard on the site's uuid for this backend (sync.json) and
    * write the result back immediately — see `ensureSiteExists`.
    *
-   * @param {{ name: string, foundation: string, asOrg?: string|null }} opts
+   * The owner is the workspace the client names (`setWorkspace`) — the create is where
+   * that choice is made, once.
+   *
+   * @param {{ name: string, foundation: string }} opts
    * @returns {Promise<Response>} `{ site_content_uuid }`
    */
-  async createSite({ name, foundation, asOrg } = {}) {
+  async createSite({ name, foundation } = {}) {
     return this.request('/dev/site', {
       method: 'POST',
       // Both fields are REQUIRED: `info.name` is `required: true` on the model
@@ -417,35 +618,34 @@ export class BackendClient {
       // render), and a site must resolve to a foundation. Adoption of the ref is
       // best-effort on the backend, but the field itself cannot be blank — so send
       // whatever the site declares and let the backend judge it.
-      body: JSON.stringify({ name, foundation }),
-      query: { as_org: asOrg }
+      body: JSON.stringify({ name, foundation })
     })
   }
 
   /** POST /dev/site/content — CREATE a site from its content lane (.uwx zip). */
-  async createSiteContent(buffer, { asOrg } = {}) {
+  async createSiteContent(buffer) {
     return this.request('/dev/site/content', {
       method: 'POST',
       body: buffer,
-      query: pushQuery(asOrg)
+      query: PUSH_QUERY
     })
   }
 
   /** POST /dev/site/content/push/{uuid} — UPDATE the content lane by site uuid (.uwx zip). */
-  async updateSiteContent(uuid, buffer, { asOrg } = {}) {
+  async updateSiteContent(uuid, buffer) {
     return this.request(`/dev/site/content/push/${encodeURIComponent(uuid)}`, {
       method: 'POST',
       body: buffer,
-      query: pushQuery(asOrg)
+      query: PUSH_QUERY
     })
   }
 
   /** POST /dev/site/folder/push/{uuid} — push the folder lane, keyed by the site uuid (.uwx zip). */
-  async pushFolder(uuid, buffer, { asOrg } = {}) {
+  async pushFolder(uuid, buffer) {
     return this.request(`/dev/site/folder/push/${encodeURIComponent(uuid)}`, {
       method: 'POST',
       body: buffer,
-      query: pushQuery(asOrg)
+      query: PUSH_QUERY
     })
   }
 
@@ -565,8 +765,17 @@ export class BackendClient {
       const res = await this.request(
         `/dev/site/status/${encodeURIComponent(uuid)}`
       )
+      if (res.status === 409) {
+        // A refusal about the workspace — e.g. a deployment with one workspace, naming
+        // it — is an answer to report, not an absent status.
+        const refused = new Error((await refusalDetail(res)) || 'HTTP 409 Conflict')
+        refused.status = 409
+        throw refused
+      }
       return res.ok ? await res.json().catch(() => null) : null
-    } catch {
+    } catch (err) {
+      // A mismatch or a refusal is an answer, not an absent status.
+      if (err instanceof WorkspaceMismatchError || err?.status === 409) throw err
       return null
     }
   }
@@ -596,7 +805,9 @@ export function dataSchemaPath(modelName) {
   return `/dev/registry/data-schemas/${encodeURIComponent(modelName)}`
 }
 
-/** The shared push query: last-push-wins, plus an optional acting-org. */
-function pushQuery(asOrg) {
-  return { collision: 'force', ...(asOrg ? { as_org: asOrg } : {}) }
-}
+/**
+ * The shared push query: last-push-wins. ⛔ No `as_org` — the workspace rides the
+ * `x-uniweb-workspace` header on every site request (`BackendClient.setWorkspace`),
+ * since 2026-09-23.
+ */
+const PUSH_QUERY = { collision: 'force' }

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

@@ -44,7 +44,6 @@ import {
 } from '@uniweb/build'
 import { computeFoundationDigest } from '../utils/code-upload.js'
 import { isNonInteractive } from '../utils/interactive.js'
-import { publishScope } from '../utils/registry-orgs.js'
 import { compareSemverPrecedence } from '../utils/semver-precedence.js'
 
 /**
@@ -119,18 +118,20 @@ export function resolveLocalExtensions(siteDir, siteYml) {
 /**
  * The foundation's scoped catalog name (`@org/name`): its name — `main.js`'s
  * `name`, else package.json's, the one rule the build reads for the schema
- * `register` submits (`readFoundationName`) — scoped by `uniweb.scope` unless
- * already scoped. Null when no registrable scoped name can be formed; the caller
+ * `register` submits (`readFoundationName`). ⭐ The scope is part of that name
+ * (2026-09-22), so a scoped name IS the catalog name. Null otherwise; the caller
  * then treats the foundation as unreleased, and `register` — which it runs to
- * release — is where a missing scope is derived and a missing name is asked for.
+ * release — is where a missing scope is chosen and written into the name, and a
+ * missing name is asked for.
  *
  * ⛔ A NAME THAT CANNOT REGISTER IS NULL, not looked up. `src` and `foundation`
  * name a folder (`checkFoundationName`); looking one up would find some other
  * project's `@org/src` — the very collision refusing them prevents.
  *
- * ⛔ And the scope goes through `publishScope`, as `register`'s does: `uniweb.scope`
- * may read `acme` as well as `@acme`, and until 2026-09-21 this joined it raw — so a
- * bare one looked the foundation up as `acme/src` and pinned the site to that.
+ * ⛔ A BARE NAME IS NULL too: it has not registered, since `register` writes the scope
+ * it registers under into the name. Until 2026-09-22 this joined a bare name with
+ * `package.json::uniweb.scope`; that key is refused now (`readFoundationName` throws,
+ * so a leftover reads as unreleased here and `register` says what to write instead).
  * *(This read package.json alone until 2026-09-21 — `uniweb.id`, else `name` — and
  * so named a foundation differently from the build whenever `main.js` named it.)*
  *
@@ -145,9 +146,7 @@ export async function foundationScopedName(dir) {
     return null
   }
   if (checkFoundationName(name)) return null
-  if (name.startsWith('@')) return name
-  const scope = publishScope(readPkgField(dir, 'uniweb')?.scope)
-  return scope ? `${scope}/${name}` : null
+  return name.startsWith('@') ? name : null
 }
 
 function readPkgField(dir, field) {
@@ -303,9 +302,9 @@ async function bringLocalCodeAlong({
     // exists to avoid.
     //
     // ⚠️ It is null for a foundation that has NEVER been registered and carries no
-    // scope (a fresh scaffold), because the scope is what `register` writes back
-    // (`writePkgScope`) — and for one with no name of its own (`src`), which
-    // `register` asks for. So the preview shows the authored value there, and the
+    // scope (a fresh scaffold), because the scope is what `register` writes into its
+    // name (`settleFoundationScope`) — and for one with no name of its own (`src`),
+    // which `register` asks for. So the preview shows the authored value there, and the
     // first real push — which releases, and so acquires both — sends the pinned ref
     // instead. That gap is unavoidable offline: before the first release there is
     // no registered name to name.