uniweb 1.0.0 → 1.0.2

package/src/utils/scaffold.js

@@ -0,0 +1,483 @@
+/**
+ * Scaffolding Utilities
+ *
+ * Shared scaffolding functions used by both `create` and `add` commands.
+ * Each function scaffolds a single package from its package template.
+ */
+
+import fs from 'node:fs/promises'
+import { existsSync, readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import yaml from 'js-yaml'
+import Handlebars from 'handlebars'
+import {
+  copyTemplateDirectory,
+  enumerateTemplateOutputs,
+  registerVersions
+} from '../templates/processor.js'
+import { getVersionsForTemplates, getCliVersion } from '../versions.js'
+import { writeJsonPreservingStyleAsync } from './json-file.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const TEMPLATES_DIR = join(__dirname, '..', '..', 'templates')
+const STARTER_DIR = join(__dirname, '..', '..', 'starter')
+
+/**
+ * Scaffold a workspace root from the workspace package template
+ *
+ * @param {string} targetDir - Target directory
+ * @param {Object} context - Template context
+ * @param {string} context.projectName - Workspace/project name
+ * @param {string[]} context.workspaceGlobs - Workspace glob patterns
+ * @param {Object} context.scripts - Root package.json scripts
+ * @param {Object} [options] - Processing options
+ */
+export async function scaffoldWorkspace(targetDir, context, options = {}) {
+  registerVersions(getVersionsForTemplates())
+
+  // Skip pnpm-workspace.yaml for blank workspaces (no packages yet).
+  // The `add` command creates it on demand via addWorkspaceGlob().
+  // Without this, pnpm fails with ERR_PNPM_NO_IMPORTER_MANIFEST_FOUND
+  // because an empty packages: [] makes pnpm search parent directories.
+  const skip = context.workspaceGlobs?.length ? [] : ['pnpm-workspace.yaml']
+
+  // Inject CLI version for AGENTS.md stamp
+  context = { ...context, cliVersion: getCliVersion() }
+
+  const templatePath = join(TEMPLATES_DIR, 'workspace')
+  await copyTemplateDirectory(templatePath, targetDir, context, {
+    onProgress: options.onProgress,
+    onWarning: options.onWarning,
+    skip
+  })
+}
+
+/**
+ * Return the relative paths the workspace template would write into the
+ * project root, given the same skip rules `scaffoldWorkspace` applies.
+ * Used by the in-place create flow (`uniweb create .`) to detect conflicts
+ * before any I/O begins.
+ *
+ * Only the workspace template's outputs are enumerated. The foundation,
+ * site, and starter stages write into newly-created subdirectories
+ * (`src/`, `site/`) that don't pre-exist in a target like a fresh GitHub
+ * clone, so they can't conflict.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.blank] - True when scaffolding a blank workspace
+ *   (no packages yet) — skips `pnpm-workspace.yaml`, mirroring scaffoldWorkspace.
+ * @returns {Promise<string[]>}
+ */
+export async function getWorkspaceTemplateOutputs({ blank = false } = {}) {
+  const skip = blank ? ['pnpm-workspace.yaml'] : []
+  const templatePath = join(TEMPLATES_DIR, 'workspace')
+  return enumerateTemplateOutputs(templatePath, { skip })
+}
+
+/**
+ * Scaffold a foundation from the foundation package template.
+ *
+ * @param {string} targetDir
+ * @param {Object} context - Template context
+ * @param {string} context.name - Package name — workspace plumbing (`src`, `docs-src`)
+ * @param {string} [context.registryName] - The foundation's own name, written to
+ *   main.js's `name`: what it registers as (`@org/<name>`). Omitted when none can be
+ *   made, and `uniweb register` asks for one
+ * @param {string} context.projectName - Workspace name
+ * @param {boolean} [context.isExtension]
+ */
+export async function scaffoldFoundation(targetDir, context, options = {}) {
+  registerVersions(getVersionsForTemplates())
+
+  const templatePath = join(TEMPLATES_DIR, 'foundation')
+  await copyTemplateDirectory(templatePath, targetDir, context, {
+    onProgress: options.onProgress,
+    onWarning: options.onWarning
+  })
+}
+
+/**
+ * Scaffold a site from the site package template
+ *
+ * Two shapes, by whether a local foundation is wired:
+ *  - Local foundation (the default for `create`/`add site`): pass
+ *    `foundationName` + `foundationPath` (a `file:` spec) and the site's
+ *    package.json gets that dependency.
+ *  - Referenced foundation (no local sibling — what `uniweb clone` uses):
+ *    OMIT `foundationName`/`foundationPath` and set `foundationRef` to a
+ *    registry ref (`@ns/name@ver`) or URL. No `file:` dependency is written;
+ *    `site.yml::foundation` carries the ref and the runtime loads it as a
+ *    federated module (runtime mode). Deps still pin to the CLI version
+ *    matrix via the template's `{{version}}` helper.
+ *
+ * @param {string} targetDir - Target directory for the site
+ * @param {Object} context - Template context
+ * @param {string} context.name - Package name
+ * @param {string} context.projectName - Workspace name
+ * @param {string} [context.foundationName] - Local foundation package name (omit for a referenced foundation)
+ * @param {string} [context.foundationPath] - Relative file: path to a local foundation (omit for a referenced foundation)
+ * @param {string} [context.foundationRef] - Foundation ref written to site.yml (a local package name, a registry ref, or a URL)
+ * @param {Object} [options] - Processing options
+ */
+export async function scaffoldSite(targetDir, context, options = {}) {
+  registerVersions(getVersionsForTemplates())
+
+  const templatePath = join(TEMPLATES_DIR, 'site')
+  // A ref is written as a YAML scalar, not pasted as text: a scoped ref
+  // (`@acme/base@1.0.0`, `@acme/marketing`) starts with `@`, which plain YAML
+  // reserves, so the file would not parse — and every reader that swallows
+  // the parse error then reports the site as having no `$uuid`. js-yaml quotes
+  // only when needed, so `src` stays `src`. Rendered with `{{{ }}}`, because
+  // Handlebars' HTML escaping would also rewrite a URL's `&` and `=`.
+  const siteContext = context.foundationRef
+    ? { ...context, foundationRefYaml: yaml.dump(context.foundationRef, { lineWidth: -1 }).trim() }
+    : context
+  await copyTemplateDirectory(templatePath, targetDir, siteContext, {
+    onProgress: options.onProgress,
+    onWarning: options.onWarning
+  })
+}
+
+/**
+ * Apply content overlay from a content directory onto a target
+ *
+ * Content files overwrite scaffolded defaults. Structural files
+ * (package.json, vite.config.js, entry.js, index.html) are NOT overwritten.
+ *
+ * Note: a foundation's `main.js` (the user-authored declarations file) is
+ * NOT structural — templates legitimately provide their own `main.js` to
+ * override the empty scaffold default. The site's `entry.js` (formerly
+ * `main.js`) IS structural — the boilerplate `start({...})` is identical
+ * across all sites and shouldn't be overwritten.
+ *
+ * @param {string} contentDir - Source content directory (e.g., starter/foundation/)
+ * @param {string} targetDir - Target directory to overlay onto
+ * @param {Object} context - Handlebars context for .hbs files
+ * @param {Object} [options] - Processing options
+ */
+export async function applyContent(
+  contentDir,
+  targetDir,
+  context,
+  options = {}
+) {
+  if (!existsSync(contentDir)) return
+
+  registerVersions(getVersionsForTemplates())
+
+  // Structural files that content should never overwrite
+  const STRUCTURAL_FILES = new Set([
+    'package.json',
+    'vite.config.js',
+    'entry.js',
+    'index.html',
+    '.gitignore'
+  ])
+
+  // Config files that should be merged, not overwritten: for each listed
+  // key, when the scaffolded version's value is used.
+  //
+  //   foundation  ALWAYS — the CLI resolved it for this project, and a
+  //               content template cannot know it.
+  //   name        ONLY WHEN THE TEMPLATE SETS NONE. A template's own name is
+  //               the default name of a site made from it — the same thing
+  //               cloning a template in an app gives — so a literal
+  //               `name: Product Launch` survives, and the project name fills
+  //               in for a template with no name, or only the
+  //               `{{projectName}}` placeholder.
+  const MERGE_FILES = {
+    'site.yml': [
+      ['name', 'when-template-has-none'],
+      ['foundation', 'always']
+    ]
+  }
+
+  await copyContentRecursive(
+    contentDir,
+    targetDir,
+    context,
+    STRUCTURAL_FILES,
+    MERGE_FILES,
+    options,
+    0
+  )
+}
+
+/**
+ * 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.
+ *
+ * `depth` is tracked so the project-state names (INHERITED_STATE) are
+ * skipped only at the top of the content directory.
+ */
+async function copyContentRecursive(
+  sourceDir,
+  targetDir,
+  context,
+  structuralFiles,
+  mergeFiles,
+  options,
+  depth = 0
+) {
+  await fs.mkdir(targetDir, { recursive: true })
+
+  const entries = readdirSync(sourceDir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    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,
+        targetSubDir,
+        context,
+        structuralFiles,
+        mergeFiles,
+        options,
+        depth + 1
+      )
+    } else {
+      // Determine the output filename (strip .hbs extension)
+      const outputName = entry.name.endsWith('.hbs')
+        ? entry.name.slice(0, -4)
+        : entry.name
+
+      // Skip structural files
+      if (structuralFiles.has(outputName)) continue
+      if (depth === 0 && INHERITED_STATE.has(outputName)) continue
+
+      const targetPath = join(targetDir, outputName)
+
+      // Get new content (process .hbs or read as-is)
+      let newContent
+      if (entry.name.endsWith('.hbs')) {
+        const Handlebars = (await import('handlebars')).default
+        const raw = await fs.readFile(sourcePath, 'utf-8')
+        const template = Handlebars.compile(raw)
+        newContent = template(context)
+      }
+
+      // Merge config files instead of overwriting.
+      //
+      // The "merge" here is narrow: take the content template's output
+      // as the source of truth (so comments, formatting, and the full
+      // educational structure of the content template survive) and
+      // override only the specific top-level keys listed in
+      // preserveKeys with the values from the already-scaffolded base
+      // file (so the resolved foundation ref is never replaced by whatever
+      // the content template hardcoded, and a project name fills in for a
+      // template that names nothing).
+      //
+      // Earlier versions of this code parsed both files through
+      // js-yaml, merged the objects, and re-emitted the result via
+      // yaml.dump() — which stripped every comment and blank line on
+      // the way through. For templates like `cv/site/site.yml.hbs`
+      // whose comments are the template's educational payload, that
+      // was devastating. The line-level override below preserves the
+      // content template's text verbatim except for the preserved keys.
+      const preserveKeys = mergeFiles[outputName]
+      if (preserveKeys && existsSync(targetPath)) {
+        const existingContent = await fs.readFile(targetPath, 'utf-8')
+        const existing = yaml.load(existingContent) || {}
+        let merged = newContent ?? (await fs.readFile(sourcePath, 'utf-8'))
+
+        for (const [key, when] of preserveKeys) {
+          if (existing[key] === undefined) continue
+          const baseLine = matchTopLevelLine(existingContent, key)
+          if (!baseLine) continue
+          // If the new content carries the key, replace its line with
+          // the scaffolded value — unless the key only fills in, and the
+          // template set a value of its own. Otherwise insert the line —
+          // older content templates (notably `docs/site/site.yml.hbs`) omit
+          // `foundation:` entirely, and dropping it leaves the site without a
+          // foundation ref so the entry's `import '#foundation/styles'` fails
+          // at build time.
+          if (matchTopLevelLine(merged, key)) {
+            if (when === 'when-template-has-none' && hasOwnValue(merged, key)) {
+              continue
+            }
+            merged = replaceTopLevelLine(merged, key, baseLine)
+          } else {
+            merged = insertTopLevelLine(merged, baseLine)
+          }
+        }
+
+        await fs.writeFile(targetPath, merged)
+      } else if (newContent !== undefined) {
+        await fs.writeFile(targetPath, newContent)
+      } else {
+        // Copy as-is
+        await fs.copyFile(sourcePath, targetPath)
+      }
+
+      if (options.onProgress) {
+        options.onProgress(`Creating ${outputName}`)
+      }
+    }
+  }
+}
+
+/**
+ * Apply the built-in starter content
+ *
+ * The starter ships its foundation content under `cli/starter/foundation/`
+ * (a description of the *kind* of content), and is applied into whatever
+ * folder the workspace uses for the foundation package — which is `src/`
+ * in the current single-foundation layout, not `foundation/`. Callers
+ * can override via options when scaffolding multi-foundation workspaces.
+ *
+ * @param {string} projectDir - Root project directory
+ * @param {Object} context - Template context
+ * @param {Object} [options] - Processing options
+ * @param {string} [options.foundationDir] - Foundation directory name (default: 'src')
+ * @param {string} [options.siteDir] - Site directory name (default: 'site')
+ */
+export async function applyStarter(projectDir, context, options = {}) {
+  const foundationDir = options.foundationDir || 'src'
+  const siteDir = options.siteDir || 'site'
+
+  // Apply foundation starter content
+  const foundationContentDir = join(STARTER_DIR, 'foundation')
+  const foundationTargetDir = join(projectDir, foundationDir)
+  await applyContent(
+    foundationContentDir,
+    foundationTargetDir,
+    context,
+    options
+  )
+
+  // Apply site starter content
+  const siteContentDir = join(STARTER_DIR, 'site')
+  const siteTargetDir = join(projectDir, siteDir)
+  await applyContent(siteContentDir, siteTargetDir, context, options)
+}
+
+/**
+ * Escape a string for safe inclusion in a RegExp literal. Used by the
+ * site.yml line-level merge path.
+ */
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Whether a content template sets `key` to a value of its own: a non-empty
+ * string that is not an unrendered `{{placeholder}}` (a plain `site.yml`, not
+ * `.hbs`, is copied without rendering). Content that does not parse counts as
+ * setting nothing, so the scaffolded value fills in, as it always did.
+ */
+function hasOwnValue(content, key) {
+  let value
+  try {
+    value = (yaml.load(content) || {})[key]
+  } catch {
+    return false
+  }
+  return typeof value === 'string' && value.trim() !== '' && !value.includes('{{')
+}
+
+/**
+ * Find the verbatim text of a single-line top-level YAML entry like
+ * `name: foo bar` or `foundation: my-foundation`. Returns the matched
+ * line (including any inline comment) or null if the key isn't present.
+ * Multi-line values (block scalars, nested maps) are deliberately
+ * unsupported — the merge path only uses this for simple scalar keys.
+ */
+function matchTopLevelLine(content, key) {
+  const match = content.match(new RegExp(`^${escapeRegex(key)}:.*$`, 'm'))
+  return match ? match[0] : null
+}
+
+/**
+ * Replace the verbatim text of a single-line top-level YAML entry.
+ * Returns the content unchanged if the key isn't present. See
+ * matchTopLevelLine for scope.
+ */
+function replaceTopLevelLine(content, key, replacement) {
+  return content.replace(
+    new RegExp(`^${escapeRegex(key)}:.*$`, 'm'),
+    () => replacement
+  )
+}
+
+/**
+ * Insert a top-level YAML line into a content string.
+ *
+ * Used by the merge path when the content template omits a key that
+ * the scaffolded base file declared (e.g. an older `site.yml.hbs` with
+ * no `foundation:` line). Inserts immediately after the `name:` line
+ * if one exists — that's the conventional position for site
+ * configuration — and otherwise prepends to the file. The original
+ * trailing newline (or lack thereof) of the file is preserved.
+ */
+function insertTopLevelLine(content, line) {
+  const nameMatch = content.match(/^name:.*$/m)
+  if (nameMatch) {
+    const idx = nameMatch.index + nameMatch[0].length
+    return content.slice(0, idx) + '\n' + line + content.slice(idx)
+  }
+  return line + '\n' + content
+}
+
+/**
+ * Resolve a dependency version string from a template.json entry.
+ *
+ * Template authors can either hardcode a concrete spec (`"^0.2.1"`) or
+ * use the same `{{version}}` Handlebars helper that `package.json.hbs`
+ * uses (`"{{version \"@uniweb/press\"}}"`). The helper is populated
+ * earlier in the scaffold flow via `registerVersions()`, so by the time
+ * this runs `versionData` already holds the current on-disk versions
+ * of every `@uniweb/*` package.
+ *
+ * Plain strings without `{{…}}` pass through untouched. Strings that
+ * fail to compile (rare — e.g. malformed mustache) fall back to the
+ * original literal so a bad template.json doesn't break scaffolding.
+ */
+function resolveDependencyVersion(rawValue) {
+  if (typeof rawValue !== 'string' || !rawValue.includes('{{')) {
+    return rawValue
+  }
+  try {
+    return Handlebars.compile(rawValue)({})
+  } catch {
+    return rawValue
+  }
+}
+
+/**
+ * Merge additional dependencies from a content template into a scaffolded package.json
+ *
+ * Reads the package.json at the given path, adds any deps not already present
+ * (in either dependencies or devDependencies), and writes it back.
+ *
+ * Each version string in `deps` is first processed through the shared
+ * Handlebars pipeline so template.json entries can reference live
+ * workspace versions via `{{version "@uniweb/press"}}` instead of
+ * hardcoding a spec that goes stale on the next publish.
+ *
+ * @param {string} packageJsonPath - Absolute path to package.json
+ * @param {Object} deps - Dependencies to merge (name → version spec)
+ */
+export async function mergeTemplateDependencies(packageJsonPath, deps) {
+  if (!deps || Object.keys(deps).length === 0) return
+  const src = await fs.readFile(packageJsonPath, 'utf-8')
+  const pkg = JSON.parse(src)
+  if (!pkg.dependencies) pkg.dependencies = {}
+  for (const [name, version] of Object.entries(deps)) {
+    if (!pkg.dependencies[name] && !pkg.devDependencies?.[name]) {
+      pkg.dependencies[name] = resolveDependencyVersion(version)
+    }
+  }
+  await writeJsonPreservingStyleAsync(packageJsonPath, pkg, src)
+}

package/src/utils/schemaless-report.js

@@ -0,0 +1,30 @@
+/**
+ * Report queries publishing without a data schema.
+ *
+ * ⭐ This is a PRODUCT decision the author is making, usually without knowing:
+ * entities or static files. It is reported at warn level for that reason — the
+ * producer deliberately emits a structured entry rather than a prose warning so
+ * this can say what the trade actually is.
+ *
+ * The old line said `"… — not synced"`, dim, among everything else. The data IS
+ * delivered (as static files), so that read as "my data did not upload" to
+ * anyone who did not skim past it. Neither reading tells an author what they
+ * gave up or how to get it back.
+ *
+ * @param {Array<{name: string, model?: string}>} schemaless
+ * @param {{ warn: (m: string) => void, dim: (m: string) => void }} out
+ */
+export function reportSchemalessQueries(schemaless, out) {
+  if (!schemaless?.length) return
+  const names = schemaless.map((c) => c.name)
+  const label = names.length === 1 ? 'query' : 'queries'
+  out.warn(
+    `${names.length} ${label} shipping as STATIC FILES, not entities: ${names.join(', ')}`
+  )
+  out.dim('No queries, no editor, no detail projection — and a republish to change the data.')
+  out.dim(
+    `Declare a data schema to get entities. Each resolves its schema by subfolder name (${schemaless
+      .map((c) => `${c.name} → ${c.model || c.name}`)
+      .join(', ')}), or set \`schema:\` on the query.`
+  )
+}

package/src/utils/semver-precedence.js

@@ -0,0 +1,80 @@
+/**
+ * SemVer 2.0.0 precedence — how a registry orders a foundation's versions.
+ *
+ * A pre-release sorts below its release (`1.0.0-rc.1` < `1.0.0`), and build
+ * metadata carries no order (`1.2.0+b` equals `1.2.0`).
+ *
+ * ⚖️ Not `compareSemver` in `dep-survey.js`: that one reads dependency specs
+ * (`^1.2.3`) for `uniweb update` and compares major.minor.patch only. This one
+ * is strict — anything that is not a SemVer version is `null`, never a guess.
+ */
+
+// The regex published with the SemVer 2.0.0 specification (semver.org, §FAQ).
+const SEMVER =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/
+
+/**
+ * @param {unknown} version
+ * @returns {{ major: number, minor: number, patch: number, pre: string[] }|null}
+ */
+export function parseSemver(version) {
+  if (typeof version !== 'string') return null
+  const m = SEMVER.exec(version)
+  if (!m) return null
+  return { major: +m[1], minor: +m[2], patch: +m[3], pre: m[4] ? m[4].split('.') : [] }
+}
+
+/**
+ * The next version above `version` on its own line — what `--bump` releases under
+ * when the registry already holds the local version with other code.
+ *
+ * A release gets its next patch (`1.4.2` → `1.4.3`); a pre-release its next
+ * pre-release (`2.0.0-beta.3` → `2.0.0-beta.4`, `1.0.0-rc` → `1.0.0-rc.0`), so a bump
+ * nobody chose never promotes a beta line to a release. Build metadata is dropped: it
+ * carries no order, so it could not make a version newer.
+ *
+ * @param {string} version
+ * @returns {string|null} null when `version` is not SemVer
+ */
+export function nextVersionAbove(version) {
+  const v = parseSemver(version)
+  if (!v) return null
+  if (!v.pre.length) return `${v.major}.${v.minor}.${v.patch + 1}`
+  const pre = [...v.pre]
+  const last = pre.length - 1
+  if (/^\d+$/.test(pre[last])) pre[last] = String(BigInt(pre[last]) + 1n)
+  else pre.push('0')
+  return `${v.major}.${v.minor}.${v.patch}-${pre.join('.')}`
+}
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1|0|1|null} how `a` sorts against `b`; null when either is not SemVer
+ */
+export function compareSemverPrecedence(a, b) {
+  const x = parseSemver(a)
+  const y = parseSemver(b)
+  if (!x || !y) return null
+  for (const part of ['major', 'minor', 'patch']) {
+    if (x[part] !== y[part]) return x[part] > y[part] ? 1 : -1
+  }
+  // A version with a pre-release sorts below the same version without one.
+  if (!x.pre.length || !y.pre.length) {
+    return x.pre.length === y.pre.length ? 0 : x.pre.length ? -1 : 1
+  }
+  for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+    const p = x.pre[i]
+    const q = y.pre[i]
+    if (p === undefined) return -1
+    if (q === undefined) return 1
+    if (p === q) continue
+    const pNum = /^\d+$/.test(p)
+    const qNum = /^\d+$/.test(q)
+    // Numeric identifiers compare numerically and sort below alphanumeric ones.
+    if (pNum && qNum) return BigInt(p) > BigInt(q) ? 1 : -1
+    if (pNum !== qNum) return pNum ? -1 : 1
+    return p > q ? 1 : -1
+  }
+  return 0
+}

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
+}