uniweb 0.13.4 → 0.13.6

package/src/commands/refresh.js

@@ -0,0 +1,176 @@
+/**
+ * uniweb refresh — catch up with everything outside your working copy.
+ *
+ * A developer on a synced site has TWO independent external sources, and nothing
+ * in the tool used to connect them:
+ *
+ *   - the git remote — teammates' commits;
+ *   - the backend    — content authors' edits, made in the app.
+ *
+ * Someone who runs only `git pull` silently misses every app edit; someone who
+ * runs only `uniweb pull` misses their teammates. The person most likely to be
+ * caught out is exactly the one starting their day believing they are current.
+ * This is the one command for that: run it in the morning, or before a milestone.
+ *
+ * READ-ONLY, and that is the load-bearing decision. It never pushes. Because it
+ * cannot ship anything, it can be run reflexively without weighing consequences —
+ * 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. The three-way merge's common
+ * ancestor is the COMMITTED version of each file, so taking teammates' commits
+ * first makes that ancestor fresher and the merge more accurate. And if git itself
+ * conflicts, refresh stops there — one source of conflict at a time.
+ *
+ * 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
+ * construction: without it, the obvious one-liner ships conflict markers into live
+ * 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 --no-git        skip the git remote; backend only
+ *   uniweb refresh --no-backend    skip the backend; git only
+ *   uniweb refresh --backend <url> Override the backend origin
+ */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+
+import { resolveSiteDir } from './deploy.js'
+import { isGitRepo, hasRemote, pullRemote, headProvenance } from '../utils/git.js'
+import { probeUnpushed } from '../backend/site-sync.js'
+
+const c = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  cyan: '\x1b[36m', green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m',
+}
+const say = {
+  ok: (m) => console.log(`${c.green}✓${c.reset} ${m}`),
+  info: (m) => console.log(`${c.cyan}→${c.reset} ${m}`),
+  warn: (m) => console.log(`${c.yellow}⚠${c.reset} ${m}`),
+  err: (m) => console.error(`${c.red}✗${c.reset} ${m}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`),
+}
+
+// Forward a flag AND its value to the delegated verb. `--backend http://x` is two
+// argv entries, so a naive filter passes the flag and drops the URL — leaving the
+// delegated pull pointed at the default backend while the user believes they
+// overrode it. `--backend=http://x` is one entry and passes through as-is.
+function collectPassthrough(args, names) {
+  const out = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    const name = names.find((n) => a === n || a.startsWith(`${n}=`))
+    if (!name) continue
+    out.push(a)
+    if (a === name && args[i + 1] && !args[i + 1].startsWith('-')) out.push(args[++i])
+  }
+  return out
+}
+
+// A site is backend-synced once it has an identity to pull by.
+function siteContentUuid(siteDir) {
+  try {
+    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
+    return typeof y?.$uuid === 'string' ? y.$uuid : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @param {string[]} args
+ * @param {object} [deps] - injectable seams for testing, mirroring pull.js:
+ *   `resolveSiteDir`, and `pull` (so the backend step can be driven without a
+ *   network or a real backend).
+ */
+export async function refresh(args = [], deps = {}) {
+  const skipGit = args.includes('--no-git')
+  const skipBackend = args.includes('--no-backend')
+  const resolveSite = deps.resolveSiteDir || resolveSiteDir
+  const siteDir = await resolveSite(args, 'refresh')
+
+  // Which sources this run actually consulted. Reported at the end, because
+  // "up to date" is a different claim from "up to date with the two things I
+  // happened to be able to check" — and the second is all we can ever honestly
+  // say. Silently skipping a source is how someone concludes they are current
+  // when they are not.
+  const consulted = []
+  const skipped = []
+  let conflicts = 0
+
+  // ── 1. the git remote ─────────────────────────────────────────────────────
+  if (skipGit) {
+    skipped.push('git (--no-git)')
+  } else if (!isGitRepo(siteDir)) {
+    skipped.push('git (not a repository)')
+  } else if (!hasRemote(siteDir)) {
+    skipped.push('git (no remote configured)')
+  } else {
+    say.info('Pulling from the git remote…')
+    const r = pullRemote(siteDir)
+    if (!r.ok) {
+      say.err('git pull failed — resolve this before continuing.')
+      for (const line of r.message.split('\n').slice(0, 6)) say.dim(line)
+      // Deliberately stop. Layering the backend's content on top of an unresolved
+      // git state gives the user two independent conflicts at once, and no clear
+      // order to address them in.
+      return { exitCode: 1 }
+    }
+    say.dim(r.changed ? 'Took new commits from the remote.' : 'Already up to date with the remote.')
+    consulted.push('git')
+  }
+
+  // ── 2. the backend ────────────────────────────────────────────────────────
+  if (skipBackend) {
+    skipped.push('backend (--no-backend)')
+  } else if (!siteContentUuid(siteDir)) {
+    skipped.push('backend (this site has never been synced)')
+  } 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.
+    const passthrough = collectPassthrough(args, ['--backend', '--registry', '--token'])
+    const res = await pull(['--merge', ...passthrough])
+    conflicts = res?.merge?.conflicted?.length ?? 0
+    if (res?.exitCode && !conflicts) {
+      // Failed for a reason other than conflicts — say so plainly rather than
+      // reporting a clean refresh over a lane that never ran.
+      say.err('Could not merge the backend content.')
+      return { exitCode: res.exitCode }
+    }
+    consulted.push('backend')
+  }
+
+  // ── 3. where that leaves you ──────────────────────────────────────────────
+  console.log('')
+  if (consulted.length) say.dim(`Checked: ${consulted.join(', ')}`)
+  for (const s of skipped) say.dim(`Skipped: ${s}`)
+
+  const git = headProvenance(siteDir)
+  if (git) say.dim(`Commit : ${git.sha.slice(0, 8)}${git.dirty ? ' (working tree has changes)' : ''}`)
+
+  // What is still yours to send. The point of a milestone check is knowing both
+  // directions, not just that you took what was waiting.
+  if (!skipBackend && siteContentUuid(siteDir)) {
+    try {
+      const probe = await probeUnpushed(siteDir)
+      if (probe.changed) say.dim(`Unpushed: ${probe.changed} entit${probe.changed === 1 ? 'y' : 'ies'} changed locally`)
+    } catch {
+      /* the probe is a courtesy; never fail a refresh over it */
+    }
+  }
+
+  console.log('')
+  if (conflicts) {
+    say.err(`${conflicts} file(s) need you to resolve conflicts before pushing.`)
+    return { exitCode: 1 }
+  }
+  say.ok('Up to date.')
+  return { exitCode: 0 }
+}
+
+export default refresh

package/src/commands/sync.js

@@ -0,0 +1,75 @@
+/**
+ * uniweb sync — catch up, then share. `refresh` followed by `push`.
+ *
+ * The two halves already exist and already carry the safety:
+ *
+ *   - `refresh` takes teammates' commits and merges the backend's content, and
+ *     exits NON-ZERO when a merge left conflicts;
+ *   - `push` refuses when the backend has moved under you, and never overwrites
+ *     an author's work blind.
+ *
+ * So this verb adds no guarantees of its own — it composes two commands that
+ * already hold them. That is deliberate: a safety check you can only get by
+ * remembering to type `sync` is not a safety check, which is why the gate lives in
+ * `push` and the conflict stop lives in `refresh`. Anyone typing
+ * `uniweb refresh && uniweb push` gets the identical behaviour, and the exit codes
+ * are what make that chain correct rather than anything here.
+ *
+ * A THIN COMPOSITION, not a reimplementation. Both halves are called, never
+ * re-created. The `deploy`/`publish` split is the cautionary tale: two paths that
+ * did nearly the same thing drifted until one of them was quietly wrong.
+ *
+ * WHY IT STOPS ON CONFLICTS. Pushing after an unresolved merge would put conflict
+ * markers into content authors see. `refresh` reports them and exits non-zero; this
+ * stops there and says what is left to do.
+ *
+ * WHAT IT DOES NOT DO: publish. Sync brings the local copy and the backend DRAFT
+ * into agreement; going live stays a separate, deliberate act (`uniweb publish`).
+ * That separation is what keeps an unintended sync recoverable — the worst case is
+ * work-in-progress visible to authors in the app, not shipped to visitors.
+ *
+ * Reach for `refresh` when you only want to catch up — it cannot ship anything, so
+ * it is the one to run reflexively. Reach for `sync` when you also mean to share.
+ *
+ * Usage:
+ *   uniweb sync                    refresh, then push
+ *   uniweb sync --no-git           skip the git remote half of the refresh
+ *   uniweb sync --force            forwarded to push (overwrite upstream changes)
+ *   uniweb sync --backend <url>    override the backend origin
+ */
+
+const c = { reset: '\x1b[0m', dim: '\x1b[2m', cyan: '\x1b[36m', red: '\x1b[31m' }
+const say = {
+  info: (m) => console.log(`${c.cyan}→${c.reset} ${m}`),
+  err: (m) => console.error(`${c.red}✗${c.reset} ${m}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`),
+}
+
+/**
+ * @param {string[]} args
+ * @param {object} [deps] - injectable seams for testing: `refresh`, `push`.
+ */
+export async function sync(args = [], deps = {}) {
+  const refresh = deps.refresh || (await import('./refresh.js')).refresh
+  const push = deps.push || (await import('./push.js')).push
+
+  // `--force` means "overwrite upstream" and belongs to the push half only. Passing
+  // it to the refresh would ask pull to DISCARD the local work this command exists
+  // to send — the same word meaning opposite things on the two halves.
+  const refreshArgs = args.filter((a) => a !== '--force')
+
+  const r = await refresh(refreshArgs)
+  if (r?.exitCode) {
+    // refresh already explained itself — conflicts, or a git failure. Adding a
+    // second summary here would just bury it.
+    say.dim('Not pushing while that is unresolved.')
+    return { exitCode: r.exitCode }
+  }
+
+  console.log('')
+  say.info('Pushing your changes…')
+  const p = await push(args)
+  return { exitCode: p?.exitCode ?? 0 }
+}
+
+export default sync

package/src/framework-index.json

@@ -1,31 +1,32 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-25T17:53:51.666Z",
+  "generatedAt": "2026-07-26T22:08:46.287Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.15.4",
+      "version": "0.15.6",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
         "@uniweb/content-writer",
         "@uniweb/core",
+        "@uniweb/projections",
         "@uniweb/runtime",
         "@uniweb/schemas",
         "@uniweb/theming"
       ]
     },
     "@uniweb/content-reader": {
-      "version": "1.1.15",
+      "version": "1.1.16",
       "path": "framework/content-reader",
       "deps": []
     },
     "@uniweb/content-writer": {
-      "version": "0.2.7",
+      "version": "0.2.8",
       "path": "framework/content-writer",
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.7.28",
+      "version": "0.7.30",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -43,7 +44,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.9.36",
+      "version": "0.9.38",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -60,8 +61,16 @@
       "path": "framework/press",
       "deps": []
     },
+    "@uniweb/projections": {
+      "version": "0.1.1",
+      "path": "framework/projections",
+      "deps": [
+        "@uniweb/content-writer",
+        "@uniweb/core"
+      ]
+    },
     "@uniweb/runtime": {
-      "version": "0.8.35",
+      "version": "0.8.37",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -84,7 +93,7 @@
       "deps": []
     },
     "@uniweb/semantic-parser": {
-      "version": "1.1.18",
+      "version": "1.1.19",
       "path": "framework/semantic-parser",
       "deps": []
     },
@@ -94,12 +103,12 @@
       "deps": []
     },
     "@uniweb/theming": {
-      "version": "0.1.13",
+      "version": "0.1.14",
       "path": "framework/theming",
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.5.3",
+      "version": "0.5.5",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -622,6 +622,20 @@ async function main() {
     process.exit(result?.exitCode ?? 0)
   }
 
+  // Handle sync command (refresh + push; both halves imported, never reimplemented)
+  if (command === 'sync') {
+    const { sync } = await importProjectCommand('./commands/sync.js')
+    const result = await sync(args.slice(1))
+    process.exit(result?.exitCode ?? 0)
+  }
+
+  // Handle refresh command (dynamic import — depends on @uniweb/build via pull)
+  if (command === 'refresh') {
+    const { refresh } = await importProjectCommand('./commands/refresh.js')
+    const result = await refresh(args.slice(1))
+    process.exit(result?.exitCode ?? 0)
+  }
+
   // Handle status command (dynamic import — offline emit via @uniweb/build)
   if (command === 'status') {
     const { status } = await importProjectCommand('./commands/status.js')
@@ -1490,6 +1504,8 @@ ${colors.bright}Commands:${colors.reset}
   runtime register   Register an @uniweb/runtime version to the backend (@std only)
   push               Push a site's content to the backend
   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)
   inspect <path>     Inspect parsed content shape of a markdown file or folder
   docs               Generate component documentation

package/src/utils/git.js

@@ -0,0 +1,203 @@
+/**
+ * Git awareness for the sync verbs.
+ *
+ * The CLI's file-based workflow is for people who keep their content in git, so
+ * git is the right place to look before doing something destructive to the working
+ * tree — rather than building a merge engine to solve a problem the user's VCS
+ * already solves better.
+ *
+ * DETECTED, NEVER REQUIRED. A project may legitimately have no repo, and — more
+ * commonly — may live *inside* a larger one: `uniweb create` already skips
+ * `git init` when it finds itself inside a work tree ("common for
+ * 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.
+ */
+
+import { execFileSync } from 'node:child_process'
+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.
+ */
+export function siteContentRoots(siteDir) {
+  const roots = new Set(['site.yml', 'theme.yml', 'head.html', 'collections.yml', 'locales'])
+  let paths = {}
+  try {
+    paths = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))?.paths || {}
+  } catch { /* no or unreadable site.yml — the defaults are right */ }
+  roots.add(paths.pages || 'pages')
+  roots.add(paths.layout || 'layout')
+  roots.add(paths.collections || 'collections')
+  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, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+}
+
+/**
+ * Is `dir` inside a git work tree? False when git is absent, when the path isn't
+ * tracked, or on any error — the caller treats all three the same way.
+ */
+export function isGitRepo(dir) {
+  try {
+    return git(['rev-parse', '--is-inside-work-tree'], dir).trim() === 'true'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 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.
+ *
+ * @returns {string[]|null} repo-relative-ish paths as git reports them, 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
+  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))
+      .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 committed content — the COMMON ANCESTOR for a three-way merge.
+ *
+ * This is the input a merge needs and the backend cannot supply: it 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. `uniweb pull` writes the backend's content into these files, so the
+ * committed version IS the state both sides diverged from — the ancestor was always
+ * on this side, in the tool that already knows how to merge.
+ *
+ * @returns {Buffer|null} null when the path isn't in HEAD (a file added locally and
+ *   never committed has no ancestor, so there is nothing to merge against).
+ */
+export function showAtHead(dir, relPath) {
+  try {
+    return execFileSync('git', ['show', `HEAD:${relPath}`], {
+      cwd: dir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024,
+    })
+  } catch {
+    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 {
+    return git(['remote'], dir).trim().length > 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * `git pull --ff-only` — bring in teammates' commits.
+ *
+ * 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.
+ *
+ * @returns {{ ok: boolean, changed: boolean, message: string }}
+ */
+export function pullRemote(dir) {
+  const before = (() => { try { return git(['rev-parse', 'HEAD'], dir).trim() } catch { return null } })()
+  try {
+    const out = execFileSync('git', ['pull', '--ff-only'], {
+      cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    const after = (() => { try { return git(['rev-parse', 'HEAD'], dir).trim() } catch { return null } })()
+    return { ok: true, changed: Boolean(before && after && before !== after), message: out.trim() }
+  } catch (err) {
+    const msg = [err?.stderr, err?.stdout].map((b) => (b ? String(b) : '')).join('\n').trim()
+    return { ok: false, changed: false, message: msg || 'git pull failed' }
+  }
+}
+
+/**
+ * Provenance for a deploy record: `{ sha, dirty }`, or null outside a repo.
+ * Answers "what is actually live?" later, which a version number cannot.
+ */
+export function headProvenance(dir) {
+  if (!isGitRepo(dir)) return null
+  try {
+    const sha = git(['rev-parse', 'HEAD'], dir).trim()
+    const dirty = git(['status', '--porcelain'], dir).trim().length > 0
+    return { sha, dirty }
+  } catch {
+    return null // a repo with no commits yet
+  }
+}