uniweb 0.59.1 → 0.60.0

package/src/utils/site-copies.js

@@ -0,0 +1,123 @@
+/**
+ * Is this project a copy of another one in the same workspace?
+ *
+ * A plain directory copy carries `sync.json`, so the copy holds the ORIGINAL's site
+ * on every backend the original synced with — and its first push updates that site.
+ * `uniweb forget --all` in the copy is the fix. This is how the CLI notices a copy in
+ * which nobody ran it, before the push goes out.
+ *
+ * ## The signal, and why it is exact
+ *
+ * **Two directories in one workspace holding the same site uuid on the same
+ * backend.** Every create mints a new site, so two directories can only name one site
+ * if one got it from the other. Whichever of them pushes, the other is a stale copy
+ * of the same site waiting to overwrite it — so refusing is right from both sides.
+ *
+ * ## Why only within a workspace
+ *
+ * A teammate's clone holds the same site too, and legitimately: it IS the same
+ * project. A clone is a separate checkout, so it is never scanned. The price is the
+ * case this cannot see: a copy placed outside the workspace is byte-for-byte a clone,
+ * and nothing on disk tells them apart.
+ *
+ * ## Where it looks
+ *
+ * The workspace root and two levels below it — where sites live (`site/`, `sites/*`)
+ * and where a copy usually lands — plus this site's own siblings, for a site deeper
+ * than that. Dot-directories, `node_modules` and `dist` are skipped, and the walk is
+ * bounded, so a workspace root found somewhere unexpected costs a few milliseconds,
+ * not a disk scan.
+ */
+
+import { existsSync, readdirSync, realpathSync } from 'node:fs'
+import { dirname, isAbsolute, join, relative } from 'node:path'
+import { findWorkspaceRoot } from './workspace.js'
+import { normalizeOrigin, readSiteIdentity } from './site-identity.js'
+
+const SKIP = new Set(['node_modules', 'dist'])
+const MAX_ENTRIES = 5000
+
+const real = (p) => {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
+const within = (dir, root) => {
+  const rel = relative(root, dir)
+  return !rel.startsWith('..') && !isAbsolute(rel)
+}
+
+/** Directories holding a `sync.json`, `depth` levels below `dir` at most. */
+function collect(dir, depth, out, budget) {
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    if (--budget.left < 0) return
+    if (!entry.isDirectory() || entry.name.startsWith('.') || SKIP.has(entry.name)) continue
+    const child = join(dir, entry.name)
+    if (existsSync(join(child, 'sync.json'))) out.add(child)
+    if (depth > 1) collect(child, depth - 1, out, budget)
+  }
+}
+
+/**
+ * The other directories in this workspace that hold this site's site on `origin`.
+ *
+ * @param {string} siteDir
+ * @param {string} origin - the backend a push is about to go to
+ * @returns {string[]} absolute paths, sorted; `[]` when the site has no identity on
+ *   that backend yet (its push will create one), or it is in no workspace
+ */
+export function findSiteCopies(siteDir, origin) {
+  const key = normalizeOrigin(origin)
+  const mine = key ? readSiteIdentity(siteDir, key).uuid : null
+  if (!mine) return []
+  const root = findWorkspaceRoot(siteDir)
+  if (!root) return []
+
+  const candidates = new Set()
+  const budget = { left: MAX_ENTRIES }
+  if (existsSync(join(root, 'sync.json'))) candidates.add(root)
+  collect(root, 2, candidates, budget)
+  const parent = dirname(siteDir)
+  if (real(siteDir) !== real(root) && within(parent, root)) collect(parent, 1, candidates, budget)
+
+  const self = real(siteDir)
+  const found = []
+  for (const dir of candidates) {
+    if (real(dir) === self) continue
+    if (readSiteIdentity(dir, key).uuid === mine) found.push(dir)
+  }
+  return found.sort()
+}
+
+/**
+ * What to tell the person, as a headline and detail lines — each verb prints them
+ * with its own reporter.
+ *
+ * ⚖️ It cannot say WHICH directory is the copy: the two are identical, which is the
+ * whole problem. The person knows, because they made it.
+ *
+ * @param {string[]} copies - from findSiteCopies
+ * @param {string} origin
+ * @param {'push'|'publish'} verb
+ */
+export function describeSiteCopies(copies, origin, verb) {
+  const here = (dir) => relative(process.cwd(), dir) || '.'
+  return {
+    headline: `Another project in this workspace holds the same site on ${origin}:`,
+    lines: [
+      ...copies.map((dir) => `  ${here(dir)}`),
+      `One of them is a copy of the other, so a ${verb} from either one updates that site.`,
+      'In the copy, run:  uniweb forget --all',
+      `The copy then ${verb === 'publish' ? 'publishes' : 'pushes'} as a new site. The original needs nothing.`
+    ]
+  }
+}

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

@@ -19,9 +19,10 @@
  *
  * ## Why this is not the asset lane
  *
- * Assets are **global and content-addressed** — identical bytes dedup across
- * sites — so the relation from a site's path to an object is many-to-one and a
- * serve path cannot be a property of the object. This lane is **per-site and
+ * Assets are **content-addressed, and dedup across the sites of one backend**
+ * — so the relation from a site's path to an object is many-to-one and a serve
+ * path cannot be a property of the object. *("Global" names that dedup scope; it
+ * never meant across backends — see utils/asset-upload.js.)* This lane is **per-site and
  * path-addressed**. Sending static data through the asset store is what forced
  * the old "data ball": one bundled asset the backend had to fetch, parse and
  * fan out, which is the only place these bytes ever transited it.

package/src/utils/site-identity.js

@@ -1,347 +1,137 @@
 /**
- * The project's SYNC SCOPE — reading and asserting `site.yml::$backend`.
+ * The project's backend-minted identity — read from `sync.json`, never from `site.yml`.
  *
- * A project that has synced holds backend-minted identity on **four** surfaces:
+ * ⭐ **`site.yml` holds nothing a backend minted, as of 2026-09-20.** It carried
+ * `$uuid`, `$org` and `$backend`; all three moved to
+ * `sync.json::backends.<origin>.site`, keyed by the backend that minted them.
+ * Spec: `kb/framework/reference/sync-json.md`. Why:
+ * `kb/framework/plans/backend-scoped-project-state.md`.
  *
- *   · `site.yml::$uuid`               the site-content entity
- *   · every collection record `$uuid` in its own source file (the pull-side match key)
- *   · `assets.json`                   local asset path → content-addressed id
- *   · `.uniweb/sync-cache.json`       item uuids, hashes, base versions
+ * ## ⛔ What is GONE, and why nothing replaces it
  *
- * All four are meaningless against a different backend, and none of them says which
- * backend it came from. `$backend` is the one fact that scopes all of them — which is
- * why a mismatch is a **stop**, not a fallback: it does not mean "we guessed the wrong
- * default", it means the entire stored surface is foreign.
+ * `assertSiteBackendScope` refused a command whose resolved origin disagreed with
+ * the project's recorded `$backend`. It existed because ONE `$uuid` sat in
+ * `site.yml` with no way to say which backend it was for, so it could be read
+ * against the wrong one and sent there.
  *
- * ⛔ **`$backend` is absent for the default backend, deliberately.** The 98% case keeps a
- * clean `site.yml`, and an absent value reads as the default — correct both for a project
- * written before this key existed and for one synced against the default. That inference
- * is monotone: it is never worse than the pre-`$backend` behaviour, which recorded nothing
- * at all.
+ * ⭐ **Keyed by origin that is unrepresentable.** A command for backend B reads B's
+ * section and finds B's ids or nothing at all. There is no configuration in which
+ * A's identity reaches B, so there is no mismatch to detect, no stop to print, and
+ * no accepted false positive to live with. The guard is not replaced; the shape it
+ * guarded against stopped existing.
  *
- * ⚠️ **Reads `site.yml` only, not the legacy `site.yaml`.** That matches every existing
- * identity reader AND all three writers (`writeSiteEntityUuid`, `writeSiteOrg`,
- * `clone.js`'s `seedYamlUuid`), so this module is consistent with what is on disk. It is
- * also a KNOWN GAP, not an oversight: five other readers do accept `site.yaml`, and
- * `upsertYamlScalar` creates a file when missing — so on a `site.yaml` project the writers
- * produce a phantom `site.yml` holding nothing but identity. Closing that is its own change,
- * and it has to move the readers and the writers together or it makes the split worse.
+ * `recordSiteBackend` and `$backend` went with it: the store's KEY is the scope.
+ *
+ * ## ⛔ NO STATIC `@uniweb/build` IMPORT
+ *
+ * This module is reachable from the CLI's startup graph, and `@uniweb/build` is an
+ * OPTIONAL PEER — a static import makes `uniweb --version` die with
+ * ERR_MODULE_NOT_FOUND on a global install (`test/smoke-startup.test.js` catches it).
+ *
+ * ⭐ **`sync.json` is plain JSON, so reading it needs no parser and no dependency.**
+ * That is the whole reason the format is JSON rather than YAML: `site.yml`'s
+ * equivalent needed a hand-rolled dependency-free fallback WRITER to survive the
+ * same constraint. Writes go through `@uniweb/build/uwx`'s store, which is the one
+ * implementation; this file only reads.
  */
 
-import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import yaml from 'js-yaml'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
 import { DEFAULT_BACKEND_ORIGIN } from './config.js'
 
-// ⛔ NO STATIC `@uniweb/build` IMPORT IN THIS FILE — it is an OPTIONAL PEER, and this
-// module is reachable from the CLI's startup graph (`index.js` imports `clone` eagerly,
-// and `clone` imports this). A static import here makes `uniweb --version` die with
-// ERR_MODULE_NOT_FOUND on a global install that has no build package:
-//
-//   $ npm i -g uniweb && uniweb --version
-//   Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@uniweb/build'
-//
-// `test/smoke-startup.test.js` catches this structurally — and did, on the commit that
-// introduced this file. The writer below therefore imports lazily, which also keeps the
-// cost off every startup that never writes. Command modules may import build statically;
-// anything a `utils/` leaf pulls in cannot.
-
 /** A bare origin with no trailing slash, or null when unparseable. */
 export function normalizeOrigin(value) {
   if (typeof value !== 'string' || !value.trim()) return null
   try {
-    return new URL(value).origin
+    // 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
   }
 }
 
 /**
- * The project's identity trio, read from `site.yml`. Every field is independently
- * optional — a project may be unsynced (no `uuid`), on the default backend (no
- * `backend`), or personally owned (no `org`).
+ * `sync.json`'s backends map, or `{}`. Read-only, dependency-free — see the header.
  *
- * ⚠️ This is NOT yet the single accessor for `$uuid`. Nine other places still read it
- * directly; they are correct as they stand and were deliberately left alone when the
- * scope check was centralized here (a per-read accessor was solving a coupling problem
- * that one guard solves better). Consolidating them is separable cleanup.
- *
- * @param {string} siteDir
- * @returns {{ uuid: string|null, backend: string|null, org: string|null }}
+ * ⚠️ A second READER of a format whose writer lives in `@uniweb/build`. Deliberate,
+ * and bounded: it parses one object and normalizes its keys. The shape it assumes is
+ * exactly what `sync-store.js` writes, and `test/two-backends.test.js` drives both.
  */
-export function readSiteIdentity(siteDir) {
-  const path = join(siteDir, 'site.yml')
-  if (!existsSync(path)) return { uuid: null, backend: null, org: null }
-  let y
+function readBackends(siteDir) {
+  const p = join(siteDir, 'sync.json')
+  if (!existsSync(p)) return {}
   try {
-    y = yaml.load(readFileSync(path, 'utf8'))
+    const parsed = JSON.parse(readFileSync(p, 'utf8'))
+    const backends = parsed?.backends
+    if (!backends || typeof backends !== 'object' || Array.isArray(backends)) return {}
+    const out = {}
+    for (const [origin, state] of Object.entries(backends)) {
+      const key = normalizeOrigin(origin)
+      if (key && state && typeof state === 'object') out[key] = state
+    }
+    return out
   } catch {
-    // Unreadable or malformed — report "nothing recorded" rather than throwing. Every
-    // caller here is a guard or a default; none of them should be the reason a command
-    // dies, and a malformed site.yml has its own, better error elsewhere.
-    return { uuid: null, backend: null, org: null }
-  }
-  if (!y || typeof y !== 'object') return { uuid: null, backend: null, org: null }
-  const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null)
-  return {
-    uuid: str(y.$uuid),
-    backend: normalizeOrigin(y.$backend),
-    org: str(y.$org)
+    return {}
   }
 }
 
 /**
- * The backend this project is bound to, with the default filled in.
- *
- * Use this rather than `readSiteIdentity().backend` wherever an absent value means the
- * default — which is everywhere except a "was it recorded?" question.
- *
- * ⛔ **NOT for the origin ladder.** `resolveBackendOrigin`'s `siteScope` tier must receive
- * the RAW `readSiteIdentity().backend`, which is null when nothing was recorded. Handing
- * it this defaulted value would make the tier fire for EVERY project, and since it sits
- * above the session it would shadow `uniweb login --backend <local>` on any project
- * without `$backend` — i.e. break local development for the 98% that never record one.
- * "Absent means the default" is the right rule for a comparison and the wrong one for a
- * precedence chain, where absent has to mean "defer to the next tier".
+ * The identity this project holds for ONE backend.
  *
  * @param {string} siteDir
- * @returns {string} a bare origin
+ * @param {string} origin
+ * @returns {{ uuid: string|null, org: string|null }}
  */
-export function resolveSiteScope(siteDir) {
-  return readSiteIdentity(siteDir).backend || DEFAULT_BACKEND_ORIGIN
+export function readSiteIdentity(siteDir, origin) {
+  const key = normalizeOrigin(origin)
+  const site = key ? readBackends(siteDir)[key]?.site : null
+  const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null)
+  return { uuid: str(site?.uuid), org: str(site?.org) }
 }
 
-/**
- * Record the sync scope on a site that has just been created or seeded.
- *
- * A no-op for the default backend (see the ⛔ above) and a no-op when the value is
- * already what we would write, so a re-push never dirties `git status`.
- *
- * @param {string} siteDir
- * @param {string} origin - the backend the site was just created on
- * @param {object} [deps]
- * @param {() => Promise<object>} [deps.loadUwx] - injected module loader. Exists so the
- *        two failure branches below can be TESTED: both are about which `@uniweb/build`
- *        happens to be on disk, which a test cannot otherwise vary — and the too-old
- *        branch is precisely the one that used to fail silently.
- * @returns {Promise<string|null>} the origin recorded, or null when nothing was written
- */
-export async function recordSiteBackend(siteDir, origin, deps = {}) {
-  const norm = normalizeOrigin(origin)
-  if (!norm || norm === DEFAULT_BACKEND_ORIGIN) return null
-  if (readSiteIdentity(siteDir).backend === norm) return null
-  const loadUwx = deps.loadUwx || (() => import('@uniweb/build/uwx'))
-  let mod
-  try {
-    // Lazy by necessity, not by taste — see the header.
-    mod = await loadUwx()
-  } catch {
-    // ⛔ NO `@uniweb/build` — and this is the COMMON case on the path that needs it
-    // most, not the rare one this branch used to assume.
-    //
-    // `clone` calls us straight after scaffolding and BEFORE `pnpm install`, so the
-    // site has no `node_modules` yet; under `npx uniweb@latest` the CLI's own tree
-    // may not carry build either (it is an optional peer). The import therefore
-    // fails on a FRESH CLONE essentially always, and returning null wrote nothing.
-    //
-    // The cost is not cosmetic: the clone then holds a `$uuid` minted by the
-    // `--backend` origin it was given, with nothing recording that origin, so the
-    // scope guard infers the DEFAULT backend and stops the very next command with
-    // "this project's stored identity belongs to https://uniweb.app". The origin was
-    // on the command line the whole time.
-    // Measured by the backend lane 2026-09-18: `0.48.5` recorded `$backend`,
-    // `0.57.0` did not, and their clone was unusable until they added the line by hand.
-    //
-    // ⇒ Fall back to a dependency-free write. `js-yaml` is the CLI's own direct
-    // dependency, so this path needs nothing installed in the project.
-    return writeSiteBackendFallback(siteDir, norm)
-  }
-
-  // ⚠️ PRESENT BUT TOO OLD is a different problem, and it must not look like the one
-  // above. `@uniweb/build` gained `writeSiteBackend` in 0.25.3; against an older copy the
-  // import SUCCEEDS and the export is `undefined`, so calling it throws a TypeError that
-  // a blanket catch would swallow — leaving the scope silently unrecorded on a project
-  // that will later be stopped by the guard and told to add `$backend` by hand. Since the
-  // CLI declares build as a peer at a caret range, a lockfile pinned to an older patch
-  // reaches exactly this state on a CLI-only upgrade. Say so once.
-  if (typeof mod.writeSiteBackend !== 'function') {
-    console.error(
-      `\x1b[33m⚠\x1b[0m This project's @uniweb/build is too old to record which backend it syncs with — upgrade it (\`npx uniweb@latest update\`), or add \`$backend: ${norm}\` to site.yml.`
-    )
-    return null
-  }
-
-  try {
-    mod.writeSiteBackend(siteDir, norm)
-    return norm
-  } catch {
-    // Same rule as `recordSiteOrg`: the uuid is the load-bearing write. Losing the scope
-    // note must never fail a create that already succeeded on the backend — the guard
-    // degrades to the pre-`$backend` behaviour, which is what everyone had until now.
-    return null
-  }
+/** Every backend this project has synced with, sorted. */
+export function syncedBackends(siteDir) {
+  return Object.keys(readBackends(siteDir)).sort()
 }
 
 /**
- * Write `$backend` into `site.yml` without `@uniweb/build` — the fallback for a
- * project whose dependencies are not installed yet (see `recordSiteBackend`).
+ * The backends this project HAS synced with, when `origin` is not one of them — or null.
  *
- * ⭐ Verifies the RESULT rather than trusting the edit: the file must still parse and
- * must read back the origin we meant to write. A write that corrupts `site.yml` would
- * be far worse than an unrecorded scope — an unparseable `site.yml` is the failure this
- * same channel spent an evening on.
+ * Every backend verb goes to the backend the user is logged in to *[Diego, 2026-09-21]*,
+ * so it can land where this project has no site while it has one elsewhere. A push
+ * there CREATES a second site rather than updating the one the project knows, and the
+ * owner question it asks does not say why — this is what lets the verb say it first.
  *
- * @returns {string|null} the recorded origin, or null when nothing was written
+ * @param {string} siteDir
+ * @param {string} origin - where the verb resolved to
+ * @returns {string[]|null}
  */
-function writeSiteBackendFallback(siteDir, norm) {
-  const file = join(siteDir, 'site.yml')
-  let text
-  try {
-    text = readFileSync(file, 'utf8')
-  } catch {
-    return null // no site.yml — nothing to annotate, and we do not create one
-  }
-  try {
-    // Quote through js-yaml rather than by hand: an origin is plain today, but the
-    // value is not ours to assume. Replace an existing key, else prepend.
-    const scalar = yaml.dump(norm, { lineWidth: -1 }).trim()
-    const next = /^\$backend:/m.test(text)
-      ? text.replace(/^\$backend:.*$/m, `$backend: ${scalar}`)
-      : `$backend: ${scalar}\n` + text
-    const parsed = yaml.load(next)
-    if (!parsed || typeof parsed !== 'object' || parsed.$backend !== norm) return null
-    writeFileSync(file, next)
-    return norm
-  } catch {
-    return null
-  }
+export function syncedElsewhere(siteDir, origin) {
+  const key = normalizeOrigin(origin)
+  const known = syncedBackends(siteDir)
+  if (!key || !known.length || known.includes(key)) return null
+  return known
 }
 
 /**
- * Refuse to act on a site whose stored identity belongs to a different backend.
+ * The heads-up for `syncedElsewhere`, as lines — each verb prints them with its own
+ * reporter. Only worth saying when the verb was not TOLD where to go: a `--backend` the
+ * user typed is already a decision.
  *
- * ⭐ **A stop, not a warning.** `BackendClient.token()` already carries an advisory
- * origin-mismatch guard for the SESSION (wrong bearer → a rejected request, recoverable).
- * This is the third leg and it is categorically worse: the stored surface is foreign, so
- * proceeding sends one backend's identity to another. The observed outcomes are a 404
- * whose stock advice destroys the binding, and — on the record lane — a hard refusal
- * (*"item uuids are globally unique; cross-entity move is not supported"*).
+ * ⚖️ Worded for where the verb GOES, not for why: it is the logged-in backend, or — logged
+ * in nowhere — the default one, where the login it is about to ask for will be.
  *
- * Silent for an unsynced project (nothing stored yet ⇒ nothing to be foreign) and for a
- * project on the default backend with no explicit override.
- *
- * @param {string} siteDir
- * @param {string} origin - the backend this command resolved to
- * @returns {{ ok: true } | { ok: false, message: string, hint: string[] }}
+ * @param {string[]} known
+ * @param {string} origin
+ * @param {'push'|'publish'} verb
  */
-export function assertSiteBackendScope(siteDir, origin) {
-  const { uuid, backend } = readSiteIdentity(siteDir)
-  // Nothing minted here yet — a create is exactly what is supposed to happen next, and
-  // it will record the scope itself. Checking a project with no stored identity would
-  // reject the first push of every new site.
-  if (!uuid) return { ok: true }
-
-  const target = normalizeOrigin(origin)
-  const bound = backend || DEFAULT_BACKEND_ORIGIN
-  if (!target || target === bound) return { ok: true }
-
-  const hint = [
-    `site.yml::$uuid (${uuid}) was minted by ${bound}, and the record uuids, assets.json`,
-    'and .uniweb/sync-cache.json are scoped to it too. Sending them elsewhere is refused.',
-    '',
-    `To work with ${bound}:  uniweb login --backend ${bound}   (or pass --backend ${bound})`,
-    `To move this project to ${target}, it becomes a NEW site there — clear $uuid, $org and`,
-    '$backend from site.yml and delete .uniweb/ and assets.json first.'
+export function describeSyncedElsewhere(known, origin, verb) {
+  const where = known.length === 1 ? `site is on ${known[0]}` : `sites are on ${known.join(', ')}`
+  return [
+    `This project's ${where} — not on ${origin}, where this ${verb} goes.`,
+    `It creates a new site there. To ${verb} to ${known.length === 1 ? 'that one' : 'one of those'} instead: uniweb login --backend <url>`
   ]
-
-  // ⚠️ THE ONE FALSE POSITIVE, and it prints its own fix.
-  //
-  // `$backend` is omitted for the default backend, so an ABSENT value is ambiguous: it
-  // means "the default" for anything written under this scheme, and "unknown" for a
-  // project that synced to a non-default backend BEFORE the key existed. This branch
-  // reads absent as the default, so that second project is stopped and told it belongs
-  // to a backend it never used.
-  //
-  // Accepted deliberately rather than softened to a warning, because the alternative is
-  // worse in the case that matters: warning-on-absent would leave every DEFAULT-backend
-  // project — the 98% — unprotected forever, since those never record the key. Stopping
-  // on a guess is only tolerable when the guess prints the one-line correction, so it
-  // does. (The population at risk is also near-empty by construction: pre-`$backend`
-  // projects on a non-default backend, at a moment when no such backend is running.)
-  if (!backend) {
-    hint.push(
-      '',
-      `If this project actually syncs with ${target}, nothing recorded that — say so once:`,
-      `  add   $backend: ${target}   to site.yml, and this stops asking.`
-    )
-  }
-
-  return {
-    ok: false,
-    message: `This project's stored identity belongs to ${bound}, but this command targets ${target}.`,
-    hint
-  }
 }
 
-/**
- * The `$backend` of the site project `startDir` sits in — for verbs that are NOT site
- * verbs and so never resolve a site directory of their own.
- *
- * ⛔ **This does NOT feed the origin ladder, deliberately.** `login` writes a
- * MACHINE-WIDE session (`~/.uniweb/registry-auth.json`), not a per-project one, so
- * letting whichever directory you happen to stand in decide which backend you
- * authenticate against would be a silent surprise — the same class of surprise
- * `$backend` exists to remove. What this enables is a **notice**: the project says
- * where it belongs, so we say so before authenticating somewhere else.
- *
- * ⭐ **Conservative by construction — it answers only when there is exactly ONE
- * candidate.** A workspace of several sites has no single answer, and a confident
- * *"did you mean localhost?"* aimed at the wrong one of three sites is worse than
- * saying nothing. Ambiguity returns null and the caller stays quiet.
- *
- * ⚠️ Build-free, like everything else in this file — `login` is a STANDALONE command
- * that must work outside a project, where `@uniweb/build` is not installed. That is why
- * this cannot reuse `resolveSiteDir` (`commands/deploy.js`), which pulls build in.
- *
- * @param {string} startDir
- * @returns {{ siteDir: string, backend: string }|null}
- */
-export function findNearbySiteBackend(startDir) {
-  // 1. Walk UP for the site we are standing in or under. Bounded: a `site.yml` more
-  //    than a few levels above is not "the project you are in", it is a coincidence,
-  //    and at the filesystem root it would be someone else's entirely.
-  let dir = startDir
-  for (let i = 0; i < 4; i++) {
-    if (existsSync(join(dir, 'site.yml'))) {
-      const { backend } = readSiteIdentity(dir)
-      return backend ? { siteDir: dir, backend } : null
-    }
-    const up = dirname(dir)
-    if (up === dir) break
-    dir = up
-  }
-
-  // 2. Standing AT a project root, the site is one level down — `site/` in the default
-  //    layout, or a lone entry under `sites/`. Two or more candidates is a workspace,
-  //    which is exactly the ambiguity above.
-  const candidates = []
-  if (existsSync(join(startDir, 'site', 'site.yml')))
-    candidates.push(join(startDir, 'site'))
-  const sitesDir = join(startDir, 'sites')
-  if (existsSync(sitesDir)) {
-    let entries = []
-    try {
-      entries = readdirSync(sitesDir, { withFileTypes: true })
-    } catch {
-      entries = []
-    }
-    for (const e of entries) {
-      if (!e.isDirectory()) continue
-      const d = join(sitesDir, e.name)
-      if (existsSync(join(d, 'site.yml'))) candidates.push(d)
-    }
-  }
-  if (candidates.length !== 1) return null
-  const { backend } = readSiteIdentity(candidates[0])
-  return backend ? { siteDir: candidates[0], backend } : null
-}
+export { DEFAULT_BACKEND_ORIGIN }