uniweb 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {

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,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-16T05:48:07.516Z",
+  "generatedAt": "2026-08-16T13:24:21.340Z",
   "packages": {
     "@uniweb/build": {
       "version": "0.24.0",
@@ -111,7 +111,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.9",
+      "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.