uniweb 0.59.2 → 0.61.0

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 }

package/templates/site/site.yml.hbs

@@ -25,7 +25,7 @@ index: home
 #   pages/docs: ../../../docs       # Mount docs repo at /docs route
 #   pages/blog: ../../blog-content  # Mount blog content at /blog route
 #   layout: ./custom-layout         # Custom layout directory
-#   entities: ./data                # Where this site's entities live
+#   records: ./data                 # Where this site's records live
 #
 # To give a mounted route a layout or a title, add a local folder for it
 # (pages/docs/) holding a folder.yml — folder.yml, not page.yml, because the
@@ -41,14 +41,16 @@ index: home
 # ─── Structured Content ───────────────────────────────────────────────────────
 # Three things, and they are separate on purpose:
 #
-#   entities/{schema}/   your stored records. The folder names their data schema:
-#                          entities/article/       → @/article  (your foundation's)
-#                          entities/std/person/    → @std/person
-#   records.yml          WHAT IS PUBLISHED. Listing an entity here is what makes it
-#                        a record; anything you leave out is a draft. Usually three
-#                        lines:
-#                            - article/*.md
-#                            - person/*.md
+#   records/{schema}/    your site's records — every file here is one. The folder
+#                        names their data schema:
+#                          records/article/        → @/article  (your foundation's)
+#                          records/std/person/     → @std/person
+#                        A file whose name starts with `_` is not a record.
+#   records.yml          OPTIONAL — sorts records into folders a query can slice
+#                        with `scope:`. Most sites have none:
+#                            - folder: archive
+#                              records:
+#                                - article/2025-*.md
 #   queries.yml          HOW CONTENT IS REACHED — named queries over those records:
 #                            recent:
 #                              schema: '@/article'