uniweb 0.59.2 → 0.61.0

package/src/utils/config.js

@@ -21,6 +21,7 @@ import { homedir } from 'node:os'
 import yaml from 'js-yaml'
 import { filterCmd } from './pm.js'
 import { writeJsonPreservingStyleAsync } from './json-file.js'
+import { loggedInOriginOf, readSessionFileSync } from './session-file.js'
 
 // ── Backend origin ─────────────────────────────────────────────
 
@@ -57,64 +58,100 @@ function readCliConfig() {
  * to keep this module off the optional-peer / import-cycle path.
  * @returns {string|null}
  */
-function readSessionOrigin() {
+/**
+ * **The backend the user is logged in to** — the one session's backend — or null.
+ *
+ * ⛔ This read `~/.uniweb/registry-auth.json`'s top-level `origin` itself until
+ * 2026-09-21: the v1 shape. The file had become one session per backend, which has no
+ * such field, so this answered null for every new login and the session tier below
+ * silently fell through to the default backend. It reads through the file's one reader
+ * now (utils/session-file.js).
+ *
+ * @returns {string|null}
+ */
+export function loggedInOrigin() {
+  return loggedInOriginOf(readSessionFileSync(DEFAULT_BACKEND_ORIGIN))
+}
+
+/** A value's bare origin, or null when it is not a URL. */
+function originOrNull(value) {
+  if (!value) return null
   try {
-    const p = join(homedir(), '.uniweb', 'registry-auth.json')
-    if (!existsSync(p)) return null
-    const o = JSON.parse(readFileSync(p, 'utf8'))?.origin
-    return o || null
+    // ⛔ http(s) only: `new URL('localhost:8080')` PARSES — as the scheme `localhost:` —
+    // and its origin is the string "null", which is truthy. A bare host:port is the
+    // easy slip, and it must not become a backend.
+    const u = new URL(value)
+    return u.protocol === 'http:' || u.protocol === 'https:' ? u.origin : null
   } catch {
     return null
   }
 }
 
 /**
- * Get the backend's API base origin. `register` POSTs to
- * {origin}/dev/registry/register, `login` to {origin}/dev/auth/login, etc.
- * (BackendClient.resolveBackendOrigin layers the --backend flag and a site's
- * deploy.yml backend on top of this.)
+ * **The default backend** — where a bare `uniweb login` goes, and where a backend command
+ * goes when nobody is logged in (the login it asks for is then this one).
+ *
+ * `UNIWEB_REGISTER_URL`, else `~/.uniweb/config.json` `registryApiUrl`, else
+ * https://uniweb.app. ⛔ **Never the current session** *[Diego, 2026-09-21: "the default
+ * backend for login, if not specified, is uniweb.app"]* — a bare `uniweb login` means the
+ * default backend, not "the one I am already on".
+ *
+ * @returns {string}
+ */
+export function getDefaultBackendOrigin() {
+  return (
+    originOrNull(process.env.UNIWEB_REGISTER_URL) ||
+    originOrNull(readCliConfig().registryApiUrl) ||
+    DEFAULT_BACKEND_ORIGIN
+  )
+}
+
+/**
+ * The backend `uniweb login` logs in to: `--backend`, else the default backend.
+ *
+ * ⛔ A mistyped `--backend` is an error, never a fallback — it would log you in, and so
+ * point every command, somewhere you did not name.
+ *
+ * @param {string|null|undefined} flag - `readFlagValue`'s answer: undefined when the
+ *   flag is absent, null when it was given with no value
+ * @returns {string}
+ * @throws {Error} when --backend was given and is not a URL
+ */
+export function resolveLoginOrigin(flag) {
+  if (flag === undefined) return getDefaultBackendOrigin()
+  const origin = originOrNull(flag)
+  if (!origin) throw new Error(flag ? `Not a URL: ${flag}` : '--backend needs a URL')
+  return origin
+}
+
+/**
+ * **The backend a command talks to** when no `--backend` is given — the base of every
+ * `/dev/*` route (`register` POSTs to {origin}/dev/registry/register, and so on).
+ *
+ * `UNIWEB_REGISTER_URL` > **the backend the user is logged in to** > the default
+ * (`getDefaultBackendOrigin`). ⭐ Nothing talks to a backend the user is not logged in
+ * to *[Diego, 2026-09-21]*: when this falls through to the default, the command's first
+ * request asks for that login — so the default is where the login goes, never a
+ * backend reached without one. `resolveBackendOrigin` puts `--backend` on top.
  *
- * Priority: UNIWEB_REGISTER_URL's origin > the logged-in session origin >
- * ~/.uniweb/config.json registryApiUrl > the default (uniweb.app). Local dev
- * points at a local backend EXPLICITLY (--backend / UNIWEB_REGISTER_URL /
- * `uniweb login --backend …`), rather than the default being localhost.
  * @returns {string}
  */
 export function getRegistryApiBaseUrl() {
-  const fromEnv = process.env.UNIWEB_REGISTER_URL
-  if (fromEnv) {
-    try {
-      return new URL(fromEnv).origin
-    } catch {
-      /* fall through */
-    }
-  }
-  const fromSession = readSessionOrigin()
-  if (fromSession) {
-    try {
-      return new URL(fromSession).origin
-    } catch {
-      return fromSession
-    }
-  }
-  const fromCfg = readCliConfig().registryApiUrl
-  if (fromCfg) {
-    try {
-      return new URL(fromCfg).origin
-    } catch {
-      return fromCfg
-    }
-  }
-  return DEFAULT_BACKEND_ORIGIN
+  return (
+    originOrNull(process.env.UNIWEB_REGISTER_URL) ||
+    originOrNull(loggedInOrigin()) ||
+    getDefaultBackendOrigin()
+  )
 }
 
 /**
  * The built-in backend origin — the last tier of the ladder, and the 98% case.
  *
- * Exported because `site.yml::$backend` is written ONLY when the backend is NOT this
- * (`recordSiteBackend`, utils/site-identity.js). That test needs the *built-in* default,
- * which `getRegistryApiBaseUrl()` cannot give it — that function returns whatever tier
- * won, so on a machine with a session or a saved config it returns something else
+ * Exported because several readers need the *built-in* default, not the resolved one:
+ * a v1 session file with no origin stamp, `login`'s list of known backends, and a
+ * deploy.yml `host: uniweb` target with no `backend:` (its documented meaning).
+ * `getRegistryApiBaseUrl()` cannot give it — that function returns whatever tier won,
+ * so on a machine with a session or a saved config it returns something else
  * entirely. Two copies of the literal would silently disagree exactly there.
  */
 export const DEFAULT_BACKEND_ORIGIN = 'https://uniweb.app'

package/src/utils/flag-guard.js

@@ -6,16 +6,17 @@
  * does not recognize does not fail: it *disappears*, and the thing it was meant to
  * change silently keeps its default.
  *
- * That is tolerable for a cosmetic flag and dangerous for these two:
+ * Tolerable for a cosmetic flag; dangerous for any flag that aims the command or picks
+ * its identity. This turns that class into one sentence.
  *
- *   --backend   mistyped ⇒ the origin ladder falls through to the session origin,
- *               ~/.uniweb/config.json, and finally https://uniweb.app. A command
- *               aimed at a local backend can reach production.
- *   --token     mistyped ⇒ falls back to the stored session, so the request is
- *               made as whoever is logged in rather than whoever was intended.
- *
- * Neither produces an error today; both produce a plausible success against the
- * wrong host. This turns that class into one sentence.
+ * ⛔ **`--backend` and `--token` are NOT flags of these verbs** *(2026-09-21)*. Every
+ * backend verb goes to the backend you are logged in to, with that login's session:
+ * switching and signing in are `uniweb login` (`--backend`, `--token`), and a script
+ * aims one process with UNIWEB_REGISTER_URL + UNIWEB_TOKEN. Both flags predate
+ * per-backend sessions. Passed now, each is an unknown flag — and this guard is what
+ * makes that a loud error, with a pointer to the login, instead of a command that
+ * quietly runs against wherever and as whoever you happen to be. `--backend` stays on
+ * `forget`, where it SELECTS which backend's records to remove.
  *
  * ⚠️ A wrong rejection is worse than a missed one — it breaks an invocation that
  * works — so the per-command lists must be complete, INCLUDING flags read by
@@ -38,8 +39,8 @@ const GLOBAL = ['--non-interactive', '--help', '-h']
 const AUTH = ['--browser', '--password', '--token-paste']
 
 /**
- * Flags a verb inherits by importing `commands/deploy.js` for `resolveSiteDir` /
- * `resolveSiteBackend`. Inert on these verbs, and listed rather than filtered:
+ * Flags a verb inherits by importing `commands/deploy.js` for `resolveSiteDir`.
+ * Inert on these verbs, and listed rather than filtered:
  * accepting a flag that does nothing is exactly the pre-guard behaviour, while
  * rejecting one that works is a broken command. The guard's job is catching
  * `--backed`, not policing inert-but-valid spellings.
@@ -54,8 +55,8 @@ const VIA_DEPLOY = ['--target', '--host', '--no-save']
  */
 const VERBS = {
   push: [
-    '--all', '--as-org', '--org', '--backend', '--dry-run', '--force',
-    '--foundation', '--output', '-o', '--personal', '--token',
+    '--all', '--as-org', '--org', '--dry-run', '--force',
+    '--foundation', '--output', '-o', '--personal',
     // read in utils/conformance.js and backend/site-sync.js respectively —
     // neither appears in push.js
     '--no-validate', '--yes',
@@ -68,29 +69,36 @@ const VERBS = {
     '--no-release', ...VIA_DEPLOY
   ],
   publish: [
-    '--as-org', '--org', '--backend', '--dry-run', '--force', '--foundation',
-    '--personal', '--token',
+    '--as-org', '--org', '--dry-run', '--force', '--foundation',
+    '--personal',
     // read in utils/conformance.js, backend/site-sync.js, and
     // backend/foundation-bring-along.js — none appear in publish.js
     '--no-validate', '--yes', '--no-verify', '--no-release', ...VIA_DEPLOY
   ],
   pull: [
-    '--backend', '--content-only', '--dry-run', '--force', '--merge',
+    '--content-only', '--dry-run', '--force', '--merge',
     '--no-assets',
-    '--no-records', '--no-delete', '--no-prune', '--token',
+    '--no-records', '--no-delete', '--no-prune',
     // via backend/site-sync.js (the owner resolver) and utils/conformance.js
     '--yes', '--org', '--as-org', '--no-validate', ...VIA_DEPLOY
   ],
   clone: [
-    '--backend', '--content-only', '--no-assets', '--no-records', '--path',
-    '--project', '--token', '--org', '--as-org'
+    '--content-only', '--no-assets', '--no-records', '--path',
+    '--project', '--org', '--as-org'
   ],
   register: [
-    '--backend', '--dry-run', '--json', '--output', '-o',
-    '--schema-only', '--scope', '--token', '--org', '--as-org'
+    '--dry-run', '--json', '--output', '-o',
+    '--schema-only', '--scope', '--org', '--as-org'
   ],
+  /**
+   * `forget` = remove one backend's records (`--backend <url>`), or everything a
+   * copied project inherited (`--all`). One of the two is required — the verb refuses
+   * without it — and they exclude each other. `--non-interactive` reaches it through
+   * resolveSiteDir in a workspace of several sites.
+   */
+  forget: ['--backend', '--all'],
   status: [
-    '--backend', '--json', '--remote', '--token', '--dry-run',
+    '--json', '--remote', '--dry-run',
     '--force', '--no-verify', '--no-validate', '--yes', '--org', '--as-org',
     // inert here, reachable through the bring-along module status imports for
     // `resolveLocalFoundation` — listed per the over-approximation note above
@@ -99,10 +107,9 @@ const VERBS = {
   /**
    * `refresh` = `git pull`, then a DELEGATED `pull --merge`.
    *
-   * It forwards exactly two flags to that pull — `--backend` /
-   * `--token`, via its own `collectPassthrough` — and constructs the rest of the
-   * argv itself. So pull's own flags (`--merge`, `--force`, `--no-delete`,
-   * `--no-prune`, `--content-only`, …) are NOT reachable from a `refresh` argv and
+   * It forwards nothing of its own argv to that pull — it builds `['--merge']`
+   * itself. So pull's own flags (`--merge`, `--force`, `--no-delete`, `--no-prune`,
+   * `--content-only`, …) are NOT reachable from a `refresh` argv and
    * are deliberately absent here. ⚠️ `--force` especially: `refresh` is read-only by
    * design, and forwarding it would ask pull to DISCARD local work.
    *
@@ -111,7 +118,7 @@ const VERBS = {
    * the VIA_DEPLOY note above, and required by `flag-guard-coverage.test.js`.
    */
   refresh: [
-    '--backend', '--no-backend', '--no-git', '--token',
+    '--no-backend', '--no-git',
     '--as-org', '--org', '--dry-run', '--no-validate', '--yes', ...VIA_DEPLOY
   ]
 }
@@ -143,6 +150,18 @@ VERBS.sync = [...new Set([...VERBS.refresh, ...VERBS.push])]
  * flag accepted here but inert costs nothing (it was ignored before the guard
  * existed), while one rejected here breaks a working command.
  */
+/**
+ * Read in the verbs' import graphs, and deliberately NOT accepted by them.
+ *
+ * `--token` is read by `runRegistryLogin` (utils/registry-auth.js) for
+ * `uniweb login --token <bearer>`, which seeds and STORES a session. The verbs reach
+ * that function through `ensureRegistryAuth`, which strips `--token` from their argv
+ * first — so a static walk sees the read, and no verb can honour it.
+ * `flag-guard-coverage.test.js` subtracts this list; add to it only with the same
+ * proof: a read no verb's argv can reach.
+ */
+export const LOGIN_ONLY = ['--token']
+
 export const VERB_FLAGS = Object.fromEntries(
   Object.entries(VERBS).map(([verb, flags]) => [
     verb,
@@ -170,6 +189,30 @@ export function checkFlags(verb, args = []) {
   if (!unknown.length) return null
 
   const flag = unknown[0]
+  // ⭐ `--backend` and `--token` are not typos on these verbs — they are RETIRED
+  // (2026-09-21), and the useful answer is what replaced them, not "run --help".
+  if (flag === '--backend') {
+    return {
+      flag,
+      suggestion: null,
+      message: [
+        `\`uniweb ${verb}\` has no \`--backend\`: it goes to the backend you are logged in to.`,
+        '  Switch with: uniweb login --backend <url>',
+        '  (A script can aim one process with UNIWEB_REGISTER_URL instead.)'
+      ].join('\n')
+    }
+  }
+  if (flag === '--token') {
+    return {
+      flag,
+      suggestion: null,
+      message: [
+        `\`uniweb ${verb}\` has no \`--token\`: it uses the session of the backend you are logged in to.`,
+        '  Sign in with a token: uniweb login --backend <url> --token <bearer>',
+        '  (A script can authenticate one process with UNIWEB_TOKEN instead.)'
+      ].join('\n')
+    }
+  }
   const suggestion = didYouMean(flag, all)
   const lines = [`Unknown flag \`${flag}\` for \`uniweb ${verb}\`.`]
   if (suggestion) lines.push(`  Did you mean \`${suggestion}\`?`)

package/src/utils/git.js

@@ -54,7 +54,7 @@ export function siteContentRoots(siteDir) {
   }
   roots.add(paths.pages || 'pages')
   roots.add(paths.layout || 'layout')
-  roots.add(paths.entities || 'entities')
+  roots.add(paths.records || 'records')
   return [...roots]
 }
 

package/src/utils/interactive.js

@@ -45,6 +45,44 @@ export async function confirm(question, defaultYes = false) {
   }
 }
 
+/**
+ * Ask the user to pick one of a short list, returning `fallback` on an empty answer
+ * or anything unparseable.
+ *
+ * ⛔ **Prompts on STDERR**, like everything else a human reads here — `stdout` is the
+ * CLI's data channel and a prompt written there corrupts any caller piping it.
+ *
+ * ⛔ Callers must decide NOT to ask before calling (see `confirm`): this reads stdin,
+ * and a prompt in a non-interactive run hangs a pipeline.
+ *
+ * @param {string} question
+ * @param {string[]} options - shown in order, numbered from 1
+ * @param {string} fallback - returned for an empty or unparseable answer
+ * @returns {Promise<string>}
+ */
+export async function pickOne(question, options, fallback) {
+  if (!Array.isArray(options) || options.length === 0) return fallback
+  if (options.length === 1) return options[0]
+  const { createInterface } = await import('node:readline/promises')
+  const rl = createInterface({ input: process.stdin, output: process.stderr })
+  try {
+    process.stderr.write(`${question}\n`)
+    options.forEach((o, i) => {
+      const mark = o === fallback ? ' \x1b[2m(default)\x1b[0m' : ''
+      process.stderr.write(`  \x1b[1m${i + 1}\x1b[0m) ${o}${mark}\n`)
+    })
+    const a = (await rl.question(`Choose [1-${options.length}]: `)).trim()
+    if (!a) return fallback
+    const n = Number.parseInt(a, 10)
+    if (Number.isInteger(n) && n >= 1 && n <= options.length) return options[n - 1]
+    // A pasted origin is a reasonable answer to a list of origins.
+    if (options.includes(a)) return a
+    return fallback
+  } finally {
+    rl.close()
+  }
+}
+
 /**
  * Get the CLI invocation prefix to use in suggested commands.
  * Mirrors however the user actually ran the CLI.

package/src/utils/records-guard.js

@@ -1,69 +1,77 @@
 // ⛔ THE ONE PLACE AN ORDINARY ACT IS DESTRUCTIVE.
 //
-// `records.yml` is the sync control, and `missing` and `empty` deliberately mean
-// different things: missing leaves the server's folder untouched, empty says the
-// folder holds nothing and the backend removes what is there. The asymmetry is
-// well-shaped — the safe state is the ABSENCE of a file, so a live folder cannot
-// be wiped by deleting one, and the destructive act requires affirmatively
-// creating one.
+// A push sends the site's records folder whole, and it REPLACES the backend's. A site
+// with no records directory sends none and leaves the backend's alone; a records
+// directory that holds no records sends an EMPTY folder, and the backend removes what
+// is there. The asymmetry is well-shaped — the safe state is the ABSENCE of the
+// directory, so a site whose records live only on the backend is never emptied by a
+// push of its pages — and it leaves exactly one sharp edge: a directory emptied by
+// accident, or kept with only a placeholder (`records/.gitkeep`), and pushed.
 //
-// ⚠️ WHICH LEAVES EXACTLY ONE SHARP EDGE: a PLACEHOLDER. Someone creates an empty
-// `records.yml` intending to fill it in, pushes, and the live folder empties.
-// That is plausible and it is the only path where a normal act destroys content.
+// ⭐ THE CLI DOES THE ASKING. Never make "empty" mean "missing" to dodge this: that
+// would delete a capability to avoid writing a prompt.
 //
-// ⭐ THE FORMAT STAYS HONEST AND THE CLI DOES THE ASKING. Never make "empty" mean
-// "missing" to dodge this: that would delete a capability to avoid writing a
-// prompt.
+// ⛔ Until 2026-09-21 both states were `records.yml`'s — missing and empty — because
+// that file listed the records. The directory holds them now (`@uniweb/build`'s
+// `sendsFolder` decides what a push sends, and this asks about exactly its empty case).
 //
 // The count comes from the placement identity a previous push banked — what WE
 // last saw the folder hold. It needs no network call, and it is the right source:
 // a site that has never pushed has nothing to lose and is never asked.
 
-import { readRecordsConfig, FOLDER_EMPTY } from '@uniweb/build/uwx'
+import { readEntityPool } from '@uniweb/build/uwx'
 import { readFolderItemUuids } from '../backend/site-sync.js'
 import { confirm, isNonInteractive, getCliPrefix } from './interactive.js'
 
 /**
- * Leaf placements in a banked path→uuid map.
+ * Record placements in a banked placement map.
  *
- * A branch's path is a prefix of every path beneath it, so anything that is a
- * prefix of another key is a folder rather than a record. Counting raw keys would
- * report a two-record site inside one folder as three things to lose.
+ * ⭐ A placement banked since 2026-09-21 is keyed by the record it references —
+ * `@<record uuid>`, one per record — so where those exist they ARE the count. A map
+ * banked before holds `name` chains only: a branch's path is a prefix of every path
+ * beneath it, so anything that is a prefix of another key is a folder rather than a
+ * record. Counting raw keys would report a two-record site inside one folder as
+ * three things to lose — or, with both kinds of key, each record twice.
  */
 export function countPlacedRecords(pathToUuid) {
-  const paths = Object.keys(pathToUuid || {})
-  return paths.filter((p) => !paths.some((q) => q !== p && q.startsWith(`${p}/`))).length
+  const keys = Object.keys(pathToUuid || {})
+  const byRecord = keys.filter((k) => k.startsWith('@'))
+  if (byRecord.length) return byRecord.length
+  return keys.filter((p) => !keys.some((q) => q !== p && q.startsWith(`${p}/`))).length
 }
 
 /**
- * Stop an empty `records.yml` from silently emptying a live folder.
+ * Stop an empty records directory from silently emptying the backend's folder.
  *
  * @param {object} params
  * @param {string} params.siteDir
+ * @param {string} params.backend - whose placements to count; they are minted per backend
  * @param {string[]} params.args - the verb's argv, for --yes / non-interactive
  * @param {(m: string) => void} params.warn - the CALLER's reporter. Each verb owns
  *        its own output style; a second copy here would drift from all of them.
  * @param {(m: string) => void} params.note
  * @returns {Promise<{ ok: boolean, count: number }>} `ok: false` means abort
  */
-export async function guardEmptyRecords({ siteDir, args = [], warn, note }) {
-  const cfg = await readRecordsConfig(siteDir)
-  if (cfg.state !== FOLDER_EMPTY) return { ok: true, count: 0 }
+export async function guardEmptyRecords({ siteDir, backend, args = [], warn, note }) {
+  const pool = await readEntityPool(siteDir)
+  // Only a directory that is there and holds nothing at all — no records, and no
+  // files that fail to be records — sends the empty folder.
+  if (!pool.exists || pool.entities.length > 0 || pool.errors.length > 0) return { ok: true, count: 0 }
 
-  const count = countPlacedRecords(readFolderItemUuids(siteDir))
+  const count = countPlacedRecords(readFolderItemUuids(siteDir, backend))
   // Nothing banked ⇒ nothing this push can remove. A first push of an empty
   // folder is a legitimate (if odd) thing to do, and asking about it would train
   // people to type y.
   if (count === 0) return { ok: true, count: 0 }
 
   warn(
-    `records.yml is empty, and this push would REMOVE ${count} record${count === 1 ? '' : 's'} ` +
-      `from the live folder.`
+    `${pool.dir}/ holds no records, and this push would REMOVE ${count} record${count === 1 ? '' : 's'} ` +
+      `from the site's folder on the backend.`
   )
   note(
-    'An empty records.yml means "the folder holds nothing" — it is not the same as ' +
-      'having no records.yml, which leaves the live folder alone. If you meant to ' +
-      'start listing records, delete the file until you have.'
+    `An empty ${pool.dir}/ means "the folder holds nothing" — it is not the same as having no ` +
+      `${pool.dir}/ at all, which leaves the backend's folder alone. If you did not mean to remove ` +
+      `them, put the files back (or pull) before pushing.`
   )
 
   // ⚠️ `--yes` ONLY. `-y` is not a flag this CLI has anywhere, and adding one here
@@ -75,6 +83,6 @@ export async function guardEmptyRecords({ siteDir, args = [], warn, note }) {
     return { ok: false, count }
   }
 
-  const yes = await confirm(`Remove ${count} record${count === 1 ? '' : 's'} from the live folder?`, false)
+  const yes = await confirm(`Remove ${count} record${count === 1 ? '' : 's'} from the site's folder?`, false)
   return { ok: yes, count }
 }