uniweb 0.83.0 → 0.85.0

package/src/backend/service-request.js

@@ -1,68 +1,45 @@
 /**
- * The services request — is the file ASKING for something, or just carrying an
- * old answer?
+ * The requests a push or publish carries — what the owner asks for, and whether it
+ * is new.
  *
- * ## The defect this exists to close
+ * Two of them, kept by two mechanisms:
  *
- * `$services` / `$secrets` are Sections of the site-content document, so they ride
- * inside **every** push — the block is emitted whenever the key exists in
- * `site.yml`. Editing one paragraph on one page therefore re-sends the whole
- * request block.
+ *   - ⭐ **The services** — `site.yml::services`, a map by service name *[Diego,
+ *     2026-10-06]*. A push STATES them — the file's, and off for each held one it no
+ *     longer lists — and the backend decides per service from the versions sent
+ *     (`statedServices`, `@uniweb/build/uwx`; spec:
+ *     kb/framework/reference/site-services-request.md). All this module does for them
+ *     is say what the file asks that will not be sent (`announceServices`).
+ *   - **The language selection** — `site.yml::publishLanguages` — told apart from the
+ *     status quo by a fingerprint banked in `deploy.yml` (`reconcile`, `bankLanguages`).
  *
- * ⛔ And the backend REPLACES what it is sent: a row anchors by its natural key and
- * is updated in place (`SectionScope::DeclaredOnly`; backend's
- * `uuidless_records_anchor_by_natural_key_and_keep_the_stored_uuid`, written
- * against this emitter's shape). So a re-send is not a harmless echo — it
- * **overwrites the stored request**, including a decision the owner made in the
- * app, which is where the consent workflow's publish happens.
+ * ⭐ The model both follow — *"the services in `site.yml` are a request, never a
+ * tracking of what is running"* [Diego, 2026-09-05]. You ask by CHANGING the file.
  *
- * ⭐ Under the model the file follows — *"the services in `site.yml` are a request,
- * never a tracking of what is running"* [Diego, 2026-09-05] — **re-sending an
- * unchanged block is making a request nobody made.** You ask by CHANGING the file.
- *
- * ⚠️ It was mostly inert until 2026-09-08: `enabled` was honoured for `api` alone,
- * so a stale re-send of the other names overwrote rows nothing read. That stopped
- * being true the same day, and `api` was never inert — an `enabled: false` on it
- * with a live plan schedules a paid service to end.
- *
- * ## What "changed" is measured against
- *
- * The last block we are known to have sent, recorded in **`deploy.yml`** — a
- * COMMITTED project file that travels with a clone.
- *
- * ⛔ Deliberately NOT `.uniweb/sync-cache.json`, which is the obvious place and the
- * wrong one: it is gitignored, per-clone and deletable, so a teammate's fresh clone
- * has no base at all — and this workflow is multi-machine by construction (consent
- * in a browser, publish from the app). A base that vanishes turns this gate into
- * either the original defect or a silently dropped request.
- *
- * ## ⛔ A HASH, never the block
- *
- * `$secrets` names every secret the site has (values are the `#ref` marker, never
- * secret material — the old wording here said otherwise), and `$services[].config` is opaque and
- * per-service — anything may be in it. `deploy.yml` is committed, so recording
- * either verbatim would write them into git. Equality is all this gate needs;
- * *what* differs is a question for the backend's own copy of the request, not for
- * a mirror of our own.
+ * ⛔ *From 2026-09-20 to 2026-10-06 the services lived only in `sync.json`, which
+ * nobody edits, so a CLI user could ask for nothing; this module then compared them by
+ * a fingerprint in `deploy.yml`, which could not tell who moved; and until 2026-10-07
+ * it read the site's services before every push and settled each against a record in
+ * `sync.json` (`settleServices`), because the backend replaced the list it was sent.*
  *
  * @module
  */
 
 import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { readServicesRequest } from '@uniweb/build/uwx'
 
 /**
- * A stable fingerprint of one declared block, or `null` when the key is absent.
+ * A stable fingerprint of one declared value, or `null` when the key is absent.
  *
- * ⭐ `null` (absent) and the hash of `[]` are DIFFERENT, and must stay so: absent
- * means *"I am not telling you about this"* and `[]` is an explicit clear. This
- * function only has to preserve that distinction — the destructive difference
- * between them is the backend's.
+ * ⭐ `null` (absent) and the hash of `[]` are DIFFERENT, and must stay so: for the
+ * language selection, no key means "every declared language" and `[]` means none.
  *
- * Rows are ordered by their serialized form and object keys sorted, so reordering
- * rows or keys in the file is not a change. It is not a request to move a line.
+ * List entries are ordered by their serialized form and object keys sorted, so
+ * reordering them in the file is not a change.
  *
- * @param {*} declared - the raw value: provisioned `services` / `secrets` rows (from
- *   `sync.json`), what the site has stored for them, or `site.yml::publishLanguages`
+ * @param {*} declared
  * @returns {string|null} 16 hex chars, or null when undeclared
  */
 export function fingerprintDeclaration(declared) {
@@ -70,13 +47,10 @@ export function fingerprintDeclaration(declared) {
   const canonical = Array.isArray(declared)
     ? declared.map(stableString).sort()
     : [stableString(declared)]
-  return createHash('sha256')
-    .update(JSON.stringify(canonical))
-    .digest('hex')
-    .slice(0, 16)
+  return createHash('sha256').update(JSON.stringify(canonical)).digest('hex').slice(0, 16)
 }
 
-/** Absent, or an empty list — a stored request that asks for nothing. */
+/** Absent, or an empty list — a stored value that asks for nothing. */
 function isNothing(value) {
   return value === undefined || value === null || (Array.isArray(value) && value.length === 0)
 }
@@ -91,125 +65,22 @@ function stableString(value) {
 }
 
 /**
- * Both blocks' fingerprints, in the shape `deploy.yml::lastDeploy.<target>` keeps
- * them. Keys are omitted rather than set to null, so an undeclared block leaves no
- * trace in the file.
+ * A two-way request field, reconciled against what the site has stored.
  *
- * @param {object} siteYml
- * @returns {{servicesRequest?: string, secretsRequest?: string}}
- */
-export function fingerprintRequest(siteYml, provisioned = {}) {
-  const out = {}
-  // ⭐ Two sources, on purpose. The PROVISIONED rows come from `sync.json` for the
-  // backend being published to (they were `site.yml::$services` / `$secrets` until
-  // 2026-09-20). The language selection below is still authored, so still site.yml.
-  const services = fingerprintDeclaration(provisioned?.services)
-  if (services) out.servicesRequest = services
-  const secrets = fingerprintDeclaration(provisioned?.secrets)
-  if (secrets) out.secretsRequest = secrets
-  // ⭐ The language selection is a request too, and it is the one that moves a
-  // PRICE — the line is billed on how many languages go out. Banking it is what
-  // lets a later edit read as "the owner asked for another language" rather than
-  // as a value that was always there.
-  const langs = fingerprintDeclaration(siteYml?.publishLanguages)
-  if (langs) out.publishLanguagesRequest = langs
-  return out
-}
-
-/**
- * Should this push DECLARE the request blocks?
- *
- * ⛔ **Absence of a record means YES.** Three reasons, and the third is the one
- * that decides it:
- *
- *   1. It is the behaviour every CLI has had, so nothing regresses.
- *   2. A project may legitimately have no `deploy.yml` (never published, or
- *      `autoSave: off`), and that is not evidence about the request.
- *   3. ⭐ Failing the other way DROPS A REAL REQUEST IN SILENCE. Between the two
- *      failure directions, sending an unchanged block writes back what is usually
- *      already there, while withholding a changed one leaves an owner's edit with
- *      no effect and nothing said. The loud failure is the better one.
- *
- * @param {object} siteYml - the parsed site.yml
- * @param {object|null} lastDeploy - `deploy.yml::lastDeploy.<target>`, or null
- * @returns {{declare: boolean, reason: 'no-record'|'changed'|'unchanged'|'undeclared'}}
- */
-export function decideDeclaration(siteYml, lastDeploy, provisioned = {}) {
-  const now = fingerprintRequest(siteYml, provisioned)
-  if (!now.servicesRequest && !now.secretsRequest) {
-    // Nothing in the file to send. The gate is moot; say so rather than
-    // reporting "unchanged", which would imply a comparison happened.
-    return { declare: true, reason: 'undeclared' }
-  }
-  if (!lastDeploy || typeof lastDeploy !== 'object') {
-    return { declare: true, reason: 'no-record' }
-  }
-  const same =
-    now.servicesRequest === (lastDeploy.servicesRequest || undefined) &&
-    now.secretsRequest === (lastDeploy.secretsRequest || undefined)
-  return same
-    ? { declare: false, reason: 'unchanged' }
-    : { declare: true, reason: 'changed' }
-}
-
-/**
- * The four-way reconcile, once the backend's own copy of the request is in hand.
- *
- * ⭐ THIS SUPERSEDES `decideDeclaration` WHERE THE STATUS READ SUCCEEDS. That one
- * compares the file to our MEMORY of what we last sent, which leaves a window: a
- * request changed in the app between a `uniweb pull` and the next publish reads as
- * unchanged-from-nothing. Comparing to the backend's own rows closes it, because
- * the base stops being something we have to remember correctly.
- *
- * ⛔ It still needs the banked fingerprint. Local and remote differing says the two
- * disagree; it does not say WHO MOVED. Only the last agreed state does, and that is
- * the difference between "the app decided, adopt it" and "you edited, send it".
- *
- * ## The four outcomes
- *
- * | local | remote | |
- * |---|---|---|
- * | unchanged | unchanged | `none` — nobody asked anything |
- * | unchanged | **moved** | `adopt` — the app decided; the file is merely behind |
- * | **edited** | unchanged | `send` — a real request |
- * | **edited** | **moved** | `conflict` — ⛔ two intents, and only the owner ranks them |
+ * `site.yml::publishLanguages` is the owner's ASK, pushed up, projected back on pull,
+ * and stored on the other side where something else may move it.
  *
- * ⛔ `conflict` never guesses and never sends. A last-write-wins on a field that
- * schedules a paid service to end is not a tie-break, it is a coin toss with the
- * owner's money.
- *
- * ⚖️ No base ⇒ we cannot tell `adopt` from `conflict`, so we fall back to the
- * conservative reading of a difference: if the two differ, `conflict`; if they
- * agree, `none`. That withholds rather than sends, which is safe HERE — unlike
- * `decideDeclaration`, nothing is silently dropped, because a conflict is reported.
- *
- * @param {object} siteYml
- * @param {*} remoteServices - the status read's `services` rows, or undefined
- * @param {object|null} lastDeploy - the banked base
- * @returns {{action:'none'|'adopt'|'send'|'conflict', local:string|null, remote:string|null}}
- */
-export function reconcileRequest(siteYml, remoteServices, lastDeploy, provisioned = {}) {
-  return reconcile(provisioned?.services, remoteServices, lastDeploy?.servicesRequest)
-}
-
-/**
- * The same reconcile over any two-way request field.
- *
- * ⭐ `$services` was the first, not the only one. `site.yml::publishLanguages` is
- * the same shape — the owner's ASK, pushed up, projected back on pull, and stored
- * on the other side where something else may move it.
- *
- * ⛔ AND A BASE IS NEEDED EVEN WHERE NOTHING ELSE WRITES THE FIELD. That was the
- * reasoning that nearly left languages out: "nobody overwrites it, so there is no
- * hazard." Overwriting is not the only thing a base is for — without one, a value
- * that has always been in the file is indistinguishable from one the owner just
- * typed, so the CLI cannot tell an intentional change from the status quo. For
- * languages that difference is money: the count is priced, so a new language is a
- * charge, and saying so before sending requires knowing it is new.
+ * ⛔ A BASE IS NEEDED EVEN WHERE NOTHING ELSE WRITES THE FIELD. Overwriting is not the
+ * only thing a base is for — without one, a value that has always been in the file
+ * is indistinguishable from one the owner just typed, so the CLI cannot tell an
+ * intentional change from the status quo. For languages that difference is money:
+ * the count is priced, so a new language is a charge, and saying so before sending
+ * requires knowing it is new.
  *
  * @param {*} localValue - the file's declaration
  * @param {*} remoteValue - what the site has stored
  * @param {string|null} baseFingerprint - what we last agreed on
+ * @returns {{action: 'none'|'adopt'|'send'|'conflict', local: string|null, remote: string|null}}
  */
 export function reconcile(localValue, remoteValue, baseFingerprint) {
   const local = fingerprintDeclaration(localValue)
@@ -217,11 +88,9 @@ export function reconcile(localValue, remoteValue, baseFingerprint) {
   const base = baseFingerprint || null
 
   if (local === remote) return { action: 'none', local, remote }
-  // ⛔ A FILE THAT DECLARES NOTHING ASKS NOTHING, so it is never one side of a conflict. With
-  // nothing stored either — an empty list is the store's nothing — there is nothing to do; with
-  // something stored, the file is merely behind. Until 2026-09-26 this was a `conflict`, and the
-  // first publish of a site whose file is silent warned that its services "were changed
-  // elsewhere, and site.yml changed too", listing both as nothing.
+  // ⛔ A FILE THAT DECLARES NOTHING ASKS NOTHING, so it is never one side of a conflict.
+  // With nothing stored either there is nothing to do; with something stored, the file
+  // is merely behind.
   if (local === null) return { action: isNothing(remoteValue) ? 'none' : 'adopt', local, remote }
   if (!base) return { action: 'conflict', local, remote }
 
@@ -231,3 +100,107 @@ export function reconcile(localValue, remoteValue, baseFingerprint) {
   if (localMoved && !remoteMoved) return { action: 'send', local, remote }
   return { action: 'conflict', local, remote }
 }
+
+/**
+ * What a publish records in `deploy.yml` about the language selection: its
+ * fingerprint, on EVERY publish — it rides the content push, so what went live is
+ * what was agreed.
+ *
+ * ⛔ A FINGERPRINT, never the list: `deploy.yml` records what a publish did, and the
+ * selection itself is in `site.yml`.
+ *
+ * @param {object} siteYml
+ * @returns {{publishLanguagesRequest?: string}}
+ */
+export function bankLanguages(siteYml) {
+  const langs = fingerprintDeclaration(siteYml?.publishLanguages)
+  return langs ? { publishLanguagesRequest: langs } : {}
+}
+
+/**
+ * The services the site's foundation says it renders — the build's `_self.supports`, else
+ * `package.json::uniweb.supports` — or null when that is unknown: no local foundation, or
+ * one that declares nothing. ⛔ Absent is UNKNOWN, never "none".
+ *
+ * @param {string} siteDir
+ * @param {object} siteYml - parsed
+ * @returns {Promise<string[]|null>}
+ */
+export async function foundationSupports(siteDir, siteYml) {
+  try {
+    if (!siteYml?.foundation) return null
+    const { detectFoundationType } = await import('@uniweb/build')
+    const found = detectFoundationType(siteYml.foundation, siteDir)
+    if (found?.type !== 'local' || !found.path) return null
+    const built = join(found.path, 'dist', 'meta', 'schema.json')
+    if (existsSync(built)) {
+      const derived = JSON.parse(readFileSync(built, 'utf8'))?._self?.supports
+      if (Array.isArray(derived)) return derived
+    }
+    const declared = JSON.parse(readFileSync(join(found.path, 'package.json'), 'utf8'))?.uniweb?.supports
+    return Array.isArray(declared) ? declared : null
+  } catch {
+    return null
+  }
+}
+
+const names = (list) => list.map((n) => `\`${n}\``).join(', ')
+
+/**
+ * Say what `site.yml::services` asks that will not be sent as written — a credential,
+ * an entry that is not one, an `api` address — and where it and the foundation disagree,
+ * before a push or publish sends the rest. What a push sends is the producer's
+ * (`statedServices`), from the same file.
+ *
+ * ⭐ The foundation INFORMS and never decides [Diego, 2026-10-07]: a service the file turns
+ * on that the foundation does not say it renders is said; so is one it renders that the
+ * file does not mention, since every service is off unless the site asks for it. An
+ * explicit `false` is a decision, and quiets the second. `tracking` is in neither — a
+ * foundation may not claim it, since it renders nothing — and `records` is left to
+ * publish, which knows whether the pages show any (`recordsNotAsked`).
+ *
+ * @param {object} p
+ * @param {object} p.siteYml - parsed
+ * @param {{ warn: Function }} p.say
+ * @param {string[]|null} [p.supports] - from `foundationSupports`; null = unknown
+ */
+export function announceServices({ siteYml, say, supports = null }) {
+  const asks = readServicesRequest(siteYml?.services, { warn: (m) => say.warn(m) }) || []
+  if (!Array.isArray(supports)) return
+  const ignored = new Set(['tracking', 'records'])
+  const has = (ask) => ask.enabled !== false || typeof ask.config?.endpoint === 'string'
+  const unrendered = asks.filter((a) => has(a) && !ignored.has(a.name) && !supports.includes(a.name)).map((a) => a.name)
+  if (unrendered.length) {
+    say.warn(`site.yml turns on ${names(unrendered)}, which your foundation does not say it renders (\`uniweb.supports\`).`)
+  }
+  const mentioned = new Set(asks.map((a) => a.name))
+  const unasked = supports.filter((n) => !ignored.has(n) && !mentioned.has(n))
+  if (unasked.length) {
+    say.warn(
+      `Your foundation renders ${names(unasked)}, which site.yml does not ask for — a service is off ` +
+        `unless the site asks for it. Add ${unasked.length === 1 ? 'it' : 'them'} under \`services:\`, or set ` +
+        `${unasked.length === 1 ? 'it' : 'each'} to \`false\` if that is what you mean.`
+    )
+  }
+}
+
+/**
+ * The publish warning for `records`: the site's pages show records live, and `site.yml`
+ * does not ask for the service that delivers them on a published site [Diego, 2026-10-07:
+ * "When records is off and the site is published with us, there is no meant to be a fall
+ * back at all"]. Syncing records does not depend on it, so push and pull say nothing.
+ *
+ * @param {object} p
+ * @param {object} p.siteYml - parsed
+ * @param {string[]} p.shown - from the package (`recordsShown`)
+ * @returns {string|null} the warning, or null
+ */
+export function recordsNotAsked({ siteYml, shown }) {
+  if (!Array.isArray(shown) || !shown.length) return null
+  const records = (readServicesRequest(siteYml?.services) || []).find((a) => a.name === 'records')
+  if (records && records.enabled !== false) return null
+  return (
+    `Your pages show records from ${names(shown)}, but site.yml does not ask for \`records\` — ` +
+    'a published site delivers them only with it on. Add `records: true` under `services:`.'
+  )
+}