uniweb 0.12.21 → 0.12.23

package/src/commands/push.js

@@ -0,0 +1,400 @@
+/**
+ * uniweb push — push a site to the backend over its two directional lanes:
+ *   - content lane → `@uniweb/site-content` (the static half: pages, sections,
+ *     layout, theme, foundation ref, extensions, collection decls);
+ *   - folder lane → one `@uniweb/folder` + the collection-record entities it
+ *     references (the dynamic half; the `$ref` closure rides together).
+ *
+ * Each entity is an entity-content document (`$id` + `$model` + sections). The site
+ * holds exactly one identity: `site.yml::$uuid` (the site-content entity). A first
+ * push has none — it CREATEs the site (`POST /dev/site/content`, uuid-less), the
+ * backend mints + adopts it and returns the new uuid, which `push` records into
+ * `site.yml`. Later pushes UPDATE by that uuid (`POST /dev/site/content/push/{uuid}`).
+ * The folder lane is keyed by the SAME site-content uuid (`POST
+ * /dev/site/folder/push/{uuid}`) — the backend owns the site's `@uniweb/folder`, so
+ * the framework never holds a folder uuid. Records still round-trip their own `$uuid`
+ * (back-filled into their source files). site-content is pushed wholesale (no per-item
+ * uuids on the wire). Push-only, last-push-wins (`collision=force`) in v1.
+ *
+ * Order: content first (CREATE or UPDATE — the site must exist before its folder),
+ * then the folder, keyed by the site's uuid. On a brand-new site the backend creates
+ * the folder on its first folder push for that uuid.
+ *
+ * `uniweb login && uniweb push`. Run from a site, or a workspace with one site.
+ *
+ * Usage:
+ *   uniweb push                          Build, push both lanes, back-fill $uuid
+ *   uniweb push --as-org @org            Act as @org (membership-gated)
+ *   uniweb push --dry-run                Report what would be pushed; submit nothing
+ *   uniweb push -o out.uwx               Write the .uwx file(s) per lane; submit nothing
+ *   uniweb push --registry <url>         Override the backend origin
+ *   uniweb push --token <bearer>         Submit with this bearer; skips `uniweb login`
+ *   uniweb push --foundation <dir>       Use this local foundation for the Model schema
+ *   uniweb push --all                    Send every record (bypass the changed-only cache)
+ *
+ * Endpoints: <origin>/dev/site/content (create), /dev/site/content/push/{uuid}
+ *   (update), /dev/site/folder/push/{uuid}. origin from
+ *   --registry  >  UNIWEB_REGISTER_URL  >  the local default.
+ * Auth:  --token  >  UNIWEB_TOKEN  >  `uniweb login` session.
+ */
+
+import { writeFileSync, readFileSync, mkdirSync } from 'node:fs'
+import { resolve, join, dirname } from 'node:path'
+import {
+  emitSyncPackages,
+  backfillEntityUuids,
+  writeSiteEntityUuid,
+} from '@uniweb/build/uwx'
+import { ensureRegistryAuth } from '../utils/registry-auth.js'
+import { resolveSiteDir } from './deploy.js'
+
+// Same backend host as `uniweb register`; only the path differs (the restore
+// lane). Overridable via --registry / UNIWEB_REGISTER_URL (a URL; origin taken).
+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',
+}
+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
+}
+
+// Pull the finalized entities out of the restore response. The backend returns
+// `{ report: { finalized: [ { index, uuid, changed, document }, … ] } }` — each
+// entry carries its position in the SUBMITTED sequence (`index`, the correlation
+// key — `$id` is not echoed), the minted entity `uuid`, a `changed` flag, and the
+// full `document` (verbatim stored content with every `$uuid` filled in). A couple
+// of shapes are tolerated; only entries with a valid `index` + `uuid` are usable.
+function extractFinalized(payload) {
+  const list = Array.isArray(payload?.report?.finalized)
+    ? payload.report.finalized
+    : Array.isArray(payload?.finalized)
+      ? payload.finalized
+      : Array.isArray(payload)
+        ? payload
+        : null
+  if (!list) return null
+  return list
+    .map((d) => ({
+      index: d?.index,
+      uuid: d?.uuid ?? d?.document?.$uuid ?? null,
+      changed: d?.changed,
+      document: d?.document ?? null,
+    }))
+    .filter((e) => Number.isInteger(e.index) && e.uuid)
+}
+
+// Pull the minted site-content uuid out of a CREATE (`POST /dev/site/content`)
+// response. The exact shape is an open backend item — tolerant of a bare
+// `{ siteContentUuid }` / `{ $uuid }` / `{ uuid }`, or the same `report.finalized[]`
+// envelope the update/folder lanes return (the site entity is submitted alone, so its
+// minted uuid is the first finalized entry). Returns null if none is present. (Single
+// adjust-point to pin at the first live CREATE.)
+export function extractMintedSiteUuid(payload) {
+  if (typeof payload?.siteContentUuid === 'string') return payload.siteContentUuid
+  if (typeof payload?.$uuid === 'string') return payload.$uuid
+  if (typeof payload?.uuid === 'string') return payload.uuid
+  const finalized = extractFinalized(payload)
+  if (finalized && finalized.length) {
+    const site = finalized.find((f) => f.index === 0) || finalized[0]
+    return site?.uuid ?? null
+  }
+  return null
+}
+
+// One-line summary from the authoritative per-entity `changed` flag (`false` = a
+// true no-op). Falls back silently when the backend omits it.
+function changedSummary(finalized) {
+  const changed = finalized.filter((f) => f.changed === true).length
+  const unchanged = finalized.filter((f) => f.changed === false).length
+  const parts = []
+  if (changed) parts.push(`${changed} changed`)
+  if (unchanged) parts.push(`${unchanged} unchanged`)
+  return parts.length ? parts.join(', ') : null
+}
+
+// Build the data-schema-read path for a registry name. `@scope/name` →
+// /dev/registry/data-schemas/{scope}/{name}; a bare name →
+// /dev/registry/data-schemas/{name}. The `@` sigil is not part of the path
+// segment. (Path segment encoding to confirm at live e2e.)
+export function modelPathFor(modelName) {
+  const m = /^@([^/]+)\/(.+)$/.exec(modelName)
+  if (m) return `/dev/registry/data-schemas/${encodeURIComponent(m[1])}/${encodeURIComponent(m[2])}`
+  return `/dev/registry/data-schemas/${encodeURIComponent(modelName)}`
+}
+
+// Resolve a Model NOT defined by the local foundation by fetching its declaration
+// (the `@uniweb/data-schema` form) from the backend's Model-read route. Cached per
+// run; HTTP 404 → null (the emitter then says "register it first"). The bearer is
+// acquired lazily via getToken, so a fully-local sync never authenticates.
+export function makeModelResolver({ apiBase, getToken, fetchImpl = fetch }) {
+  const cache = new Map()
+  return async (modelName) => {
+    if (cache.has(modelName)) return cache.get(modelName)
+    const url = `${apiBase}${modelPathFor(modelName)}`
+    const token = await getToken()
+    let res
+    try {
+      res = await fetchImpl(url, { headers: { Authorization: `Bearer ${token}` } })
+    } catch (err) {
+      throw new Error(`could not reach the Model-read endpoint ${url}: ${err.message}`)
+    }
+    if (res.status === 404) {
+      cache.set(modelName, null)
+      return null
+    }
+    if (!res.ok) {
+      throw new Error(`Model-read ${url} failed: HTTP ${res.status} ${res.statusText}`)
+    }
+    let decl
+    try {
+      decl = await res.json()
+    } catch (err) {
+      throw new Error(`Model-read ${url} returned non-JSON: ${err.message}`)
+    }
+    cache.set(modelName, decl)
+    return decl
+  }
+}
+
+// "Send only changed" cache: content hashes from the last successful sync, keyed
+// `<model> <id>`. Gitignored, per-clone, deletable (a deleted cache just means one
+// full re-sync, which the backend then no-ops). NOT identity — the minted `$uuid`
+// lives in the source files; this is a pure wire-efficiency cache.
+function syncCachePath(siteDir) {
+  return join(siteDir, '.uniweb', 'sync-cache.json')
+}
+function readSyncCache(siteDir) {
+  try {
+    const obj = JSON.parse(readFileSync(syncCachePath(siteDir), 'utf8'))
+    return obj && typeof obj.hashes === 'object' && obj.hashes ? obj.hashes : {}
+  } catch {
+    return {} // missing / unreadable → treat everything as changed
+  }
+}
+function writeSyncCache(siteDir, hashes) {
+  const p = syncCachePath(siteDir)
+  mkdirSync(dirname(p), { recursive: true })
+  writeFileSync(p, JSON.stringify({ version: 1, hashes }, null, 2) + '\n')
+}
+
+export async function push(args = []) {
+  const dryRun = args.includes('--dry-run')
+  const output = flagValue(args, '-o') || flagValue(args, '--output')
+  const tokenFlag = flagValue(args, '--token')
+  const asOrg = flagValue(args, '--as-org')
+  const foundationDir = flagValue(args, '--foundation')
+  const sendAll = args.includes('--all') // bypass the send-only-changed cache
+  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, 'push')
+
+  // Lazy bearer — acquired once, on first need (a non-local Model fetch during the
+  // build, or the submit). A fully-local sync never triggers it, so --dry-run / -o
+  // stay offline when every Model is defined by the local foundation.
+  let cachedToken = null
+  const getToken = async () => {
+    if (cachedToken) return cachedToken
+    cachedToken =
+      tokenFlag || process.env.UNIWEB_TOKEN || (await ensureRegistryAuth({ apiBase, command: 'Syncing', args }))
+    return cachedToken
+  }
+
+  // Build BOTH directional packages (the producer side). Each carries its own
+  // `index` — the per-entity source-file map for back-fill, correlated by submission
+  // position. Non-local Models are fetched from the registry on demand. `priorHashes`
+  // (the .uniweb push-cache) drives "send only changed" across both lanes; --all bypasses.
+  const priorHashes = readSyncCache(siteDir)
+  let pkg
+  try {
+    pkg = await emitSyncPackages(siteDir, {
+      ...(foundationDir ? { foundationDir } : {}),
+      resolveModel: makeModelResolver({ apiBase, getToken }),
+      priorHashes,
+      sendAll,
+    })
+  } catch (err) {
+    error(`Could not build the sync package: ${err.message}`)
+    return { exitCode: 2 }
+  }
+  const { siteContent, collections, siteContentUuid, warnings, hashes, skipped } = pkg
+  log('')
+  for (const w of warnings) note(`! ${w}`)
+
+  const totalEntities = (siteContent?.entityCount || 0) + (collections?.entityCount || 0)
+
+  // Nothing changed since the last push — the backend is already up to date.
+  if (totalEntities === 0) {
+    success(`Nothing to push — ${skipped} entit${skipped === 1 ? 'y' : 'ies'} unchanged since the last push.`)
+    return { exitCode: 0 }
+  }
+  if (siteContent) info(`${colors.bright}site-content${colors.reset} → ${siteContent.models.join(', ')}`)
+  if (collections) {
+    const n = collections.entityCount
+    info(`${colors.bright}collections${colors.reset} (${n} entit${n === 1 ? 'y' : 'ies'}) → ${collections.models.join(', ')}`)
+  }
+  if (skipped) note(`${skipped} unchanged, skipped`)
+
+  // Preview paths — no submit, no auth. Two lanes → up to two files / two routes.
+  if (output) {
+    const base = output.replace(/\.uwx$/, '')
+    if (siteContent) writeFileSync(resolve(`${base}.site-content.uwx`), siteContent.buffer)
+    if (collections) writeFileSync(resolve(`${base}.collections.uwx`), collections.buffer)
+    const lanes = [siteContent && 'site-content', collections && 'collections'].filter(Boolean)
+    success(`Wrote ${lanes.join(' + ')} .uwx — not submitted`)
+    return { exitCode: 0 }
+  }
+  if (dryRun) {
+    if (siteContent) {
+      const route = siteContentUuid ? `/dev/site/content/push/${siteContentUuid}` : '/dev/site/content'
+      const verb = siteContentUuid ? 'update' : 'create'
+      info(`Dry run — would ${verb} content at ${colors.dim}${apiBase}${route}${colors.reset}`)
+    }
+    if (collections) {
+      const key = siteContentUuid || '{new-site-uuid}'
+      info(`Dry run — would push the folder to ${colors.dim}${apiBase}/dev/site/folder/push/${key}${colors.reset}`)
+    }
+    return { exitCode: 0 }
+  }
+
+  const token = await getToken()
+  const wrote = []
+  let finalizedTotal = 0
+
+  // POST one lane's .uwx and parse the JSON response. Returns the parsed payload, or
+  // null on any transport/HTTP/parse failure (already reported). `collision=force`
+  // (last-push-wins) rides on every lane; `--as-org` rides as `as_org`. (Both the
+  // scope-param name — `as_org` vs the backend's `as_unit` — and whether `collision`
+  // stays required now that create/update are split are open backend items; preserved
+  // as-is until pinned at the first live run.)
+  const postLane = async (label, path, buffer) => {
+    const params = new URLSearchParams({ collision: 'force' })
+    if (asOrg) params.set('as_org', asOrg)
+    const url = `${apiBase}${path}?${params.toString()}`
+    info(`Pushing ${label} to ${colors.dim}${url}${colors.reset} …`)
+    let res
+    try {
+      res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/zip', Authorization: `Bearer ${token}` },
+        body: buffer,
+      })
+    } 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.ok) {
+      error(`${label} push rejected: HTTP ${res.status} ${res.statusText}`)
+      if (res.status === 401 || res.status === 403) {
+        note("Credentials weren't accepted — supply a bearer with --token <bearer> (or UNIWEB_TOKEN).")
+      }
+      const body = await res.text().catch(() => '')
+      if (body) note(body.slice(0, 800))
+      return null
+    }
+    try {
+      return await res.json()
+    } catch (err) {
+      error(`Could not parse the ${label} response as JSON: ${err.message}`)
+      return null
+    }
+  }
+
+  // POST a lane that round-trips entity uuids (content UPDATE + the folder): parse the
+  // finalized list (for record back-fill + the changed summary). Returns the finalized
+  // array, or null on failure (already reported).
+  const pushLane = async (label, path, buffer) => {
+    const payload = await postLane(label, path, buffer)
+    if (payload === null) return null
+    const finalized = extractFinalized(payload)
+    if (!finalized) {
+      error(`The ${label} response carried no recognizable finalized list (expected report.finalized[] with index + uuid).`)
+      note(JSON.stringify(payload).slice(0, 800))
+      return null
+    }
+    const summary = changedSummary(finalized)
+    if (summary) note(`${label}: ${summary}`)
+    return finalized
+  }
+
+  // Lane 1 — site-content (the site is born here; it must exist before its folder). A
+  // known site uuid → UPDATE by uuid; none → CREATE (the backend mints + adopts the
+  // site and returns its uuid, which we record into site.yml). `boundSiteUuid` carries
+  // the minted/known uuid forward to key the folder push.
+  let boundSiteUuid = siteContentUuid
+  if (siteContent) {
+    if (siteContentUuid) {
+      const finalized = await pushLane(
+        'site-content',
+        `/dev/site/content/push/${encodeURIComponent(siteContentUuid)}`,
+        siteContent.buffer
+      )
+      if (!finalized) return { exitCode: 1 }
+      finalizedTotal += finalized.length
+    } else {
+      const payload = await postLane('site-content', '/dev/site/content', siteContent.buffer)
+      if (payload === null) return { exitCode: 1 }
+      const minted = extractMintedSiteUuid(payload)
+      if (!minted) {
+        error('The create response carried no minted site-content uuid — cannot record the site identity or push its folder.')
+        note(JSON.stringify(payload).slice(0, 800))
+        return { exitCode: 1 }
+      }
+      writeSiteEntityUuid(siteDir, minted)
+      boundSiteUuid = minted
+      wrote.push('recorded site $uuid in site.yml')
+      finalizedTotal += extractFinalized(payload)?.length ?? 1
+    }
+  }
+
+  // Lane 2 — collections (the @uniweb/folder + the records it references), keyed by the
+  // site-content uuid. On a brand-new site the backend creates the folder on this first
+  // push. Records round-trip their own $uuid (back-filled into source files); the folder
+  // itself has no uuid (the backend owns it).
+  if (collections) {
+    if (!boundSiteUuid) {
+      error('Cannot push collections — the site has no uuid yet. Push the site-content lane first.')
+      return { exitCode: 1 }
+    }
+    const finalized = await pushLane(
+      'collections',
+      `/dev/site/folder/push/${encodeURIComponent(boundSiteUuid)}`,
+      collections.buffer
+    )
+    if (!finalized) return { exitCode: 1 }
+    const bf = backfillEntityUuids({ index: collections.index, finalized })
+    for (const w of bf.warnings) note(`! ${w}`)
+    for (const d of bf.deferred) note(`↷ ${d.id ?? `#${d.index}`}: ${d.reason}`)
+    if (bf.updated.length) wrote.push(`wrote ${bf.updated.length} record file(s)`)
+    finalizedTotal += finalized.length
+  }
+
+  // Persist the full content-hash map so the next push skips unchanged entities.
+  writeSyncCache(siteDir, hashes)
+  success(
+    `Pushed ${finalizedTotal} entit${finalizedTotal === 1 ? 'y' : 'ies'}` +
+      (wrote.length ? ` — ${wrote.join(', ')}` : '')
+  )
+  return { exitCode: 0 }
+}

package/src/commands/register.js

@@ -0,0 +1,274 @@
+/**
+ * uniweb register — submit a foundation (and the data schemas it renders), or a
+ * standalone schemas package (the data schemas alone, no foundation), to the
+ * registry as one names-only `.uwx` document (uwx-format.md §5).
+ *
+ * `uniweb login && uniweb register`. Distinct from `uniweb publish` (which
+ * targets the legacy unicloud / uniweb-edge platform) — `register` talks to the
+ * registry over HTTP at a configurable endpoint.
+ *
+ * Run from a foundation, or from a schemas-only package — a package that exports
+ * schemas (e.g. `@uniweb/schemas`, any `@org/schemas`) or a bare `schemas/*.yml`
+ * folder. The schemas-only package is auto-detected and submits its data schemas
+ * standalone (foundation-less); same flags, `--scope` names them.
+ *
+ * Usage:
+ *   uniweb register                      Build the .uwx and submit it
+ *   uniweb register --scope @org         Publish under @org (resolves @/x -> @org/x).
+ *                                        Default: the package's package.json "uniweb.scope".
+ *   uniweb register --dry-run            Print the .uwx; submit nothing
+ *   uniweb register -o foundation.uwx    Write the .uwx to a file; submit nothing
+ *   uniweb register --registry <url>     Override the submit endpoint
+ *   uniweb register --token <bearer>     Submit with this bearer; skips `uniweb login`
+ *
+ * Endpoint resolution: --registry <url>  >  UNIWEB_REGISTER_URL  >  the local default.
+ * Auth (submit only):  --token <bearer>  >  UNIWEB_TOKEN  >  `uniweb login` session.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { buildRegistryPackage, buildSchemaOnlyPackage } from '@uniweb/build/uwx'
+import { classifyPackage, isSchemasPackage, collectStandaloneSchemas } from '@uniweb/build'
+import { ensureRegistryAuth, readRegistryAuth } from '../utils/registry-auth.js'
+import { deriveScope } from '../utils/registry-orgs.js'
+import { writeJsonPreservingStyleAsync } from '../utils/json-file.js'
+import { findWorkspaceRoot, findFoundations, promptSelect } from '../utils/workspace.js'
+import { isNonInteractive, getCliPrefix } from '../utils/interactive.js'
+
+// The backend route is `/dev/registry/register`; the host defaults to a local
+// server and is overridable via --registry / UNIWEB_REGISTER_URL (full URL).
+const DEFAULT_REGISTER_URL = 'http://localhost:8080/dev/registry/register'
+
+const colors = {
+  reset: '\x1b[0m', bright: '\x1b[1m', dim: '\x1b[2m',
+  red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', 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}`)
+
+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
+}
+
+// The uniweb CLI version, for the `.uwx` exporter envelope. Safe fallback if the
+// package.json isn't reachable.
+function cliVersion() {
+  try {
+    return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version
+  } catch {
+    return '0.0.0'
+  }
+}
+
+// The foundation's recorded publish org, from its package.json `uniweb.scope`
+// (`{ "uniweb": { "scope": "@acme" } }`) — the default when `--scope` is absent.
+function readPkgScope(foundationDir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(foundationDir, 'package.json'), 'utf8'))
+    return pkg?.uniweb?.scope || null
+  } catch {
+    return null
+  }
+}
+
+// Record the chosen publish scope in the foundation's package.json so it travels
+// with the foundation (read back by readPkgScope on the next register). Preserves
+// the file's existing JSON style.
+async function writePkgScope(foundationDir, scope) {
+  const path = join(foundationDir, 'package.json')
+  const pkg = JSON.parse(readFileSync(path, 'utf8'))
+  pkg.uniweb = { ...(pkg.uniweb || {}), scope }
+  await writeJsonPreservingStyleAsync(path, pkg)
+}
+
+// The package's name from its package.json, for display. The standalone schemas
+// register has no foundation `_self` to name, so it labels by package name.
+function readPkgName(dir) {
+  try {
+    return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))?.name || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Resolve which foundation to register: the cwd if it's a foundation, else the
+ * single foundation in the workspace, else prompt (or error in non-interactive).
+ * Mirrors `uniweb publish`.
+ */
+async function resolveFoundationDir(args) {
+  const cwd = process.cwd()
+  if (classifyPackage(cwd) === 'foundation') return cwd
+
+  const workspaceRoot = findWorkspaceRoot(cwd)
+  if (workspaceRoot) {
+    const foundations = await findFoundations(workspaceRoot)
+    if (foundations.length === 1) return resolve(workspaceRoot, foundations[0])
+    if (foundations.length > 1) {
+      if (isNonInteractive(args)) {
+        error('Multiple foundations found. Run register from the one you mean.')
+        for (const f of foundations) log(`  ${colors.cyan || ''}cd ${f} && ${getCliPrefix()} register${colors.reset}`)
+        process.exit(1)
+      }
+      const choice = await promptSelect('Which foundation?', foundations)
+      if (!choice) { log('\nRegister cancelled.'); process.exit(0) }
+      return resolve(workspaceRoot, choice)
+    }
+  }
+
+  error('No foundation found. Run register from a foundation directory or a workspace that has one.')
+  process.exit(1)
+}
+
+export async function register(args = []) {
+  const dryRun = args.includes('--dry-run')
+  const output = flagValue(args, '-o') || flagValue(args, '--output')
+  const scopeFlag = flagValue(args, '--scope')
+  const tokenFlag = flagValue(args, '--token')
+  const registryUrl = flagValue(args, '--registry') || process.env.UNIWEB_REGISTER_URL || DEFAULT_REGISTER_URL
+
+  // Target: a schemas-only package (standalone data-schema register) or a
+  // foundation (foundation + the schemas it renders). A schemas package is only
+  // detected when the cwd isn't a foundation, so the foundation path — including
+  // its workspace-scan + prompt (resolveFoundationDir) — is unchanged.
+  const standalone = isSchemasPackage(process.cwd())
+  const targetDir = standalone ? process.cwd() : await resolveFoundationDir(args)
+
+  // Scope: --scope flag, else package.json `uniweb.scope`, else (real submit
+  // only) derived from login membership in the bootstrap below.
+  const pkgScope = readPkgScope(targetDir)
+  let scope = scopeFlag || pkgScope
+  let scopeSource = scopeFlag ? '--scope' : pkgScope ? 'package.json uniweb.scope' : null
+  const isPreview = !!output || dryRun
+  const apiBase = new URL(registryUrl).origin
+  let token = null
+
+  // Each path supplies a different schema source: the standalone path discovers
+  // the package's own schemas; the foundation path reads its built schema.json.
+  let schema = null
+  let schemas = null
+  if (standalone) {
+    try {
+      schemas = await collectStandaloneSchemas(targetDir)
+    } catch (err) {
+      error(`Could not read the schemas package: ${err.message}`)
+      return { exitCode: 2 }
+    }
+    if (!schemas || Object.keys(schemas).length === 0) {
+      error('No data schemas found in this package.')
+      log(`  ${colors.dim}Expected a package that exports schemas (getSchema / schemas), or a schemas/ directory of *.yml files.${colors.reset}`)
+      return { exitCode: 2 }
+    }
+  } else {
+    const schemaPath = join(targetDir, 'dist', 'meta', 'schema.json')
+    if (!existsSync(schemaPath)) {
+      error('No built schema found (dist/meta/schema.json).')
+      log(`  Build the foundation first: ${colors.bright}uniweb build${colors.reset}`)
+      return { exitCode: 2 }
+    }
+    try {
+      schema = JSON.parse(readFileSync(schemaPath, 'utf8'))
+    } catch (err) {
+      error(`Could not read ${schemaPath}: ${err.message}`)
+      return { exitCode: 2 }
+    }
+  }
+
+  // No scope for a real submit → derive it from login membership (list → 1 use /
+  // 0 create / N pick), persist to package.json, and reuse the session token.
+  if (!scope && !isPreview) {
+    token = tokenFlag || (await ensureRegistryAuth({ apiBase, command: 'Registering', args }))
+    const sess = await readRegistryAuth()
+    const derived = await deriveScope({ apiBase, token, accountHandle: sess?.handle || null, args })
+    if (!derived) return { exitCode: 0 }
+    scope = `@${derived}`
+    scopeSource = 'login'
+    try {
+      await writePkgScope(targetDir, scope)
+      info(`Saved ${colors.bright}${scope}${colors.reset} as this ${standalone ? 'package' : 'foundation'}'s publish scope (package.json).`)
+    } catch {
+      log(`  ${colors.dim}(Could not save the scope to package.json — pass --scope ${scope} next time.)${colors.reset}`)
+    }
+  }
+
+  const exporter = { tool: 'uniweb', version: cliVersion(), instance: 'build' }
+  let doc
+  try {
+    doc = standalone
+      ? buildSchemaOnlyPackage({ schemas, scope, exporter })
+      : buildRegistryPackage({ schema, foundationDir: targetDir, scope, exporter })
+  } catch (err) {
+    error(`Could not assemble the .uwx: ${err.message}`)
+    return { exitCode: 2 }
+  }
+  const json = JSON.stringify(doc, null, 2)
+
+  const defined = doc.entities.filter((e) => e.model === '@uniweb/data-schema').map((e) => e.name)
+  log('')
+  if (standalone) {
+    info(`${colors.bright}${readPkgName(targetDir) || 'schemas'}${colors.reset} ${colors.dim}(schemas-only — no foundation)${colors.reset}`)
+  } else {
+    info(`${colors.bright}${schema._self.name}@${schema._self.version}${colors.reset}`)
+  }
+  log(`  ${colors.dim}data schemas ${standalone ? 'registered' : 'defined'}: ${defined.length ? defined.join(', ') : '(none)'}${colors.reset}`)
+  if (scope) log(`  ${colors.dim}scope: ${scope} (${scopeSource})${colors.reset}`)
+
+  // Preview paths — no submit, no auth needed.
+  if (output) {
+    writeFileSync(resolve(output), json)
+    success(`Wrote ${output} (${doc.entities.length} entities) — not submitted`)
+    return { exitCode: 0 }
+  }
+  if (dryRun) {
+    log('')
+    log(json)
+    log('')
+    info(`Dry run — would submit to ${registryUrl}`)
+    return { exitCode: 0 }
+  }
+
+  // Submit requires a concrete scope — the registry rejects @/… fail-closed.
+  if (!scope) {
+    error('No publish scope — set "uniweb.scope" in package.json, or pass --scope @org.')
+    log(`  ${colors.dim}Without a scope, names stay @/… and the registry rejects them.${colors.reset}`)
+    return { exitCode: 2 }
+  }
+  // Submit auth: reuse the token from the scope bootstrap if it ran, else
+  // --token › UNIWEB_TOKEN › stored session › login (ensureRegistryAuth).
+  token = token || tokenFlag || (await ensureRegistryAuth({ apiBase, command: 'Registering', args }))
+  info(`Submitting to ${colors.dim}${registryUrl}${colors.reset} …`)
+  let res
+  try {
+    res = await fetch(registryUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: json,
+    })
+  } catch (err) {
+    error(`Could not reach the registry at ${registryUrl}: ${err.message}`)
+    log(`  ${colors.dim}Set the endpoint with --registry <url> or UNIWEB_REGISTER_URL.${colors.reset}`)
+    return { exitCode: 2 }
+  }
+  if (!res.ok) {
+    error(`Registry rejected the submission: HTTP ${res.status} ${res.statusText}`)
+    if (res.status === 401 || res.status === 403) {
+      log(`  ${colors.dim}The registry didn't accept your credentials — it may use different ones than \`uniweb login\`.${colors.reset}`)
+      log(`  ${colors.dim}Supply a registry bearer with --token <bearer> (or UNIWEB_TOKEN); an existing one may be wrong or expired.${colors.reset}`)
+    }
+    const body = await res.text().catch(() => '')
+    if (body) log(`  ${colors.dim}${body.slice(0, 500)}${colors.reset}`)
+    return { exitCode: 1 }
+  }
+  success(
+    standalone
+      ? `Registered ${defined.length} data schema(s)${scope ? ` under ${scope}` : ''}`
+      : `Registered ${schema._self.name}@${schema._self.version}${defined.length ? ` + ${defined.length} data schema(s)` : ''}`
+  )
+  return { exitCode: 0 }
+}