uniweb 1.0.0 → 1.0.2

package/src/commands/register.js

@@ -0,0 +1,1092 @@
+/**
+ * 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 ships a
+ * SITE — and releases the site's local foundation by running this command
+ * (`backend/foundation-bring-along.js`).
+ *
+ * If the foundation's `dist/` is missing or stale — no build, a version bump
+ * since it, a source file newer than it, no SSR bundle (`foundationNeedsBuild`)
+ * — `register` builds it first. Preview paths (`--dry-run`, `-o`) never write to
+ * `dist/`; they require a pre-built foundation.
+ *
+ * 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, submit it, then deliver
+ *                                        the foundation's dist/ code (plan +
+ *                                        upload — see utils/code-upload.js)
+ *   uniweb register --scope @org         A foundation whose name is bare: register it under
+ *                                        @org (resolves @/x -> @org/x) and write the scope
+ *                                        into its name in main.js. Refused when the name
+ *                                        already carries another scope — a foundation's
+ *                                        scope is the one in its name.
+ *                                        A schemas-only package: publish under @org.
+ *                                        Default: its package.json "uniweb.scope".
+ *   uniweb register --schema-only        Skip the code delivery (schemas land, no dist upload)
+ *   uniweb register --dry-run            Print the .uwx + the code file plan; submit nothing
+ *   uniweb register -o foundation.uwx    Write the .uwx to a file; submit nothing
+ *   uniweb register --json               Porcelain: ONE compact JSON line on stdout
+ *                                        ({ok,scope,origin,entities:[{name,uuid,version,unchanged}]}),
+ *                                        all human output to stderr — for scripted callers
+ *
+ * Endpoint: UNIWEB_SERVER  >  the backend you are logged in to  >  the default
+ *   (~/.uniweb/config.json, else uniweb.app) — resolveBackendOrigin. No backend flag:
+ *   switching is `uniweb login --server <url>`.
+ * Auth (submit only):  UNIWEB_TOKEN  >  the stored session  >  `uniweb login`.
+ */
+
+// DEFERRED foundation-registration capabilities (the legacy `uniweb publish` had
+// these; the new backend doesn't yet — captured here so the design intent isn't
+// lost, and the legacy code could be removed). Implement as `register` flags (or
+// backend-side policy) when the need is real:
+//
+//   • ACCESS POLICY — legacy `--edit-access open|restricted`. On the old registry
+//     this gated who could act on the foundation. Its meaning is
+//     unclear for the new model: there is no editing of a foundation's code or
+//     schema, so it is most likely a LICENSING / access-control concern (who may
+//     use/reference the foundation), not "editing". Revisit as `--access` (or an
+//     org/licensing policy on the backend) when foundation licensing lands.
+//
+//   • VERSION PROPAGATION — legacy `--propagate`. Opts a newly-registered version
+//     into the registry's version-update walk: trusting sites whose policy allows
+//     the jump (e.g. auto-patch) adopt it with no rebuild; default was "silent"
+//     (stored, nothing moves). Implement once the backend has a
+//     version-update/propagation policy; until then every register is silent.
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  statSync
+} from 'node:fs'
+import { execSync } from 'node:child_process'
+import { resolve, join, relative } from 'node:path'
+import prompts from 'prompts'
+import { buildRegistryPackage, buildSchemaOnlyPackage } from '@uniweb/build/uwx'
+import {
+  classifyPackage,
+  isSchemasPackage,
+  collectStandaloneSchemas,
+  readFoundationName,
+  checkFoundationName,
+  splitFoundationName
+} from '@uniweb/build'
+import {
+  suggestFoundationName,
+  writeFoundationName
+} from '../utils/foundation-name.js'
+import { readRegistryAuth } from '../utils/registry-auth.js'
+import {
+  collectDistFiles,
+  computeFoundationDigest,
+  readRuntimePin
+} from '../utils/code-upload.js'
+import { deriveScope, publishScope, belongsToScope } from '../utils/registry-orgs.js'
+import { BackendClient } from '../backend/client.js'
+import { resolveWorkspace, scopeOfWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
+import { writeJsonPreservingStyleAsync } from '../utils/json-file.js'
+import {
+  findWorkspaceRoot,
+  findFoundations,
+  promptSelect
+} from '../utils/workspace.js'
+import { isNonInteractive, getCliPrefix } from '../utils/interactive.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'
+}
+// Porcelain (`--json`) mode: stdout carries ONLY the final compact JSON line, so
+// all human/colored output diverts to stderr. `emitJson` writes to the REAL
+// stdout (bypassing the redirect). `jsonMode`/`jsonEmitted`/`lastError` are reset
+// per run by the exported `register` wrapper.
+let jsonMode = false
+let jsonEmitted = false
+let lastError = null
+const log = (...a) => (jsonMode ? console.error(...a) : console.log(...a))
+const success = (m) => log(`${colors.green}✓${colors.reset} ${m}`)
+const error = (m) => {
+  lastError = String(m)
+  console.error(`${colors.red}✗${colors.reset} ${m}`)
+}
+const info = (m) => log(`${colors.blue}→${colors.reset} ${m}`)
+const emitJson = (obj) => {
+  jsonEmitted = true
+  process.stdout.write(JSON.stringify(obj) + '\n')
+}
+
+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'
+  }
+}
+
+// A SCHEMAS-ONLY package's recorded publish org, from its package.json `uniweb.scope`
+// (`{ "uniweb": { "scope": "@acme" } }`) — the default when `--scope` is absent. It
+// has no main.js whose name could carry it. ⛔ A foundation's scope is part of its name
+// (2026-09-22); its `uniweb.scope` is refused by `readFoundationName`.
+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 a schemas-only package's package.json so it
+// travels with the package (read back by readPkgScope on the next register). Preserves
+// the file's existing JSON style. A foundation's goes into its name instead
+// (`settleFoundationScope`).
+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)
+}
+
+/**
+ * The foundation's name, settled before anything is built or sent.
+ *
+ * A foundation registers as `@org/<name>`, and sites pin it by that name. The name
+ * is `main.js`'s `name`, else package.json's — `readFoundationName`, the rule the
+ * build reads for the schema this command submits. ⛔ `src` and `foundation` are
+ * the folder the code sits in, not the code: a project scaffolded before the name
+ * moved to main.js has package name `src`, and every such project in an org would
+ * register the same `@org/src`. So a name that cannot register is ASKED FOR here,
+ * once, and kept in main.js — or, with nobody to ask, refused with the line to add.
+ * Before the build, so a written name is built into the schema like any edit.
+ *
+ * @param {string} targetDir
+ * @param {{ args: string[], isPreview: boolean }} o
+ * @returns {Promise<boolean>} false → stop; the reason is printed
+ */
+export async function settleFoundationName(targetDir, { args, isPreview }) {
+  let read
+  try {
+    read = await readFoundationName(targetDir)
+  } catch (err) {
+    error(err.message)
+    return false
+  }
+  const problem = checkFoundationName(read.name)
+  if (!problem) return true
+
+  const where = relative(process.cwd(), read.mainFile) || read.mainFile
+  const suggestion = suggestFoundationName(targetDir)
+  const reason = `${problem[0].toUpperCase()}${problem.slice(1)}.`
+
+  // Nobody to ask — a script, a preview (which writes nothing), or --json (whose
+  // stdout is a data channel a prompt would corrupt). Name the fix exactly.
+  if (isPreview || jsonMode || isNonInteractive(args)) {
+    error(`This foundation has no name it can register under. ${reason}`)
+    log(`  Name it in ${colors.bright}${where}${colors.reset}, in the default export:`)
+    log(`    ${colors.bright}name: '${suggestion || '<name>'}',${colors.reset}`)
+    log(`  ${colors.dim}It registers as @<org>/<name>, and sites pin that name.${colors.reset}`)
+    return false
+  }
+
+  info(`This foundation needs a name to register under. ${reason}`)
+  const { name } = await prompts(
+    {
+      type: 'text',
+      name: 'name',
+      message: 'Foundation name (it registers as @<org>/<name>):',
+      initial: suggestion || '',
+      validate: (v) => checkFoundationName(String(v).trim()) || true
+    },
+    {
+      onCancel: () => {
+        log('\nRegister cancelled.')
+        process.exit(0)
+      }
+    }
+  )
+  const chosen = String(name || '').trim()
+  if (!chosen) return false
+
+  const written = writeFoundationName(read.mainFile, chosen, {
+    replace: read.source === 'main.js' ? read.name : null
+  })
+  if (!written.ok) {
+    error(`Could not write the name: ${written.reason}.`)
+    log(`  Add it to the default export in ${colors.bright}${where}${colors.reset}:  name: '${chosen}',`)
+    return false
+  }
+  // Read it back through the build's own rule — the text edit is only a means.
+  const again = await readFoundationName(targetDir).catch(() => null)
+  if (again?.name !== chosen) {
+    error(`${where} now names the foundation '${chosen}', but it still reads as "${again?.name}".`)
+    return false
+  }
+  success(`Named the foundation ${colors.bright}${chosen}${colors.reset} — kept in ${where}.`)
+  return true
+}
+
+/**
+ * Settle the scope a foundation registers under — the one in its name.
+ *
+ * ⭐ THE SCOPE IS PART OF THE NAME (2026-09-22): `name: '@acme/marketing'` in main.js.
+ * A scoped name decides it, and a `--scope` naming another org is refused — which org
+ * was meant is not ours to guess, and today's alternative was a split identity (the
+ * foundation under one org, its data schemas under the other). A bare name has not
+ * registered yet: it takes `--scope`, else one derived from your orgs, and the chosen
+ * scope is WRITTEN INTO THE NAME, so it is chosen once and travels with the code.
+ * ⛔ Until then it was written to `package.json::uniweb.scope`, which is refused now
+ * (`readFoundationName`, naming the line to write).
+ *
+ * A preview (`--dry-run`, `-o`) writes nothing: a bare name previews under `--scope`,
+ * or unscoped.
+ *
+ * @returns {Promise<{ scope: string|null, source: string|null } | null>}
+ *   null when refused, the reason printed — no scope chosen included, since a name with
+ *   no scope cannot register. ⛔ Until 2026-10-06 "no scope chosen" was `cancelled`, and
+ *   register exited 0 having registered nothing.
+ */
+export async function settleFoundationScope(targetDir, { args, isPreview, flagScope, client }) {
+  let read
+  try {
+    read = await readFoundationName(targetDir)
+  } catch (err) {
+    error(err.message)
+    return null
+  }
+  const where = relative(process.cwd(), read.mainFile) || read.mainFile
+  const { scope: nameScope, bare } = splitFoundationName(read.name)
+
+  if (nameScope) {
+    if (flagScope && flagScope !== nameScope) {
+      error(
+        `${where} names this foundation ${read.name}, so it registers under ${nameScope} — ` +
+          `--scope ${flagScope} names another org.`
+      )
+      log(
+        `  ${colors.dim}To register it under ${flagScope}, change its name in ${where}: ` +
+          `name: '${flagScope}/${bare}'${colors.reset}`
+      )
+      return null
+    }
+    return { scope: nameScope, source: 'main.js' }
+  }
+
+  if (isPreview) return { scope: flagScope, source: flagScope ? '--scope' : null }
+
+  let scope = flagScope
+  let source = flagScope ? '--scope' : null
+  if (!scope) {
+    scope = await deriveScopeFromLogin(client, args)
+    if (!scope) return null
+    source = 'login'
+  }
+
+  const scoped = `${scope}/${bare}`
+  const written = writeFoundationName(read.mainFile, scoped, {
+    replace: read.source === 'main.js' ? read.name : null
+  })
+  if (!written.ok) {
+    error(`Could not write the scope into the foundation's name: ${written.reason}.`)
+    log(`  Name it in the default export in ${colors.bright}${where}${colors.reset}:  name: '${scoped}',`)
+    return null
+  }
+  // Read it back through the build's own rule — the text edit is only a means.
+  const again = await readFoundationName(targetDir).catch(() => null)
+  if (again?.name !== scoped) {
+    error(`${where} now names the foundation '${scoped}', but it still reads as "${again?.name}".`)
+    return null
+  }
+  success(`This foundation registers as ${colors.bright}${scoped}${colors.reset} — kept in ${where}.`)
+  return { scope, source }
+}
+
+/**
+ * The scope a bare name registers under when `--scope` names none — as `@handle`, or null
+ * when none was chosen.
+ *
+ * ⭐ THE WORKSPACE THIS COMMAND WORKS IN *[Diego, 2026-10-06]* — an organization's handle,
+ * or your own for your personal workspace — said, not asked (`scopeOfWorkspace`). A team
+ * working in `@acme` registers `@acme/…`, which any of its members can release.
+ * ⛔ Until 2026-10-06 the default was your personal scope wherever you worked, so a team's
+ * foundation registered as `@jane/…` — releasable by Jane alone, and fixed only by
+ * renaming it into a new foundation.
+ *
+ * When the workspace names no scope — none is chosen, or it is a unit without a handle —
+ * the scope is derived from your orgs as before (`deriveScope`): your personal scope when
+ * you belong to none, else a pick at a terminal, your personal scope without one.
+ */
+async function deriveScopeFromLogin(client, args) {
+  const token = await client.token()
+  const ws = await resolveWorkspace({ client, args })
+  const personal = !ws.refused && ws.source !== 'offline' && ws.workspace === null
+  const accountHandle = personal ? (await client.fetchOrgs()).account_handle : null
+  const fromWorkspace = scopeOfWorkspace(ws, accountHandle)
+  if (fromWorkspace) {
+    const named = `${colors.bright}${fromWorkspace}${colors.reset}`
+    console.error(
+      personal
+        ? `Registering under your personal scope ${named} — you work in your personal workspace (${SOURCE_LABEL[ws.source]}). For an org: --scope @org.`
+        : `Registering under ${named} — the workspace you work in (${SOURCE_LABEL[ws.source]}). For another scope: --scope @org.`
+    )
+    return fromWorkspace
+  }
+  const sess = await readRegistryAuth(client.origin)
+  const derived = await deriveScope({
+    apiBase: client.origin,
+    token,
+    accountHandle: sess?.handle || null,
+    args
+  })
+  return derived ? `@${derived}` : null
+}
+
+// Directories that are never foundation source. `dist` is the output we compare
+// against; the rest are tooling. Dotted entries are skipped wholesale.
+const NON_SOURCE_DIRS = new Set(['dist', 'node_modules'])
+
+/**
+ * The newest mtime under `dir`, skipping build output and tooling. `0` when the
+ * tree is unreadable — which reads as "no source is newer", i.e. it degrades to
+ * the pre-existing behaviour rather than forcing a build on an fs error.
+ *
+ * @param {string} dir
+ * @returns {number} epoch ms
+ */
+function newestSourceMtime(dir) {
+  let newest = 0
+  const walk = (d) => {
+    let entries
+    try {
+      entries = readdirSync(d, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.') || NON_SOURCE_DIRS.has(e.name)) continue
+      const p = join(d, e.name)
+      if (e.isDirectory()) {
+        walk(p)
+        continue
+      }
+      try {
+        const m = statSync(p).mtimeMs
+        if (m > newest) newest = m
+      } catch {
+        /* unreadable file — ignore */
+      }
+    }
+  }
+  walk(dir)
+  return newest
+}
+
+/**
+ * Does the foundation's `dist/` need a (re)build before we can register it?
+ *
+ * Three staleness signals:
+ *   - MISSING: no `dist/entry.js` (or the legacy `dist/foundation.js`), or no
+ *     `dist/meta/schema.json` — nothing built yet.
+ *   - STALE VERSION: the version baked into `dist/meta/schema.json::_self.version`
+ *     differs from `package.json::version` — a version bump without a rebuild,
+ *     so the artifact encodes the OLD version while the register intends the
+ *     NEW one (we'd otherwise submit a schema whose version disagrees with the
+ *     code we deliver).
+ *   - STALE SOURCE: a source file is newer than `dist/entry.js`.
+ *
+ * ⛔ **The source signal was missing until 2026-08-16, and its absence shipped the
+ * PREVIOUS bundle silently.** Edit a component's rendered output, re-run
+ * `register` with a `dist/` present, and the version signal says fresh (nothing
+ * bumped), the artifact signal says fresh (files exist) — so the old bytes upload
+ * and the content digest legitimately does not move. The developer's freshness
+ * indicator reports "unchanged" and it is telling the truth about an input that
+ * never changed. Found by end-to-end testing against a live backend, which is
+ * the only place the two halves meet: a unit test on this predicate agrees with
+ * it, and the digest agrees with the bytes.
+ *
+ * ⚠️ **This header used to claim it "mirrors `uniweb publish`'s build-if-stale".
+ * It does not, and that sentence is why nobody looked.** `publish` does not do
+ * build-if-stale at all — `backend/foundation-bring-along.js` builds
+ * UNCONDITIONALLY before digesting, precisely so the digest reflects current
+ * source. So publish was already correct and register was not, while a docblock
+ * asserted they matched.
+ *
+ * ⛔ **And do NOT "fix" this by building unconditionally to match publish.**
+ * `publish` builds and then shells out to THIS command
+ * (`foundation-bring-along.js` → `execFileSync(cliBin, ['register', …])`), so an
+ * unconditional build here makes every publish build twice. The mtime signal is
+ * what keeps both paths right: publish's fresh `dist/` is newer than its source,
+ * so this correctly skips.
+ *
+ * Returns `{ needs: false }` or `{ needs: true, reason }`.
+ *
+ * @param {string} targetDir  the foundation directory
+ */
+export function foundationNeedsBuild(targetDir) {
+  const distDir = join(targetDir, 'dist')
+  const schemaPath = join(distDir, 'meta', 'schema.json')
+  // @uniweb/build emits dist/entry.js; older builds emitted dist/foundation.js.
+  const hasArtifact =
+    existsSync(join(distDir, 'entry.js')) ||
+    existsSync(join(distDir, 'foundation.js'))
+  if (!hasArtifact || !existsSync(schemaPath))
+    return { needs: true, reason: 'no dist/ found' }
+  // The SSR bundle is required by any host that server-renders, and a dist can
+  // lack one for two reasons that both reach here looking complete: it was left
+  // by a `uniweb dev` session (which skips that sub-build), or it was built by
+  // a toolchain older than @uniweb/build@0.14.25, which did not emit it at all.
+  // Shipping either produces a site that renders client-side at HTTP 200 with
+  // nothing reporting why, so treat it as stale and rebuild.
+  if (!existsSync(join(distDir, 'entry-ssr.js')))
+    return { needs: true, reason: 'dist/ has no entry-ssr.js (SSR bundle)' }
+  let pkgVersion = null
+  try {
+    pkgVersion =
+      JSON.parse(readFileSync(join(targetDir, 'package.json'), 'utf8'))
+        ?.version || null
+  } catch {
+    // No readable package.json version — fall through; a present schema with no
+    // version to compare is treated as fresh (the submit path validates names).
+  }
+  try {
+    const peek = JSON.parse(readFileSync(schemaPath, 'utf8'))
+    if (
+      peek?._self?.version &&
+      pkgVersion &&
+      peek._self.version !== pkgVersion
+    ) {
+      return {
+        needs: true,
+        reason: `package.json version (${pkgVersion}) differs from built schema (${peek._self.version})`
+      }
+    }
+  } catch {
+    return { needs: true, reason: 'dist/meta/schema.json could not be parsed' }
+  }
+  // STALE SOURCE — the signal whose absence shipped the previous bundle. Compared
+  // against the built entry rather than the schema: the schema is emitted by a
+  // later plugin hook, so it is always the newer of the two and using it would
+  // widen the window in which an edit reads as already-built.
+  //
+  // Ties count as fresh (`>`, not `>=`). A build writes its output after reading
+  // its input, so equal mtimes mean a same-millisecond build, not a missed edit —
+  // and on a fresh clone, where whole trees share a timestamp, `>=` would rebuild
+  // every foundation once for nothing.
+  try {
+    const entryPath = existsSync(join(distDir, 'entry.js'))
+      ? join(distDir, 'entry.js')
+      : join(distDir, 'foundation.js')
+    const builtAt = statSync(entryPath).mtimeMs
+    if (newestSourceMtime(targetDir) > builtAt)
+      return { needs: true, reason: 'a source file is newer than dist/entry.js' }
+  } catch {
+    // Can't compare — leave the other signals to decide rather than forcing a
+    // build on an fs error.
+  }
+  return { needs: false }
+}
+
+export async function register(args = []) {
+  // 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('register', args)
+  if (badFlag) {
+    error(badFlag.message)
+    return { exitCode: 2 }
+  }
+  jsonMode = args.includes('--json')
+  jsonEmitted = false
+  lastError = null
+  const result = await runRegister(args)
+  // Guarantee a porcelain line on stdout for every --json exit: the success path
+  // emits its own; here we cover the error / early-return paths so a scripted
+  // caller can always JSON.parse(stdout).
+  if (jsonMode && !jsonEmitted) {
+    emitJson(
+      result?.exitCode === 0
+        ? { ok: true, entities: [] }
+        : {
+            ok: false,
+            error:
+              lastError || `register failed (exit ${result?.exitCode ?? 1})`
+          }
+    )
+  }
+  return result
+}
+
+async function runRegister(args = []) {
+  const dryRun = args.includes('--dry-run')
+  const output = flagValue(args, '-o') || flagValue(args, '--output')
+  const scopeFlag = flagValue(args, '--scope')
+  // The backend you are logged in to (UNIWEB_SERVER overrides it for a script) —
+  // resolveBackendOrigin, like every backend command.
+  const client = new BackendClient({
+    args,
+    command: 'Registering'
+  })
+
+  // 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. ⭐ A FOUNDATION's is the one in its name (`name: '@acme/marketing'` in
+  // main.js), settled below before the build; a bare name takes --scope, else the
+  // workspace the command works in (`deriveScopeFromLogin`), and register writes it
+  // into the name (2026-09-22). A SCHEMAS-ONLY package has no name to carry one:
+  // --scope, else package.json `uniweb.scope`, else (real submit only) the workspace
+  // the command works in. Either spelling, `@acme` or `acme`, and from here on the one
+  // form: `@acme` (publishScope). ⛔ This said "derived from your orgs" / "from login
+  // membership" until 2026-10-06, read as the personal-scope default that was replaced.
+  const pkgScope = standalone ? readPkgScope(targetDir) : null
+  const givenScope = scopeFlag || pkgScope
+  let scope = publishScope(givenScope)
+  let scopeSource = scopeFlag
+    ? '--scope'
+    : pkgScope
+      ? 'package.json uniweb.scope'
+      : null
+  // A scope that was GIVEN but names no org (`--scope @`) is refused, never read as
+  // absent: absent derives one from the login, which would register under an org the
+  // caller did not name.
+  if (givenScope && !scope) {
+    error(`Not an org scope: ${givenScope} (from ${scopeSource})`)
+    log(`  ${colors.dim}Pass --scope @org.${colors.reset}`)
+    return { exitCode: 2 }
+  }
+  const isPreview = !!output || dryRun
+
+  // 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 {
+    if (!(await settleFoundationName(targetDir, { args, isPreview }))) {
+      return { exitCode: 2 }
+    }
+    // ⭐ BEFORE THE BUILD, so the build embeds the name the foundation registers as.
+    // Settled after it, a scope written into main.js would leave dist/ describing the
+    // bare name — stale the moment it was built.
+    const settled = await settleFoundationScope(targetDir, {
+      args,
+      isPreview,
+      flagScope: scope,
+      client
+    })
+    if (!settled) return { exitCode: 2 }
+    scope = settled.scope
+    scopeSource = settled.source
+    // Build-if-stale (`foundationNeedsBuild`): a missing or stale dist/ gets
+    // (re)built before we read its schema. Preview paths
+    // (--dry-run / -o) must not write to dist/, so they require a pre-built
+    // foundation and say so instead of building.
+    const { needs, reason } = foundationNeedsBuild(targetDir)
+    if (needs) {
+      if (isPreview) {
+        error(`No usable build (${reason}).`)
+        log(
+          `  Build the foundation first: ${colors.bright}uniweb build${colors.reset}`
+        )
+        return { exitCode: 2 }
+      }
+      info(`${reason} — building the foundation first …`)
+      try {
+        execSync('npx uniweb build --target foundation', {
+          cwd: targetDir,
+          // ⛔ `inherit` wires the DELEGATE's stdout to ours, so under --json the
+          // builder's progress lands on stdout ahead of the JSON line and
+          // `JSON.parse(stdout)` throws — on exactly the cold path a fresh
+          // checkout always takes. register's own output is already redirected to
+          // stderr (see `log` above); this child is the one stream it did not own,
+          // so --json was porcelain only when a build was NOT needed.
+          //
+          // fd 2 is our stderr: progress stays visible, stdout stays parseable.
+          // Found by a harness that had to work around it by taking the last
+          // JSON line off stdout.
+          stdio: jsonMode ? ['inherit', 2, 'inherit'] : 'inherit',
+          // A step of register: the build's "Share with clients: uniweb register" hint
+          // would tell someone running register to run register.
+          env: { ...process.env, UNIWEB_BUILD_STEP: '1' }
+        })
+      } catch (err) {
+        error(`Build failed: ${err.message}`)
+        return { exitCode: 2 }
+      }
+    }
+    const schemaPath = join(targetDir, 'dist', 'meta', 'schema.json')
+    if (!existsSync(schemaPath)) {
+      error('No built schema found (dist/meta/schema.json) after build.')
+      log(`  Build the foundation: ${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 }
+    }
+  }
+
+  // A schemas-only package with no scope, on a real submit → the workspace you work in,
+  // else derived from your orgs (`deriveScopeFromLogin`), and persisted to package.json.
+  // (A foundation's was settled before its build — `settleFoundationScope`.)
+  if (standalone && !scope && !isPreview) {
+    const derived = await deriveScopeFromLogin(client, args)
+    if (!derived) return { exitCode: 2 }
+    scope = derived
+    scopeSource = 'login'
+    try {
+      await writePkgScope(targetDir, scope)
+      info(
+        `Saved ${colors.bright}${scope}${colors.reset} as this package's publish scope (package.json).`
+      )
+    } catch {
+      log(
+        `  ${colors.dim}(Could not save the scope to package.json — pass --scope ${scope} next time.)${colors.reset}`
+      )
+    }
+  }
+
+  // Content digest (foundation path only) — the freshness fingerprint over what
+  // register ships (shipping-model.md §4.1). Rides in the foundation-schema
+  // entity's info.digest; the backend stores it opaque and returns it so
+  // publish/status can detect "code changed since release" with no local state.
+  const digest = standalone
+    ? null
+    : computeFoundationDigest(join(targetDir, 'dist'))
+
+  // Compatibility floor (foundation path only) — the @uniweb/runtime version
+  // this build linked against. Rides in info.runtime beside info.digest.
+  //
+  // Until this shipped, `dist/runtime-pin.json` was written by the build and
+  // read by NOTHING, so a floor a foundation stated could never reach anyone
+  // able to act on it. It cannot be acted on here either: a site's floor is
+  // max() over its primary foundation AND its extensions, and this command
+  // publishes one foundation without sight of the others. So the producer
+  // states its own floor and whoever resolves a whole site does the arithmetic.
+  const runtime = standalone ? null : readRuntimePin(join(targetDir, 'dist'))
+
+  const exporter = { tool: 'uniweb', version: cliVersion(), instance: 'build' }
+  let doc
+  try {
+    doc = standalone
+      ? buildSchemaOnlyPackage({ schemas, scope, exporter })
+      : buildRegistryPackage({
+          schema,
+          foundationDir: targetDir,
+          scope,
+          exporter,
+          digest,
+          runtime
+        })
+  } 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}`)
+  if (digest) log(`  ${colors.dim}digest: ${digest}${colors.reset}`)
+  if (runtime) log(`  ${colors.dim}runtime floor: ${runtime}${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 ${client.origin}`)
+    if (!standalone && !args.includes('--schema-only')) {
+      const distFiles = collectDistFiles(join(targetDir, 'dist'))
+      log('')
+      info(
+        `Would then deliver ${distFiles.length} code file(s) (meta/ excluded):`
+      )
+      for (const f of distFiles) {
+        log(
+          `  ${colors.dim}${f.path}  ${f.size} bytes  ${f.content_type}${colors.reset}`
+        )
+      }
+    }
+    return { exitCode: 0 }
+  }
+
+  // Submit requires a concrete scope — the registry rejects @/… fail-closed.
+  if (!scope) {
+    error(
+      standalone
+        ? 'No publish scope — set "uniweb.scope" in package.json, or pass --scope @org.'
+        : "No publish scope — name the foundation '@org/<name>' in main.js, or pass --scope @org."
+    )
+    log(
+      `  ${colors.dim}Without a scope, names stay @/… and the registry rejects them.${colors.reset}`
+    )
+    return { exitCode: 2 }
+  }
+  // Submit — the client carries the bearer (UNIWEB_TOKEN › stored
+  // session › login), resolved lazily on this first authed call.
+  info(`Submitting to ${colors.dim}${client.origin}${colors.reset} …`)
+  let res
+  try {
+    res = await client.register(json)
+  } catch (err) {
+    error(`Could not reach the registry at ${client.origin}: ${err.message}`)
+    log(
+      `  ${colors.dim}Is that the backend you meant? Switch with: uniweb login --server <url>${colors.reset}`
+    )
+    return { exitCode: 2 }
+  }
+  // Read the response body once: the --json success path needs it for the minted
+  // entity ids; the error path shows it.
+  const rawBody = await res.text().catch(() => '')
+  let parsedBody = null
+  try {
+    parsedBody = rawBody ? JSON.parse(rawBody) : null
+  } catch {
+    parsedBody = null
+  }
+  let alreadyRegistered = false
+  if (!res.ok) {
+    // Resume path: a registered version is immutable, so re-running after a
+    // partial code delivery hits the duplicate rejection here — a STRUCTURED
+    // 409 (problem+json, title "Conflict", naming the `version` it refused) — and
+    // proceeds to phase 2 (the code-uploads plan authorizes against the REGISTERED
+    // version; files it already stores come back `present` and are skipped).
+    //
+    // ⛔ ONE STATUS, MORE THAN ONE MEANING. A 409 that names no version is another
+    // refusal — a data schema changed where the backend holds records of it
+    // (`reason: "destructive_republish"`) — and until 2026-09-26 it was read as a
+    // resume too: "already registered — resuming code delivery", then a 404 for a
+    // version that was never registered, and the refusal's own sentence never shown.
+    // A body with no shape to read resumes, as it always did.
+    const isDuplicate =
+      !standalone && res.status === 409 && (!parsedBody || typeof parsedBody !== 'object' || parsedBody.version !== undefined)
+    if (isDuplicate) {
+      alreadyRegistered = true
+      info(
+        `${colors.dim}Schema for this version is already registered — resuming code delivery.${colors.reset}`
+      )
+    } else {
+      // ⭐ NOT A MEMBER OF THE SCOPE IS SAID AS THAT *[Diego, 2026-10-06]*. The registry
+      // decides who may release into a scope — its account, or an org's members — and
+      // when the orgs read says you are neither, that is the refusal to name. ⛔ Until then
+      // a 403 here printed "log in again", the wrong advice for a scope that is not yours.
+      // Read to explain a refusal, never to gate one; a 401 is the credential itself.
+      const member =
+        res.status === 401 ? null : belongsToScope(scope, await client.fetchOrgs().catch(() => null))
+      if (member === false) {
+        const what = standalone
+          ? `data schemas under ${scope}`
+          : doc.entities.find((e) => e.model === '@uniweb/foundation-schema')?.info?.name || `a foundation under ${scope}`
+        error(`You can't release ${what}: you're not a member of ${scope}.`)
+        log(
+          `  ${colors.dim}A member of ${scope} can release it. (The registry answered HTTP ${res.status}.)${colors.reset}`
+        )
+      } else {
+        error(
+          `Registry rejected the submission: HTTP ${res.status} ${res.statusText}`
+        )
+      }
+      if (member !== false && (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}Log in again (uniweb login --server <url>), or check UNIWEB_TOKEN — an existing one may be wrong or expired.${colors.reset}`
+        )
+      }
+      // ⭐ **Surface `detail` as a sentence, not as a JSON dump.** The registry
+      // answers with problem+json (RFC 9457), and its `detail` is written for a
+      // human — it carries the actual next step, which for a rejected
+      // re-register is "bump the version". Printing the whole body dimmed put
+      // that sentence inside a blob, at the end of a 500-char truncation, in the
+      // one moment the reader most needs it.
+      //
+      // ⚖️ Keyed on the SHAPE, not on any particular code: a new refusal the CLI
+      // has never seen explains itself the day the backend ships it, with no
+      // release here. That is the property worth having — this branch exists
+      // because a 422 the CLI did not know about arrived exactly that way.
+      if (parsedBody?.detail) {
+        log(`  ${parsedBody.detail}`)
+        const code = parsedBody.code ?? parsedBody.reason
+        if (code) {
+          log(`  ${colors.dim}(${code})${colors.reset}`)
+        }
+      } else if (rawBody) {
+        log(`  ${colors.dim}${rawBody.slice(0, 500)}${colors.reset}`)
+      }
+      return { exitCode: 1 }
+    }
+  }
+  // The foundation's name as the registry holds it (`@org/name`) — read from the
+  // document just submitted, never composed again. See phase 2.
+  const registeredName = standalone
+    ? null
+    : doc.entities.find((e) => e.model === '@uniweb/foundation-schema')?.info
+        ?.name
+  if (!alreadyRegistered) {
+    success(
+      standalone
+        ? `Registered ${defined.length} data schema(s)${scope ? ` under ${scope}` : ''}`
+        : `Registered ${registeredName}@${schema._self.version}${defined.length ? ` + ${defined.length} data schema(s)` : ''}`
+    )
+  }
+
+  // Phase 2 — deliver the foundation's code (plan → PUT-per-file, entry
+  // last; contract: foundation-code-upload.md). Schemas-
+  // only packages have no dist; --schema-only skips deliberately.
+  if (!standalone && !args.includes('--schema-only')) {
+    const distDir = join(targetDir, 'dist')
+    // ⭐ The plan authorizes against the REGISTERED (name, version), so the name here
+    // is the one phase 1 registered — the `.uwx`'s own `info.name`, where a scoped
+    // package name passes through and a bare one gets the scope. ⛔ Not composed a
+    // second time: this line composed it from the raw scope until 2026-09-21, so
+    // `--scope std` registered `@std/src` and then asked to deliver `std/src`, which
+    // the registry refuses. One name, read from the one place it was decided.
+    const name = registeredName
+    const version = schema._self.version
+    info(
+      `Delivering code for ${colors.bright}${name}@${version}${colors.reset} …`
+    )
+    try {
+      const result = await client.uploadFoundationCode({
+        name,
+        version,
+        distDir,
+        onProgress: (m) => log(`  ${colors.dim}${m}${colors.reset}`)
+      })
+      if (result.failed.length) {
+        error(`${result.failed.length} file(s) failed to upload:`)
+        for (const f of result.failed) {
+          log(
+            `  ${colors.red}${f.path}${colors.reset} ${colors.dim}HTTP ${f.status} ${f.detail}${colors.reset}`
+          )
+        }
+        log(
+          `  ${colors.dim}Re-run \`uniweb register\` to resume — files already stored are skipped.${colors.reset}`
+        )
+        return { exitCode: 1 }
+      }
+      // "4 files" on a first upload; "1 uploaded, 3 already stored" on a resume.
+      const delivered = result.stored?.length
+        ? `${result.uploaded.length} uploaded, ${result.stored.length} already stored`
+        : `${result.uploaded.length} files`
+      if (result.verified === true) {
+        // serveBase is guaranteed here — it is what gated the check.
+        success(
+          `Code delivered (${delivered}) — entry verified live at ${colors.dim}${result.serveBase}${colors.reset}`
+        )
+      } else if (result.verified === false) {
+        error(
+          'Code uploaded but the entry verification fetch did not match — investigate before using this version.'
+        )
+        return { exitCode: 1 }
+      } else {
+        success(`Code delivered (${delivered}, ${result.mode} mode)`)
+        // Say WHY nothing was checked, rather than skipping in silence. The CLI
+        // never reconstructs a serve URL (see utils/code-upload.js), so a plan
+        // without `serve_base` means the location is not ours to know — name it
+        // as a backend gap so it surfaces there instead of looking like a pass.
+        if (!result.serveBase) {
+          log(
+            `  ${colors.dim}Not verified: the backend reported no serve location for this version.${colors.reset}`
+          )
+        }
+      }
+    } catch (err) {
+      // ⚖️ A 4xx is the registry REFUSING the plan — e.g. a stored file
+      // declared at a different size (`version_content_changed`). Running the
+      // same command again gets the same answer, so do not suggest it: print
+      // the refusal's own sentence, which says what does help.
+      if (err.status >= 400 && err.status < 500 && err.detail) {
+        error(`Code delivery refused: HTTP ${err.status}`)
+        log(`  ${err.detail}`)
+        if (err.code) log(`  ${colors.dim}(${err.code})${colors.reset}`)
+        return { exitCode: 1 }
+      }
+      error(`Code delivery failed: ${err.message}`)
+      log(
+        `  ${colors.dim}The schema registration above succeeded; re-run \`uniweb register\` to deliver the code.${colors.reset}`
+      )
+      return { exitCode: 1 }
+    }
+  }
+  // Registering ≠ delivering the file. A registered schema is a content type
+  // authors use in the app; a FOUNDATION build still resolves '@scope/name' from
+  // disk (a package or a routed folder). This is the moment that belief forms —
+  // you just registered it — so correct it here, not in a doc nobody's reading.
+  if (!jsonMode && defined.length > 0 && scope) {
+    log('')
+    info(
+      'Registered schemas are content types authors can use in the Uniweb app.'
+    )
+    log(
+      `  ${colors.dim}Delivery is separate: a foundation that binds ${scope}/<name> resolves it from${colors.reset}`
+    )
+    log(
+      `  ${colors.dim}disk — an ${scope}/schemas package, or a folder routed in schemas.config.js.${colors.reset}`
+    )
+  }
+
+  if (jsonMode) {
+    // Join my authoritative submitted names with the backend's minted ids. Each
+    // response entry is `{ registered: { name, version, payload_model_uuid, … },
+    // unchanged }` (symmetric on the new-version + unchanged branches); a flat
+    // shape is tolerated as a fallback. Names from doc.entities are the spine, so
+    // the porcelain always reports WHICH names landed even if a field is absent.
+    const minted = {}
+    const addMint = (e) => {
+      if (!e || typeof e !== 'object') return
+      const reg = e.registered ?? e
+      if (reg.name)
+        minted[reg.name] = {
+          uuid: reg.payload_model_uuid ?? null,
+          version: reg.version ?? null,
+          unchanged: e.unchanged === true
+        }
+    }
+    if (parsedBody && typeof parsedBody === 'object') {
+      if (Array.isArray(parsedBody.data_schemas))
+        parsedBody.data_schemas.forEach(addMint)
+      if (parsedBody.foundation_schema) addMint(parsedBody.foundation_schema)
+    }
+    const names = [
+      ...doc.entities
+        .filter((e) => e.model === '@uniweb/data-schema')
+        .map((e) => e.name),
+      // The foundation-schema entity carries its `@scope/name` under `info`, not a
+      // top-level `name` (that's the foundation-schema shape).
+      ...doc.entities
+        .filter((e) => e.model === '@uniweb/foundation-schema')
+        .map((e) => e.info?.name ?? e.name)
+    ].filter(Boolean)
+    const entities = names.map((name) => ({
+      name,
+      ...(minted[name] || { uuid: null, version: null, unchanged: false })
+    }))
+    emitJson({
+      ok: true,
+      scope: scope || null,
+      origin: client.origin,
+      digest: digest || null,
+      entities
+    })
+  }
+  return { exitCode: 0 }
+}