uniweb 0.12.20 → 0.12.22

package/src/commands/clone.js

@@ -0,0 +1,337 @@
+/**
+ * uniweb clone <site-uuid> — materialize a backend site as a local file project.
+ *
+ * The "git clone" of the site-content remote model (see
+ * kb/framework/plans/site-content-remote-model.md): the backend is the remote, a
+ * file project is a working clone. `clone` is the create-side sibling of
+ * `uniweb pull`/`uniweb push` — it bootstraps a brand-new project from a site that
+ * already lives in the backend (typically authored in the visual app).
+ *
+ * What it does, and a key constraint: clone runs from a GLOBAL install before any
+ * project exists, so it must NOT statically import `@uniweb/build` (that would crash
+ * `npx uniweb clone`, same reason utils/workspace.js loads the classifier lazily).
+ * So clone does the minimum itself and delegates the heavy lifting:
+ *
+ *   1. plain `fetch` GET <origin>/dev/site/content/pull/<uuid> — read the `foundation`
+ *      ref out of that one document (no `@uniweb/build` needed for a GET);
+ *   2. scaffold the HARNESS — a full Vite site package whose foundation is
+ *      REFERENCED (runtime-loaded), no local foundation sibling (scaffoldSite with
+ *      foundationRef and no foundationPath) + AGENTS.md + deps pinned to this CLI's
+ *      version matrix; placement reuses create (new workspace / in-place) and add's
+ *      resolver (into an existing workspace, any shape);
+ *   3. seed the site's one identity — site.yml::$uuid (a plain YAML scalar write).
+ *      The folder is pulled by this same uuid, so there is no separate folder uuid to
+ *      seed;
+ *   4. install, then delegate the projection to the project-local `uniweb pull` (which
+ *      resolves the now-installed project-local `@uniweb/build`; clone forwards
+ *      `--no-collections` to it when set).
+ *
+ * Sites are private — authenticate with `uniweb login` first; the session carries
+ * identity + the backend origin. There is no `--foundation` flag: the site carries
+ * its foundation ref and clone honors it verbatim (switching a site's foundation is a
+ * deliberate, high-risk operation, never a clone convenience).
+ *
+ * Usage:
+ *   uniweb login
+ *   uniweb clone <site-uuid> [name|.]    New workspace (or `.` in-place / a site in
+ *                                        the current workspace when run inside one)
+ *   uniweb clone <uuid> --path sites     Place under sites/ (segregated layout)
+ *   uniweb clone <uuid> --project docs   Co-located docs/site
+ *   uniweb clone <uuid> --no-collections Pull pages only; skip collection records
+ *
+ * Endpoints: <origin>/dev/site/content/pull/<uuid>. Origin from
+ *   --registry  >  UNIWEB_REGISTER_URL  >  the local default (internal dev overrides;
+ *   not the user-facing path — `uniweb login` determines the origin).
+ * Auth:  --token  >  UNIWEB_TOKEN  >  `uniweb login` session.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, resolve, basename, dirname } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { scaffoldWorkspace, scaffoldSite } from '../utils/scaffold.js'
+import { resolvePlacement, SITE_KIND } from '../utils/placement.js'
+import { findWorkspaceRoot } from '../utils/workspace.js'
+import { addWorkspaceGlob } from '../utils/config.js'
+import { detectWorkspacePm, installCmd } from '../utils/pm.js'
+import { ensureRegistryAuth } from '../utils/registry-auth.js'
+import { isNonInteractive, getCliPrefix } from '../utils/interactive.js'
+import { extractFoundationRef } from '../utils/site-content-refs.js'
+
+const DEFAULT_BACKEND_ORIGIN = 'http://localhost:8080'
+
+const colors = {
+  reset: '\x1b[0m', bright: '\x1b[1m', dim: '\x1b[2m',
+  red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', blue: '\x1b[36m', cyan: '\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
+}
+
+function slugify(s) {
+  return String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+}
+
+// Tolerant single-entity document extraction (mirrors pull.js; duplicated rather
+// than imported because pull.js statically imports @uniweb/build).
+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
+}
+
+// Unwrap a possibly-localized scalar (a `{ <locale>: value }` map) to a plain string.
+function unwrapScalar(v) {
+  if (typeof v === 'string') return v
+  if (v && typeof v === 'object') {
+    const first = Object.values(v).find((x) => typeof x === 'string')
+    if (first) return first
+  }
+  return null
+}
+
+/**
+ * Read the seeds clone needs out of a site-content `$`-document:
+ *  - foundationRef: the `foundation` ref (a URL or our `@ns/name@ver`) — written
+ *    verbatim into site.yml so the runtime loads it as a federated module;
+ *  - name: a display name for the new project.
+ *
+ * No folder uuid is read: the site holds one identity (its site-content uuid), and
+ * the folder is pulled by that same uuid — the framework never holds a folder uuid.
+ */
+export function extractCloneSeeds(document) {
+  const info = document?.info || {}
+  return {
+    foundationRef: extractFoundationRef(info, document),
+    name: unwrapScalar(info.name) ?? unwrapScalar(document?.name) ?? null,
+  }
+}
+
+// Insert/replace a top-level `$uuid:` scalar in a YAML file's text without
+// disturbing the rest (the scaffolded site.yml is comment-heavy — don't round-trip
+// through a YAML dumper). Inserts after the first `name:` line, else prepends.
+function seedYamlUuid(filePath, uuid) {
+  let text = existsSync(filePath) ? readFileSync(filePath, 'utf8') : ''
+  if (/^\$uuid:/m.test(text)) {
+    text = text.replace(/^\$uuid:.*$/m, `$uuid: ${uuid}`)
+  } else {
+    const nameMatch = text.match(/^name:.*$/m)
+    if (nameMatch) {
+      const idx = nameMatch.index + nameMatch[0].length
+      text = text.slice(0, idx) + `\n$uuid: ${uuid}` + text.slice(idx)
+    } else {
+      text = `$uuid: ${uuid}\n` + text
+    }
+  }
+  mkdirSync(dirname(filePath), { recursive: true })
+  writeFileSync(filePath, text)
+}
+
+// Build the package-manager argv to run the project-local `uniweb pull`.
+function pullExecArgv(pm, extra) {
+  // npm needs `exec --` to forward flags to the binary; pnpm/yarn don't.
+  if (pm === 'npm') return ['exec', '--', 'uniweb', 'pull', ...extra]
+  return ['exec', 'uniweb', 'pull', ...extra]
+}
+
+/**
+ * @param {string[]} args
+ * @param {object} [deps] - injectable seams for testing:
+ *   fetch, getToken, skipInstall, skipPull, runInstall(projectDir, pm),
+ *   runPull(siteDir, pm, extraArgs).
+ */
+export async function clone(args = [], deps = {}) {
+  const fetchImpl = deps.fetch || globalThis.fetch
+
+  const positionals = args.filter((a) => !a.startsWith('-'))
+  const siteUuid = positionals[0]
+  const target = positionals[1] || null // [name|.]
+
+  if (!siteUuid) {
+    error('Missing site uuid.')
+    log(`\nUsage: ${getCliPrefix()} clone <site-uuid> [name|.] [--path <dir>] [--project <name>] [--no-collections]`)
+    log(`${colors.dim}Sites are private — run \`uniweb login\` first.${colors.reset}`)
+    return { exitCode: 2 }
+  }
+
+  const noCollections = args.includes('--no-collections') || args.includes('--content-only')
+  const pathFlag = flagValue(args, '--path')
+  const projectFlag = flagValue(args, '--project')
+  const tokenFlag = flagValue(args, '--token')
+  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 }
+  }
+
+  let cachedToken = null
+  const getToken =
+    deps.getToken ||
+    (async () => {
+      if (cachedToken) return cachedToken
+      cachedToken = tokenFlag || process.env.UNIWEB_TOKEN || (await ensureRegistryAuth({ apiBase, command: 'Cloning', args }))
+      return cachedToken
+    })
+
+  // 1. GET the site-content document (plain fetch — no @uniweb/build).
+  const url = `${apiBase}/dev/site/content/pull/${encodeURIComponent(siteUuid)}`
+  info(`Reading site ${colors.bright}${siteUuid}${colors.reset} from ${colors.dim}${url}${colors.reset} …`)
+  let payload
+  try {
+    const res = await fetchImpl(url, { headers: { Authorization: `Bearer ${await getToken()}` } })
+    if (res.status === 404) {
+      error(`Site not found (404) — check the uuid, or you lack access.`)
+      return { exitCode: 1 }
+    }
+    if (!res.ok) {
+      error(`Could not read the site: HTTP ${res.status} ${res.statusText}`)
+      if (res.status === 401 || res.status === 403) note('Run `uniweb login` first (or pass --token <bearer>).')
+      return { exitCode: 1 }
+    }
+    payload = await res.json()
+  } catch (err) {
+    error(`Could not reach the backend at ${url}: ${err.message}`)
+    return { exitCode: 1 }
+  }
+
+  const document = extractDocument(payload)
+  if (!document) {
+    error('The site-content response carried no recognizable document.')
+    return { exitCode: 1 }
+  }
+  const { foundationRef, name: siteDisplayName } = extractCloneSeeds(document)
+  if (!foundationRef) {
+    note('! The pulled site declares no foundation ref — set `foundation:` in site.yml after clone.')
+  }
+
+  // 2. Resolve placement (one verb, context-aware).
+  const cwd = deps.cwd || process.cwd()
+  const inPlace = target === '.'
+  const existingRoot = inPlace ? null : findWorkspaceRoot(cwd)
+
+  let projectDir // the package-manager root (for install)
+  let siteDir // where the site package lands
+  let sitePkgName
+  let workspaceName
+  let isNewWorkspace
+  let placement = null
+
+  if (inPlace) {
+    isNewWorkspace = true
+    projectDir = cwd
+    workspaceName = slugify(basename(cwd)) || 'site'
+    siteDir = join(projectDir, 'site')
+    sitePkgName = 'site'
+  } else if (existingRoot) {
+    isNewWorkspace = false
+    projectDir = existingRoot
+    placement = resolvePlacement(existingRoot, target, { path: pathFlag, project: projectFlag }, SITE_KIND)
+    siteDir = join(existingRoot, placement.relativePath)
+    sitePkgName = placement.packageName
+    workspaceName = sitePkgName
+  } else {
+    isNewWorkspace = true
+    workspaceName = target || slugify(siteDisplayName) || null
+    if (!workspaceName) {
+      error('Could not derive a project name from the site. Pass one: `uniweb clone <uuid> <name>`.')
+      return { exitCode: 2 }
+    }
+    if (!/^[a-z0-9-]+$/.test(workspaceName)) {
+      error(`Invalid project name "${workspaceName}" — use lowercase letters, numbers, and hyphens.`)
+      return { exitCode: 2 }
+    }
+    projectDir = resolve(cwd, workspaceName)
+    siteDir = join(projectDir, 'site')
+    sitePkgName = 'site'
+  }
+
+  // Conflict guards.
+  if (isNewWorkspace && !inPlace && existsSync(projectDir)) {
+    error(`Directory already exists: ${workspaceName}`)
+    return { exitCode: 1 }
+  }
+  if (existsSync(join(siteDir, 'site.yml'))) {
+    error(`A site already exists at ${siteDir} — refusing to overwrite.`)
+    return { exitCode: 1 }
+  }
+
+  // 3. Scaffold the harness (ref-only site: foundationRef, no foundationPath).
+  const onProgress = (m) => note(m)
+  const siteContext = { name: sitePkgName, projectName: workspaceName, ...(foundationRef ? { foundationRef } : {}) }
+
+  if (isNewWorkspace) {
+    info(`Scaffolding ${colors.bright}${workspaceName}${colors.reset} …`)
+    await scaffoldWorkspace(
+      projectDir,
+      { projectName: workspaceName, workspaceGlobs: ['site'], scripts: { dev: 'uniweb dev', build: 'uniweb build' } },
+      { onProgress },
+    )
+    await scaffoldSite(siteDir, siteContext, { onProgress })
+  } else {
+    info(`Adding site ${colors.bright}${sitePkgName}${colors.reset} to the workspace at ${colors.dim}${placement.relativePath}/${colors.reset} …`)
+    await scaffoldSite(siteDir, siteContext, { onProgress })
+    await addWorkspaceGlob(existingRoot, placement.relativePath)
+  }
+
+  // 4. Seed the site's one identity — site.yml::$uuid. The folder is pulled by this
+  // same uuid (the backend resolves the site's @uniweb/folder from it), so there is no
+  // separate folder uuid to seed.
+  seedYamlUuid(join(siteDir, 'site.yml'), siteUuid)
+  success(`Scaffolded the site harness${foundationRef ? ` (foundation: ${foundationRef})` : ''}.`)
+
+  // 5. Install, then delegate the projection to the project-local `uniweb pull`.
+  const pm = detectWorkspacePm(projectDir) || 'pnpm'
+
+  if (deps.skipInstall) {
+    note('Skipping install (test mode).')
+  } else if (deps.runInstall) {
+    await deps.runInstall(projectDir, pm)
+  } else {
+    info(`Installing dependencies (${installCmd(pm)}) …`)
+    const r = spawnSync(pm, ['install'], { cwd: projectDir, stdio: 'inherit' })
+    if (r.status !== 0) {
+      error(`Install failed. Once it succeeds, run \`uniweb pull\` from ${siteDir} to fetch the content.`)
+      return { exitCode: 1 }
+    }
+  }
+
+  const pullExtra = []
+  if (flagValue(args, '--registry')) pullExtra.push('--registry', registryFlag)
+  if (tokenFlag) pullExtra.push('--token', tokenFlag)
+  if (noCollections) pullExtra.push('--no-collections')
+
+  if (deps.skipPull) {
+    note('Skipping pull (test mode).')
+  } else if (deps.runPull) {
+    await deps.runPull(siteDir, pm, pullExtra)
+  } else {
+    info('Pulling content …')
+    const r = spawnSync(pm, pullExecArgv(pm, pullExtra), { cwd: siteDir, stdio: 'inherit' })
+    if (r.status !== 0) {
+      error(`Content pull failed. Fix the issue, then run \`uniweb pull\` from ${siteDir}.`)
+      return { exitCode: 1 }
+    }
+  }
+
+  log('')
+  success(`Cloned site into ${colors.bright}${isNewWorkspace && !inPlace ? workspaceName : siteDir}${colors.reset}`)
+  if (isNewWorkspace && !inPlace) {
+    log(`\nNext: ${colors.cyan}cd ${workspaceName} && uniweb dev${colors.reset}`)
+  } else {
+    log(`\nNext: ${colors.cyan}uniweb dev${colors.reset}`)
+  }
+  return { exitCode: 0 }
+}

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: