uniweb 1.21.0 → 1.21.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.21.0",
+  "version": "1.21.2",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,12 +42,12 @@
     "prompts": "^2.4.2",
     "tar": "^7.5.21",
     "@uniweb/content-writer": "~1.3.1",
-    "@uniweb/core": "~1.4.7",
     "@uniweb/schemas": "~1.6.5",
+    "@uniweb/core": "~1.4.7",
     "@uniweb/semantic-parser": "~1.13.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "~1.10.2",
+    "@uniweb/build": "~1.10.4",
     "@uniweb/content-reader": "~1.5.7",
     "@uniweb/semantic-parser": "~1.13.0"
   },

package/partials/agents.md

@@ -44,7 +44,7 @@ uniweb doctor                # diagnose project configuration (--fix to repair)
 
 `uniweb inspect` is the important one for content. Every parse rule in Part 3 is faster to *confirm* than to re-derive, and re-deriving from memory is where agents go wrong. Don't predict the shape — print it.
 
-`uniweb status` is the one for a project other people edit. A site in the Uniweb app can change there at any time, teammates push to git, and Uniweb releases often. Run it when you begin, before you push, and after a command refuses: it changes nothing, and ends with the commands to run, in order (`--json` for a script).
+`uniweb status` is the one for a project other people edit. A site in the Uniweb app can change there at any time, teammates push to git, and Uniweb releases often. Run it when you begin, when you come back to the project, before you push, publish or deploy, and after a command refuses: it changes nothing, opens with what the site is — synced where, live where — and ends with the commands to run, in order (`--json` for a script).
 
 ### The four silent failures
 
@@ -192,7 +192,7 @@ The rest of this guide explains how Uniweb works. This part is what to do *first
 
 ### 1. Orient — what kind of workspace is this?
 
-**Run `uniweb status` first.** It says whether the site changed in the app since this copy last synced, whether git or Uniweb has something newer, and what to run about each — before you edit something someone else just changed.
+**Run `uniweb status` first.** It says where the site sits and what it is made of — the workspace's sites and foundations, the foundation this site is built with and which other sites a change to it reaches, pages it takes from outside its folder (another repository, sometimes), the languages it is written in — then whether it changed in the app since this copy last synced, whether git or Uniweb has something newer, and what to run about each, before you edit something someone else just changed. Run at the root of a workspace with several sites, it says what each one is. The rest of this step is how to read the same wiring by hand.
 
 **There is no single layout. Read `pnpm-workspace.yaml` first** — its `packages:` globs name the shape in one glance:
 
@@ -2864,6 +2864,14 @@ uniweb <command> --help           # Per-command flags — no side effects. Prefe
 
 Foundations have their own free path too: `uniweb add ci --target foundation` publishes to permanent versioned URLs on GitHub Pages.
 
+**Three facts about a site, and they are independent — `uniweb status` opens with all three:**
+
+- **Synced** — the project has a site on a backend, so authors can edit it in the Uniweb app. `sync.json` names it on each backend: `https://uniweb.app` by default, or a server of your own (`uniweb login --server <url>`).
+- **Published** — that backend serves it live: Uniweb Cloud, on `https://uniweb.app`. A published site is a synced site; a synced site need not be published — it can sit in the app as a draft.
+- **Deployed** — a build of it is on another host, such as GitHub Pages or S3: by CI on every push (`uniweb add ci`), or by hand (`uniweb deploy`). `deploy.yml` lists those hosts, and a bare `uniweb deploy` goes to its default target.
+
+A site can be in more than one place — usually while it moves from one host to another. Before you ship, read where it is: `publish` makes a change live on Uniweb Cloud, `git push` on a CI-deployed host, and `uniweb deploy --target <name>` on one deployed by hand — and each of these is the person's to decide. `uniweb status` also lists the services the live site has (`services:` in `site.yml` is the request, never proof of what the site has).
+
 ### Uniweb Cloud and the two-sided workflow
 
 `uniweb publish` ships to Uniweb Cloud, and it's worth understanding what that buys, because it isn't only hosting — it's how a team of technical and non-technical people works on one site.
@@ -2902,7 +2910,7 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 - **Git is the reviewed, durable record** — you `pull` content back, read it with `git diff`, and commit.
 - **Authors never push or pull.** For them, content simply updates, whether the change came from another author or from a developer's CLI.
 
-**Working on a site others edit — run `uniweb status` when you begin, before you push, and after any refusal.** It reads the backend without taking anything: what changed there since this copy last synced, file by file; what you hold that it lacks; whether the site is live; who has it open in the app right now, and on which file. Then it lists the commands to run, in an order that works from the top — `uniweb pull` before the push it would otherwise refuse. Three habits go with it: take what changed (`pull`, or `refresh`) before you edit; never `--force` past a refusal; and when someone has a page open in the app, tell the person before you change that page. A step marked *ask the person first* — going live, which may cost money — is theirs to decide.
+**Working on a site others edit — run `uniweb status` when you begin, when you come back to it, before you push, publish or deploy, and after any refusal.** It reads the backend without taking anything: what changed there since this copy last synced, file by file — as `uniweb pull` would write it, translations and records included; what you hold that it lacks; where the site is live, and what services it has; who has it open in the app right now, and on which file. Then it lists the commands to run, in an order that works from the top — `uniweb pull` before the push it would otherwise refuse. Three habits go with it: take what changed (`pull`, or `refresh`) before you edit; never `--force` past a refusal; and when someone has a page open in the app, tell the person before you change that page. A step marked *ask the person first* — going live, which may cost money — is theirs to decide.
 
 **Nobody's work is overwritten without asking.** `uniweb push` is refused if the site changed on the backend since your last pull — usually an author editing in the app — and reports what changed; nothing is written. Edits to different sections never collide. **In a git repository `uniweb pull` merges, like `git pull`:** it commits the backend's content (*"The site's content on …"*) and merges that commit into your branch, against the last state of the site your history shares with the backend. Your work, committed or not, and a teammate's arriving through git are kept; a file the backend never had is never deleted; changes to different parts of a file combine silently; and only a genuine overlap leaves conflict markers and a non-zero exit — so `uniweb pull && uniweb push` never ships markers. Settle a conflict as in any merge, then `git commit`; where your uncommitted changes overlap what the pull brought, the markers are theirs — settle them and `git add` each file, then `git stash drop` (git keeps them in the stash too). A push or publish is refused while a file under the site is in conflict. **In a git repository a push sends what you have committed:** with the site's content not committed it is refused before anything is sent, naming the files — commit them, or run `uniweb push --commit -m "…"` (it commits the site's content only, and leaves anything else staged as it is); `publish` and `sync` take `--commit` too. That commit is where the next pull merges from, which is how the pull tells your changes from the backend's. What the push writes back into the files — the ids the backend assigned — it commits itself, as `uniweb`. When the backend has nothing new, a pull says so and lists the files where yours hold changes it lacks. `uniweb refresh` runs `git pull` first, then the same pull. A push is also refused when your branch does not hold what this copy last took from the backend — after `git merge --abort`, or in a fresh clone that has not pulled — so pull, then push. Outside git — which includes a folder the repository around it ignores, such as a scratch directory — `uniweb pull` takes the backend's version over your files, asking first. `--force` is the deliberate overwrite (on `push` it replaces the backend's changes, on `pull` it discards yours); don't use it to get past a refusal. `uniweb sync` is `refresh` then `push`; neither publishes.
 

package/src/backend/app-changes.js

@@ -1,6 +1,12 @@
 /**
  * What changed on the backend since this copy last synced — READ, never taken.
  *
+ * ⚠️ THE SECOND ANSWER. In a repository `uniweb status` asks the pull itself
+ * (`commands/pull.js::probePull`), which names every file a pull would change. This answers
+ * where that cannot — outside git, or with no sync point to merge from — by units and
+ * records, not files: a section's translations, which a pull writes to `locales/*.json`,
+ * travel inside the section here (measured 2026-10-26: 8 units named, 11 files pulled).
+ *
  * `uniweb pull` takes the backend's content; `uniweb status` asks what there is to take.
  * The two must agree on what "changed" means, so this reads the backend as a pull does —
  * the same two lanes, the same conditional GET (`etagsHold`) — and compares the answer

package/src/backend/service-request.js

@@ -164,27 +164,43 @@ const names = (list) => list.map((n) => `\`${n}\``).join(', ')
  * @param {string[]|null} [p.supports] - from `foundationSupports`; null = unknown
  */
 export function announceServices({ siteYml, say, supports = null }) {
+  for (const note of serviceNotes({ siteYml, supports, warn: (m) => say.warn(m) })) say.warn(note)
+}
+
+/**
+ * Where `site.yml::services` and the foundation disagree — the notes `announceServices`
+ * says, as lines, for a caller that reports them (`uniweb status`).
+ *
+ * @param {object} p
+ * @param {object} p.siteYml - parsed
+ * @param {string[]|null} [p.supports] - from `foundationSupports`; null = unknown
+ * @param {(m: string) => void} [p.warn] - told what the file asks that will not be sent as written
+ * @returns {string[]}
+ */
+export function serviceNotes({ siteYml, supports = null, warn = () => {} }) {
   // An entry the push cannot read stops the package build next, which says what to write
   // (`refuseUnreadableServices`). Nothing to add before it — and what this would say, read
   // past that entry, is wrong: `search: yes` was "site.yml turns on `search`" (F14).
-  if (unreadableServices(siteYml?.services).length) return
-  const asks = readServicesRequest(siteYml?.services, { warn: (m) => say.warn(m) }) || []
-  if (!Array.isArray(supports)) return
+  if (unreadableServices(siteYml?.services).length) return []
+  const asks = readServicesRequest(siteYml?.services, { warn }) || []
+  if (!Array.isArray(supports)) return []
+  const notes = []
   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\`).`)
+    notes.push(`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(
+    notes.push(
       `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.`
     )
   }
+  return notes
 }
 
 /**

package/src/commands/doctor.js

@@ -1993,6 +1993,54 @@ async function runDoctor(args = []) {
       }
     }
 
+    // ⛔ The keys retired on 2026-09-20 read as nothing, without a word: a deploy recorded
+    // under `lastDeploy:` is one `uniweb status` cannot see, and `autoSave: off` is ignored,
+    // so deploys are recorded after all. A renamed key returns empty; it does not fail.
+    const retired = ['lastDeploy', 'autoSave'].filter((k) => deployYml[k] !== undefined)
+    if (retired.length) {
+      const id = 'deploy-yml-retired-key'
+      const issue = {
+        id,
+        type: 'warn',
+        site: siteName,
+        message: `deploy.yml uses ${retired.map((k) => `\`${k}:\``).join(' and ')}, which the CLI no longer reads`
+      }
+      issues.push(issue)
+      warn(`[${id}] ${siteName}: deploy.yml uses ${retired.map((k) => `\`${k}:\``).join(' and ')}, which the CLI no longer reads.`)
+      const lost = []
+      if (deployYml.lastDeploy && typeof deployYml.lastDeploy === 'object') {
+        const names = Object.keys(deployYml.lastDeploy).filter((n) => !deployYml.deploys?.[n])
+        if (names.length) lost.push(`the last deploy of ${names.map((n) => `\`${n}\``).join(', ')} is recorded only there, where nothing sees it`)
+      }
+      if (String(deployYml.autoSave) === 'off') lost.push('`autoSave: off` is ignored, so deploys are recorded')
+      const renamed = { lastDeploy: 'deploys', autoSave: 'saveDeploys' }
+      log(
+        `    ${colors.dim}${retired.map((k) => `\`${k}:\` is \`${renamed[k]}:\``).join(' and ')} now${lost.length ? ` — ${lost.join('; ')}` : ''}.${colors.reset}`
+      )
+      if (shouldFix(id)) {
+        try {
+          const { retireDeployYmlKeys } = await import('@uniweb/build/site')
+          const done = await retireDeployYmlKeys(sitePath)
+          if (done) {
+            issue.fixed = true
+            fixed(
+              `${relative(workspaceDir, deployYmlPath)}: ${[
+                done.moved.length && `moved ${done.moved.join(', ')} to \`deploys:\``,
+                done.saveDeploys === false && 'wrote `saveDeploys: false`',
+                'removed the old keys'
+              ]
+                .filter(Boolean)
+                .join(', ')}`
+            )
+          }
+        } catch (err) {
+          warn(`[${id}] could not rewrite ${relative(workspaceDir, deployYmlPath)}: ${err.message}`)
+        }
+      } else {
+        log(`    ${colors.dim}Run \`uniweb doctor --fix ${id}\` to move them, keeping your comments.${colors.reset}`)
+      }
+    }
+
     // github-pages-specific: if a target has `domain`, `site/public/CNAME`
     // should exist with that value. Vite copies public/ into dist/, and
     // GH Pages reads dist/CNAME on each deploy to keep the custom domain

package/src/commands/pull.js

@@ -150,10 +150,12 @@ const colors = {
   green: '\x1b[32m',
   blue: '\x1b[36m'
 }
-// Looked up at each call, so a caller that captures the console captures these too.
-const log = (...a) => console.log(...a)
+// Looked up at each call, so a caller that captures the console captures these too — and
+// silent while a probe runs (`probePull`), which answers by what it returns.
+let quiet = false
+const log = (...a) => quiet || console.log(...a)
 const success = (m) => log(`${colors.green}✓${colors.reset} ${m}`)
-const error = (m) => console.error(`${colors.red}✗${colors.reset} ${m}`)
+const error = (m) => quiet || console.error(`${colors.red}✗${colors.reset} ${m}`)
 const info = (m) => log(`${colors.blue}→${colors.reset} ${m}`)
 const note = (m) => log(`  ${colors.dim}${m}${colors.reset}`)
 
@@ -568,6 +570,34 @@ const pulledFrom = (origin) => `The site's content on ${origin}`
 const mergedFrom = (origin) => `Merge the site's content from ${origin}`
 const takenFrom = (origin) => `Take the site's content from ${origin}`
 
+/**
+ * What a pull would change in the files, and nothing more — for `uniweb status`.
+ *
+ * ⭐ THE PULL ITSELF, STOPPED BEFORE IT TAKES ANYTHING. The same requests, the same base,
+ * the same projection onto it in a stand-in — so status and pull cannot disagree about
+ * which files the backend changed: a section's translations (`locales/*.json`) and a
+ * record's file are named as the pull would write them. It downloads no media, merges
+ * nothing, commits nothing and banks nothing — no ETag, version, hash or sync point —
+ * and prints nothing.
+ *
+ * Null when a probe cannot answer: outside git, where a pull writes into the files; in a
+ * repository with no commit or no sync point to merge from; when a lane failed or the
+ * workspace was refused. The caller then says what it can by other means.
+ *
+ * @param {string[]} [args] - the workspace flags only (`--org`, `--personal`)
+ * @param {object} [deps] - as for `pull`; `getToken` keeps it from ever asking for a login
+ * @returns {Promise<{ files: Array<[string, string]>, recordsNotPlaced: boolean } | null>}
+ *   `files` — `[status, path]`, status `A`, `M` or `D`, the path relative to the site
+ */
+export async function probePull(args = [], deps = {}) {
+  quiet = true
+  try {
+    return (await pull(args, { ...deps, probe: true }))?.probe ?? null
+  } finally {
+    quiet = false
+  }
+}
+
 export async function pull(args = [], deps = {}) {
   // See utils/flag-guard.js — an unrecognized flag is invisible to a literal scan, so
   // it silently keeps the default: a mistyped `--dry-run` would pull for real, and a
@@ -587,13 +617,20 @@ export async function pull(args = [], deps = {}) {
   const force = args.includes('--force')
 
   const siteDir = await resolveSiteDir(args, 'pull')
-  const fetchAssets = shouldFetchAssets(args, siteDir)
+  // ⛔ A probe (`probePull`) fetches no media: it says what changes, and takes nothing.
+  const probe = Boolean(deps.probe)
+  const fetchAssets = !probe && shouldFetchAssets(args, siteDir)
 
   // ⭐ IN A REPOSITORY A PULL MERGES; OUTSIDE ONE IT CHECKS OUT. A merge needs the state both
   // sides started from, and only a history holds one (`utils/sync-point.js`). Outside git
   // a pull rewrites the files, so work there that a pull did not write stops it.
   const repo = repoOf(siteDir)
-  if (repo && !dryRun) {
+  // A probe writes onto a commit in a stand-in, never into the files: with no repository,
+  // or no commit to write onto, it has nothing to say.
+  if (probe && !repo?.head) return { exitCode: 0, probe: null }
+  // …and touching nothing here, it is not stopped by what a merge would be: a conflict or a
+  // merge waiting is the caller's to report.
+  if (repo && !dryRun && !probe) {
     if (!repo.head) {
       error('This repository has no commits yet, so there is nothing for a pull to merge into.')
       note('Commit the project, then pull.')
@@ -631,7 +668,9 @@ export async function pull(args = [], deps = {}) {
     command: 'Pulling'
   })
   // One reader of Models for the whole pull, so a Model is read once whichever lane asks first.
-  const readModel = makeModelResolver({ client, siteDir })
+  // ⛔ A probe keeps none: a Model kept here is what a later offline emit resolves with, and a
+  // probe takes nothing (`probePull`).
+  const readModel = makeModelResolver({ client, siteDir: probe ? null : siteDir })
 
   // ⭐ No scope check any more — and none is needed. This project's identity on
   // `client.origin` is read from that origin's own section of sync.json, so a
@@ -703,6 +742,9 @@ export async function pull(args = [], deps = {}) {
   // body). `doRequest` is a thunk returning the client's Response promise. 404 / any
   // failure → null (the lane is skipped, not fatal) — except a workspace mismatch,
   // `{ refused: true }`, which stops the pull: the other lane would only say it again.
+  // A lane that answered 404 is named in `missing`, so a probe can tell a site with no
+  // records lane from a lane that did not answer.
+  const missing = new Set()
   const getDocs = async (label, doRequest) => {
     info(
       `Pulling ${colors.bright}${label}${colors.reset} from ${colors.dim}${client.origin}${colors.reset} …`
@@ -718,6 +760,7 @@ export async function pull(args = [], deps = {}) {
     }
     if (res.status === 404) {
       note(`${label}: not found (404) — it was deleted, or you lack access.`)
+      missing.add(label)
       return null
     }
     if (res.status === 304) {
@@ -820,6 +863,12 @@ export async function pull(args = [], deps = {}) {
       ? splitRecordsPull(folderLane.docs)
       : null
   const projected = Boolean(siteDoc) || Boolean(folderTaken)
+  if (probe) {
+    // A lane that did not answer is not knowing — a records lane the backend has none of
+    // (404) is no records; both unchanged is nothing to take.
+    if (!content || (!noRecords && !folderLane && !missing.has('records'))) return { exitCode: 1, probe: null }
+    if (!projected) return { exitCode: 0, probe: { files: [], recordsNotPlaced: false } }
+  }
 
   // ── What the project itself says, read before anything is written ──────────
   // The foundation, the Models and the scope come from the project as it is: in a
@@ -950,6 +999,9 @@ export async function pull(args = [], deps = {}) {
       origin: client.origin,
       siteUuid: siteContentUuid
     })
+    // A probe with no base has no way to tell the backend's changes from this copy's: onto
+    // HEAD, every difference would read as the backend's.
+    if (probe && !base) return { exitCode: 0, probe: null }
     onto = force || !base ? repo.head : base
     try {
       standIn = openStandIn(repo, { roots, rev: onto })
@@ -1071,7 +1123,7 @@ export async function pull(args = [], deps = {}) {
       // ⭐ A FILE RECORD'S BYTES (`@uniweb/file`, 2026-09-28): fetched to where `folder.yml` now
       // places each one, as media are fetched. A file that did not arrive is a record not taken —
       // reported, and the pull fails below as it does for any, so the next one fetches it again.
-      if (report.fileDownloads?.length) {
+      if (report.fileDownloads?.length && !probe) {
         const got = await downloadFileRecords({
           downloads: report.fileDownloads,
           siteDir: projDir,
@@ -1106,6 +1158,12 @@ export async function pull(args = [], deps = {}) {
       for (const w of report.warnings) note(`! ${w}`)
     }
 
+    // ⭐ A PROBE STOPS HERE, the stand-in holding what this pull would take: what differs
+    // from the base is what the backend changed. Nothing is banked; `finally` closes it.
+    if (probe) {
+      return { exitCode: 0, probe: { files: standIn.changes(), recordsNotPlaced: Boolean(recordsNotPlaced) } }
+    }
+
     // Outside git: what this pull wrote, so the next one can tell its own output from the
     // author's work. Config files are rewritten every pull whether or not they changed;
     // include the ones the projector owns so a pull-then-pull doesn't trip on them either.