uniweb 1.0.0 → 1.0.2

package/src/commands/clone.js

@@ -0,0 +1,466 @@
+/**
+ * uniweb clone <site-uuid> — materialize a backend site as a local file project.
+ *
+ * The "git clone" of the site-content remote model (see
+ * the site-content remote model): 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. read the site-content document via the backend client — pull the `foundation`
+ *      ref out of that one document (no `@uniweb/build` needed for a read);
+ *   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 identity on that backend — its section of `sync.json` (plain
+ *      JSON, written with no dependencies).
+ *      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-records` 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-records Pull pages only; skip records
+ *   uniweb clone <uuid> --org @org       Work in @org for this clone, instead of the
+ *                                        workspace chosen at `uniweb login`. A site in
+ *                                        another workspace stops it.
+ *
+ * Backend: via BackendClient (the site-content pull lane). Origin from
+ *   UNIWEB_SERVER  >  the local default (internal dev overrides;
+ *   not the user-facing path — `uniweb login` determines the origin).
+ * Auth:  UNIWEB_TOKEN  >  the stored session  >  `uniweb login`. No `--token` (retired
+ *   from the backend commands 2026-09-21).
+ */
+
+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 { BackendClient, describeRequestError, refusalDetail } from '../backend/client.js'
+import { resolveWorkspace } from '../backend/workspace.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',
+  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.$schema || payload.$uuid || 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
+  }
+}
+
+// Seed `sync.json` with the identity this clone was pulled by.
+//
+// ⛔ **Dependency-free on purpose, and this has bitten before.** `clone` runs BEFORE
+// `pnpm install`, so `@uniweb/build`'s store is not on disk yet. The previous version
+// of this recorded the scope through a lazy `import('@uniweb/build/uwx')` whose
+// failure branch returned null and wrote NOTHING — so a fresh clone recorded nothing
+// essentially always, and the next command stopped dead complaining about a backend
+// the user had named on the command line. Measured by the backend lane 2026-09-18:
+// 0.48.5 recorded it, 0.57.0 did not.
+//
+// ⭐ JSON needs no parser, which is most of why the store is JSON rather than YAML —
+// `site.yml`'s equivalent needed a hand-rolled dependency-free WRITER for exactly
+// this. The store stays the one writer everywhere else; this seeds a fresh file.
+// `test/clone.test.js` covers it end to end with `skipInstall: true`.
+function seedSyncJson(siteDir, origin, uuid) {
+  const file = join(siteDir, 'sync.json')
+  let doc = { version: 1, backends: {} }
+  if (existsSync(file)) {
+    try {
+      const parsed = JSON.parse(readFileSync(file, 'utf8'))
+      if (parsed?.backends && typeof parsed.backends === 'object') doc = parsed
+    } catch {
+      /* unreadable — a fresh clone's file is ours to write */
+    }
+  }
+  const key = new URL(origin).origin
+  // ⛔ No workspace: a command works in the one chosen with the login, and the clone
+  // does not know which workspace OWNS the site — it may read it from a parent.
+  doc.backends[key] = {
+    ...(doc.backends[key] || {}),
+    site: { ...(doc.backends[key]?.site || {}), uuid }
+  }
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, JSON.stringify(doc, null, 2) + '\n')
+}
+
+// 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 = {}) {
+  // 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|.]
+
+  if (!siteUuid) {
+    error('Missing site uuid.')
+    log(
+      `\nUsage: ${getCliPrefix()} clone <site-uuid> [name|.] [--path <dir>] [--project <name>] [--no-records]`
+    )
+    log(
+      `${colors.dim}Sites are private — run \`uniweb login\` first.${colors.reset}`
+    )
+    return { exitCode: 2 }
+  }
+
+  const noRecords =
+    args.includes('--no-records') || args.includes('--content-only')
+  const pathFlag = flagValue(args, '--path')
+  const projectFlag = flagValue(args, '--project')
+  const client = new BackendClient({
+    getToken: deps.getToken,
+    fetchImpl: deps.fetch,
+    args,
+    command: 'Cloning'
+  })
+  // The workspace this clone works in — the login's, unless this command names another
+  // (`workspace.js`). A site the backend keeps elsewhere stops it, naming how to switch.
+  const ws = await resolveWorkspace({ client, args })
+  if (ws.refused) {
+    error('This clone works in one workspace, and none is chosen.')
+    note(ws.reason)
+    return { exitCode: 2 }
+  }
+  client.setWorkspace(ws.workspace, { source: ws.source })
+
+  // 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 documents
+  try {
+    const res = await client.pullSiteContent(siteUuid)
+    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}`)
+      const detail = await refusalDetail(res)
+      if (detail) note(detail)
+      if (res.status === 401 || res.status === 403)
+        note('Run `uniweb login` first.')
+      return { exitCode: 1 }
+    }
+    documents = readUwxDocuments(Buffer.from(await res.arrayBuffer()))
+  } catch (err) {
+    error(describeRequestError(err, client.origin))
+    return { exitCode: 1 }
+  }
+
+  const document =
+    documents.map(extractDocument).find(Boolean) || null
+  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
+    )
+    if (placement.outsideRoot) {
+      error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
+      note(
+        `The workspace root is ${existingRoot}. A package outside it cannot be a ` +
+          `workspace member — the directory and the manifests would disagree.`
+      )
+      return { exitCode: 1 }
+    }
+    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 identity this clone was pulled by, under the backend that minted it.
+  // The folder is pulled by the same uuid (the backend resolves the site's
+  // @uniweb/folder from it), so there is no separate folder uuid to seed.
+  //
+  // ⭐ The backend is the KEY, not a separate note. `clone` was the sharpest case for
+  // the old `$backend`: the uuid came from whoever we read and nothing on disk said
+  // so, and a teammate who pulled while logged in elsewhere sent it to the wrong
+  // backend. Stored under the origin, that cannot be expressed.
+  seedSyncJson(siteDir, client.origin, siteUuid)
+  success(
+    `Scaffolded the site harness${foundationRef ? ` (foundation: ${foundationRef})` : ''}.`
+  )
+  note(`Bound to ${client.origin} (recorded in sync.json).`)
+
+  // 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 }
+    }
+  }
+
+  // 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', 'queries.yml', join('records', 'folder.yml')]
+      .map((f) => join(siteDir, f))
+      .filter((p) => existsSync(p))
+  )
+
+  const pullExtra = []
+  if (noRecords) pullExtra.push('--no-records')
+  // The workspace this clone was told to work in: the pull is another process, and asks the same
+  // question. ⛔ Until 2026-09-26 it was not told, so it used the login's — or, with none chosen,
+  // refused: "none is chosen". A workspace from the login or the environment reaches it by itself.
+  const orgFlag = flagValue(args, '--org')
+  if (orgFlag) pullExtra.push('--org', orgFlag)
+  if (args.includes('--personal')) pullExtra.push('--personal')
+
+  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,202 @@
+/**
+ * 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.queries?.length) counts.queries = entity.queries.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, records, and @-nested section')
+  say.dim('hierarchy are not yet carried (documented).')
+}