uniweb 0.23.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "^0.9.0",
-    "@uniweb/kit": "^0.12.1",
-    "@uniweb/runtime": "^0.11.8"
+    "@uniweb/core": "^0.10.0",
+    "@uniweb/kit": "^0.12.2",
+    "@uniweb/runtime": "^0.12.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.23.0",
-    "@uniweb/content-reader": "^1.2.2",
-    "@uniweb/semantic-parser": "^1.2.2"
+    "@uniweb/build": "^0.24.0",
+    "@uniweb/semantic-parser": "^1.2.2",
+    "@uniweb/content-reader": "^1.2.2"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -1962,17 +1962,27 @@ runtime emits by itself.
 
 ```yaml
 # site.yml — your own collector, on any host
-tracking: https://plausible.io/api/event
+tracking: https://collector.example.com/events
 
 # or, when it needs more than an address
 tracking:
-  endpoint: https://plausible.io/api/event
+  endpoint: /collect
   consent: required
 ```
 
 A host may also supply one under `services.tracking`, and the usual precedence
 applies: yours wins, then the host's, then neither.
 
+⚠️ **The endpoint has to accept the framework's own format** — a batched
+`{ "events": [ … ] }` POST, documented in `reference/site-configuration.md`. It
+is not a third-party analytics product's public API, which expects that
+product's own shape.
+
+A site may also name a vendor's own script under `tracking.scripts`, which the
+runtime loads once, after consent when a gate is declared, and never in a frame
+or during prerender. That is a **separate path with no connection to the stream
+below** — the vendor measures its own way, and nothing you `track()` reaches it.
+
 **The runtime reports `page_view` on every route change, including the first.**
 That is the only thing it emits on its own — everything else is yours to report:
 
@@ -1991,7 +2001,12 @@ const { track } = useTracker()
 <button onClick={() => track('brochure_download', { file: 'specs.pdf' })}>…</button>
 ```
 
-The event name is yours — there is no list of permitted names.
+The event name is yours — there is no list of permitted names. Three are already
+in use, so reach for these rather than inventing a synonym: **`page_view`** (the
+runtime), **`scroll_depth`** (kit's `useScrollDepth()`, with a `depth` of 25 /
+50 / 75 / 100) and **`video_milestone`** (kit's `<Media>`, with `milestone` and
+`src`). Put the varying part in a **field**, never in the name — four names for
+one event turn a collector's event dimension into a cardinality problem.
 
 ⛔ **Never guard a `track()` call.** A site with **no** tracking destination is
 the default and the majority: the call returns having done nothing, opened no

package/src/commands/doctor.js

@@ -307,7 +307,7 @@ export function checkAgentsBlock({ siteName, siteYml, issues }) {
       .join(', ')} ${unknown.length === 1 ? 'is' : 'are'} not recognized.`
   )
   for (const key of unknown) {
-    const near = nearestAgentsKey(key, known)
+    const near = nearestKnownKey(key, known)
     if (near) log(`    ${colors.dim}'${key}' — did you mean ${colors.reset}${colors.green}${near}${colors.reset}${colors.dim}?${colors.reset}`)
   }
   log(
@@ -326,7 +326,7 @@ export function checkAgentsBlock({ siteName, siteYml, issues }) {
  * for `origins`, and a wrong suggestion is worse than none — it sends the
  * author to change a line that was not their mistake.
  */
-function nearestAgentsKey(input, known) {
+function nearestKnownKey(input, known) {
   let best = null
   let bestScore = Infinity
   for (const candidate of known) {
@@ -339,6 +339,148 @@ function nearestAgentsKey(input, known) {
   return bestScore <= 3 ? best : null
 }
 
+/**
+ * The options `tracking:` actually has a reader.
+ *
+ * ⚠️ **Kept here rather than imported, because nothing at runtime enumerates
+ * them** — `wireTracker` reads named properties off the resolved declaration, it
+ * does not iterate a list. So there is no existing array to import and this
+ * duplicates nothing. It does mean the list can drift: the readers are
+ * `runtime/src/wire-foundation.js::wireTracker` (`consent`, `scripts`, `debug`)
+ * and `core/src/services.js::readEndpoint` (`endpoint`). Add a key there, add it
+ * here.
+ */
+const TRACKING_KEYS = ['endpoint', 'consent', 'scripts', 'debug']
+
+/**
+ * Spellings that read as an ATTEMPT to require consent but do not require it.
+ *
+ * `consentRequired` is `options.consent === 'required'` — an exact match — so
+ * every one of these silently means *no gate*. That is the one field in this
+ * block where a silent no-op has a consequence beyond a missing metric.
+ *
+ * ⚖️ Deliberately not "anything that is not `required`": `consent: none` is a
+ * documented, useful value — it is how a site overrides a gate its **host**
+ * declared, under the per-key tier fill. Flagging that would flag correct code.
+ */
+const CONSENT_NEAR_MISSES = new Set(['require', 'requires', 'required.', 'true', 'yes', 'on', '1'])
+
+/**
+ * `tracking:` — flag the keys and values that are carried and never acted on.
+ *
+ * The block is forwarded to the host as opaque data and resolved at render, so
+ * nothing downstream rejects a mistake in it. Every error here therefore fails
+ * the same way: **silently, at a visitor's browser, as an absence** — which is
+ * also exactly what a site that configured nothing looks like. There is no
+ * symptom to notice and nothing to grep for.
+ *
+ * ⭐ That is the whole argument for checking it at `doctor` time: it is the only
+ * moment in the chain where a person who can fix it is looking at it.
+ *
+ * A bare `tracking: <url>` string is the documented shorthand and carries no
+ * options — there is nothing in it to be wrong.
+ */
+export function checkTrackingBlock({ siteName, siteYml, issues }) {
+  const tracking = siteYml?.tracking
+  if (tracking === undefined || tracking === null) return
+  if (typeof tracking === 'string') return
+
+  if (typeof tracking !== 'object' || Array.isArray(tracking)) {
+    const id = 'tracking-not-an-object'
+    issues.push({
+      id,
+      type: 'warning',
+      site: siteName,
+      message: `site.yml: \`tracking:\` should be an endpoint string, or a map of options`
+    })
+    warn(`[${id}] ${siteName}: \`tracking:\` is neither an endpoint string nor a map of options.`)
+    return
+  }
+
+  const known = new Set(TRACKING_KEYS)
+  const unknown = Object.keys(tracking).filter((k) => !known.has(k))
+  if (unknown.length > 0) {
+    const id = 'tracking-unknown-key'
+    issues.push({
+      id,
+      type: 'warning',
+      site: siteName,
+      message: `site.yml: \`tracking:\` has ${unknown.length === 1 ? 'an unknown key' : 'unknown keys'}: ${unknown.join(', ')}`
+    })
+    warn(
+      `[${id}] ${siteName}: \`tracking:\` ${unknown.length === 1 ? 'key' : 'keys'} ${unknown
+        .map((k) => `'${k}'`)
+        .join(', ')} ${unknown.length === 1 ? 'is' : 'are'} not recognized.`
+    )
+    for (const key of unknown) {
+      const near = nearestKnownKey(key, known)
+      if (near) log(`    ${colors.dim}'${key}' — did you mean ${colors.reset}${colors.green}${near}${colors.reset}${colors.dim}?${colors.reset}`)
+    }
+    log(
+      `    ${colors.dim}Carried to the host as opaque data and never read. Known: ${TRACKING_KEYS.join(', ')}.${colors.reset}`
+    )
+  }
+
+  // `consent` is exact-matched against 'required'. A near miss is not a typo
+  // with a cosmetic cost — it is a consent gate the author believes they asked
+  // for and did not get.
+  if ('consent' in tracking) {
+    const value = tracking.consent
+    const spelling = value === null || value === undefined ? '' : String(value).trim().toLowerCase()
+
+    // ⛔ The gate test is against the RAW value, because the runtime's is:
+    // `options.consent === 'required'`, exact and case-sensitive. Lowercasing
+    // before this comparison made `Required` look correct to the checker — the
+    // check stopped testing the thing it was written to catch. The normalized
+    // spelling is only for deciding whether a wrong value reads as an ATTEMPT.
+    const gateIsOn = value === 'required'
+    const looksIntended =
+      spelling === '' || spelling === 'required' || CONSENT_NEAR_MISSES.has(spelling)
+
+    if (!gateIsOn && looksIntended) {
+      const id = 'tracking-consent-not-required'
+      const shown = spelling === '' ? 'an empty value' : `\`${String(value)}\``
+      issues.push({
+        id,
+        type: 'warning',
+        site: siteName,
+        message: `site.yml: \`tracking.consent:\` is ${shown} — only the exact value \`required\` turns the gate on`
+      })
+      warn(`[${id}] ${siteName}: \`tracking.consent:\` is ${shown}; the gate is OFF.`)
+      log(
+        `    ${colors.dim}Only \`consent: required\` holds events until a visitor answers. Anything else${colors.reset}`
+      )
+      log(
+        `    ${colors.dim}sends immediately — including a blank value, which YAML reads as null.${colors.reset}`
+      )
+    }
+  }
+
+  // An entry that yields no URL is dropped by the loader without a sound.
+  const declared = tracking.scripts
+  if (declared !== undefined) {
+    const list = Array.isArray(declared) ? declared : [declared]
+    const bad = list.filter(
+      (e) => !(typeof e === 'string' ? e.trim() : typeof e?.src === 'string' && e.src.trim())
+    )
+    if (bad.length > 0) {
+      const id = 'tracking-script-without-url'
+      issues.push({
+        id,
+        type: 'warning',
+        site: siteName,
+        message: `site.yml: \`tracking.scripts:\` has ${bad.length} ${bad.length === 1 ? 'entry' : 'entries'} with no URL`
+      })
+      warn(
+        `[${id}] ${siteName}: ${bad.length} \`tracking.scripts:\` ${bad.length === 1 ? 'entry has' : 'entries have'} no URL and will not load.`
+      )
+      log(
+        `    ${colors.dim}An entry is a URL, or an object with a \`src\`. Anything else is dropped silently.${colors.reset}`
+      )
+    }
+  }
+}
+
 /** Levenshtein distance, iterative two-row form. */
 function editDistance(a, b) {
   if (a === b) return 0
@@ -760,6 +902,7 @@ export async function doctor(args = []) {
     // Forms need a destination, and having none is only visible on the page.
     await checkFormSubmitTarget({ sitePath, siteName, siteYml, issues })
     checkAgentsBlock({ siteName, siteYml, issues })
+    checkTrackingBlock({ siteName, siteYml, issues })
 
     checkGeneratedDataDir({
       sitePath,

package/src/commands/push.js

@@ -113,13 +113,18 @@ function flagValue(args, name) {
   return null
 }
 
-export async function push(args = []) {
+export async function push(args = [], deps = {}) {
   // An unrecognized flag is invisible to a literal scan, so it silently keeps the
   // default — including for --backend, where the default can be production.
-  const bad = checkFlags('push', args)
-  if (bad) {
-    error(bad.message)
-    return { exitCode: 2 }
+  //
+  // `sync` validates the UNION of its two halves' flags and forwards raw argv, so a
+  // legal `uniweb sync --no-git` would be rejected here. It passes `skipFlagCheck`.
+  if (!deps.skipFlagCheck) {
+    const bad = checkFlags('push', args)
+    if (bad) {
+      error(bad.message)
+      return { exitCode: 2 }
+    }
   }
   const dryRun = args.includes('--dry-run')
   const output = flagValue(args, '-o') || flagValue(args, '--output')

package/src/commands/refresh.js

@@ -46,6 +46,7 @@ import {
   headProvenance
 } from '../utils/git.js'
 import { probeUnpushed } from '../backend/site-sync.js'
+import { checkFlags } from '../utils/flag-guard.js'
 
 const c = {
   reset: '\x1b[0m',
@@ -98,6 +99,21 @@ function siteContentUuid(siteDir) {
  *   network or a real backend).
  */
 export async function refresh(args = [], deps = {}) {
+  // An unrecognized flag is invisible to a literal scan, so it silently keeps the
+  // default — and for `--backend` the default can be production. This verb never
+  // sent data anywhere, which is why it went unguarded; but it DELEGATES to `pull`,
+  // and a mistyped `--backend` is not forwarded, so the pull runs against whatever
+  // the origin ladder resolves instead of the backend the user named.
+  //
+  // `sync` validates the UNION of both halves and forwards raw argv, so a legal
+  // `uniweb sync --force` would be rejected here. It passes `skipFlagCheck`.
+  if (!deps.skipFlagCheck) {
+    const bad = checkFlags('refresh', args)
+    if (bad) {
+      say.err(bad.message)
+      return { exitCode: 2 }
+    }
+  }
   const skipGit = args.includes('--no-git')
   const skipBackend = args.includes('--no-backend')
   const resolveSite = deps.resolveSiteDir || resolveSiteDir

package/src/commands/sync.js

@@ -38,6 +38,8 @@
  *   uniweb sync --backend <url>    override the backend origin
  */
 
+import { checkFlags } from '../utils/flag-guard.js'
+
 const c = {
   reset: '\x1b[0m',
   dim: '\x1b[2m',
@@ -55,6 +57,18 @@ const say = {
  * @param {object} [deps] - injectable seams for testing: `refresh`, `push`.
  */
 export async function sync(args = [], deps = {}) {
+  // THE ONE flag check for the whole composite, against the union of both halves'
+  // accepted sets (`VERBS.sync`, derived in flag-guard.js). It has to happen here
+  // and only here: each half's set is a strict subset, so `push` would reject
+  // `--no-git` and `refresh` would reject `--force` — both legal on `sync`. Hence
+  // `skipFlagCheck` below; the halves are not being trusted, they are being told
+  // the caller already validated a superset.
+  const bad = checkFlags('sync', args)
+  if (bad) {
+    say.err(bad.message)
+    return { exitCode: 2 }
+  }
+
   const refresh = deps.refresh || (await import('./refresh.js')).refresh
   const push = deps.push || (await import('./push.js')).push
 
@@ -63,7 +77,7 @@ export async function sync(args = [], deps = {}) {
   // to send — the same word meaning opposite things on the two halves.
   const refreshArgs = args.filter((a) => a !== '--force')
 
-  const r = await refresh(refreshArgs)
+  const r = await refresh(refreshArgs, { skipFlagCheck: true })
   if (r?.exitCode) {
     // refresh already explained itself — conflicts, or a git failure. Adding a
     // second summary here would just bury it.
@@ -73,7 +87,7 @@ export async function sync(args = [], deps = {}) {
 
   console.log('')
   say.info('Pushing your changes…')
-  const p = await push(args)
+  const p = await push(args, { skipFlagCheck: true })
   return { exitCode: p?.exitCode ?? 0 }
 }
 

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-14T23:58:32.904Z",
+  "generatedAt": "2026-08-16T13:24:21.340Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.23.0",
+      "version": "0.24.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -28,7 +28,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.9.0",
+      "version": "0.10.0",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -46,7 +46,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.12.1",
+      "version": "0.12.2",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -65,7 +65,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.3.2",
+      "version": "0.3.3",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -73,7 +73,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.11.8",
+      "version": "0.12.0",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -111,7 +111,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.8",
+      "version": "0.8.10",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -1544,6 +1544,58 @@ ${colors.bright}Options:${colors.reset}
 In non-interactive mode (CI / no TTY), pass \`--token <bearer>\`, or set
 \`UNIWEB_USERNAME\` + \`UNIWEB_PASSWORD\`, or set \`UNIWEB_TOKEN\` (used per-command,
 not stored). Run \`uniweb logout\` to clear the stored session.
+`,
+    refresh: `
+${colors.cyan}${colors.bright}uniweb refresh${colors.reset} ${colors.dim}— Catch up with teammates AND app authors${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb refresh [options]
+
+A developer on a synced site has TWO external sources: the git remote (teammates'
+commits) and the backend (content authors' edits in the app). Run only \`git pull\`
+and you miss every app edit; run only \`uniweb pull\` and you miss your teammates.
+This does both — git first, then \`pull --merge\`.
+
+${colors.bright}READ-ONLY.${colors.reset} It never pushes and cannot ship anything, so it is safe to run
+reflexively. Exits non-zero if a merge leaves conflicts.
+
+${colors.bright}Options:${colors.reset}
+  --no-git           Skip the git remote; backend only
+  --no-backend       Skip the backend; git only
+  --backend <url>    Override the backend origin
+  --token <bearer>   Read with this bearer; skips \`uniweb login\`
+
+\`--force\` and \`--merge\` are NOT accepted here: this verb builds the delegated
+pull's arguments itself, and to pull \`--force\` means "discard my local work".
+Use \`uniweb sync\` when you also mean to share.
+`,
+    sync: `
+${colors.cyan}${colors.bright}uniweb sync${colors.reset} ${colors.dim}— Catch up, then share${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb sync [options]
+
+\`uniweb refresh\` followed by \`uniweb push\`, and nothing more. It adds no
+guarantees of its own — refresh stops on conflicts, push refuses when the backend
+has moved under you, and sync inherits both. \`uniweb refresh && uniweb push\`
+behaves identically.
+
+${colors.bright}It does NOT publish.${colors.reset} Sync brings your copy and the backend DRAFT into
+agreement; going live stays a separate act (\`uniweb publish\`). So the worst case
+of an unintended sync is work-in-progress visible to authors, not shipped to
+visitors.
+
+${colors.bright}Options:${colors.reset}
+  Accepts every option of both halves — see \`uniweb refresh --help\` and the push
+  options in \`uniweb --help\`. The common ones:
+
+  --no-git           Skip the git remote half of the refresh
+  --force            Overwrite upstream changes (reaches the PUSH half only)
+  --backend <url>    Override the backend origin
+  --token <bearer>   Auth bearer; skips \`uniweb login\`
+
+\`--force\` means "overwrite upstream" to push but "discard my local work" to pull,
+so it is deliberately kept away from the refresh half.
 `,
     invite: `
 ${colors.cyan}${colors.bright}uniweb invite${colors.reset} ${colors.dim}— (reserved; not available on the new backend yet)${colors.reset}

package/src/utils/flag-guard.js

@@ -85,9 +85,44 @@ const VERBS = {
     '--backend', '--json', '--registry', '--remote', '--token', '--dry-run',
     '--force', '--no-verify', '--no-validate', '--yes', '--org', '--as-org',
     ...VIA_DEPLOY
+  ],
+  /**
+   * `refresh` = `git pull`, then a DELEGATED `pull --merge`.
+   *
+   * It forwards exactly three flags to that pull — `--backend` / `--registry` /
+   * `--token`, via its own `collectPassthrough` — and constructs the rest of the
+   * argv itself. So pull's own flags (`--merge`, `--force`, `--no-delete`,
+   * `--no-prune`, `--content-only`, …) are NOT reachable from a `refresh` argv and
+   * are deliberately absent here. ⚠️ `--force` especially: `refresh` is read-only by
+   * design, and forwarding it would ask pull to DISCARD local work.
+   *
+   * The trailing group is inert on this verb but reachable through the
+   * `resolveSiteDir` / `probeUnpushed` imports — listed rather than filtered, per
+   * the VIA_DEPLOY note above, and required by `flag-guard-coverage.test.js`.
+   */
+  refresh: [
+    '--backend', '--no-backend', '--no-git', '--registry', '--token',
+    '--as-org', '--org', '--dry-run', '--no-validate', '--yes', ...VIA_DEPLOY
   ]
 }
 
+/**
+ * `sync` is `refresh` + `push`, forwarding RAW argv to both halves — so its
+ * accepted set is exactly the UNION of theirs. Derived, never hand-written.
+ *
+ * Hand-writing it would rot the moment either half gained a flag, and it would rot
+ * in the expensive direction: `uniweb sync --no-git` and `uniweb sync --force` are
+ * both documented in `sync.js`, and a union that forgot either would reject a
+ * working command.
+ *
+ * ⭐ The union is also WHY `sync` checks and the two halves skip (`skipFlagCheck`,
+ * see `sync.js`). Each half's set is a strict subset of this one, so letting them
+ * re-check would have `push` reject `--no-git` and `refresh` reject `--force` —
+ * both legal on `sync`. Validating once, against the union, at the only layer that
+ * knows both halves are in play, is what makes the composite safe.
+ */
+VERBS.sync = [...new Set([...VERBS.refresh, ...VERBS.push])]
+
 /**
  * The accepted set per verb: its own flags, plus the login-method flags every
  * backend verb can reach, plus the globals.