uniweb 1.6.2 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,14 +42,14 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/content-writer": "~1.1.2",
-    "@uniweb/schemas": "~1.3.0",
     "@uniweb/core": "~1.2.2",
+    "@uniweb/schemas": "~1.3.0",
     "@uniweb/semantic-parser": "~1.8.1"
   },
   "peerDependencies": {
-    "@uniweb/content-reader": "~1.3.3",
-    "@uniweb/semantic-parser": "~1.8.1",
-    "@uniweb/build": "~1.3.4"
+    "@uniweb/build": "~1.3.5",
+    "@uniweb/content-reader": "~1.4.0",
+    "@uniweb/semantic-parser": "~1.8.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -572,6 +572,8 @@ Content is markdown. Components decide how it renders, so a tag written in it
 
 The one exception is `<br/>`, a line break where markdown has no other spelling — inside a heading. For a headline split across lines, the multi-line heading above usually says it better.
 
+A plain newline inside a paragraph is a space, so wrap prose however you like — re-wrapping a paragraph changes nothing, and pushes nothing. A line break in a paragraph is written on purpose: a backslash (`\`) at the end of the line.
+
 ### Fenced code: data blocks vs snippets
 
 Fenced code serves three purposes depending on its info string: `yaml:`/`json:` for data, `md:` for a named kind of prose (see *Concept blocks*), and a bare language for a code sample.

package/src/backend/client.js

@@ -192,12 +192,14 @@ export function workspaceHeader(value) {
  */
 export class WorkspaceMismatchError extends Error {
   /**
-   * @param {{ named: string|null, answer: string|null, source?: string, origin?: string|null }} p -
+   * @param {{ named: string|null, answer: string|null, nowhere?: boolean, source?: string, origin?: string|null, message?: string|null }} p -
    *   the workspace the request named and the one the backend named (`@handle`, a unit's
    *   uuid, null for personal), where the named one came from (`workspace.js`), and the
-   *   backend — a login that switches must name it unless it is the default (`loginCommand`)
+   *   backend — a login that switches must name it unless it is the default (`loginCommand`).
+   *   `nowhere`: the backend named NO workspace the caller may open (`workspace: null`), so
+   *   there is nothing to switch to. `message` replaces the sentence (`WorkspaceRefusedError`).
    */
-  constructor({ named, answer, source = 'login', origin = null }) {
+  constructor({ named, answer, nowhere = false, source = 'login', origin = null, message = null }) {
     const where = (w) =>
       !w ? 'your personal workspace' : w.startsWith('@') ? w : `the unit ${w}`
     // How to work in the site's workspace, said for the way this one was chosen.
@@ -219,15 +221,64 @@ export class WorkspaceMismatchError extends Error {
           ? `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}`)
+    super(
+      message ??
+        (nowhere
+          ? `This site is not in a workspace you can open${origin ? ` on ${origin}` : ''}, so it cannot be worked on from here — there is none to switch to.`
+          : `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.nowhere = nowhere
     this.source = source
   }
 }
 
+/**
+ * The workspace this command named is not one it may open — `403`, `op: "act_as_unit"`.
+ *
+ * ⭐ The header admits exactly the workspaces the account may open: an organization it is a
+ * direct member of, and not an archived one — its own members included [backend, 2026-10-16].
+ * So a login whose workspace was archived after it was chosen hears this on every site
+ * request. ⛔ It is not a refused credential, and "log in again" is the wrong advice for it:
+ * the session is fine, the workspace is not.
+ *
+ * ⭐ Keyed on `op`, never on `title`, which is the `"Forbidden"` every denial shares; and only for
+ * a request that named a workspace, the one kind that can answer it [backend, 2026-10-16].
+ *
+ * A kind of `WorkspaceMismatchError` because every caller treats the two alike — the command
+ * stops and says how to choose — except `siteState`: a refused workspace says nothing about the
+ * site, so it is `unknown` there, never `live`.
+ */
+export class WorkspaceRefusedError extends WorkspaceMismatchError {
+  /**
+   * @param {{ named: string, source?: string, origin?: string|null }} p - the workspace the
+   *   request named (`@handle`, or a unit's uuid), where it came from (`workspace.js`), the backend
+   */
+  constructor({ named, source = 'login', origin = null }) {
+    const where = named.startsWith('@') ? named : `the unit ${named}`
+    const on = origin ? ` on ${origin}` : ''
+    const why = source === 'flag' ? ' (named on this command)' : source === 'env' ? ' (UNIWEB_WORKSPACE)' : ''
+    const fix =
+      source === 'flag'
+        ? 'Name one you can open, or pass --personal.'
+        : source === 'env'
+          ? 'Set UNIWEB_WORKSPACE to one you can open, or to personal.'
+          : `Your login works in it. Choose another: ${loginCommand(origin)} --org @<org> (or --personal) — it does not sign you in again.`
+    super({
+      named,
+      answer: null,
+      source,
+      origin,
+      message: `${where}${why} is not a workspace you can open${on}: you are not a member of it, or it is archived. ${fix}`
+    })
+    this.name = 'WorkspaceRefusedError'
+    this.status = 403
+  }
+}
+
 /**
  * The backend could not be reached at all — the request never got an answer.
  *
@@ -329,6 +380,11 @@ export class BackendClient {
     return this._workspace
   }
 
+  /** Where that workspace came from (`workspace.js`) — so a refusal says how to switch. */
+  get workspaceSource() {
+    return this._workspaceSource
+  }
+
   /**
    * Name the workspace every site request from here on works in (`x-uniweb-workspace`)
    * — the one `resolveWorkspace` answered for this command.
@@ -383,7 +439,9 @@ export class BackendClient {
    * (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`, thrown as
-   * `WorkspaceMismatchError`: the site is in another workspace than this command's.
+   * `WorkspaceMismatchError`: the site is in another workspace than this command's, or in
+   * none the caller may open; and a `403` refusing the workspace this request named, thrown
+   * as `WorkspaceRefusedError`.
    *
    * @param {string} path - leading-slash path, e.g. '/dev/site/content'
    * @param {object} [opts]
@@ -396,16 +454,43 @@ export class BackendClient {
    */
   async request(path, opts = {}) {
     const res = await this._send(path, opts)
-    if (res?.status !== 409) return res
+    if (res?.status !== 409 && res?.status !== 403) return res
+    const problem =
+      typeof res.clone === 'function' ? await res.clone().json().catch(() => null) : null
+
+    // ⭐ THE WORKSPACE THIS REQUEST NAMED IS NOT ONE THE ACCOUNT MAY OPEN — `403`,
+    // `op: "act_as_unit"`: not a member of it, or it is archived (`WorkspaceRefusedError`).
+    // Only for a request that named one: any other 403 — a credential, a foundation the site
+    // may not take — is the caller's, as before.
+    if (res.status === 403) {
+      if (problem?.op !== 'act_as_unit' || !this._workspace || !namesWorkspace(path)) return res
+      throw new WorkspaceRefusedError({
+        named: this._workspace,
+        source: this._workspaceSource,
+        origin: this.origin
+      })
+    }
 
     // ⭐ 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
     if (problem?.reason !== 'wrong_workspace') return res
+    // ⭐ `workspace: null` — NO workspace the caller may open holds the site — is not the
+    // personal workspace, which is the object with both fields null (backend, 2026-10-16). There
+    // is nothing to switch to, so it stops the command whatever workspace it works in.
+    // ⛔ Until 2026-10-16 it was read as personal, and the command said "To work on it: uniweb
+    // login --personal" — false, and following it ended on the same 409.
+    if (problem.workspace === null) {
+      throw new WorkspaceMismatchError({
+        named: this._workspace,
+        answer: null,
+        nowhere: true,
+        source: this._workspaceSource,
+        origin: this.origin
+      })
+    }
     const where = problem.workspace || {}
     // A unit with no handle is named by its uuid, bare — the header takes either.
     const answer = where.handle
@@ -885,23 +970,30 @@ export class BackendClient {
    * the first. Folding `unknown` into `gone` would be worse than no answer.
    *
    *   live     the site's status came back, or the site was refused as belonging to
-   *            another workspace (`409 wrong_workspace` names where it is: it exists)
+   *            another workspace (`409 wrong_workspace` names where it is: it exists) —
+   *            or to none the caller may open (`workspace: null`: it exists too)
    *   gone     a `404` naming this site
-   *   unknown  anything else — no answer, a credential or an id refused, a `404` that
-   *            names something else (a backend too old for the route)
+   *   unknown  anything else — no answer, a credential or an id refused, the workspace
+   *            this request named refused (`refused: true`), a `404` that names something
+   *            else (a backend too old for the route)
    *
    * *Measured 2026-10-06 against a local backend — its wire, its to change:* `200` with
    * the status; `409 wrong_workspace` naming the site's workspace; `404 {kind: "site",
    * key}`; `400` for a malformed id; `401` for a bad bearer.
    *
    * @param {string} uuid
-   * @returns {Promise<{ state: 'live'|'gone'|'unknown', status: number|null, site?: object, workspace?: string|null, detail?: string|null }>}
+   * @returns {Promise<{ state: 'live'|'gone'|'unknown', status: number|null, site?: object, workspace?: string|null, refused?: boolean, detail?: string|null }>}
    */
   async siteState(uuid) {
     let res
     try {
       res = await this.request(`/dev/site/status/${encodeURIComponent(uuid)}`)
     } catch (err) {
+      // The workspace this request named was refused: that says nothing about the site.
+      if (err instanceof WorkspaceRefusedError) {
+        return { state: 'unknown', status: 403, refused: true, detail: err.message }
+      }
+      // In another workspace, or in none the caller may open: either way it exists.
       if (err instanceof WorkspaceMismatchError) {
         return { state: 'live', status: 409, workspace: err.answer, detail: err.message }
       }

package/src/backend/site-sync.js

@@ -855,13 +855,18 @@ export function writeSyncCache(siteDir, backend, hashes, applied) {
  * Lives beside the content hashes because it is the same kind of thing — "the
  * backend state this clone last agreed with" — and is already per-entity, which
  * the per-lane `pull-cache.json` (two ETags) is not. Gitignored, per-clone,
- * deletable: losing it means the next push is unconditional, i.e. today's
- * behavior, never a wrong-but-plausible token.
+ * deletable: losing it leaves the next write no base to claim, which a pull
+ * resolves — never a wrong-but-plausible token.
  *
  * Fed from BOTH directions, which is what makes the gate usable: `pull` records
- * the manifest's `extra.version`, and every successful push records the
- * post-write `finalized[].version` the backend returns. Without the push half a
- * second consecutive push would be stale by construction and refused.
+ * each manifest entry's top-level `version` (`readPullVersions`), and every
+ * successful push records the post-write `finalized[].version` the backend returns.
+ * Without the push half a second consecutive push would be stale by construction
+ * and refused.
+ *
+ * ⛔ Until 2026-10-16 this said `pull` records the manifest's `extra.version`. There is
+ * no `extra` on the wire in either direction — the token rides beside `sha256` — and
+ * building against that name disarms the gate without an error.
  */
 export function readBaseVersions(siteDir, backend) {
   return readMap(siteDir, backend, 'baseVersions')

package/src/commands/publish.js

@@ -8,9 +8,15 @@
  *
  *   1. resolves WHICH site (your location, or the workspace's one site; multiple
  *      → prompt);
- *   2. BRINGS THE FOUNDATION ALONG — if the site's local foundation changed
- *      since its last release, releases the new version first (or asks); a
- *      published registry ref needs nothing (§4, foundation-bring-along.js);
+ *   2. BRINGS THE FOUNDATION ALONG — a local foundation is released when its
+ *      version is not registered yet, and under the next patch (written into its
+ *      package.json) when its code changed since that version was registered;
+ *      unchanged code is not re-released, and a newer registered version stops
+ *      the publish (`--bump`, `--no-release`). It asks only when the backend
+ *      cannot say whether the code changed. A published registry ref needs
+ *      nothing (§4, foundation-bring-along.js). *(This read "releases the new
+ *      version first (or asks)" until 2026-10-16; changed code has been released
+ *      without asking since 2026-09-24.)*
  *   3. SYNCS — builds the site data (link mode), uploads media and the
  *      schema-less data files, and pushes content (the same two-lane sync
  *      `uniweb push` uses);
@@ -752,6 +758,7 @@ export async function publish(args = []) {
       siteUuid: site.uuid,
       // The plan and every direct PUT name the workspace the rest of the publish did.
       workspace: client.workspace,
+      workspaceSource: client.workspaceSource,
       ball,
       onProgress: (m) => say.dim(`  ${m}`)
     })
@@ -766,6 +773,11 @@ export async function publish(args = []) {
     }
     say.dim(`Record data     : ${r.uploaded.length} file(s) [${r.mode}]`)
   } catch (err) {
+    // The workspace this publish works in, refused — said as itself, as at every other door.
+    if (err instanceof WorkspaceMismatchError) {
+      say.err(err.message)
+      return { exitCode: 1 }
+    }
     // A typed plan refusal gets its own account (quota, or whatever else the
     // backend names); anything else falls through to the raw message. Same
     // treatment the asset plan and the site create already get — this was the

package/src/commands/pull.js

@@ -653,8 +653,10 @@ async function confirm(question) {
 }
 
 export async function pull(args = [], deps = {}) {
-  // See utils/flag-guard.js — an unrecognized flag is invisible to a
-  // literal scan, so it silently keeps the default (production, for --backend).
+  // See utils/flag-guard.js — an unrecognized flag is invisible to a literal scan, so
+  // it silently keeps the default: a mistyped `--dry-run` would pull for real, and a
+  // mistyped `--no-delete` would prune. *(This named `--backend` until 2026-10-16;
+  // pull has taken no backend flag since 2026-09-21.)*
   const badFlag = checkFlags('pull', args)
   if (badFlag) {
     error(badFlag.message)
@@ -690,7 +692,7 @@ export async function pull(args = [], deps = {}) {
     if (captured === null) {
       error('Cannot merge: this site is not in a git repository.')
       note(
-        'The common ancestor a merge needs is the committed version of each file.'
+        'The common ancestor a merge needs is in git history: the version of each file your last pull wrote.'
       )
       note(
         'Without a repo there is nothing to merge against — use `uniweb pull --force` to take the backend version.'

package/src/commands/push.js

@@ -133,7 +133,10 @@ function flagValue(args, name) {
 
 export async function push(args = [], deps = {}) {
   // An unrecognized flag is invisible to a literal scan, so it silently keeps the
-  // default — including for --backend, where the default can be production.
+  // default — a mistyped `--dry-run` would push for real. A backend flag or `--token`
+  // is refused too, naming `uniweb login` (`utils/flag-guard.js`). *(This named
+  // `--backend` as the example until 2026-10-16; push has taken no backend flag since
+  // 2026-09-21.)*
   //
   // `sync` validates the UNION of its two halves' flags and forwards raw argv, so a
   // legal `uniweb sync --no-git` would be rejected here. It passes `skipFlagCheck`.

package/src/commands/refresh.js

@@ -17,10 +17,17 @@
  * which is the whole point of a start-of-day command. A version that also pushed
  * would be one you had to think about first, and so one people would stop running.
  *
- * Order is deliberate: git first, then the backend. The three-way merge's common
- * ancestor is the COMMITTED version of each file, so taking teammates' commits
- * first makes that ancestor fresher and the merge more accurate. And if git itself
- * conflicts, refresh stops there — one source of conflict at a time.
+ * Order is deliberate: git first, then the backend. Teammates' commits are then in
+ * the files when the backend's content arrives, and `pull --merge` merges a
+ * teammate's change to a file the last pull wrote just as it merges your own edits:
+ * against the version that pull wrote, found in the repo's history (`pull.js`,
+ * `captureLocalWork`). And if git itself conflicts, refresh stops there — one source
+ * of conflict at a time.
+ *
+ * ⛔ Until 2026-10-16 this said the merge's ancestor was the COMMITTED version of each
+ * file, so taking teammates' commits first made it fresher. That was HEAD — the rule
+ * `pull --merge` dropped on 2026-09-23, because HEAD stops being the version a pull
+ * wrote the moment an edit is committed on top of it.
  *
  * Exits NON-ZERO when a merge left conflicts, the way a conflicted `git merge`
  * does. That is what makes `uniweb refresh && uniweb push` correct by
@@ -91,10 +98,11 @@ function siteContentUuid(siteDir, backend) {
  */
 export async function refresh(args = [], deps = {}) {
   // An unrecognized flag is invisible to a literal scan, so it silently keeps the
-  // default — and for `--backend` the default can be production. This verb never
-  // sent data anywhere, which is why it went unguarded; but it DELEGATES to `pull`,
-  // and a mistyped `--backend` is not forwarded, so the pull runs against whatever
-  // the origin ladder resolves instead of the backend the user named.
+  // default — a mistyped `--no-git` would still pull from the git remote. And this is
+  // the only check refresh's argv gets: the pull it runs is handed `--merge` alone
+  // (below). A backend flag or `--token` is refused here too, naming `uniweb login`
+  // (`utils/flag-guard.js`). *(This explained the check by a mistyped `--backend`
+  // until 2026-10-16; the verb has taken no backend flag since 2026-09-21.)*
   //
   // `sync` validates the UNION of both halves and forwards raw argv, so a legal
   // `uniweb sync --force` would be rejected here. It passes `skipFlagCheck`.

package/src/commands/status.js

@@ -221,6 +221,9 @@ export async function status(args = []) {
           site = siteState.site || null
           // In another workspace: it exists, and the refusal says where — report it.
           if (siteState.status === 409) remoteError = siteState.detail
+        } else if (siteState.refused) {
+          // The workspace this status works in, refused: say so — it is not a fact about the site.
+          remoteError = siteState.detail
         }
       }
       // Foundation freshness: prefer the LOCAL foundation's scoped name (so a
@@ -321,9 +324,9 @@ export async function status(args = []) {
         `To push this as a new site: uniweb forget --server ${probeBackend}, then uniweb push.`
       )
     } else if (siteState?.state === 'unknown') {
-      say.dim(
-        `Could not tell whether the backend holds this site${siteState.detail ? ` (${siteState.detail})` : ''}.`
-      )
+      // A refused workspace is already said above, as itself.
+      const detail = siteState.refused ? null : siteState.detail
+      say.dim(`Could not tell whether the backend holds this site${detail ? ` (${detail})` : ''}.`)
     }
     if (site) {
       if (site.draft_dirty) {

package/src/framework-index.json

@@ -1,15 +1,15 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-16T21:09:24.298Z",
+  "generatedAt": "2026-10-16T22:49:32.412Z",
   "packages": {
     "@uniweb/api": {
       "version": "1.2.5"
     },
     "@uniweb/build": {
-      "version": "1.3.4"
+      "version": "1.3.5"
     },
     "@uniweb/content-reader": {
-      "version": "1.3.3"
+      "version": "1.4.0"
     },
     "@uniweb/content-writer": {
       "version": "1.1.2"
@@ -60,7 +60,7 @@
       "version": "1.2.0"
     },
     "@uniweb/unipress": {
-      "version": "1.1.4"
+      "version": "1.1.5"
     }
   },
   "templates": {

package/src/utils/git.js

@@ -161,17 +161,23 @@ export function uncommittedUnder(dir, relPaths) {
 }
 
 /**
- * A file's committed content — the COMMON ANCESTOR for a three-way merge.
+ * A file's content at HEAD — the ancestor of a three-way merge for a file no pull
+ * wrote. For one a pull wrote, the ancestor is the version it wrote, found in history
+ * by `findCommitted` below: HEAD stops being that version the moment an edit is
+ * committed on top of it.
  *
- * This is the input a merge needs and the backend cannot supply: it keeps no
+ * Either way the ancestor is on this side, which is the point: the backend keeps no
  * per-version item content, and retaining some so it could feed a merge running on
  * the client would put a permanent second write on its hottest table. It doesn't
- * have to. `uniweb pull` writes the backend's content into these files, so the
- * committed version IS the state both sides diverged from — the ancestor was always
- * on this side, in the tool that already knows how to merge.
+ * have to — the tool that already knows how to merge holds the history.
  *
- * @returns {Buffer|null} null when the path isn't in HEAD (a file added locally and
- *   never committed has no ancestor, so there is nothing to merge against).
+ * ⛔ Until 2026-10-16 this called HEAD's content THE common ancestor ("`uniweb pull`
+ * writes the backend's content into these files, so the committed version IS the
+ * state both sides diverged from") — the rule `pull --merge` dropped on 2026-09-23.
+ *
+ * @returns {Buffer|null} null when the path isn't in HEAD — a file added locally and
+ *   never committed has no ancestor; when the backend holds it too, `pull --merge`
+ *   merges the two versions two-way.
  */
 export function showAtHead(dir, relPath) {
   return showAt(dir, 'HEAD', relPath)

package/src/utils/site-data-upload.js

@@ -51,7 +51,7 @@
  * demonstrated.**
  */
 
-import { WORKSPACE_HEADER } from '../backend/client.js'
+import { WORKSPACE_HEADER, WorkspaceRefusedError } from '../backend/client.js'
 import { createHash } from 'node:crypto'
 import { humanBytes } from './bytes.js'
 import { fetchWithRetry, isTransientStatus } from './fetch-retry.js'
@@ -66,6 +66,8 @@ import { fetchWithRetry, isTransientStatus } from './fetch-retry.js'
  * @param {string|null} [opts.workspace] - the workspace the requests name, `@handle`
  *   (`x-uniweb-workspace`) — on the plan and on every DIRECT PUT, never on a presigned
  *   one, which is self-authorizing and must carry nothing it was not signed with
+ * @param {string} [opts.workspaceSource] - where that workspace came from (`workspace.js`),
+ *   so a refusal of it says how to choose another (`WorkspaceRefusedError`)
  * @param {{ data: Record<string, unknown> }|null} opts.ball - source of the set:
  *   `{ "<relpath under dist/data>": <json> }`, media refs already rewritten
  * @param {(m: string) => void} [opts.onProgress]
@@ -77,6 +79,7 @@ export async function uploadSiteData({
   token,
   siteUuid,
   workspace = null,
+  workspaceSource = 'login',
   ball,
   onProgress = () => {}
 }) {
@@ -167,6 +170,11 @@ export async function uploadSiteData({
         /* not a problem document — prose refusal, or an upstream error page */
       }
     }
+    // ⭐ The workspace the plan named is not one the account may open — said as every other
+    // site request says it (`WorkspaceRefusedError`, backend/client.js), never as a raw 403.
+    if (planRes.status === 403 && problem?.op === 'act_as_unit' && workspace) {
+      throw new WorkspaceRefusedError({ named: workspace, source: workspaceSource, origin })
+    }
     const err = new Error(
       `site data-uploads plan rejected: HTTP ${planRes.status}${body ? ` — ${body.slice(0, 300)}` : ''}`
     )