uniweb 1.20.4 → 1.21.1

package/src/framework-index.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-26T02:00:48.151Z",
+  "generatedAt": "2026-10-26T17:19:54.265Z",
   "packages": {
     "@uniweb/api": {
       "version": "1.6.4"
     },
     "@uniweb/build": {
-      "version": "1.10.2"
+      "version": "1.10.3"
     },
     "@uniweb/content-reader": {
       "version": "1.5.7"

package/src/index.js

@@ -876,7 +876,7 @@ async function main() {
     await exitWhenDrained(result?.exitCode ?? 0)
   }
 
-  // Handle status command (dynamic import — offline emit via @uniweb/build)
+  // Handle status command (dynamic import — its checks reach @uniweb/build)
   if (command === 'status') {
     const { status } = await importProjectCommand('./commands/status.js')
     const result = await status(args.slice(1))
@@ -1770,6 +1770,42 @@ ${colors.bright}Options:${colors.reset}
   --non-interactive  Fail with usage info instead of prompting
 
 Exit code is 1 if errors are found (warnings only → exit 0).
+`,
+    status: `
+${colors.cyan}${colors.bright}uniweb status${colors.reset} ${colors.dim}— What to know before working on a site, and what to run about it${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb status [options]
+
+Run it when you begin, when you come back to the project, before you push, publish
+or deploy, and after a command refuses. It opens with what the site is — synced
+where, live where, deployed where — and checks:
+
+  git      conflicts, a merge waiting, the site's files not committed, the git remote
+  app      the session, what changed on the backend since this copy last synced —
+           the files a pull would change — what is not pushed, who has the site
+           open in the app, the foundation
+  hosting  where the site is live, the other hosts deploy.yml lists (by CI or by
+           hand, and how far behind), and the services the live site has
+  uniweb   whether a newer release is out
+  health   doctor's findings
+  dev      the dev server
+
+and ends with the steps to take, in the order to take them. A step marked
+"ask the person first" is theirs to decide — going live, for one.
+
+It changes nothing and asks nothing: with no session it says how to sign in.
+A check it could not make says so, and is never reported as fine.
+
+${colors.bright}Options:${colors.reset}
+  --offline          Ask nothing beyond this machine — no backend, npm, git remote
+                     or dev server
+  --json             One JSON document: { schema: 1, checks: [...], next: [...] }
+  --org @org         The workspace to ask the backend in, for this command only
+  --personal         Your personal workspace, for this command only
+
+Exit code is 0 whenever a status is produced, 2 for a usage error — read the
+document, not the exit code, for what needs doing.
 `,
     validate: `
 ${colors.cyan}${colors.bright}uniweb validate${colors.reset} ${colors.dim}— Check your content against your foundation's data schemas${colors.reset}
@@ -2137,7 +2173,7 @@ ${colors.bright}Commands:${colors.reset}
   pull               Pull a site's content from the backend
   refresh            Catch up with the git remote AND the backend (never pushes)
   sync               Catch up, then push (refresh + push)
-  status             Show a site's sync state (unpushed content, foundation)
+  status             What changed in the app, in git and in Uniweb — and what to run
   forget             Forget a backend, or --all to make a copied project a new one
   site <cmd>         The sites in a workspace: list, unpublish, delete
   inspect <path>     Inspect parsed content shape of a markdown file or folder

package/src/utils/code-upload.js

@@ -119,33 +119,6 @@ export function uploadOrder(files) {
   return [...rest, ...entry]
 }
 
-/**
- * The deterministic content digest of a built foundation — the freshness
- * fingerprint `register` records and `publish`/`status` later compare against
- * (shipping-model.md §4.1). It answers one question — "did the foundation change
- * since it was released?" — with NO local state, so it has to be reproducible:
- * the same source, built on any machine, must yield the same digest.
- *
- * Algorithm (§4.1): `sha256` over the newline-joined, SORTED list of the
- * per-file `sha256` (hex) of exactly what `register` ships for a foundation —
- *   - the code-upload set (`collectDistFiles`: entry + chunks + assets, with
- *     `meta/**` and `*.map` already excluded), and
- *   - the schema source (`meta/schema.json`) — NOT uploaded as a file, and not
- *     sent verbatim: register submits its *content* as the foundation-schema
- *     ENTITY in the `.uwx`. It's read here only to fold the schema into the
- *     local freshness fingerprint (so a schema edit shows as "changed").
- * Hashes are SORTED (so the digest is order-independent) and taken over file
- * CONTENTS, not names, so content-hashed chunk filenames don't perturb it.
- * Returns null when there's nothing to hash (no usable dist), so callers skip
- * cleanly rather than fingerprinting emptiness.
- *
- * The result is OPAQUE to the backend — it stores the string and returns it
- * verbatim; the framework owns the algorithm end-to-end and can change it
- * freely (a digest only ever compares against one the same CLI computed).
- *
- * @param {string} distDir - the built `dist/` directory
- * @returns {string|null} `sha256:<hex>` or null when there's nothing to hash
- */
 /**
  * The `@uniweb/runtime` version a built foundation linked against, from
  * `dist/runtime-pin.json`.
@@ -180,6 +153,33 @@ export function readRuntimePin(distDir) {
   }
 }
 
+/**
+ * The deterministic content digest of a built foundation — the freshness
+ * fingerprint `register` records and `publish`/`status` later compare against
+ * (shipping-model.md §4.1). It answers one question — "did the foundation change
+ * since it was released?" — with NO local state, so it has to be reproducible:
+ * the same source, built on any machine, must yield the same digest.
+ *
+ * Algorithm (§4.1): `sha256` over the newline-joined, SORTED list of the
+ * per-file `sha256` (hex) of exactly what `register` ships for a foundation —
+ *   - the code-upload set (`collectDistFiles`: entry + chunks + assets, with
+ *     `meta/**` and `*.map` already excluded), and
+ *   - the schema source (`meta/schema.json`) — NOT uploaded as a file, and not
+ *     sent verbatim: register submits its *content* as the foundation-schema
+ *     ENTITY in the `.uwx`. It's read here only to fold the schema into the
+ *     local freshness fingerprint (so a schema edit shows as "changed").
+ * Hashes are SORTED (so the digest is order-independent) and taken over file
+ * CONTENTS, not names, so content-hashed chunk filenames don't perturb it.
+ * Returns null when there's nothing to hash (no usable dist), so callers skip
+ * cleanly rather than fingerprinting emptiness.
+ *
+ * The result is OPAQUE to the backend — it stores the string and returns it
+ * verbatim; the framework owns the algorithm end-to-end and can change it
+ * freely (a digest only ever compares against one the same CLI computed).
+ *
+ * @param {string} distDir - the built `dist/` directory
+ * @returns {string|null} `sha256:<hex>` or null when there's nothing to hash
+ */
 export function computeFoundationDigest(distDir) {
   const hashes = collectDistFiles(distDir).map((f) => f.sha256)
   // The schema rides in the register `.uwx`, not the code-upload set, so fold

package/src/utils/flag-guard.js

@@ -109,11 +109,14 @@ const VERBS = {
    */
   site: ['--json', '--yes', '--org', '--personal'],
   status: [
-    '--json', '--remote', '--dry-run',
+    '--json', '--offline', '--dry-run',
     '--force', '--no-verify', '--no-validate', '--yes', '--org', '--personal',
     // inert here, reachable through the bring-along module status imports for
     // `resolveLocalFoundation` — listed per the over-approximation note above
-    '--no-release', '--bump', ...VIA_DEPLOY
+    '--no-release', '--bump', ...VIA_DEPLOY,
+    // inert here too, reachable through `commands/pull.js`, whose lane readers status uses
+    // to ask what changed on the backend (`backend/app-changes.js`)
+    '--no-assets', '--no-delete', '--no-prune', '--no-records', '--content-only'
   ],
   /**
    * `refresh` = `git pull`, then a DELEGATED `pull`.
@@ -249,6 +252,18 @@ export function checkFlags(verb, args = []) {
       message: `\`--as-org\` is retired — use \`--org @org\` (e.g. \`uniweb ${verb} --org @acme\`).`
     }
   }
+  // ⭐ `status --remote` is RETIRED (2026-10-26): a status asks the backend by default, and
+  // `--offline` keeps it to this machine.
+  if (flag === '--remote' && verb === 'status') {
+    return {
+      flag,
+      suggestion: null,
+      message: [
+        '`uniweb status` has no `--remote`: it asks the backend by default now.',
+        '  Run `uniweb status`, or `uniweb status --offline` to ask nothing beyond this machine.'
+      ].join('\n')
+    }
+  }
   // ⭐ `pull --merge` is RETIRED (2026-10-17): in a repository a pull always merges — from the
   // newest sync point the history holds (`utils/sync-point.js`) — and outside one there is
   // nothing to merge against.

package/src/utils/git.js

@@ -21,7 +21,7 @@
  * project counted as inside the harness, so `refresh` ran `git pull` on the harness.
  */
 
-import { execFileSync } from 'node:child_process'
+import { execFile, execFileSync } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import yaml from 'js-yaml'
@@ -198,6 +198,96 @@ export function pullRemote(dir) {
   }
 }
 
+/**
+ * The branch HEAD is on and the one it tracks — `{ branch, remote, merge, tracking }`
+ * (`main`, `origin`, `refs/heads/main`, `origin/main`) — or null: no branch, or no upstream.
+ */
+export function upstreamOf(dir) {
+  try {
+    const branch = git(['symbolic-ref', '--short', '-q', 'HEAD'], dir).trim()
+    if (!branch) return null
+    const remote = git(['config', '--get', `branch.${branch}.remote`], dir).trim()
+    const merge = git(['config', '--get', `branch.${branch}.merge`], dir).trim()
+    const tracking = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], dir).trim()
+    return remote && merge && tracking ? { branch, remote, merge, tracking } : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The commits HEAD has that its upstream lacks (`ahead`), and the reverse (`behind`) — as of
+ * the last fetch, which is all a repository knows without asking its remote. Null with no
+ * upstream.
+ */
+export function aheadBehind(dir) {
+  try {
+    const [behind, ahead] = git(['rev-list', '--left-right', '--count', '@{u}...HEAD'], dir)
+      .trim()
+      .split(/\s+/)
+      .map(Number)
+    return Number.isInteger(ahead) && Number.isInteger(behind) ? { ahead, behind } : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Does the git remote hold commits HEAD does not — teammates' work since the last fetch?
+ * Asked with `git ls-remote`, which fetches nothing and writes nothing, so a read-only
+ * command can ask it.
+ *
+ * ⛔ IT NEVER PROMPTS. A credential prompt would hang a command run by an agent, so: no
+ * terminal prompt (`GIT_TERMINAL_PROMPT=0`), no credential manager window
+ * (`GCM_INTERACTIVE=never`), ssh in batch mode with a connect timeout — added to the ssh
+ * command the person configured, never instead of it — and the whole call bounded.
+ *
+ * @param {string} dir
+ * @param {{ timeoutMs?: number }} [opts]
+ * @returns {Promise<{ moved: boolean, upstream: object } | null>} null when there is no
+ *   upstream, or the remote did not answer in time
+ */
+export async function remoteMoved(dir, { timeoutMs = 5000 } = {}) {
+  const upstream = upstreamOf(dir)
+  if (!upstream) return null
+  let ssh = process.env.GIT_SSH_COMMAND || ''
+  try {
+    ssh ||= git(['config', '--get', 'core.sshCommand'], dir).trim()
+  } catch {
+    // not configured
+  }
+  const env = {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GCM_INTERACTIVE: 'never',
+    GIT_SSH_COMMAND: `${ssh || 'ssh'} -o BatchMode=yes -o ConnectTimeout=${Math.ceil(timeoutMs / 1000)}`
+  }
+  let out
+  try {
+    out = await new Promise((resolve, reject) => {
+      execFile('git', ['ls-remote', '--', upstream.remote, upstream.merge], { cwd: dir, env, timeout: timeoutMs, encoding: 'utf8' }, (err, stdout) =>
+        err ? reject(err) : resolve(stdout)
+      )
+    })
+  } catch {
+    return null
+  }
+  const head = String(out)
+    .split('\n')
+    .map((line) => line.split('\t'))
+    .find(([, ref]) => ref === upstream.merge)?.[0]
+  if (!head) return null
+  // A head HEAD already holds — fetched earlier, or HEAD's own — is nothing new.
+  let held = false
+  try {
+    git(['merge-base', '--is-ancestor', head, 'HEAD'], dir)
+    held = true
+  } catch {
+    held = false
+  }
+  return { moved: !held, upstream }
+}
+
 /**
  * Provenance for a deploy record: `{ sha, dirty }`, or null outside a repo.
  * Answers "what is actually live?" later, which a version number cannot.

package/src/utils/status-next.js

@@ -0,0 +1,47 @@
+/**
+ * The order `uniweb status`'s next steps are taken in.
+ *
+ * ⭐ FOLLOWED FROM THE TOP, THE LIST WORKS: each step's precondition is met by the ones above
+ * it. A list of individually right steps in the wrong order is a guard that names an
+ * unavailable recovery step — a push before the pull it needs is refused, and the refusal
+ * then sends the reader back up. So the order is one table, not each check's own idea:
+ *
+ *   sign in → settle conflicts → finish a merge → take what others did (refresh, or pull)
+ *   → push → push to git → go live → deploy to another host → update Uniweb → read doctor's findings
+ *
+ * Each check proposes steps by name (`step`); this sorts them, folds the ones another step
+ * already does, and drops duplicates.
+ */
+
+const ORDER = ['login', 'conflicts', 'merge', 'refresh', 'pull', 'push', 'gitpush', 'publish', 'deploy', 'update', 'doctor']
+
+/**
+ * @param {Array<{ step: string, command: string|null, why: string, ask?: boolean }>} proposals
+ * @returns {Array<{ command: string|null, why: string, ask: boolean }>}
+ */
+export function planNext(proposals) {
+  const steps = [...proposals]
+  // `refresh` is `git pull`, then the same pull: it takes the app's changes too.
+  const refresh = steps.find((p) => p.step === 'refresh')
+  const pull = steps.find((p) => p.step === 'pull')
+  if (refresh && pull) {
+    refresh.why = `${refresh.why}, and ${pull.why}`
+    steps.splice(steps.indexOf(pull), 1)
+  }
+  // A newer release's update aligns the dependencies and AGENTS.md too: the project's own
+  // CLI aligning them to its matrix is then one step too many.
+  if (steps.some((p) => p.step === 'update' && p.latest)) {
+    for (let i = steps.length - 1; i >= 0; i--) if (steps[i].step === 'update' && !steps[i].latest) steps.splice(i, 1)
+  }
+  const seen = new Set()
+  return steps
+    .filter((p) => ORDER.includes(p.step))
+    .sort((a, b) => ORDER.indexOf(a.step) - ORDER.indexOf(b.step))
+    .filter((p) => {
+      const key = p.command ?? `${p.step}:${p.why}`
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    })
+    .map(({ command, why, ask }) => ({ command: command ?? null, why, ask: Boolean(ask) }))
+}

package/src/utils/sync-point.js

@@ -382,7 +382,7 @@ function differsIn(repo, a, b, roots) {
  * @param {string[]} opts.roots - the site's content roots, relative to the site
  * @param {string|null} opts.rev - the commit whose content the roots are filled from;
  *   null for none
- * @returns {{ siteDir: string, commit: Function, placeIgnored: Function, close: Function }}
+ * @returns {{ siteDir: string, commit: Function, changes: Function, placeIgnored: Function, close: Function }}
  */
 export function openStandIn(repo, { roots, rev }) {
   for (const r of roots) {
@@ -543,6 +543,24 @@ export function openStandIn(repo, { roots, rev }) {
       return placed
     }
 
+    /**
+     * What is written under the roots that `rev` does not hold so — each `[status, path]`,
+     * status `A`, `M` or `D`, the path relative to the site. Asked of the stand-in's own
+     * index, which holds `rev`: nothing is staged, committed or written to the repository.
+     * What the repository ignores is no change, as for `commit`.
+     * @returns {Array<[string, string]>}
+     */
+    const changes = () => {
+      const roots = full.filter((f) => present.includes(f) || existsSync(join(root, f)))
+      if (!roots.length) return []
+      const site = (p) => (sitePrefix && p.startsWith(sitePrefix) ? p.slice(sitePrefix.length) : p)
+      const out = []
+      const tracked = zlist(at(['diff', '--name-status', '-z', '--no-renames', '--', ...roots]))
+      for (let i = 0; i + 1 < tracked.length; i += 2) out.push([tracked[i], site(tracked[i + 1])])
+      for (const p of zlist(at(['ls-files', '--others', '--exclude-standard', '-z', '--', ...roots]))) out.push(['A', site(p)])
+      return out.sort((a, b) => (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0))
+    }
+
     // The roots git can hold here. ⛔ One the repository ignores whole is not named to
     // `git add`, which refuses an ignored path; what is written under it is placed instead.
     const held = (paths) => {
@@ -556,7 +574,7 @@ export function openStandIn(repo, { roots, rev }) {
       return paths.filter((p) => !ignored.includes(p))
     }
 
-    return { siteDir, commit, placeIgnored, close }
+    return { siteDir, commit, changes, placeIgnored, close }
   } catch (err) {
     close()
     throw err

package/src/utils/update-check.js

@@ -12,8 +12,10 @@ import { join } from 'node:path'
 import { detectGlobalCliPm, globalCliUpdateCmd } from './pm.js'
 
 const CHECK_INTERVAL = 24 * 60 * 60 * 1000 // 1 day
-const STATE_DIR = join(homedir(), '.uniweb')
-const STATE_FILE = join(STATE_DIR, 'update-check.json')
+// Found when read, not when this module loads — as `getAuthDir` is — so HOME is the one in
+// effect: a run with its own HOME (a test's) never reads or writes the person's cache.
+const stateDir = () => join(homedir(), '.uniweb')
+const stateFile = () => join(stateDir(), 'update-check.json')
 
 /**
  * Compare two semver strings.
@@ -34,8 +36,8 @@ function compareSemver(a, b) {
  */
 function readState() {
   try {
-    if (existsSync(STATE_FILE)) {
-      return JSON.parse(readFileSync(STATE_FILE, 'utf8'))
+    if (existsSync(stateFile())) {
+      return JSON.parse(readFileSync(stateFile(), 'utf8'))
     }
   } catch {
     /* ignore corrupt cache */
@@ -48,8 +50,8 @@ function readState() {
  */
 function writeState(state) {
   try {
-    if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true })
-    writeFileSync(STATE_FILE, JSON.stringify(state))
+    if (!existsSync(stateDir())) mkdirSync(stateDir(), { recursive: true })
+    writeFileSync(stateFile(), JSON.stringify(state))
   } catch {
     /* ignore write errors */
   }

package/templates/site/site.yml.hbs

@@ -32,11 +32,10 @@ index: home
 # mounted directory is a folder of pages. Whatever that stub leaves unset comes
 # from the mounted directory's own folder.yml, so it need only say what differs.
 #
-# ! A `pages/<segment>:` sub-mount is BUILD-ONLY today. `uniweb export` and
-#   `uniweb deploy --host <adapter>` mount it normally, but `uniweb push` /
-#   `uniweb publish` do not read the key, so the mounted pages do not reach a
-#   backend (the CLI warns when it skips them). The whole-directory form
-#   `paths: { pages: <dir> }` IS carried by both. Static hosting: use either.
+# A `pages/<segment>:` mount goes wherever the site goes: builds, `uniweb export`
+# and `uniweb deploy --host <adapter>`, and `uniweb push` / `uniweb publish`,
+# which send the mounted pages as they are on disk — update a mounted repository
+# before you publish. A pull never writes into a mount.
 
 # ─── Structured Content ───────────────────────────────────────────────────────
 # Three things, and they are separate on purpose: