uniweb 0.59.2 → 0.60.0

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/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

@@ -40,17 +40,18 @@ export function countPlacedRecords(pathToUuid) {
  *
  * @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 }) {
+export async function guardEmptyRecords({ siteDir, backend, args = [], warn, note }) {
   const cfg = await readRecordsConfig(siteDir)
   if (cfg.state !== FOLDER_EMPTY) 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.

package/src/utils/registry-auth.js

@@ -32,9 +32,9 @@
  *   - stored in a register-scoped slot (~/.uniweb/registry-auth.json) so it can
  *     never clobber the legacy token publish/deploy rely on.
  *
- * Token resolution for `register` (the `--token` flag is handled by the caller,
- * ahead of this): UNIWEB_TOKEN env > stored session (unexpired) >
- * UNIWEB_USERNAME/UNIWEB_PASSWORD env (non-interactive) > interactive prompt.
+ * Token resolution for the backend commands, which take no `--token` flag:
+ * UNIWEB_TOKEN env > stored session (unexpired) > UNIWEB_USERNAME/UNIWEB_PASSWORD
+ * env (non-interactive) > interactive prompt.
  *
  * Login response shape (agreed with backend, 2026-05-26):
  *   { token, expires_at, account: { uuid, username, handle } }
@@ -48,6 +48,9 @@ import { homedir } from 'node:os'
 import { createServer } from 'node:http'
 import { randomBytes } from 'node:crypto'
 
+import { DEFAULT_BACKEND_ORIGIN } from './config.js'
+import { normalizeSessionFile, sessionFilePath, loggedInOriginOf } from './session-file.js'
+
 const LOGIN_PATH = '/dev/auth/login'
 
 /** The shared ~/.uniweb credential directory. */
@@ -58,7 +61,10 @@ export function getAuthDir() {
 /** Normalize a backend URL to a bare origin (for stamping on the session). */
 function normOrigin(u) {
   try {
-    return new URL(u).origin
+    // http(s) only — `localhost:8080` parses as a scheme with the origin "null", and a
+    // session keyed "null" would answer for nothing.
+    const parsed = new URL(u)
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:' ? parsed.origin : u
   } catch {
     return u
   }
@@ -77,39 +83,102 @@ export function isExpired(auth) {
  * @returns {string}
  */
 export function getRegistryAuthPath() {
-  return join(getAuthDir(), 'registry-auth.json')
+  return sessionFilePath()
 }
 
 /**
- * Read the stored registry session, or null. No JWT backfill — the token is
- * opaque, so there are no claims to decode (unlike legacy readAuth()).
- * @returns {Promise<{ token: string, expiresAt?: string, accountId?: number, sessionId?: number, username?: string, handle?: string, uuid?: string } | null>}
+ * ONE SESSION, FOR ONE BACKEND — the on-disk shape.
+ *
+ *   { version: 2, current: "https://uniweb.app",
+ *     sessions: { "https://uniweb.app": { token, expiresAt, … } } }
+ *
+ * ⭐ **At most one session exists** *[Diego, 2026-09-21: "`uniweb login` log the user out
+ * of the existing session, if any, before logging in to the new backend … `uniweb logout`
+ * always logs you out of the one backend you may be logged in"]*. A login REPLACES the
+ * file — once it succeeds, so a cancelled or failed login leaves you where you were —
+ * and a logout deletes it. So "the backend you are logged in to" is exactly one thing
+ * or nothing, and logout needs no selector.
+ *
+ * ⚖️ The v2 map is kept, holding one entry: the file then has one reader
+ * (utils/session-file.js), and it still understands what came before — a v1 flat
+ * record, and a v2 file holding SEVERAL sessions (the per-backend store of 2026-09-20,
+ * which kept every backend's session and marked the last login `current`). The next
+ * login or logout rewrites either into the single-session shape.
+ *
+ * ⛔ Every session is still checked against the backend it is for (`readRegistryAuth`
+ * takes the origin): a token issued by A is never handed to a request against B. That
+ * was the correctness bug of the original flat record, and it stays fixed.
+ *
+ * The shape is read in ONE place, `utils/session-file.js`.
  */
-export async function readRegistryAuth() {
+
+/** The whole file, normalized to v2 shape. Never throws. */
+async function readAuthFile() {
   const path = getRegistryAuthPath()
-  if (!existsSync(path)) return null
+  if (!existsSync(path)) return normalizeSessionFile(null, DEFAULT_BACKEND_ORIGIN)
   try {
-    return JSON.parse(await readFile(path, 'utf8'))
+    return normalizeSessionFile(JSON.parse(await readFile(path, 'utf8')), DEFAULT_BACKEND_ORIGIN)
   } catch {
-    return null
+    return normalizeSessionFile(null, DEFAULT_BACKEND_ORIGIN)
   }
 }
 
+async function writeAuthFile({ version, current, sessions }) {
+  await mkdir(getAuthDir(), { recursive: true })
+  await writeFile(
+    getRegistryAuthPath(),
+    JSON.stringify({ version, ...(current ? { current } : {}), sessions }, null, 2)
+  )
+}
+
+/**
+ * The stored session FOR ONE BACKEND, or null. No JWT backfill — the token is
+ * opaque, so there are no claims to decode (unlike legacy readAuth()).
+ *
+ * ⛔ `origin` is required in spirit: calling this without one used to mean "the
+ * session", which is the assumption this file exists to remove. It falls back to the
+ * default backend rather than throwing, because every caller now passes one and a
+ * throw here would turn a stale call site into a crash instead of a wrong answer.
+ *
+ * @param {string} [origin] - the backend whose session is wanted
+ * @returns {Promise<{ token: string, expiresAt?: string, accountId?: number, sessionId?: number, username?: string, handle?: string, uuid?: string, origin: string } | null>}
+ */
+export async function readRegistryAuth(origin) {
+  const key = normOrigin(origin || DEFAULT_BACKEND_ORIGIN)
+  const { sessions } = await readAuthFile()
+  const found = sessions[key]
+  return found && typeof found.token === 'string' ? { ...found, origin: key } : null
+}
+
 /**
- * Persist the registry session record.
- * @param {Object} record
+ * Persist THE session — the backend the user is now logged in to, replacing whatever
+ * the file held. The record's own `origin` is the key, so every login path keeps
+ * stamping it exactly as before.
+ * @param {Object} record - must carry `origin` and `token`
  */
 export async function writeRegistryAuth(record) {
-  await mkdir(getAuthDir(), { recursive: true })
-  await writeFile(getRegistryAuthPath(), JSON.stringify(record, null, 2))
+  const key = normOrigin(record?.origin || DEFAULT_BACKEND_ORIGIN)
+  const { origin: _drop, ...rest } = record || {}
+  // ⭐ REPLACE, never merge: every caller is a successful login, and there is one session.
+  // Whatever the file held — another backend's session, or several from before —
+  // is gone: the user is logged in to this backend, and only this one.
+  await writeAuthFile({ version: 2, current: key, sessions: { [key]: rest } })
 }
 
 /**
- * Remove the stored registry session.
+ * Log out: delete the session file. There is one session, so there is nothing to choose.
+ *
+ * ⚠️ Local only — the token is forgotten on this machine, not revoked on the backend.
+ *
+ * @returns {Promise<string[]>} the origins whose sessions were removed — one, or
+ *   several for a file written before sessions were single (2026-09-21)
  */
 export async function clearRegistryAuth() {
   const path = getRegistryAuthPath()
-  if (existsSync(path)) await unlink(path)
+  if (!existsSync(path)) return []
+  const had = Object.keys((await readAuthFile()).sessions)
+  await unlink(path)
+  return had
 }
 
 /**
@@ -190,6 +259,21 @@ export async function loginToRegistry({ apiBase, username, password } = {}) {
  * @param {string[]} [options.args] - argv slice; checked for --non-interactive
  * @returns {Promise<string>} bearer token
  */
+/** `args` without `--token` and its value — see ensureRegistryAuth. */
+export function withoutLoginToken(args = []) {
+  const out = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--token') {
+      i++ // and its value
+      continue
+    }
+    if (a.startsWith('--token=')) continue
+    out.push(a)
+  }
+  return out
+}
+
 export async function ensureRegistryAuth({
   apiBase,
   command = 'This command',
@@ -197,7 +281,11 @@ export async function ensureRegistryAuth({
 } = {}) {
   if (process.env.UNIWEB_TOKEN) return process.env.UNIWEB_TOKEN
 
-  const stored = await readRegistryAuth()
+  // ⛔ THE SESSION MUST BE THE ONE ISSUED FOR `apiBase`. Until 2026-09-20 this read
+  // "the" session and returned its token whenever it was unexpired — so a bearer minted
+  // by backend A was sent to backend B, which rejects it. The store is keyed by origin
+  // now, so asking for the right one is the same single read.
+  const stored = await readRegistryAuth(apiBase)
   if (stored?.token && !isExpired(stored)) return stored.token
 
   // Non-interactive login from env (CI / agents) before any prompt.
@@ -240,7 +328,11 @@ export async function ensureRegistryAuth({
   }
 
   // Interactive: hand off to the multi-method login picker, reuse its session.
-  const record = await runRegistryLogin({ apiBase, args })
+  // ⛔ WITHOUT `--token`: in `runRegistryLogin` it means "seed and STORE this bearer as a
+  // session" — `uniweb login --token`'s job alone. A command's own argv reaching it
+  // would log the machine in as a side effect of that command. (The backend commands
+  // refuse `--token` since 2026-09-21; this holds for any other caller too.)
+  const record = await runRegistryLogin({ apiBase, args: withoutLoginToken(args) })
   if (!record?.token) process.exit(1)
   return record.token
 }
@@ -562,25 +654,55 @@ async function loginViaBrowser({ apiBase }) {
  * @returns {Promise<Object|undefined>} the stored session record
  */
 export async function runRegistryLogin({ apiBase, args = [] } = {}) {
-  const existing = await readRegistryAuth()
+  // For THIS backend. It read "the" session and printed `apiBase` beside it, so on a
+  // machine logged into another backend it announced "Already logged in … (this origin)"
+  // about a session belonging to a different one — and then offered to replace it.
+  const { isNonInteractive } = await import('./interactive.js')
+  const nonInteractive = isNonInteractive(args)
+
+  const key = normOrigin(apiBase)
+  const file = await readAuthFile()
+  const current = loggedInOriginOf(file)
+  const existing = await readRegistryAuth(apiBase)
+  const forced =
+    args.includes('--token') ||
+    args.includes('--browser') ||
+    args.includes('--password') ||
+    args.includes('--token-paste')
   if (existing?.token && !isExpired(existing)) {
     const who =
       existing.username ||
       existing.handle ||
       (existing.uuid ? `account ${existing.uuid}` : '')
+    if (!forced) {
+      // Already logged in to this backend: nothing to do — logging in again is behind a
+      // method flag. (Also where a file from before sessions were single, holding this
+      // backend among others, becomes single: the rewrite keeps only this session.)
+      if (current !== key || Object.keys(file.sessions).length > 1) {
+        await writeRegistryAuth({ ...existing, origin: key })
+      }
+      console.error(
+        `\x1b[32m✓\x1b[0m Already logged in to ${key}${who ? ` as \x1b[1m${who}\x1b[0m` : ''}.`
+      )
+      console.error(
+        '\x1b[2mTo log in again, name a method: --password, --browser, --token-paste or --token <bearer>.\x1b[0m'
+      )
+      return { ...existing, origin: key }
+    }
     console.error(
-      `Already logged in${who ? ` as \x1b[1m${who}\x1b[0m` : ''}${apiBase ? ` (${apiBase})` : ''}.`
+      `Already logged in${who ? ` as \x1b[1m${who}\x1b[0m` : ''} (${key}) — logging in again replaces that session.\n`
     )
-    console.error('\x1b[2mContinuing will replace the existing session.\x1b[0m\n')
+  } else if (current && current !== key) {
+    // ⭐ ONE SESSION AT A TIME *[Diego, 2026-09-21]*: logging in here logs you out of there
+    // — when this login succeeds (writeRegistryAuth replaces the file), so cancelling or
+    // failing leaves you logged in where you were.
+    console.error(`\x1b[2mYou are logged in to ${current}; logging in to ${key} logs you out of it.\x1b[0m\n`)
   }
 
-  const { isNonInteractive } = await import('./interactive.js')
-  const nonInteractive = isNonInteractive(args)
-
   // `--token <bearer>` seeds + verifies a session non-interactively (verified
   // against /dev/auth/me before it's stored, so an invalid token fails loudly
-  // instead of poisoning the session file). Distinct from the per-command
-  // `--token` (ephemeral, never stored) and from UNIWEB_TOKEN env.
+  // instead of poisoning the session file). ⭐ Login's alone: the backend commands
+  // take no `--token` (2026-09-21) — UNIWEB_TOKEN is the one-process bearer.
   const { readFlagValue } = await import('./args.js')
   const tokenFlag = readFlagValue(args, '--token')
   if (tokenFlag) {

package/src/utils/scaffold.js

@@ -207,6 +207,15 @@ export async function applyContent(
   )
 }
 
+/**
+ * What a project records about where IT synced and deployed — a site's identity on
+ * each backend, its deploy targets and history, and the local caches of both. A new
+ * project made from a template owns none of it: carried over, its first push would
+ * update the template's own site. The same line `uniweb forget --all` draws for a
+ * copied project. Matched at the top of a content directory, where a site keeps them.
+ */
+const INHERITED_STATE = new Set(['sync.json', 'deploy.yml', '.uniweb'])
+
 /**
  * Recursively copy content files, skipping structural files.
  *
@@ -234,6 +243,7 @@ async function copyContentRecursive(
     const sourcePath = join(sourceDir, entry.name)
 
     if (entry.isDirectory()) {
+      if (depth === 0 && INHERITED_STATE.has(entry.name)) continue
       const targetSubDir = join(targetDir, entry.name)
       await copyContentRecursive(
         sourcePath,
@@ -260,6 +270,7 @@ async function copyContentRecursive(
 
       // Skip structural files
       if (structuralFiles.has(outputName)) continue
+      if (depth === 0 && INHERITED_STATE.has(outputName)) continue
 
       const targetPath = join(targetDir, outputName)
 

package/src/utils/session-file.js

@@ -0,0 +1,95 @@
+/**
+ * `~/.uniweb/registry-auth.json` — the ONE reader of its shape.
+ *
+ *   { version: 2, current: "<origin>", sessions: { "<origin>": { token, … } } }
+ *
+ * ⭐ ONE session since 2026-09-21 — a login replaces the file, a logout deletes it
+ * (registry-auth.js). The map shape stays so this reader also understands a file from
+ * 2026-09-20→21, when the store kept one session PER backend.
+ *
+ * ⛔ **There were two readers until 2026-09-21, and the copy is how "the backend you are
+ * logged in to" stopped meaning anything.** `registry-auth.js` writes the file and read
+ * it; the origin ladder in `config.js` kept a sync copy that read a top-level `origin`.
+ * When the file became one session per backend (`fb4907e`), the writer moved to the shape
+ * above and the copy kept reading `origin` — a field the new shape does not have — so
+ * every command that falls back to the logged-in backend quietly fell through to the
+ * default one. Both now read through here, so the shape has one reader to change.
+ *
+ * ⛔ Dependency-free, by requirement: `config.js` imports this, and `registry-auth.js`
+ * imports `config.js`, so this module can import neither.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export const SESSION_FILE_VERSION = 2
+
+export function sessionFilePath() {
+  return join(homedir(), '.uniweb', 'registry-auth.json')
+}
+
+const originOf = (value) => {
+  try {
+    // http(s) only — `localhost:8080` parses as a scheme with the origin "null".
+    const u = new URL(value)
+    return u.protocol === 'http:' || u.protocol === 'https:' ? u.origin : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Any parsed value → `{ version: 2, current, sessions }`. Never throws.
+ *
+ * A v1 flat record is ONE session, keyed by its own `origin` stamp — or by
+ * `defaultOrigin` when it carries none — and that session is current: it was the only
+ * login there was.
+ *
+ * @param {*} raw - the parsed file, or anything
+ * @param {string} defaultOrigin
+ */
+export function normalizeSessionFile(raw, defaultOrigin) {
+  const empty = { version: SESSION_FILE_VERSION, current: null, sessions: {} }
+  if (!raw || typeof raw !== 'object') return empty
+  if (raw.sessions && typeof raw.sessions === 'object' && !Array.isArray(raw.sessions)) {
+    return { version: SESSION_FILE_VERSION, current: originOf(raw.current), sessions: raw.sessions }
+  }
+  if (typeof raw.token === 'string') {
+    const { origin, ...rest } = raw
+    const key = originOf(origin) || defaultOrigin
+    return { version: SESSION_FILE_VERSION, current: key, sessions: { [key]: rest } }
+  }
+  return empty
+}
+
+/** The file, normalized; synchronous, for the origin ladder. Never throws. */
+export function readSessionFileSync(defaultOrigin) {
+  const p = sessionFilePath()
+  if (!existsSync(p)) return normalizeSessionFile(null, defaultOrigin)
+  try {
+    return normalizeSessionFile(JSON.parse(readFileSync(p, 'utf8')), defaultOrigin)
+  } catch {
+    return normalizeSessionFile(null, defaultOrigin)
+  }
+}
+
+/**
+ * **The backend the user is logged in to** — the one session's backend.
+ *
+ * A file written since sessions became single holds one session, marked `current`. The
+ * other branches read what came before: a per-backend file names its last login
+ * `current`; one with a single unmarked session answers with it; several and none
+ * marked is no answer, and saying so beats guessing. An expired session still answers —
+ * the user logged in there, and the next request asks them to log in there again.
+ *
+ * @param {{ current?: string|null, sessions?: object }} file - normalized
+ * @returns {string|null}
+ */
+export function loggedInOriginOf(file) {
+  const sessions = file?.sessions || {}
+  const has = (o) => !!(o && sessions[o] && typeof sessions[o].token === 'string')
+  if (has(file?.current)) return file.current
+  const all = Object.keys(sessions).filter(has)
+  return all.length === 1 ? all[0] : null
+}