uniweb 0.16.4 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.16.4",
+  "version": "0.17.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "^0.8.4",
-    "@uniweb/kit": "^0.11.2",
-    "@uniweb/runtime": "^0.11.4"
+    "@uniweb/kit": "^0.11.3",
+    "@uniweb/core": "^0.8.5",
+    "@uniweb/runtime": "^0.11.6"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.18.4",
-    "@uniweb/content-reader": "^1.2.2",
-    "@uniweb/semantic-parser": "^1.2.1"
+    "@uniweb/build": "^0.18.5",
+    "@uniweb/semantic-parser": "^1.2.2",
+    "@uniweb/content-reader": "^1.2.2"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/src/backend/site-sync.js

@@ -18,6 +18,7 @@ import { hasUncommittedContent } from '../utils/git.js'
 import {
   backfillEntityUuids,
   writeSiteEntityUuid,
+  writeSiteOrg,
   emitSyncPackages,
   readZip,
   diffSiteUnits,
@@ -390,6 +391,217 @@ export function writeItemUuids(siteDir, map) {
   updateSyncCache(siteDir, { itemUuids: map })
 }
 
+/**
+ * The org this site was created under, as `@handle`, or null.
+ *
+ * Read back from `site.yml::$org` (stored bare — see `writeSiteOrg`) and re-dressed
+ * with the `@` the CLI and the wire both use. Callers pass it as `--as-org`'s default
+ * so an org named once, at create, does not have to be re-typed on every later push.
+ *
+ * Deliberately NOT a fallback for the flag: an explicit `--as-org` always wins and
+ * rides verbatim, so this can only add a value where the CLI previously sent none.
+ *
+ * @param {string} siteDir
+ * @returns {string|null}
+ */
+export function readSiteOrg(siteDir) {
+  try {
+    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
+    const h = y && typeof y === 'object' ? y.$org : null
+    return typeof h === 'string' && h.trim()
+      ? `@${h.trim().replace(/^@/, '')}`
+      : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Record the org a just-minted site was created under, if one was named.
+ *
+ * Only what we were TOLD is recorded — when no `--as-org` was passed the backend
+ * chose the owner and its create response carries no org, so there is nothing to
+ * write and guessing one would be worse than the gap. Returns the display form for
+ * the caller's "here's what resolved" line, or null when nothing was recorded.
+ *
+ * @param {string} siteDir
+ * @param {string|null|undefined} asOrg - the `--as-org` value, `@handle` or bare
+ * @returns {string|null}
+ */
+function recordSiteOrg(siteDir, asOrg) {
+  const handle = String(asOrg || '')
+    .replace(/^@/, '')
+    .replace(/\/.*$/, '')
+    .trim()
+  if (!handle) return null
+  try {
+    writeSiteOrg(siteDir, handle)
+    return `@${handle}`
+  } catch {
+    // The uuid is the load-bearing back-fill; losing the org note must never
+    // fail a push that already succeeded on the backend.
+    return null
+  }
+}
+
+/**
+ * Resolve WHICH ORG will own a site that is about to be created.
+ *
+ * The create that mints `$uuid` is the only call that reads `as_org`, and the
+ * backend never moves ownership afterwards. There is also no CLI verb to transfer
+ * or delete a site. So this is a **one-shot, unrepealable** decision — and until
+ * this function existed the CLI made it silently, by sending nothing and letting
+ * the backend fall back to the session's personal context. A developer who belongs
+ * to several orgs could put a company site, and the storage it bills, somewhere
+ * they never named.
+ *
+ * `register` has refused to guess a scope for the foundation lane since it shipped
+ * (`deriveScope` → `package.json::uniweb.scope`). This is the same refusal, one
+ * lane over.
+ *
+ * Order, and only the last step is new:
+ *   1. `--as-org @org`      — explicit, rides verbatim
+ *   2. `--personal`         — explicit "no org, I mean it" → sends NO `as_org`
+ *   3. `site.yml::$org`     — recorded at this site's own create
+ *   4. the site already exists (`$uuid`) → null; ownership is settled, ask nothing
+ *   5. otherwise ASK (TTY) or REFUSE (non-interactive)
+ *
+ * ⛔ **`--personal` sends no `as_org`, and is NOT the same as `--as-org @<handle>`.**
+ * The personal *org* `@jane` is an org like any other, lazily created on first use;
+ * the session's personal context is not an org at all. Whether the backend gives
+ * them the same owning unit is **its** business and unverified here, so the
+ * deliberate-personal spelling reproduces today's wire byte-for-byte rather than
+ * asserting an equivalence this lane cannot check.
+ *
+ * @returns {Promise<{ asOrg: string|null, refused?: true, reason?: string }>}
+ *   `asOrg: null` with no `refused` means "send no as_org" — either a settled site
+ *   or a deliberate personal choice.
+ */
+export async function resolveSiteOrgForCreate({
+  client,
+  siteDir,
+  args = [],
+  flag,
+  personal = false,
+  offline = false
+}) {
+  if (flag) return { asOrg: flag }
+  if (personal) return { asOrg: null }
+
+  const recorded = readSiteOrg(siteDir)
+  if (recorded) return { asOrg: recorded }
+
+  // Already created ⇒ nothing to decide. This is what keeps every existing site
+  // silent: ownership was settled at its create, and re-asking would be theatre.
+  let siteYml = {}
+  try {
+    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
+    if (y && typeof y === 'object') siteYml = y
+  } catch {
+    /* unreadable — treat as un-created and let the resolution below decide */
+  }
+  if (typeof siteYml.$uuid === 'string') return { asOrg: null }
+
+  // An offline preview (`--dry-run` / `-o`) must never authenticate, and it is
+  // creating nothing, so there is no decision to force. Say what is unresolved
+  // instead of prompting for an answer the run will not use.
+  if (offline) return { asOrg: null }
+
+  // `--yes` promises "never block on a prompt", so it has to answer this one too —
+  // and the only honest non-blocking answer to an unanswerable ownership question
+  // is a refusal. Treating it as consent-to-anything would reinstate the silent
+  // default this whole path exists to remove, behind a flag that reads like
+  // approval.
+  const { isNonInteractive } = await import('../utils/interactive.js')
+  if (isNonInteractive(args) || args.includes('--yes')) {
+    return {
+      asOrg: null,
+      refused: true,
+      reason:
+        'This site does not exist on the backend yet, and no org was named.\n' +
+        '  The create decides who OWNS it — and which workspace its storage is billed to —\n' +
+        '  one time, with no CLI way to change it afterwards. Name it explicitly:\n' +
+        '    --as-org @org     create it under an organization\n' +
+        '    --personal        create it under your personal account, deliberately'
+    }
+  }
+
+  // Interactive: offer the real choice. Deliberately NOT `deriveScope` — that one
+  // serves the foundation lane, where every answer is an org and 0-orgs means
+  // "claim your personal org". Here "personal" must stay reachable as *no org*,
+  // and reusing deriveScope would quietly turn it into an org creation.
+  const { fetchOrgs, createOrg, validateHandle, bareHandle } = await import(
+    '../utils/registry-orgs.js'
+  )
+  let envelope
+  try {
+    envelope = await fetchOrgs({
+      apiBase: client.origin,
+      token: await client.token()
+    })
+  } catch (err) {
+    return { asOrg: null, refused: true, reason: err.message }
+  }
+  const personalHandle = envelope.account_handle || null
+  const prompts = (await import('prompts')).default
+  const choices = [
+    ...envelope.orgs.map((o) => ({
+      title: `@${o.handle}${o.handle === personalHandle ? ' — your personal org' : o.is_primary ? ' (primary)' : ''}`,
+      value: o.handle
+    })),
+    {
+      title: `Personal — no organization${personalHandle ? ` (${personalHandle})` : ''}`,
+      value: ':personal'
+    },
+    { title: 'A new organization…', value: ':new' }
+  ]
+  const { choice } = await prompts(
+    {
+      type: 'select',
+      name: 'choice',
+      message: 'Create this site under which owner?',
+      choices,
+      initial: 0
+    },
+    {
+      onCancel: () => {
+        console.log('\nCancelled.')
+        process.exit(0)
+      }
+    }
+  )
+  if (!choice) return { asOrg: null, refused: true, reason: 'No owner chosen.' }
+  if (choice === ':personal') return { asOrg: null }
+  if (choice !== ':new') return { asOrg: `@${choice}` }
+
+  const answer = await prompts(
+    {
+      type: 'text',
+      name: 'handle',
+      message: 'Org handle (e.g. acme):',
+      validate: (v) => validateHandle(v) || true
+    },
+    {
+      onCancel: () => {
+        console.log('\nCancelled.')
+        process.exit(0)
+      }
+    }
+  )
+  if (!answer.handle)
+    return { asOrg: null, refused: true, reason: 'No org handle given.' }
+  try {
+    const org = await createOrg({
+      apiBase: client.origin,
+      token: await client.token(),
+      handle: bareHandle(answer.handle)
+    })
+    return { asOrg: `@${org.handle}` }
+  } catch (err) {
+    return { asOrg: null, refused: true, reason: err.message }
+  }
+}
+
 /**
  * Guarantee the site EXISTS on the backend before anything is uploaded against it.
  *
@@ -429,7 +641,7 @@ export async function ensureSiteExists({
     /* unreadable site.yml — treat as un-synced and let the create decide */
   }
   if (typeof siteYml.$uuid === 'string') {
-    return { uuid: siteYml.$uuid, created: false }
+    return { uuid: siteYml.$uuid, created: false, org: readSiteOrg(siteDir) }
   }
 
   // Both are required by the create. Catching it here turns a 400 into a sentence
@@ -471,7 +683,8 @@ export async function ensureSiteExists({
           : `HTTP ${res?.status} ${res?.statusText || ''}${body ? ` — ${body.slice(0, 200)}` : ''}`
     }
   }
-  const minted = extractMintedSiteUuid(await res.json().catch(() => null))
+  const payload = await res.json().catch(() => null)
+  const minted = extractMintedSiteUuid(payload)
   if (!minted) {
     return {
       uuid: null,
@@ -484,8 +697,65 @@ export async function ensureSiteExists({
   // this point cannot leave a cache pointing at a different site with no way to
   // detect it.
   updateSyncCache(siteDir, { siteUuid: minted })
-  note?.(`Created the site on the backend (recorded $uuid in site.yml).`)
-  return { uuid: minted, created: true }
+  const org = await recordAndDescribeOwner({
+    client,
+    siteDir,
+    payload,
+    asOrg,
+    note
+  })
+  return { uuid: minted, created: true, org }
+}
+
+/**
+ * Record and announce who owns a just-created site, from the backend's own echo.
+ *
+ * The echo reports what the site **is**; `asOrg` is only what we asked for. They
+ * agree in the normal case and the echo is the one to trust — it is read back off
+ * the created entity, so it also covers the case we could never record before: no
+ * `--as-org` at all, where the backend picked and we had nothing true to write.
+ *
+ * ⚠️ `org: null` is MEANINGFUL (personal), not missing. An older backend omits the
+ * key entirely, which is the only case that falls back to what we asked for.
+ *
+ * @returns {Promise<string|null>} the display handle recorded, or null for personal
+ */
+async function recordAndDescribeOwner({ client, siteDir, payload, asOrg, note }) {
+  const echoed = payload && 'org' in payload ? payload.org : undefined
+  const owner =
+    echoed === undefined ? asOrg : typeof echoed === 'string' ? echoed : null
+  const org = recordSiteOrg(siteDir, owner)
+
+  note?.(
+    org
+      ? `Created the site on the backend under ${org} (recorded $uuid + $org in site.yml).`
+      : `Created the site on the backend, owned personally (recorded $uuid in site.yml).`
+  )
+
+  // The billing line needs the JOIN of two independent facts, and either alone
+  // gives a wrong answer:
+  //   hosts_free               — a property of the SCOPE (is this owner exempt?)
+  //   siteSubscriptionRequired — a property of the DEPLOYMENT (does it charge at all?)
+  // Keyed on the scope alone, this fires on every local publish — where nothing
+  // enforces — until the warning is trained away. Keyed on the deployment alone it
+  // fires at exempt owners. An older backend supplies neither, so both read falsy
+  // and nothing is said: silence beats a claim we cannot justify.
+  const hostsFree = payload?.hosts_free === true
+  let enforces = false
+  try {
+    const cfg = await client.discover()
+    enforces = cfg?.delivery?.siteSubscriptionRequired === true
+  } catch {
+    /* discovery is advisory here — never fail a create over a message */
+  }
+  if (hostsFree) {
+    note?.('This owner is hosted free — publishing will not require a subscription.')
+  } else if (enforces) {
+    note?.(
+      'Publishing this site live will require a hosting subscription on this backend.'
+    )
+  }
+  return org
 }
 
 /**
@@ -838,6 +1108,20 @@ export async function pushSyncPackages({
       updateSyncCache(siteDir, { siteUuid: minted })
       boundSiteUuid = minted
       wrote.push('recorded site $uuid in site.yml')
+      // The OTHER create path (a media-less push never reaches `ensureSiteExists`,
+      // which is gated on the site having local media). Both mint a site, so both
+      // owe the same record — recording it in only one place would make `$org`
+      // present or absent depending on whether the site happens to have images.
+      // The backend echoes `org`/`hosts_free` top-level here too, beside `report`
+      // and `site` (NOT beside `finalized`, which lives at report.finalized).
+      const createdOrg = await recordAndDescribeOwner({
+        client,
+        siteDir,
+        payload,
+        asOrg,
+        note
+      })
+      if (createdOrg) wrote.push(`recorded site $org (${createdOrg}) in site.yml`)
       const createdFinalized = extractFinalized(payload)
       harvest(createdFinalized)
       siteFinalizedDoc = createdFinalized?.[0]?.document || null

package/src/commands/clone.js

@@ -56,6 +56,9 @@ import { detectWorkspacePm, installCmd } from '../utils/pm.js'
 import { BackendClient } from '../backend/client.js'
 import { isNonInteractive, getCliPrefix } from '../utils/interactive.js'
 import { extractFoundationRef } from '../utils/site-content-refs.js'
+import { readUwxDocuments } from '../utils/uwx-read.js'
+import { recordWritten } from '../utils/pull-written.js'
+import { checkFlags } from '../utils/flag-guard.js'
 
 const colors = {
   reset: '\x1b[0m',
@@ -158,6 +161,13 @@ function pullExecArgv(pm, extra) {
  *   runPull(siteDir, pm, extraArgs).
  */
 export async function clone(args = [], deps = {}) {
+  // See utils/flag-guard.js — an unrecognized flag is invisible to a
+  // literal scan, so it silently keeps the default (production, for --backend).
+  const badFlag = checkFlags('clone', args)
+  if (badFlag) {
+    error(badFlag.message)
+    return { exitCode: 2 }
+  }
   const positionals = args.filter((a) => !a.startsWith('-'))
   const siteUuid = positionals[0]
   const target = positionals[1] || null // [name|.]
@@ -189,11 +199,19 @@ export async function clone(args = [], deps = {}) {
     command: 'Cloning'
   })
 
-  // 1. GET the site-content document (no @uniweb/build needed for a read).
+  // 1. GET the site-content document.
+  //
+  // ⛔ The body is a `.uwx` ZIP, not JSON — `application/vnd.uniweb.exchange.
+  // entity+zip`, on `content` and `folder` pulls alike. This used to call
+  // `res.json()`, which failed on the ZIP magic and reported *"Could not reach
+  // the backend: Unexpected token 'P'"* — blaming the network for a body we had
+  // received intact and mis-read. Decode with the local reader: this command runs
+  // before a project exists, so `@uniweb/build/uwx`'s `readZip` is out of reach
+  // (see `utils/uwx-read.js`).
   info(
     `Reading site ${colors.bright}${siteUuid}${colors.reset} from ${colors.dim}${client.origin}${colors.reset} …`
   )
-  let payload
+  let documents
   try {
     const res = await client.pullSiteContent(siteUuid)
     if (res.status === 404) {
@@ -206,13 +224,14 @@ export async function clone(args = [], deps = {}) {
         note('Run `uniweb login` first (or pass --token <bearer>).')
       return { exitCode: 1 }
     }
-    payload = await res.json()
+    documents = readUwxDocuments(Buffer.from(await res.arrayBuffer()))
   } catch (err) {
     error(`Could not reach the backend at ${client.origin}: ${err.message}`)
     return { exitCode: 1 }
   }
 
-  const document = extractDocument(payload)
+  const document =
+    documents.map(extractDocument).find(Boolean) || null
   if (!document) {
     error('The site-content response carried no recognizable document.')
     return { exitCode: 1 }
@@ -338,6 +357,31 @@ export async function clone(args = [], deps = {}) {
     }
   }
 
+  // Tell the delegated pull which files WE wrote, or it refuses on them.
+  //
+  // Pull guards against overwriting uncommitted work under the paths it rewrites,
+  // and `site.yml` / `theme.yml` are exactly those paths — uncommitted here
+  // because clone scaffolded them seconds ago. Without this, clone reliably ends
+  // in "Refusing to pull: 2 uncommitted change(s)" on a project it just created,
+  // where there is no user work to protect. The advice it prints (`--force`) is
+  // both unreachable — clone does not forward that flag — and wrong, since it
+  // means "discard my changes" and the changes are ours.
+  //
+  // ⭐ This exempts them for the RIGHT reason rather than overriding the guard.
+  // `recordWritten` stores a content hash, so a file the user edits between
+  // scaffold and pull no longer matches and the refusal correctly stands. The
+  // guard keeps its teeth; it just stops firing on machine output, which is what
+  // it already does for pull's own writes.
+  //
+  // Recorded AFTER the uuid seeding above — the hash has to be of the final
+  // bytes on disk, not of what the scaffolder first wrote.
+  recordWritten(
+    siteDir,
+    ['site.yml', 'theme.yml', 'head.html', 'collections.yml']
+      .map((f) => join(siteDir, f))
+      .filter((p) => existsSync(p))
+  )
+
   const pullExtra = []
   if (explicitBackend) pullExtra.push('--backend', explicitBackend)
   if (tokenFlag) pullExtra.push('--token', tokenFlag)

package/src/commands/publish.js

@@ -28,6 +28,15 @@
  *   uniweb publish --dry-run       Resolve everything; POST nothing
  *   uniweb publish --yes           Skip confirmations (CI); never block on a prompt
  *   uniweb publish --force         Overwrite upstream app-side edits (drop the push gate)
+ *   uniweb publish --org @org      Publish under @org (alias: --as-org). Only the
+ *                                  FIRST publish of a site reads it — that create is
+ *                                  what decides which org owns the site and whose
+ *                                  storage its assets are charged to. It is then
+ *                                  recorded as `site.yml::$org` and replayed, so it
+ *                                  never has to be re-typed.
+ *   uniweb publish --personal      Own the new site personally, deliberately. Sends
+ *                                  NO `as_org` — byte-identical to the wire before
+ *                                  the owner prompt existed. First publish only.
  *   uniweb publish --no-save       Skip the deploy.yml lastDeploy auto-save
  *   uniweb publish --backend <url> Override the backend origin
  *   uniweb publish --token <bearer> Auth bearer (skips `uniweb login`)
@@ -55,7 +64,8 @@ import { resolveDefaultLocale } from '@uniweb/core/locale-config'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
 import { warnIfContentDoesNotConform } from '../utils/conformance.js'
-import { readFlagValue } from '../utils/args.js'
+import { readFlagValue, readOrgFlag } from '../utils/args.js'
+import { checkFlags } from '../utils/flag-guard.js'
 import { isNonInteractive } from '../utils/interactive.js'
 import { headProvenance } from '../utils/git.js'
 import {
@@ -66,7 +76,8 @@ import {
   ensureItemUuids,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
-  pushSyncPackages
+  pushSyncPackages,
+  resolveSiteOrgForCreate
 } from '../backend/site-sync.js'
 import { uploadDataBundle } from '../backend/data-bundle.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
@@ -165,9 +176,15 @@ async function persistLastDeploy(siteDir, opts) {
 }
 
 export async function publish(args = []) {
+  // See utils/flag-guard.js — an unrecognized flag is invisible to a literal
+  // scan, and for --backend the silent default can be production.
+  const bad = checkFlags('publish', args)
+  if (bad) {
+    say.err(bad.message)
+    return { exitCode: 2 }
+  }
   const dryRun = args.includes('--dry-run')
   const noSave = args.includes('--no-save')
-  const asOrg = readFlagValue(args, '--as-org')
   const foundationDir = readFlagValue(args, '--foundation') // optional local foundation for Model schemas
 
   const siteDir = await resolveSiteDir(args, 'publish')
@@ -189,6 +206,25 @@ export async function publish(args = []) {
     command: 'Publishing'
   })
 
+  // WHO will own this site, if this publish is the one that creates it. Resolved
+  // up front: `ensureSiteExists` below is the create, and it must not be reached
+  // with the question still open. An already-created site resolves to null without
+  // asking — its ownership was settled once and cannot be changed from here.
+  const org = await resolveSiteOrgForCreate({
+    client,
+    siteDir,
+    args,
+    flag: readOrgFlag(args),
+    personal: args.includes('--personal'),
+    offline: dryRun
+  })
+  if (org.refused) {
+    say.err('Refusing to create this site without naming an owner.')
+    say.dim(org.reason)
+    return { exitCode: 2 }
+  }
+  const asOrg = org.asOrg
+
   // Capability handshake (cached). Publish ends in a go-live, so the publish
   // lane must be offered.
   const config = await client.discover()

package/src/commands/pull.js

@@ -77,6 +77,11 @@ import {
   collectUnitUuids
 } from '@uniweb/build/uwx'
 import { makeModelResolver } from './push.js'
+import {
+  readWritten,
+  recordWritten,
+  isPullOutput
+} from '../utils/pull-written.js'
 import {
   mergeBaseVersions,
   mergeItemBaseVersions,
@@ -95,6 +100,7 @@ import {
   resolveSiteDir as defaultResolveSiteDir,
   resolveSiteBackend
 } from './deploy.js'
+import { checkFlags } from '../utils/flag-guard.js'
 
 const FOLDER_MODEL = '@uniweb/folder'
 
@@ -355,79 +361,10 @@ async function checkWorkingTree(siteDir, args) {
   return { exitCode: 1 }
 }
 
-// What the last pull wrote: `{ <repo-relative path>: <sha256 of the bytes it wrote> }`.
-//
-// Without this the guard cries wolf: pull rewrites the tree, so the very 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 — the same failure mode as a gate that refuses disjoint
-// edits. A file still byte-identical to what pull last wrote is not user work.
-function writtenCachePath(siteDir) {
-  return join(siteDir, '.uniweb', 'pull-written.json')
-}
-function readWritten(siteDir) {
-  try {
-    const o = JSON.parse(readFileSync(writtenCachePath(siteDir), 'utf8'))
-    return {
-      files: o && typeof o.files === 'object' ? o.files : {},
-      deleted: Array.isArray(o?.deleted) ? o.deleted : []
-    }
-  } catch {
-    return { files: {}, deleted: [] }
-  }
-}
-function recordWritten(siteDir, absPaths, deletedAbs = []) {
-  // MERGE, don't replace. A conditional pull that 304s writes nothing, and a
-  // partial pull writes only some lanes — in both cases the previous record is
-  // still "the last thing pull wrote there". Replacing would forget those paths and
-  // the next pull would see them as the user's work again, which is the false alarm
-  // this cache exists to prevent. A stale entry for a file that no longer exists is
-  // harmless: the hash read fails and it counts as a local change.
-  const prior = readWritten(siteDir)
-  const files = prior.files
-  for (const abs of absPaths) {
-    try {
-      files[relative(siteDir, abs)] = createHash('sha256')
-        .update(readFileSync(abs))
-        .digest('hex')
-    } catch {
-      /* deleted or unreadable — nothing to remember */
-    }
-  }
-  // Pull PRUNES too, and a deletion is a dirty path git reports just like an edit.
-  // Without recording them, pull's own pruning reads as the user having deleted
-  // files — the same false alarm as its writes, arriving by the other door.
-  const deleted = [
-    ...new Set([
-      ...prior.deleted,
-      ...deletedAbs.map((a) => relative(siteDir, a))
-    ])
-  ]
-  try {
-    mkdirSync(dirname(writtenCachePath(siteDir)), { recursive: true })
-    writeFileSync(
-      writtenCachePath(siteDir),
-      JSON.stringify({ version: 1, files, deleted }, null, 2) + '\n'
-    )
-  } catch {
-    /* best-effort: losing it only costs a spurious refusal */
-  }
-}
-// Is this dirty path just pull's own untouched output?
-function isPullOutput(siteDir, relPath, written) {
-  let exists = true
-  let hash = null
-  try {
-    hash = createHash('sha256')
-      .update(readFileSync(join(siteDir, relPath)))
-      .digest('hex')
-  } catch {
-    exists = false
-  }
-  // Absent because pull pruned it — not because the user deleted it.
-  if (!exists) return written.deleted.includes(relPath)
-  return written.files[relPath] === hash
-}
+// The written-record helpers live in `utils/pull-written.js` so `clone` can share
+// them: clone scaffolds site.yml/theme.yml and then delegates here, and this
+// module cannot be imported from there — it statically imports `@uniweb/build`,
+// which resolves from a project that does not exist yet when clone runs.
 
 /**
  * `--merge`: keep local work instead of refusing, by three-way merging it with what
@@ -539,6 +476,13 @@ async function confirm(question) {
 }
 
 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 (production, for --backend).
+  const badFlag = checkFlags('pull', args)
+  if (badFlag) {
+    error(badFlag.message)
+    return { exitCode: 2 }
+  }
   const resolveSiteDir = deps.resolveSiteDir || defaultResolveSiteDir
 
   const dryRun = args.includes('--dry-run')