uniweb 0.85.0 → 0.87.0

package/src/commands/deploy.js

@@ -195,8 +195,8 @@ export async function deploy(args = []) {
     // uniweb target's `backend:` records where that target's publishes went; it routes
     // nothing (publish files its record under the target naming its backend).
     const goingTo = getRegistryApiBaseUrl()
-    const aimedBy = process.env.UNIWEB_REGISTER_URL
-      ? 'UNIWEB_REGISTER_URL'
+    const aimedBy = process.env.UNIWEB_SERVER
+      ? 'UNIWEB_SERVER'
       : loggedInOrigin()
         ? 'the backend you are logged in to'
         : 'the default backend — you are not logged in'
@@ -215,7 +215,7 @@ export async function deploy(args = []) {
         say.err(
           `Target '${resolved.targetName}' is on ${targetBackend}, but this would publish to ${goingTo} (${aimedBy}).`
         )
-        say.dim(`To publish there, log in to it first: uniweb login --backend ${targetBackend}`)
+        say.dim(`To publish there, log in to it first: uniweb login --server ${targetBackend}`)
         process.exit(1)
       }
       say.dim(

package/src/commands/forget.js

@@ -2,10 +2,10 @@
  * `uniweb forget` — remove what this project recorded about where it has synced and
  * deployed. Local files only; nothing on any backend changes.
  *
- *   uniweb forget --backend <url>   one backend
+ *   uniweb forget --server <url>   one backend
  *   uniweb forget --all             everything — for a COPY that is to become a new project
  *
- * ## `--backend <url>`
+ * ## `--server <url>`
  *
  *   - that backend's section of `sync.json` — the site uuid, the record map, asset
  *     ids, provisioned services and the rest of what it minted;
@@ -43,12 +43,12 @@
  * ## Why it exists
  *
  * Two jobs. A script pushes a template site to a short-lived dev server and then
- * removes the traces of it without discarding the rest of the project (`--backend`)
+ * removes the traces of it without discarding the rest of the project (`--server`)
  * — which is also why traceless publish was dropped: push and pull leave traces too.
  * And someone duplicates a project to start a new site from it (`--all`).
  *
  * ⚠️ **No default target.** Forgetting a backend you still use means its next push
- * creates a second site there, so the verb makes you name it — `--backend` is
+ * creates a second site there, so the verb makes you name it — `--server` is
  * required even when the project has synced with only one.
  */
 
@@ -96,9 +96,9 @@ export async function forget(args = []) {
   }
 
   const all = args.includes('--all')
-  const flag = readFlagValue(args, '--backend')
+  const flag = readFlagValue(args, '--server')
   if (all && flag) {
-    say.err('Use --backend <url> or --all, not both.')
+    say.err('Use --server <url> or --all, not both.')
     return { exitCode: 2 }
   }
 
@@ -108,7 +108,7 @@ export async function forget(args = []) {
   if (all) return forgetAll(siteDir)
 
   if (!flag) {
-    say.err('Name what to forget: uniweb forget --backend <url>')
+    say.err('Name what to forget: uniweb forget --server <url>')
     if (known.length) {
       say.dim(`This project has synced with: ${known.join(', ')}`)
     } else {

package/src/commands/publish.js

@@ -22,9 +22,9 @@
  * Distinct from `uniweb deploy` (third-party hosts) and `uniweb register`
  * (foundation code → catalog). For a self-contained artifact, see `uniweb export`.
  *
- * Backend: the one you are logged in to — UNIWEB_REGISTER_URL overrides it for a script
+ * Backend: the one you are logged in to — UNIWEB_SERVER overrides it for a script
  *   (resolveBackendOrigin). Auth: UNIWEB_TOKEN  >  the stored session  >  `uniweb login`.
- *   No `--backend` or `--token`: switching and signing in are `uniweb login`.
+ *   No `--server` or `--token`: switching and signing in are `uniweb login`.
  *
  * Usage:
  *   uniweb publish                 Bring the foundation along, sync, and go live
@@ -66,6 +66,7 @@ import { resolveDefaultLocale } from '@uniweb/core/locale-config'
 
 import {
   BackendClient,
+  BackendUnreachableError,
   describeRequestError,
   WorkspaceMismatchError
 } from '../backend/client.js'
@@ -270,10 +271,10 @@ export async function publish(args = []) {
   }
   const siteYml = readSiteYml(join(siteDir, 'site.yml'))
   // ⭐ THE BACKEND YOU ARE LOGGED IN TO is where this goes *[Diego, 2026-09-21]*, for every
-  // backend verb (resolveBackendOrigin). Only UNIWEB_REGISTER_URL — the automation
+  // backend verb (resolveBackendOrigin). Only UNIWEB_SERVER — the automation
   // override — outranks it, and nothing talks to a backend the user is not logged in to:
   // logged in nowhere, the origin is the default backend and the first request asks for
-  // that login. ⛔ There is no `--backend` here: switching is `uniweb login --backend`.
+  // that login. ⛔ There is no `--server` here: switching is `uniweb login --server`.
   // ⛔ The project's own record — its synced backend, deploy.yml's default target — routes
   // NOTHING. For part of 2026-09-21 it answered a "logged in nowhere" tier, which cannot
   // be reached: *"We do not allow any communication with backend if the user is not
@@ -303,8 +304,8 @@ export async function publish(args = []) {
   // ⚠️ Logged in to a backend where this project has no site, while it has one
   // elsewhere: following the login CREATES a second site. Say so before the owner
   // question, which otherwise arrives with no reason attached. Not when
-  // UNIWEB_REGISTER_URL chose the backend — that is already a decision.
-  if (!process.env.UNIWEB_REGISTER_URL) {
+  // UNIWEB_SERVER chose the backend — that is already a decision.
+  if (!process.env.UNIWEB_SERVER) {
     const known = syncedElsewhere(siteDir, client.origin)
     if (known) {
       const [headline, ...rest] = describeSyncedElsewhere(known, client.origin, 'publish')
@@ -480,6 +481,12 @@ export async function publish(args = []) {
       cliBin: process.argv[1]
     })
   } catch (err) {
+    // A backend that did not answer is said as that — not as a release that failed.
+    if (err instanceof BackendUnreachableError) {
+      say.err(err.message)
+      say.dim('Nothing was released or sent. Check that the backend is running, then re-run `uniweb publish`.')
+      return { exitCode: 1 }
+    }
     // A scope you are not a member of is said as that, with the ways on (`explainReleaseFailure`).
     say.err(err.notMember ? err.message : `Foundation release failed: ${err.message}`)
     for (const line of err.notMember ? err.ways : ['Fix the foundation, then re-run `uniweb publish`.']) say.dim(line)
@@ -933,7 +940,7 @@ export async function publish(args = []) {
   } catch (err) {
     say.err(describeRequestError(err, client.origin))
     if (!(err instanceof WorkspaceMismatchError))
-      say.dim('Is that the backend you meant? Switch with: uniweb login --backend <url>')
+      say.dim('Is that the backend you meant? Switch with: uniweb login --server <url>')
     return { exitCode: 1 }
   }
   // The body of a publish that did not go through — read once, and kept for the report below.

package/src/commands/pull.js

@@ -44,9 +44,9 @@
  *
  * The content + folder pull lanes are both keyed by the site's uuid on that backend
  *   (sync.json).
- * Backend: the one you are logged in to — UNIWEB_REGISTER_URL overrides it for a script
+ * Backend: the one you are logged in to — UNIWEB_SERVER overrides it for a script
  *   (resolveBackendOrigin). Auth: UNIWEB_TOKEN  >  the stored session  >  `uniweb login`.
- *   No `--backend` or `--token`: switching and signing in are `uniweb login`.
+ *   No `--server` or `--token`: switching and signing in are `uniweb login`.
  *
  * A project that never pushed has no `$uuid` to pull by — pull is a no-op with a
  * clear message. The backend serves each lane as a `.uwx` (ZIP: `manifest.json` +
@@ -702,10 +702,10 @@ export async function pull(args = [], deps = {}) {
     if (blocked) return blocked
   }
   // ⭐ THE BACKEND YOU ARE LOGGED IN TO is where this goes *[Diego, 2026-09-21]*, for every
-  // backend verb (resolveBackendOrigin). Only UNIWEB_REGISTER_URL — the automation
+  // backend verb (resolveBackendOrigin). Only UNIWEB_SERVER — the automation
   // override — outranks it, and nothing talks to a backend the user is not logged in to:
   // logged in nowhere, the origin is the default backend and the first request asks for
-  // that login. ⛔ There is no `--backend` here: switching is `uniweb login --backend`.
+  // that login. ⛔ There is no `--server` here: switching is `uniweb login --server`.
   // ⛔ The project's own record — its synced backend, deploy.yml's default target — routes
   // NOTHING. For part of 2026-09-21 it answered a "logged in nowhere" tier, which cannot
   // be reached: *"We do not allow any communication with backend if the user is not
@@ -747,14 +747,14 @@ export async function pull(args = [], deps = {}) {
   if (!siteContentUuid) {
     // Following the login can land on a backend with no site for this project while it
     // has one elsewhere — say where, rather than only "push first", which would create a
-    // second site. Not when UNIWEB_REGISTER_URL chose the backend: that is a decision.
-    const known = !process.env.UNIWEB_REGISTER_URL
+    // second site. Not when UNIWEB_SERVER chose the backend: that is a decision.
+    const known = !process.env.UNIWEB_SERVER
       ? syncedElsewhere(siteDir, client.origin)
       : null
     if (known) {
       info(`Nothing to pull — this project has no site on ${client.origin}.`)
       note(
-        `Its ${known.length === 1 ? `site is on ${known[0]}` : `sites are on ${known.join(', ')}`}. To pull from there: uniweb login --backend <url>`
+        `Its ${known.length === 1 ? `site is on ${known[0]}` : `sites are on ${known.join(', ')}`}. To pull from there: uniweb login --server <url>`
       )
       return { exitCode: 0 }
     }
@@ -799,7 +799,7 @@ export async function pull(args = [], deps = {}) {
     } catch (err) {
       error(describeRequestError(err, client.origin))
       if (err instanceof WorkspaceMismatchError) return { refused: true }
-      note('Is that the backend you meant? Switch with: uniweb login --backend <url>')
+      note('Is that the backend you meant? Switch with: uniweb login --server <url>')
       return null
     }
     if (res.status === 404) {
@@ -816,7 +816,7 @@ export async function pull(args = [], deps = {}) {
       if (detail) note(detail)
       if (res.status === 401 || res.status === 403)
         note(
-          "Credentials weren't accepted — log in again (`uniweb login --backend <url>`), or check UNIWEB_TOKEN."
+          "Credentials weren't accepted — log in again (`uniweb login --server <url>`), or check UNIWEB_TOKEN."
         )
       return null
     }

package/src/commands/push.js

@@ -48,9 +48,9 @@
  * backend's reconcile deletes items absent from the package, so an author's NEW page
  * would be hard-deleted). `--force` omits the token and restores last-push-wins.
  *
- * Backend: the one you are logged in to — UNIWEB_REGISTER_URL overrides it for a script
+ * Backend: the one you are logged in to — UNIWEB_SERVER overrides it for a script
  *   (resolveBackendOrigin). Auth: UNIWEB_TOKEN  >  the stored session  >  `uniweb login`.
- *   No `--backend` or `--token`: switching and signing in are `uniweb login`.
+ *   No `--server` or `--token`: switching and signing in are `uniweb login`.
  *
  * The two-lane SUBMISSION (POST both lanes, back-fill uuids, persist the
  * send-only-changed cache) lives in `../backend/site-sync.js` so `uniweb publish`
@@ -65,7 +65,7 @@ import { emitSyncPackages, readBackendState } from '@uniweb/build/uwx'
 import { findSiteCopies, describeSiteCopies } from '../utils/site-copies.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
 import { updateBackendMap, carryServed, SYNC_STORE_FILE } from '@uniweb/build/uwx'
-import { BackendClient } from '../backend/client.js'
+import { BackendClient, BackendUnreachableError } from '../backend/client.js'
 import { resolveSiteDir } from './deploy.js'
 import { refuseIfContentDoesNotConform } from '../utils/conformance.js'
 import { reportSchemalessQueries } from '../utils/schemaless-report.js'
@@ -162,10 +162,10 @@ export async function push(args = [], deps = {}) {
   // arrival or lose a value on the way. See utils/conformance.js.
   if (await refuseIfContentDoesNotConform(siteDir, { args })) return { exitCode: 1 }
   // ⭐ THE BACKEND YOU ARE LOGGED IN TO is where this goes *[Diego, 2026-09-21]*, for every
-  // backend verb (resolveBackendOrigin). Only UNIWEB_REGISTER_URL — the automation
+  // backend verb (resolveBackendOrigin). Only UNIWEB_SERVER — the automation
   // override — outranks it, and nothing talks to a backend the user is not logged in to:
   // logged in nowhere, the origin is the default backend and the first request asks for
-  // that login. ⛔ There is no `--backend` here: switching is `uniweb login --backend`.
+  // that login. ⛔ There is no `--server` here: switching is `uniweb login --server`.
   // ⛔ The project's own record — its synced backend, deploy.yml's default target — routes
   // NOTHING. For part of 2026-09-21 it answered a "logged in nowhere" tier, which cannot
   // be reached: *"We do not allow any communication with backend if the user is not
@@ -209,8 +209,8 @@ export async function push(args = [], deps = {}) {
   // ⚠️ Logged in to a backend where this project has no site, while it has one
   // elsewhere: following the login CREATES a second site. Say so before the owner
   // question, which otherwise arrives with no reason attached. Not for `-o` (nothing is
-  // created) and not when UNIWEB_REGISTER_URL chose the backend — that is a decision.
-  if (!output && !process.env.UNIWEB_REGISTER_URL) {
+  // created) and not when UNIWEB_SERVER chose the backend — that is a decision.
+  if (!output && !process.env.UNIWEB_SERVER) {
     const known = syncedElsewhere(siteDir, client.origin)
     if (known) {
       const [headline, ...rest] = describeSyncedElsewhere(known, client.origin, 'push')
@@ -278,6 +278,12 @@ export async function push(args = [], deps = {}) {
       verb: 'push'
     })
   } catch (err) {
+    // A backend that did not answer is said as that — not as a release that failed.
+    if (err instanceof BackendUnreachableError) {
+      error(err.message)
+      note('Nothing was released or sent. Check that the backend is running, then re-run `uniweb push`.')
+      return { exitCode: 1 }
+    }
     // A scope you are not a member of is said as that, with the ways on (`explainReleaseFailure`).
     error(err.notMember ? err.message : `Foundation release failed: ${err.message}`)
     for (const line of err.notMember ? err.ways : ['Fix the foundation, then re-run `uniweb push`.']) note(line)

package/src/commands/refresh.js

@@ -31,7 +31,8 @@
  *   uniweb refresh                 git pull, then merge the backend's content
  *   uniweb refresh --no-git        skip the git remote; backend only
  *   uniweb refresh --no-backend    skip the backend; git only
- *   uniweb refresh --backend <url> Override the backend origin
+ *
+ * The backend is the one you are logged in to, as for every backend verb (no flag picks it).
  */
 
 import { readFileSync } from 'node:fs'

package/src/commands/register.js

@@ -35,9 +35,9 @@
  *                                        ({ok,scope,origin,entities:[{name,uuid,version,unchanged}]}),
  *                                        all human output to stderr — for scripted callers
  *
- * Endpoint: UNIWEB_REGISTER_URL  >  the backend you are logged in to  >  the default
- *   (~/.uniweb/config.json, else uniweb.app) — resolveBackendOrigin. No `--backend`:
- *   switching is `uniweb login --backend <url>`.
+ * Endpoint: UNIWEB_SERVER  >  the backend you are logged in to  >  the default
+ *   (~/.uniweb/config.json, else uniweb.app) — resolveBackendOrigin. No backend flag:
+ *   switching is `uniweb login --server <url>`.
  * Auth (submit only):  UNIWEB_TOKEN  >  the stored session  >  `uniweb login`.
  */
 
@@ -595,7 +595,7 @@ async function runRegister(args = []) {
   const dryRun = args.includes('--dry-run')
   const output = flagValue(args, '-o') || flagValue(args, '--output')
   const scopeFlag = flagValue(args, '--scope')
-  // The backend you are logged in to (UNIWEB_REGISTER_URL overrides it for a script) —
+  // The backend you are logged in to (UNIWEB_SERVER overrides it for a script) —
   // resolveBackendOrigin, like every backend command.
   const client = new BackendClient({
     args,
@@ -698,7 +698,10 @@ async function runRegister(args = []) {
           // fd 2 is our stderr: progress stays visible, stdout stays parseable.
           // Found by a harness that had to work around it by taking the last
           // JSON line off stdout.
-          stdio: jsonMode ? ['inherit', 2, 'inherit'] : 'inherit'
+          stdio: jsonMode ? ['inherit', 2, 'inherit'] : 'inherit',
+          // A step of register: the build's "Share with clients: uniweb register" hint
+          // would tell someone running register to run register.
+          env: { ...process.env, UNIWEB_BUILD_STEP: '1' }
         })
       } catch (err) {
         error(`Build failed: ${err.message}`)
@@ -845,7 +848,7 @@ async function runRegister(args = []) {
   } catch (err) {
     error(`Could not reach the registry at ${client.origin}: ${err.message}`)
     log(
-      `  ${colors.dim}Is that the backend you meant? Switch with: uniweb login --backend <url>${colors.reset}`
+      `  ${colors.dim}Is that the backend you meant? Switch with: uniweb login --server <url>${colors.reset}`
     )
     return { exitCode: 2 }
   }
@@ -905,7 +908,7 @@ async function runRegister(args = []) {
           `  ${colors.dim}The registry didn't accept your credentials — it may use different ones than \`uniweb login\`.${colors.reset}`
         )
         log(
-          `  ${colors.dim}Log in again (uniweb login --backend <url>), or check UNIWEB_TOKEN — an existing one may be wrong or expired.${colors.reset}`
+          `  ${colors.dim}Log in again (uniweb login --server <url>), or check UNIWEB_TOKEN — an existing one may be wrong or expired.${colors.reset}`
         )
       }
       // ⭐ **Surface `detail` as a sentence, not as a JSON dump.** The registry

package/src/commands/rename.js

@@ -62,7 +62,7 @@ import { writeJsonPreservingStyleAsync } from '../utils/json-file.js'
 import { getExistingPackageNames, validatePackageName } from '../utils/names.js'
 import { detectPackageManager, installCmd } from '../utils/pm.js'
 import { getCliPrefix } from '../utils/interactive.js'
-import { replaceInTopLevelList, setTopLevelScalar } from '../utils/yaml-edit.js'
+import { replaceInYamlList, setYamlKey } from '@uniweb/build/uwx'
 
 const colors = {
   reset: '\x1b[0m',
@@ -307,9 +307,9 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
         pkgSrc,
         sitePkgPath,
         siteYmlPath,
-        // Edited in place — see utils/yaml-edit.js — and computed HERE, before
+        // Edited in place — `setYamlKey`, @uniweb/build — and computed HERE, before
         // anything moves, so a file it cannot edit stops the rename cleanly.
-        newYmlText: ymlMatches ? setTopLevelScalar(ymlText, 'foundation', newName) : null,
+        newYmlText: ymlMatches ? setYamlKey(ymlText, 'foundation', newName) : null,
         hasDep,
         ymlMatches
       })
@@ -318,7 +318,7 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
   refuseUneditableSiteYml(
     affectedSites.filter((s) => s.ymlMatches && s.newYmlText === null).map((s) => s.path),
     'foundation',
-    `Write it on one line: \`foundation: ${oldName}\`.`
+    `Write \`foundation: ${oldName}\` as a plain value — not through a YAML alias (\`*name\`) or merge key (\`<<:\`).`
   )
 
   // ─── Print plan, then execute ────────────────────────────────
@@ -530,14 +530,14 @@ async function renameExtension(rootDir, oldName, newName, prefix) {
         siteYmlPath,
         hits,
         // Edited in place, and computed before anything moves — as for foundations.
-        newYmlText: replaceInTopLevelList(ymlText, 'extensions', replacements)
+        newYmlText: replaceInYamlList(ymlText, 'extensions', replacements)
       })
     }
   }
   refuseUneditableSiteYml(
     affectedSites.filter((a) => a.newYmlText === null).map((a) => a.site.path),
     'extensions',
-    `Write each entry on a line of its own, e.g. \`- ${oldUrlPrefix}dist/entry.js\`.`
+    'Write `extensions:` as a plain list — not through a YAML alias (`*name`) or merge key (`<<:`).'
   )
 
   log('')