uniweb 1.7.4 → 1.8.0

package/src/commands/push.js

@@ -95,6 +95,7 @@ import {
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
   dropSiteBoundValues,
+  untakenBase,
   pushSyncPackages
 } from '../backend/site-sync.js'
 import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
@@ -336,6 +337,17 @@ export async function push(args = [], deps = {}) {
       note(`Dropped the previous site's ${stale.join(' and ')} from site.yml.`)
     }
   }
+  // ⛔ A GATED PUSH CLAIMS A BASE ONLY WHILE THE FILES HOLD IT (`untakenBase`) — said before
+  // anything is uploaded. A dry run previews it; `-o` reaches no backend, and `--force`
+  // drops the gate.
+  if (!output && !force) {
+    const untaken = untakenBase(siteDir, client.origin)
+    if (untaken) {
+      error(untaken.headline)
+      for (const line of untaken.lines) note(line)
+      return { exitCode: 1 }
+    }
+  }
   const priorHashes = readSyncCache(siteDir, client.origin)
   // Per-item identity, without which the backend reads every record as new and
   // recreates every page and section row.

package/src/commands/refresh.js

@@ -17,17 +17,16 @@
  * which is the whole point of a start-of-day command. A version that also pushed
  * would be one you had to think about first, and so one people would stop running.
  *
- * Order is deliberate: git first, then the backend. Teammates' commits are then in
- * the files when the backend's content arrives, and `pull --merge` merges a
- * teammate's change to a file the last pull wrote just as it merges your own edits:
- * against the version that pull wrote, found in the repo's history (`pull.js`,
- * `captureLocalWork`). And if git itself conflicts, refresh stops there — one source
- * of conflict at a time.
+ * Order is deliberate: git first, then the backend. Teammates' commits — and the sync
+ * points their pulls merged — are then in the history when the backend's content
+ * arrives, so the pull merges against the newest state of the site this history shares
+ * with the backend (`utils/sync-point.js`), and a teammate's change is merged like your
+ * own. And if git itself conflicts, refresh stops there — one source of conflict at a
+ * time.
  *
- * ⛔ Until 2026-10-16 this said the merge's ancestor was the COMMITTED version of each
- * file, so taking teammates' commits first made it fresher. That was HEAD — the rule
- * `pull --merge` dropped on 2026-09-23, because HEAD stops being the version a pull
- * wrote the moment an edit is committed on top of it.
+ * ⛔ Until 2026-10-17 the merge's ancestor was what this copy's last pull wrote, per file,
+ * from a per-machine record — so a teammate's committed work outside that record was
+ * overwritten or pruned, and a fresh clone's was all outside it.
  *
  * Exits NON-ZERO when a merge left conflicts, the way a conflicted `git merge`
  * does. That is what makes `uniweb refresh && uniweb push` correct by
@@ -35,7 +34,7 @@
  * content. If a `sync` verb is ever wanted, it is that chain.
  *
  * Usage:
- *   uniweb refresh                 git pull, then merge the backend's content
+ *   uniweb refresh                 git pull, then pull: merge the backend's content
  *   uniweb refresh --no-git        skip the git remote; backend only
  *   uniweb refresh --no-backend    skip the backend; git only
  *
@@ -99,7 +98,7 @@ function siteContentUuid(siteDir, backend) {
 export async function refresh(args = [], deps = {}) {
   // An unrecognized flag is invisible to a literal scan, so it silently keeps the
   // default — a mistyped `--no-git` would still pull from the git remote. And this is
-  // the only check refresh's argv gets: the pull it runs is handed `--merge` alone
+  // the only check refresh's argv gets: the pull it runs is handed nothing of it
   // (below). A backend flag or `--token` is refused here too, naming `uniweb login`
   // (`utils/flag-guard.js`). *(This explained the check by a mistyped `--backend`
   // until 2026-10-16; the verb has taken no backend flag since 2026-09-21.)*
@@ -164,11 +163,11 @@ export async function refresh(args = [], deps = {}) {
   } else {
     say.info("Merging the backend's content…")
     const pull = deps.pull || (await import('./pull.js')).pull
-    // `--merge` rather than a plain pull: an author editing a different part of the
-    // same section is not a conflict, and should not be presented as one.
-    // Nothing of refresh's own argv is forwarded: the pull goes to the backend you are
-    // logged in to, as refresh does, and authenticates the same way.
-    const res = await pull(['--merge'])
+    // A pull merges: an author editing a different part of the same section is not a
+    // conflict, and is not presented as one. Nothing of refresh's own argv is forwarded:
+    // the pull goes to the backend you are logged in to, as refresh does, and
+    // authenticates the same way.
+    const res = await pull([])
     conflicts = res?.merge?.conflicted?.length ?? 0
     if (res?.exitCode && !conflicts) {
       // Failed for a reason other than conflicts — say so plainly rather than

package/src/index.js

@@ -1870,7 +1870,8 @@ ${colors.bright}Usage:${colors.reset}
 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\`.
+This does both — git first (merging, never rebasing), then \`uniweb pull\`, which in
+a repository merges the backend's content with yours.
 
 ${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.
@@ -1879,9 +1880,9 @@ ${colors.bright}Options:${colors.reset}
   --no-git           Skip the git remote; backend only
   --no-backend       Skip the backend; git only
 
-\`--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.
+\`--force\` is 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}

package/src/utils/flag-guard.js

@@ -77,7 +77,7 @@ const VERBS = {
     '--no-validate', '--yes', '--no-verify', '--no-release', '--bump', ...VIA_DEPLOY
   ],
   pull: [
-    '--content-only', '--dry-run', '--force', '--merge',
+    '--content-only', '--dry-run', '--force',
     '--no-assets',
     '--no-records', '--no-delete', '--no-prune',
     // via backend/site-sync.js (the owner resolver) and utils/conformance.js
@@ -85,7 +85,7 @@ const VERBS = {
   ],
   clone: [
     '--content-only', '--no-assets', '--no-records', '--path',
-    '--project', '--org', '--personal'
+    '--project', '--org', '--personal', '--no-git'
   ],
   register: [
     '--dry-run', '--json', '--output', '-o',
@@ -113,13 +113,12 @@ const VERBS = {
     '--no-release', '--bump', ...VIA_DEPLOY
   ],
   /**
-   * `refresh` = `git pull`, then a DELEGATED `pull --merge`.
+   * `refresh` = `git pull`, then a DELEGATED `pull`.
    *
-   * It forwards nothing of its own argv to that pull — it builds `['--merge']`
-   * 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.
+   * It forwards nothing of its own argv to that pull. So pull's own flags (`--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
@@ -238,6 +237,19 @@ export function checkFlags(verb, args = []) {
       message: `\`--as-org\` is retired — use \`--org @org\` (e.g. \`uniweb ${verb} --org @acme\`).`
     }
   }
+  // ⭐ `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.
+  if (flag === '--merge' && verb === 'pull') {
+    return {
+      flag,
+      suggestion: null,
+      message: [
+        '`uniweb pull` has no `--merge`: in a git repository a pull always merges.',
+        '  Run `uniweb pull`. Outside git it takes the backend\'s version, asking first.'
+      ].join('\n')
+    }
+  }
   const suggestion = didYouMean(flag, all)
   const lines = [`Unknown flag \`${flag}\` for \`uniweb ${verb}\`.`]
   if (suggestion) lines.push(`  Did you mean \`${suggestion}\`?`)

package/src/utils/git.js

@@ -12,25 +12,23 @@
  * monorepos/workspaces"), and whole scopes of real projects are versioned by a
  * parent repo rather than being repo roots themselves. So the question is never
  * "is this directory a git root" but "is this path tracked by some repo", which is
- * the question git itself answers. Callers degrade to an explicit confirmation
- * when the answer is no; sync already requires an account, and a second hard
- * dependency for a safety net we can provide anyway is a bad trade.
+ * the question git itself answers. Outside one a pull checks out, asking first; in
+ * one it merges (`utils/sync-point.js`).
  */
 
 import { execFileSync } from 'node:child_process'
-import { createHash } from 'node:crypto'
-import { readFileSync, realpathSync } from 'node:fs'
-import { join, relative } from 'node:path'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
 import yaml from 'js-yaml'
 
 /**
  * The files and directories `uniweb pull` writes into.
  *
- * ONE definition, shared by the guard that blocks a pull and the message that
- * tells someone how to recover from a refused push — a second copy would drift,
- * and a stale list here means either a guard that misses or advice that is wrong.
- * `paths:` can relocate the content roots, so the local site.yml is consulted
- * rather than assuming the defaults.
+ * ONE definition, shared by the guard that stops a pull outside git and the merge a
+ * pull makes in a repository, whose sync points hold exactly these (and `public/`, where
+ * the media land) — a second copy would drift, and a stale list here means a guard that
+ * misses or a merge that drops a file. `paths:` can relocate the content roots, so the
+ * local site.yml is consulted rather than assuming the defaults.
  */
 export function siteContentRoots(siteDir) {
   // ⚠️ `queries.yml` IS AT THE SITE ROOT, and that is why it must be named here.
@@ -62,12 +60,6 @@ export function siteContentRoots(siteDir) {
   return [...roots]
 }
 
-/** Is there uncommitted work where a pull would write? False outside a repo. */
-export function hasUncommittedContent(siteDir) {
-  const dirty = uncommittedUnder(siteDir, siteContentRoots(siteDir))
-  return Array.isArray(dirty) && dirty.length > 0
-}
-
 function git(args, cwd) {
   return execFileSync('git', args, {
     cwd,
@@ -88,196 +80,6 @@ export function isGitRepo(dir) {
   }
 }
 
-/**
- * Uncommitted work under `relPaths`, relative to `dir`.
- *
- * Counts modified, staged, deleted AND untracked files. Untracked matters as much
- * as modified here: a section file that exists only locally is not on the backend,
- * so a pruning pull deletes it — losing work that was never committed anywhere.
- *
- * ⛔ **Returned relative to `dir`, which is NOT what git prints.** `--porcelain`
- * paths are always relative to the REPOSITORY ROOT, whatever directory it runs
- * in, so they only coincide with `dir`-relative when the site *is* the repo root.
- * Both callers do `join(siteDir, rel)` with the result, so the un-normalized form
- * was wrong for every nested layout — a site at `myproject/site/` inside a repo.
- *
- * What that cost, measured 2026-08-12: pull exempts its own previous output from
- * the uncommitted-work guard by looking each dirty path up in a record keyed
- * `dir`-relative (`utils/pull-written.js`). Given `myproject/site/site.yml` the
- * lookup missed, so **pull refused on files pull itself had written** — the exact
- * false alarm that record exists to prevent, and the one its own comment warns
- * teaches people to reach for `--force`. `captureLocalWork` had the same defect
- * one door along: it reads each path back with `join(siteDir, rel)`.
- *
- * The earlier `@returns` said "repo-relative-ish paths as git reports them" while
- * the summary above said "relative to `dir`" — the ambiguity was noticed and left,
- * and both callers had picked the other reading.
- *
- * @returns {string[]|null} paths relative to `dir`, or `null` when this isn't a
- *   git work tree (distinct from `[]`, which means "clean").
- */
-export function uncommittedUnder(dir, relPaths) {
-  if (!isGitRepo(dir)) return null
-  // ⚠️ Both sides must be REAL paths before `relative` can compare them.
-  // `rev-parse --show-toplevel` resolves symlinks; the caller's `dir` usually has
-  // not. On macOS that alone breaks it — `/var` is a symlink to `/private/var`,
-  // so a repo under the temp dir yields a root of `/private/var/…` against a dir
-  // of `/var/…`, and `relative` walks all the way up and back down. The result is
-  // a valid-looking path that matches nothing, i.e. the same silent miss this
-  // normalization exists to fix. Any symlinked checkout does it, not just tmp.
-  let root
-  let base
-  try {
-    root = git(['rev-parse', '--show-toplevel'], dir).trim()
-    base = realpathSync(dir)
-  } catch {
-    return null
-  }
-  try {
-    const out = git(
-      ['status', '--porcelain', '--untracked-files=all', '--', ...relPaths],
-      dir
-    )
-    return (
-      out
-        .split('\n')
-        .filter(Boolean)
-        // porcelain v1: XY<space>path, and a rename is "orig -> new".
-        .map((line) => line.slice(3).trim())
-        .map((p) => (p.includes(' -> ') ? p.split(' -> ')[1] : p))
-        // Porcelain paths are repo-root-relative; callers want them relative to
-        // `dir`. Quoted paths (git quotes names with spaces or non-ASCII when
-        // `core.quotePath` is on) are left alone rather than half-decoded — a
-        // wrong path is worse than an unmatched one here, since an unmatched
-        // path merely stays "dirty" and the guard errs toward refusing.
-        .map((p) => (p.startsWith('"') ? p : relative(base, join(root, p))))
-        .filter(Boolean)
-    )
-  } catch {
-    // A path git doesn't know (e.g. none of the roots exist yet) is not an error
-    // worth failing a pull over.
-    return []
-  }
-}
-
-/**
- * A file's content at HEAD — the ancestor of a three-way merge for a file no pull
- * wrote. For one a pull wrote, the ancestor is the version it wrote, found in history
- * by `findCommitted` below: HEAD stops being that version the moment an edit is
- * committed on top of it.
- *
- * Either way the ancestor is on this side, which is the point: the backend keeps no
- * per-version item content, and retaining some so it could feed a merge running on
- * the client would put a permanent second write on its hottest table. It doesn't
- * have to — the tool that already knows how to merge holds the history.
- *
- * ⛔ Until 2026-10-16 this called HEAD's content THE common ancestor ("`uniweb pull`
- * writes the backend's content into these files, so the committed version IS the
- * state both sides diverged from") — the rule `pull --merge` dropped on 2026-09-23.
- *
- * @returns {Buffer|null} null when the path isn't in HEAD — a file added locally and
- *   never committed has no ancestor; when the backend holds it too, `pull --merge`
- *   merges the two versions two-way.
- */
-export function showAtHead(dir, relPath) {
-  return showAt(dir, 'HEAD', relPath)
-}
-
-/**
- * A file's content at a revision, by a path relative to `dir`.
- *
- * ⛔ THE `./` IS WHAT MAKES THE PATH RELATIVE TO `dir`. In `<rev>:<path>` a bare path
- * is read from the REPOSITORY ROOT, whatever the cwd. With the repo at the project
- * root and the site in `site/` — the default layout — `HEAD:pages/home/hero.md`
- * named nothing, every lookup failed, and `pull --merge` "kept yours" for every file:
- * the backend's changes never merged in, while the pull recorded them as taken
- * (2026-09-23). Every merge test ran with the repo AT the site directory, the one
- * layout where a bare path happens to work.
- *
- * @returns {Buffer|null} null when the path isn't in that revision
- */
-export function showAt(dir, rev, relPath) {
-  try {
-    return execFileSync('git', ['show', `${rev}:./${relPath}`], {
-      cwd: dir,
-      stdio: ['ignore', 'pipe', 'ignore'],
-      maxBuffer: 64 * 1024 * 1024
-    })
-  } catch {
-    return null
-  }
-}
-
-/**
- * The most recent committed version of a file whose content hashes to `sha256` —
- * how the version a pull wrote is found again, as the ancestor of a merge.
- *
- * HEAD is that version only until the user commits an edit on top of it. After that
- * HEAD is THEIR edit, and a merge against it reads their change as the starting
- * point: the backend's version wins whole and the committed edit is reverted in the
- * working tree. The pull recorded the hash of what it wrote (`pull-written.json`),
- * so the version is recoverable from history by content, wherever it was committed.
- *
- * @param {number} [limit] - how many commits touching the file to search
- * @returns {Buffer|null} null when no committed version matches
- */
-export function findCommitted(dir, relPath, sha256, { limit = 50 } = {}) {
-  let revs
-  try {
-    revs = git(['log', `-n${limit}`, '--format=%H', '--', `./${relPath}`], dir)
-      .split('\n')
-      .filter(Boolean)
-  } catch {
-    return null
-  }
-  for (const rev of revs) {
-    const buf = showAt(dir, rev, relPath)
-    if (buf && createHash('sha256').update(buf).digest('hex') === sha256) return buf
-  }
-  return null
-}
-
-/**
- * Three-way merge, in place: `minePath` is rewritten with the merged result.
- *
- * Delegates to `git merge-file`, which is the same machinery git uses for a merge —
- * text that only one side touched is taken silently, and only genuine overlaps get
- * conflict markers. Building our own would be a worse version of a solved problem.
- *
- * @returns {{ merged: boolean, conflicted: boolean }} `merged:false` means the merge
- *   could not be attempted at all, which is different from attempting it and finding
- *   conflicts — the caller must not conflate them.
- */
-export function mergeFile(dir, minePath, basePath, theirsPath, labels = {}) {
-  try {
-    execFileSync(
-      'git',
-      [
-        'merge-file',
-        '-L',
-        labels.mine || 'yours (local)',
-        '-L',
-        labels.base || 'common ancestor',
-        '-L',
-        labels.theirs || 'theirs (backend)',
-        minePath,
-        basePath,
-        theirsPath
-      ],
-      { cwd: dir, stdio: ['ignore', 'ignore', 'ignore'] }
-    )
-    return { merged: true, conflicted: false }
-  } catch (err) {
-    // A positive status is the CONFLICT COUNT and the file still holds a valid
-    // merge with markers. Anything else (git missing, unreadable input) means no
-    // merge happened and the caller must fall back rather than trust the file.
-    if (typeof err?.status === 'number' && err.status > 0 && err.status < 128) {
-      return { merged: true, conflicted: true }
-    }
-    return { merged: false, conflicted: false }
-  }
-}
-
 /** Does this repo have a remote configured to pull from? */
 export function hasRemote(dir) {
   try {
@@ -288,12 +90,17 @@ export function hasRemote(dir) {
 }
 
 /**
- * `git pull --ff-only` — bring in teammates' commits.
+ * `git pull`, merging — bring in teammates' commits.
+ *
+ * ⭐ A MERGE, NOT A REBASE. A pull of the backend's content merges a sync point into the
+ * branch (`utils/sync-point.js`), and a rebase would replay that commit onto another
+ * base — no longer the backend's content, and no longer a base for the next merge. So the
+ * branch is merged with its remote too, whatever `pull.rebase` says, with uncommitted
+ * work stashed and put back (`--autostash`). A conflict is git's, settled with git's
+ * vocabulary; refresh reports it and steps back.
  *
- * Fast-forward only, deliberately. A refresh should never silently create a merge
- * commit or drop the user into a rebase they didn't ask for; if the branches have
- * genuinely diverged, that is a git problem the user should handle in git, with
- * git's own vocabulary. We report and step back.
+ * ⛔ Until 2026-10-17 this was `--ff-only`, which refused once a pull had made a merge
+ * commit the remote did not have.
  *
  * @returns {{ ok: boolean, changed: boolean, message: string }}
  */
@@ -306,7 +113,7 @@ export function pullRemote(dir) {
     }
   })()
   try {
-    const out = execFileSync('git', ['pull', '--ff-only'], {
+    const out = execFileSync('git', ['pull', '--no-rebase', '--no-edit', '--autostash'], {
       cwd: dir,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe']

package/src/utils/pull-written.js

@@ -1,37 +1,24 @@
 /**
- * The record of what a machine wrote into a site project — pull's own output.
- *
- * ⭐ And, since 2026-09-23, what a push delivered: the files of the units the backend
- * now holds as they were sent (`recordPushedUnits`, site-sync.js). Both are "the last
- * version this file synced at", which is what `pull --merge` needs as its ancestor —
- * found again in the repo's history by this hash (`findCommitted`, utils/git.js).
+ * The record of what a pull wrote into a site project — outside git.
  *
  * ## What it is for
  *
- * `uniweb pull` refuses to run when there are uncommitted changes under the files
- * it rewrites, because it reconciles the working tree to the backend and would
- * overwrite them. That guard needs one distinction to be useful: **a file the
- * user edited** versus **a file a previous pull wrote and nobody has touched
- * since**. Without it the guard cries wolf — pull rewrites the tree, so the next
- * pull sees its own output as uncommitted work and refuses, listing files the
- * user never touched. A guard that fires on nothing teaches people to reach for
- * `--force`, which is the destructive option.
- *
- * So each write is recorded with a content hash, and a dirty path whose hash
- * still matches is not user work.
- *
- * ## Why it lives here rather than in `pull.js`
+ * Outside git, `uniweb pull` rewrites the files under its roots from the backend, and
+ * nothing stands behind them — so it asks before it does, unless nothing there is the
+ * author's. That needs one distinction: **a file the author edited** versus **a file a
+ * previous pull wrote and nobody has touched since**. Without it the question comes
+ * every time — pull rewrites the tree, so the next pull sees its own output as the
+ * author's — and an unattended pull refuses over files nobody touched, which teaches
+ * people to reach for `--force`, the destructive option.
  *
- * `uniweb clone` has the same claim to make and cannot make it from there.
- * `pull.js` statically imports `@uniweb/build`, which resolves from the
- * *project's* `node_modules` — and `clone` runs before a project exists (see
- * `utils/uwx-read.js` for the same constraint on the `.uwx` reader).
+ * So each write is recorded with a content hash, and a path whose hash still matches is
+ * not the author's work.
  *
- * Clone scaffolds `site.yml` and `theme.yml` and then delegates to `pull`, so
- * without this the delegated pull sees clone's own scaffolding as uncommitted
- * user work and refuses — on a project created seconds earlier, where there is no
- * user work to protect. Clone records what it wrote; the guard then exempts those
- * files **for the right reason** rather than being overridden.
+ * ⛔ In a repository there is no such record: a pull merges, from a sync point
+ * (`utils/sync-point.js`). Until 2026-10-17 this record was also a merge's ancestor —
+ * the version each file last synced at, found again in the repository by its hash — and
+ * committed work outside it was lost; and `clone` recorded its scaffold here, before a
+ * delegated pull that now takes the backend's version with `--force`.
  *
  * Nothing here imports `@uniweb/build`, and nothing here may start to.
  */