uniweb 0.12.21 → 0.12.23

package/src/commands/content.js

@@ -0,0 +1,199 @@
+/**
+ * Content Command — `uniweb content export`
+ *
+ * Packages a site project (or a built foundation's schema) as a `.uwx`
+ * entity package — the Uniweb exchange format — for import into Uniweb.
+ * No JS/HTML: pure content / declarative data.
+ *
+ *   uniweb content export                 Package the site in the cwd
+ *   uniweb content export <dir>           Package a specific site/foundation
+ *   uniweb content export -o team.uwx     Choose the output filename
+ *   uniweb content export --no-sidecar    Mint fresh ids (submit-once;
+ *                                         default is the syncable round trip,
+ *                                         persisting ids in .uniweb/uwx-ids.json)
+ *   uniweb content export --dry-run       Print a summary; write nothing
+ *   uniweb content export --source-locale fr   Wrap single-language fields under
+ *                                              this locale (default: en)
+ *
+ * A site dir is detected by `site.yml`; a foundation by a built
+ * `dist/meta/schema.json` (run `uniweb build` first for a foundation).
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, basename, resolve } from 'node:path'
+
+const c = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+}
+const say = {
+  ok: (m) => console.log(`${c.green}✓${c.reset} ${m}`),
+  info: (m) => console.log(`${c.cyan}→${c.reset} ${m}`),
+  err: (m) => console.error(`${c.red}✗${c.reset} ${m}`),
+  warn: (m) => console.log(`${c.yellow}!${c.reset} ${m}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`),
+}
+
+function usage() {
+  console.log(`
+${c.cyan}uniweb content export${c.reset} [dir] [options]
+
+  Package a site project (or built foundation schema) as a .uwx entity
+  package for import into Uniweb.
+
+  ${c.dim}-o, --output <file>${c.reset}      Output path (default: <name>.uwx)
+  ${c.dim}--no-sidecar${c.reset}             Mint fresh ids (submit-once) instead of
+                           the syncable round trip
+  ${c.dim}--dry-run${c.reset}                Print a summary; write nothing
+  ${c.dim}--source-locale <code>${c.reset}   Locale for single-language fields (default: en)
+`)
+}
+
+export async function content(args = []) {
+  const sub = args[0]
+  if (!sub || sub === '--help' || sub === '-h') {
+    usage()
+    return
+  }
+  if (sub === 'export') {
+    await contentExport(args.slice(1))
+    return
+  }
+  say.err(`Unknown subcommand: content ${sub}`)
+  usage()
+  process.exit(1)
+}
+
+async function contentExport(args) {
+  const { readFlagValue } = await import('../utils/args.js')
+  const dryRun = args.includes('--dry-run')
+  const noSidecar = args.includes('--no-sidecar')
+  const sourceLocale = readFlagValue(args, '--source-locale') || undefined
+  let output = readFlagValue(args, '-o')
+  if (!output || output === true) output = readFlagValue(args, '--output')
+  const dir = resolve(
+    args.find((a) => !a.startsWith('-') && a !== output) || process.cwd()
+  )
+
+  const isSite = existsSync(join(dir, 'site.yml'))
+  const schemaPath = join(dir, 'dist', 'meta', 'schema.json')
+  const isFoundation = !isSite && existsSync(schemaPath)
+
+  if (!isSite && !isFoundation) {
+    say.err(`No site.yml or built dist/meta/schema.json found in ${dir}`)
+    say.dim('Point at a site directory, or `uniweb build` a foundation first.')
+    process.exit(1)
+  }
+
+  const uwx = await import('@uniweb/build/uwx')
+  // --dry-run must have zero side effects: mint ids (no sidecar file).
+  const useSidecar = !dryRun && !noSidecar
+
+  let buf
+  let defaultName
+  try {
+    if (isSite) {
+      say.info(`Packaging site → @uniweb/site-content (.uwx)…`)
+      // Nested $-document on the sync lane. The sidecar is read-only here: it
+      // supplies $uuids a prior sync recorded (the backend mints, never this
+      // export), so a fresh project exports a uuid-less document.
+      buf = await uwx.emitSiteSyncPackage(dir, {
+        sidecar: useSidecar, // read <dir>/.uniweb/uwx-ids.json if present
+        sourceLocale,
+      })
+      defaultName = basename(dir)
+    } else {
+      const schema = JSON.parse(readFileSync(schemaPath, 'utf8'))
+      say.info(`Packaging foundation schema → @uniweb/foundation-schema (.uwx)…`)
+      buf = uwx.emitFoundationSchemaPackage(schema, {
+        sidecar: useSidecar ? join(dir, uwx.SIDECAR_RELPATH) : undefined,
+        foundationDir: dir,
+        sourceLocale,
+      })
+      defaultName = (schema?._self?.name || basename(dir)).replace(
+        /[^a-z0-9._-]+/gi,
+        '-'
+      )
+    }
+  } catch (err) {
+    say.err(err.message)
+    process.exit(1)
+  }
+
+  // Structural summary (not an import simulation). The entity file is located
+  // via the manifest index, which works for both lanes: the register lane
+  // (foundation schema, flat `items[]`) and the sync lane (site, nested
+  // `$`-document).
+  const files = uwx.readZip(buf)
+  const manifest = JSON.parse(files.get('manifest.json').toString('utf8'))
+  const entityFile = manifest.entries?.[0]?.file
+  const entity = JSON.parse(files.get(entityFile).toString('utf8'))
+  const counts = {}
+  if (Array.isArray(entity.items)) {
+    // Flat register lane: one item per section occurrence.
+    for (const it of entity.items) {
+      counts[it.section] = (counts[it.section] || 0) + 1
+    }
+  } else {
+    // Nested sync lane: count records per top-level section, recursing into
+    // self-nested `$children` and inline `page_sections`.
+    const countPages = (pages) => {
+      let p = 0
+      let s = 0
+      for (const page of pages || []) {
+        p++
+        s += (page.page_sections || []).length
+        const sub = countPages(page.$children)
+        p += sub.p
+        s += sub.s
+      }
+      return { p, s }
+    }
+    if (entity.info) counts.info = 1
+    const pg = countPages(entity.pages)
+    if (pg.p) counts.pages = pg.p
+    if (pg.s) counts.page_sections = pg.s
+    if (entity.layout_sections?.length) counts.layout_sections = entity.layout_sections.length
+    if (entity.extensions?.length) counts.extensions = entity.extensions.length
+    if (entity.collections?.length) counts.collections = entity.collections.length
+  }
+
+  console.log('')
+  say.dim(`subtype       ${manifest.subtype}  (format ${manifest.format})`)
+  say.dim(
+    `type          ${manifest.models_required[0].name_at_export} ${manifest.models_required[0].uuid}`
+  )
+  say.dim(`entity        ${entity.uuid || entity.$uuid || entity.$id}`)
+  say.dim(
+    `items         ${Object.entries(counts)
+      .map(([s, n]) => `${s}:${n}`)
+      .join('  ')}`
+  )
+  say.dim(`package_sha256 ${manifest.package_sha256.slice(0, 16)}…`)
+  say.dim(`size          ${(buf.length / 1024).toFixed(1)} KiB`)
+  console.log('')
+
+  if (dryRun) {
+    say.ok('Dry run — nothing written.')
+    return
+  }
+
+  const outPath = resolve(output || `${defaultName}.uwx`)
+  writeFileSync(outPath, buf)
+  say.ok(`Wrote ${c.cyan}${outPath}${c.reset}`)
+  // Only the register lane (foundation schema) mints + persists ids locally. The
+  // site sync lane reads the sidecar read-only — the backend mints on sync — so
+  // there is nothing to persist here for a site.
+  if (useSidecar && isFoundation) {
+    say.dim(
+      `ids persisted in ${uwx.SIDECAR_RELPATH} — commit it so re-exports update, not duplicate.`
+    )
+  }
+  console.log('')
+  say.warn('v0 scope: media bytes, collection records, and @-nested section')
+  say.dim('hierarchy are not yet carried (documented).')
+}

package/src/commands/deploy.js

@@ -11,7 +11,7 @@
  *   - Static-host adapters (`s3-cloudfront`, `cloudflare-pages`,
  *     `github-pages`, `generic-static`, …): build dist/ in bundle-mode
  *     and hand it to a host adapter for upload + invalidation. No login,
- *     no edge. See kb/framework/plans/static-host-deploy-adapters.md.
+ *     no edge.
  *
  * For static-host artifacts WITHOUT upload, see `uniweb export`.
  *
@@ -50,8 +50,6 @@
  *   UNIWEB_SKIP_BILLING=1                  Admin-only: bypass billing gate
  *   UNIWEB_FORCE_REVIEW=1                  Force the browser review flow
  *   UNIWEB_ALLOW_DIRTY_FOUNDATION=1        Don't treat a dirty workspace as stale
- *
- * See kb/platform/plans/cli-site-deploy-decisions.md for the full design.
  */
 
 import { createServer } from 'node:http'
@@ -453,7 +451,7 @@ export async function deploy(args = []) {
   //
   // The default flow (`uniweb`) requires a `foundation:` declaration;
   // static-host deploys don't, so this branch comes BEFORE the foundation
-  // check. See kb/framework/plans/static-host-deploy-adapters.md.
+  // check.
   const targetFromFlag = readFlagValue(args, '--target')
   let hostFromFlag = readFlagValue(args, '--host')
   const noSave = args.includes('--no-save')
@@ -907,6 +905,11 @@ export async function deploy(args = []) {
     say.dim(`Data files     : ${Object.keys(dataFiles).length} (collection JSON)`)
   }
 
+  const searchFiles = await collectSearchFiles(distDir)
+  if (Object.keys(searchFiles).length > 0) {
+    say.dim(`Search indexes : ${Object.keys(searchFiles).length} (_search/ JSON)`)
+  }
+
   // Asset pipeline — upload dist/assets/* + favicon + fonts + content-scan
   // hits (public/, data file refs) to S3, then rewrite each locale's
   // siteContent + each parsed data file so the runtime resolves CDN URLs at
@@ -948,6 +951,7 @@ export async function deploy(args = []) {
     // publish writes each to ${sitePrefix}/data/<key>; worker serve allows
     // /data/* paths from R2 alongside _pages/*.
     ...(Object.keys(dataFiles).length > 0 ? { dataFiles } : {}),
+    ...(Object.keys(searchFiles).length > 0 ? { searchFiles } : {}),
     // Same shape as Editor publish — one entry per language. Single-locale
     // sites end up with `{ [defaultLanguage]: siteContent }`; multi-locale
     // sites carry per-locale translated content emitted by buildLocalizedContent.
@@ -1039,8 +1043,6 @@ export async function deploy(args = []) {
 // registered in @uniweb/build/hosts. Always runs `uniweb build` (bundle
 // mode + prerender) first, then hands dist/ to the adapter's deploy hook
 // for upload + invalidation.
-//
-// See kb/framework/plans/static-host-deploy-adapters.md.
 
 async function deployStaticHost(siteDir, hostName, resolved, { dryRun, autoSave, hostOverridden }) {
   let getAdapter
@@ -1324,6 +1326,25 @@ async function collectDataFiles(distDir) {
   return files
 }
 
+// Collect search index files from dist/_search/ recursively.
+// Returns `{ '<locale>/<name>.json': '<utf8-content>' }` so the worker can
+// write each to `${sitePrefix}/_search/<key>` in R2, gated by searchEnabled.
+// Empty object when the build emitted no search indexes.
+async function collectSearchFiles(distDir) {
+  const searchDir = join(distDir, '_search')
+  if (!existsSync(searchDir)) return {}
+  const files = {}
+  const entries = await readdir(searchDir, { withFileTypes: true, recursive: true })
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    if (!entry.name.endsWith('.json')) continue
+    const fullPath = join(entry.parentPath || entry.path, entry.name)
+    const relPath = relative(searchDir, fullPath)
+    files[relPath] = await readFile(fullPath, 'utf8')
+  }
+  return files
+}
+
 // Optional per-language labels from site.yml's object form. Returns null when
 // site.yml uses the plain-string form (no labels declared) — server falls back
 // to its own defaults in that case.

package/src/commands/docs.js

@@ -119,8 +119,7 @@ ${colors.bright}Child Page Ordering:${colors.reset}
 
 ${colors.bright}Navigation Visibility:${colors.reset}
   ${colors.cyan}hidden${colors.reset}            Hide from all navigation (page still exists)
-  ${colors.cyan}hideInHeader${colors.reset}      Hide from header nav only
-  ${colors.cyan}hideInFooter${colors.reset}      Hide from footer nav only
+  ${colors.cyan}hideIn${colors.reset}            Hide from named nav areas, e.g. [header] or [footer, sidebar]
 
 ${colors.bright}Layout Options:${colors.reset}
   ${colors.cyan}layout${colors.reset}            Layout name or object with name, hide, params
@@ -148,7 +147,7 @@ ${colors.bright}Example:${colors.reset}
   ${colors.dim}title: About Us
   description: Learn about our company
   order: 2
-  hideInFooter: true
+  hideIn: [footer]
   layout:
     hide: [right]
   seo:

package/src/commands/org.js

@@ -0,0 +1,66 @@
+/**
+ * uniweb org — manage publish orgs on the new backend.
+ *
+ *   uniweb org list                 List the orgs you're a member of.
+ *   uniweb org create <handle>      Create an org; you become a member.
+ *
+ * Auth: the new-backend session (`uniweb login`) / UNIWEB_TOKEN. Distinct from
+ * the legacy platform (publish/deploy); this talks to the registry backend.
+ */
+
+import { getRegistryApiBaseUrl } from '../utils/config.js'
+import { ensureRegistryAuth } from '../utils/registry-auth.js'
+import { listOrgs, createOrg, validateHandle, bareHandle } from '../utils/registry-orgs.js'
+
+const colors = { reset: '\x1b[0m', bright: '\x1b[1m', dim: '\x1b[2m', red: '\x1b[31m', green: '\x1b[32m' }
+const error = (m) => console.error(`${colors.red}✗${colors.reset} ${m}`)
+const success = (m) => console.log(`${colors.green}✓${colors.reset} ${m}`)
+
+export async function org(args = []) {
+  const sub = args[0]
+  const apiBase = getRegistryApiBaseUrl()
+
+  if (sub === 'list') {
+    const token = await ensureRegistryAuth({ apiBase, command: 'Listing orgs', args })
+    const orgs = await listOrgs({ apiBase, token })
+    if (!orgs.length) {
+      console.log('You have no orgs yet. Create one: uniweb org create <handle>')
+      return { exitCode: 0 }
+    }
+    console.log('Your orgs:')
+    for (const u of orgs) {
+      console.log(`  ${colors.bright}@${u.handle}${colors.reset}${u.is_primary ? `${colors.dim} (primary)${colors.reset}` : ''}`)
+    }
+    return { exitCode: 0 }
+  }
+
+  if (sub === 'create') {
+    const handle = bareHandle(args[1])
+    if (!handle) {
+      error('Usage: uniweb org create <handle>')
+      return { exitCode: 2 }
+    }
+    const invalid = validateHandle(handle)
+    if (invalid) {
+      error(invalid)
+      return { exitCode: 2 }
+    }
+    const token = await ensureRegistryAuth({ apiBase, command: 'Creating an org', args })
+    try {
+      const org = await createOrg({ apiBase, token, handle })
+      success(`Created ${colors.bright}@${org.handle}${colors.reset} — you're a member${org.is_primary ? ' (primary)' : ''}.`)
+      console.log(`${colors.dim}Publish under it: uniweb register --scope @${org.handle}${colors.reset}`)
+      return { exitCode: 0 }
+    } catch (err) {
+      error(err.message)
+      return { exitCode: 1 }
+    }
+  }
+
+  console.log('uniweb org <command>')
+  console.log('  list             List orgs you belong to')
+  console.log('  create <handle>  Create an org (you become a member)')
+  return { exitCode: sub ? 2 : 0 }
+}
+
+export default org

package/src/commands/pull.js

@@ -0,0 +1,238 @@
+/**
+ * uniweb pull — bring the backend's copy of a site back to canonical files.
+ *
+ * The read-side mirror of `uniweb push`. The project holds exactly one identity —
+ * `site.yml::$uuid` (the site-content entity) — and BOTH pull lanes are keyed by it
+ * (the backend owns the site's `@uniweb/folder` and resolves it from the site-content
+ * uuid, so the framework never holds a folder uuid). It GETs the two lanes and projects
+ * the returned documents back to files via the framework's projection layer
+ * (`@uniweb/build/uwx`):
+ *
+ *   - content lane → `siteContentDocumentToProject` (site.yml/theme.yml/head.html,
+ *     pages/**, layout/**), and
+ *   - folder lane  → `collectionsToProject` (the folder + record files).
+ *
+ * Pull is git-pull-like: it reconciles the working tree to the backend, DELETING
+ * pages/sections that no longer exist there (toggle off with `--no-delete`). The
+ * deletion is guarded so an empty/partial payload never wipes the tree.
+ *
+ * `uniweb login && uniweb pull`. Run from a site, or a workspace with one site.
+ *
+ * Usage:
+ *   uniweb pull                          GET both lanes, project to files, prune orphans
+ *   uniweb pull --no-collections         Pull pages only; skip the folder (collections) lane
+ *   uniweb pull --no-delete              Project, but keep files with no backend item
+ *   uniweb pull --dry-run                Report what it would GET; write nothing
+ *   uniweb pull --registry <url>         Override the backend origin
+ *   uniweb pull --token <bearer>         Read with this bearer; skips `uniweb login`
+ *
+ * Endpoints: <origin>/dev/site/content/pull/{uuid} + /dev/site/folder/pull/{uuid},
+ *   both keyed by `site.yml::$uuid`. Origin from
+ *   --registry  >  UNIWEB_REGISTER_URL  >  the local default.
+ * Auth:  --token  >  UNIWEB_TOKEN  >  `uniweb login` session.
+ *
+ * A project that never pushed has no `$uuid` to pull by — pull is a no-op with a
+ * clear message. NOTE: the backend pull routes have not been exercised live; the
+ * response-envelope extraction (extractDocument / splitCollectionsPull) is
+ * deliberately tolerant and is the single point to adjust at the first live run.
+ */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+import {
+  siteContentDocumentToProject,
+  collectionsToProject,
+  resolveCollectionsConfig,
+} from '@uniweb/build/uwx'
+import { makeModelResolver } from './push.js'
+import { ensureRegistryAuth } from '../utils/registry-auth.js'
+import { resolveSiteDir as defaultResolveSiteDir } from './deploy.js'
+
+const DEFAULT_BACKEND_ORIGIN = 'http://localhost:8080'
+const FOLDER_MODEL = '@uniweb/folder'
+
+const colors = { reset: '\x1b[0m', bright: '\x1b[1m', dim: '\x1b[2m', red: '\x1b[31m', green: '\x1b[32m', blue: '\x1b[36m' }
+const log = console.log
+const success = (m) => log(`${colors.green}✓${colors.reset} ${m}`)
+const error = (m) => 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}`)
+
+function flagValue(args, name) {
+  const eq = args.find((a) => a.startsWith(`${name}=`))
+  if (eq) return eq.slice(name.length + 1)
+  const i = args.indexOf(name)
+  if (i !== -1 && args[i + 1] && !args[i + 1].startsWith('-')) return args[i + 1]
+  return null
+}
+
+// Read a top-level `$uuid:` scalar from a YAML file, or null.
+function readYamlUuid(filePath) {
+  try {
+    const obj = yaml.load(readFileSync(filePath, 'utf8'))
+    return typeof obj?.$uuid === 'string' ? obj.$uuid : null
+  } catch {
+    return null
+  }
+}
+
+// Extract a single entity `$`-document from a pull response. Tolerant of a raw
+// document, or a `{ document }` / `{ entity }` envelope. (Adjust at live e2e.)
+export function extractDocument(payload) {
+  if (!payload || typeof payload !== 'object') return null
+  if (payload.$model || payload.$id || payload.info) return payload
+  return payload.document || payload.entity || null
+}
+
+// Split a collections pull (the folder + the entities it references) into the
+// folder document and the record documents. Tolerant of an array, an
+// `{ entities }` / `{ documents }` list, or an explicit `{ folder, records }`.
+export function splitCollectionsPull(payload) {
+  if (payload?.folder) return { folderDoc: payload.folder, recordDocs: payload.records || [] }
+  const list = Array.isArray(payload)
+    ? payload
+    : Array.isArray(payload?.entities)
+      ? payload.entities
+      : Array.isArray(payload?.documents)
+        ? payload.documents
+        : null
+  if (!list) return { folderDoc: null, recordDocs: [] }
+  const docs = list.map(extractDocument).filter(Boolean)
+  return {
+    folderDoc: docs.find((d) => d.$model === FOLDER_MODEL) || null,
+    recordDocs: docs.filter((d) => d.$model !== FOLDER_MODEL),
+  }
+}
+
+/**
+ * @param {string[]} args
+ * @param {object} [deps] - injectable seams for testing: `fetch` (default global
+ *   fetch), `resolveSiteDir`, `getToken` (skip auth).
+ */
+export async function pull(args = [], deps = {}) {
+  const fetchImpl = deps.fetch || globalThis.fetch
+  const resolveSiteDir = deps.resolveSiteDir || defaultResolveSiteDir
+
+  const dryRun = args.includes('--dry-run')
+  const tokenFlag = flagValue(args, '--token')
+  const prune = !(args.includes('--no-delete') || args.includes('--no-prune')) // git-like by default
+  const noCollections = args.includes('--no-collections') || args.includes('--content-only')
+  const registryFlag = flagValue(args, '--registry') || process.env.UNIWEB_REGISTER_URL || DEFAULT_BACKEND_ORIGIN
+
+  let apiBase
+  try {
+    apiBase = new URL(registryFlag).origin
+  } catch {
+    error(`Invalid --registry / UNIWEB_REGISTER_URL: ${registryFlag}`)
+    return { exitCode: 2 }
+  }
+
+  const siteDir = await resolveSiteDir(args, 'pull')
+  // One identity per site: `site.yml::$uuid`. Both lanes (content + folder) are keyed
+  // by it — the backend resolves the site's `@uniweb/folder` from this uuid.
+  const siteContentUuid = readYamlUuid(join(siteDir, 'site.yml'))
+
+  if (!siteContentUuid) {
+    info('Nothing to pull — this project has no $uuid yet. Run `uniweb push` first.')
+    return { exitCode: 0 }
+  }
+
+  // Lazy bearer — acquired on first GET (a dry run stays offline). Tests inject
+  // deps.getToken to skip auth entirely.
+  let cachedToken = null
+  const getToken =
+    deps.getToken ||
+    (async () => {
+      if (cachedToken) return cachedToken
+      cachedToken = tokenFlag || process.env.UNIWEB_TOKEN || (await ensureRegistryAuth({ apiBase, command: 'Pulling', args }))
+      return cachedToken
+    })
+
+  if (dryRun) {
+    info(`Dry run — would GET ${colors.dim}${apiBase}/dev/site/content/pull/${siteContentUuid}${colors.reset}`)
+    if (!noCollections) info(`Dry run — would GET ${colors.dim}${apiBase}/dev/site/folder/pull/${siteContentUuid}${colors.reset}`)
+    return { exitCode: 0 }
+  }
+
+  // GET a pull lane and parse it as JSON. 404 → null (deleted / no access); any
+  // failure is reported and returns null (the lane is skipped, not fatal).
+  const getJson = async (path, label) => {
+    const url = `${apiBase}${path}`
+    info(`Pulling ${colors.bright}${label}${colors.reset} from ${colors.dim}${url}${colors.reset} …`)
+    let res
+    try {
+      res = await fetchImpl(url, { headers: { Authorization: `Bearer ${await getToken()}` } })
+    } catch (err) {
+      error(`Could not reach the backend at ${url}: ${err.message}`)
+      note('Set the origin with --registry <url> or UNIWEB_REGISTER_URL.')
+      return null
+    }
+    if (res.status === 404) {
+      note(`${label}: not found (404) — it was deleted, or you lack access.`)
+      return null
+    }
+    if (!res.ok) {
+      error(`${label} pull failed: HTTP ${res.status} ${res.statusText}`)
+      if (res.status === 401 || res.status === 403) note("Credentials weren't accepted — supply a bearer with --token <bearer>.")
+      return null
+    }
+    try {
+      return await res.json()
+    } catch (err) {
+      error(`Could not parse the ${label} response as JSON: ${err.message}`)
+      return null
+    }
+  }
+
+  let pages = 0
+  let sections = 0
+  let records = 0
+  let deleted = 0
+
+  // Lane 1 — content → config + pages/** + layout/**.
+  const siteDoc = extractDocument(
+    await getJson(`/dev/site/content/pull/${encodeURIComponent(siteContentUuid)}`, 'content')
+  )
+  if (siteDoc) {
+    const report = siteContentDocumentToProject({ document: siteDoc, siteRoot: siteDir, prune })
+    pages += report.pages.length
+    sections += report.sections.length
+    deleted += report.deleted.length
+  }
+
+  // Lane 2 — folder → the folder + record files, keyed by the SAME site-content uuid
+  // (the backend resolves the site's `@uniweb/folder` from it; the framework never
+  // holds a folder uuid). Models are resolved by name (async) up front, so
+  // collectionsToProject keeps its synchronous contract.
+  if (!noCollections) {
+    const payload = await getJson(`/dev/site/folder/pull/${encodeURIComponent(siteContentUuid)}`, 'collections')
+    if (payload) {
+      const { folderDoc, recordDocs } = splitCollectionsPull(payload)
+      const resolveModel = makeModelResolver({ apiBase, getToken, fetchImpl })
+      const declByModel = new Map()
+      for (const model of [...new Set(recordDocs.map((d) => d.$model).filter(Boolean))]) {
+        try {
+          declByModel.set(model, await resolveModel(model))
+        } catch (err) {
+          note(`! could not resolve model ${model}: ${err.message}`)
+        }
+      }
+      const collectionsConfig = await resolveCollectionsConfig(siteDir).catch(() => null)
+      const report = collectionsToProject({
+        folderDoc,
+        recordDocs,
+        siteRoot: siteDir,
+        opts: { resolveDeclaration: (name) => declByModel.get(name) || null, collectionsConfig },
+      })
+      records += report.placed.length + report.updated.length
+      for (const s of report.skipped) note(`↷ ${s.slug ?? s.uuid ?? '(record)'}: ${s.reason}`)
+      for (const w of report.warnings) note(`! ${w}`)
+    }
+  }
+
+  success(
+    `Pulled — ${pages} page(s), ${sections} section(s), ${records} record(s)` + (deleted ? `, ${deleted} deleted` : '')
+  )
+  return { exitCode: 0 }
+}