uniweb 0.12.35 → 0.12.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.35",
+  "version": "0.12.37",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -48,7 +48,7 @@
   "peerDependencies": {
     "@uniweb/content-reader": "1.1.12",
     "@uniweb/semantic-parser": "1.1.17",
-    "@uniweb/build": "0.14.18"
+    "@uniweb/build": "0.14.20"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -142,11 +142,13 @@ pnpm install                      # Install dependencies
 pnpm build                        # Build for production
 pnpm preview                      # Preview production build (SSG + SPA)
 
-# Ship a site to Uniweb hosting (or a static host)
-uniweb deploy                     # Build + push + publish in one shot (default; needs `uniweb login`)
-uniweb deploy --host=<adapter>    # Deploy to a static host instead: cloudflare-pages, netlify,
+# Ship a site to Uniweb hosting (needs `uniweb login`)
+uniweb publish                    # The smart path: bring the foundation along (releasing it to the
+                                  # catalog if its code changed), sync content, and go live
+
+# Ship a site to a third-party host instead
+uniweb deploy --host=<adapter>    # Deploy to a static host: cloudflare-pages, netlify,
                                   # vercel, github-pages, s3-cloudfront, generic-static
-uniweb deploy --dry-run           # Resolve foundation/runtime + print summary; no writes
 uniweb export                     # Build dist/ for any static host (no Uniweb account)
 
 # Sync a site with the Uniweb backend (git-style; needs `uniweb login`)
@@ -154,8 +156,6 @@ uniweb push                       # Push local content to the backend (creates t
 uniweb pull                       # Pull backend content back to local files
 uniweb clone <site-uuid>          # Start a new local project from a site already in the backend
 uniweb status                     # Show what's unpushed / out of sync (local, offline)
-uniweb publish                    # Make the synced site's current backend state live —
-                                  # does NOT push; run `uniweb push` first, or just `uniweb deploy`
 
 # Register a foundation + its data schemas to the Uniweb registry
 uniweb register                   # Register this foundation + the data schemas it defines
@@ -172,7 +172,7 @@ uniweb --help                     # Top-level help
 uniweb <command> --help           # Per-command help (no side effects)
 ```
 
-`uniweb deploy` auto-registers a workspace-local foundation as part of the deploy under a site-scoped slot — no separate `uniweb register` step needed for site-bound foundations.
+`uniweb publish` brings the site's local foundation along — releasing it to the catalog under your `@org` when its code changed — so a single site needs no separate `uniweb register` step.
 
 **Registering data schemas.** A foundation that defines data schemas (`@/article`, …) uses `uniweb register` to register the foundation together with those schemas in the Uniweb registry — so content authors can create and manage entities of those types. It requires authentication: run `uniweb login`, or supply a bearer token directly with `--token <bearer>` (or the `UNIWEB_TOKEN` env var). Point at a specific registry with `--registry <url>` (or `UNIWEB_REGISTER_URL`). Preview without auth using `--dry-run` (or `-o <file>` to write the submission), and set the org scope with `--scope @org` (default: the foundation's `package.json` `uniweb.scope`).
 
@@ -203,14 +203,14 @@ The `uniweb` block in `package.json` carries platform-specific configuration tha
 
 | Field | Where used | Default | Purpose |
 |---|---|---|---|
-| `id` | `uniweb register` | (the bare segment of a scoped `package.json::name`, or `uniweb.id`) | The foundation's registered id — the bare-name segment in `@org/<id>`. Decoupled from `package.json::name` (a workspace concern), so renaming the foundation on the registry doesn't ripple through site dependencies. Only relevant for catalog-registered foundations; site-bound foundations skip this. |
+| `id` | `uniweb register` | (the bare segment of a scoped `package.json::name`, or `uniweb.id`) | The foundation's registered id — the bare-name segment in `@org/<id>`. Decoupled from `package.json::name` (a workspace concern), so renaming the foundation on the registry doesn't ripple through site dependencies. |
 | `namespace` | `uniweb register` | (none — see scope resolution) | Legacy explicit org-namespace override. Equivalent to using a scoped `package.json::name` (`"@myorg/foundation"`). Rarely needed in modern foundations. |
 | `runtimePolicy` | `dist/runtime-pin.json` (foundation build) | `"auto-minor"` | Controls how sites using this foundation receive runtime updates. Three values: `"exact"`, `"auto-patch"`, `"auto-minor"`. See "Foundation runtime policy" below. |
 
-**Catalog vs site-bound foundations.** Two distribution intents share the same `dist/foundation.js` artifact:
+**How a foundation reaches the catalog.** Foundations on Uniweb hosting always live in the catalog as `@org/name@version`. Two ways to get one there, both from the same `dist/foundation.js` artifact:
 
-- A **catalog foundation** is a deliberate product — named, versioned, listed in the catalog, consumable by other developers' sites. Use `uniweb register --scope @org` for these — cataloging is a deliberate, explicitly-scoped step, so you don't accidentally catalog a foundation that was meant to be site-bound.
-- A **site-bound foundation** powers exactly one site. Don't run `uniweb register` for it. Just run `uniweb deploy` from the site directory — the CLI auto-registers your local foundation as part of the deploy, **uploaded with the site's other assets** (per-site storage, never to the catalog). With no naming ceremony, no catalog visibility, and no developer-vs-site ownership confusion. To later promote the foundation to a catalog product, run `uniweb register --scope @org` from the foundation directory and update the site's `site.yml` to a versioned ref (`foundation: '@org/name@1.2.3'`).
+- **Brought along by `uniweb publish`.** When a foundation powers a single site, don't run `uniweb register` yourself. Run `uniweb publish` from the site directory — it releases the site's local foundation to the catalog under your `@org` (when its code changed) and then goes live, in one step. No separate register ceremony.
+- **Registered deliberately with `uniweb register --scope @org`.** When the foundation is a product meant for multiple sites — listed in the catalog, consumable by other developers' sites — register it on its own schedule. Consuming sites then pin a versioned ref (`foundation: '@org/name@1.2.3'`).
 
 **On the split between `package.json::name` and `uniweb.id`:** the workspace name is what pnpm uses for `file:` linking and what `site.yml::foundation` references. The published id is what the registry stores. Keeping them separate means a workspace rename (e.g. `marketing` → `marketing-pro`) is a one-shot `uniweb rename foundation marketing marketing-pro` — it updates the package, folder, and every dependent site, while the foundation's registered id (`uniweb.id`) stays independent.
 

package/src/backend/client.js

@@ -28,28 +28,34 @@
  */
 
 import { getRegistryApiBaseUrl } from '../utils/config.js'
-import { ensureRegistryAuth, fetchMe } from '../utils/registry-auth.js'
+import { ensureRegistryAuth, fetchMe, readRegistryAuth, isExpired } from '../utils/registry-auth.js'
 import { fetchOrgs as fetchOrgsImpl, createOrg as createOrgImpl } from '../utils/registry-orgs.js'
 import { uploadFoundationCode } from '../utils/code-upload.js'
 import { uploadSiteAssets } from '../utils/asset-upload.js'
 import { uploadRuntime } from '../utils/runtime-upload.js'
 
 /**
- * Resolve the backend origin: an explicit flag value wins; otherwise defer to
- * the shared origin resolver (env override > saved config > local default). A
- * full URL is reduced to its origin, so callers may pass a whole endpoint URL.
+ * Resolve the backend origin via the resolution ladder (highest precedence
+ * first). A full URL is reduced to its origin, so callers may pass a whole
+ * endpoint URL; an unparseable value falls through to the next tier.
  *
- * One resolver, one place to revisit when we settle the single-origin-input +
- * discovery-handshake decision — kept delegating for now so this stays a pure,
- * behavior-preserving consolidation.
+ *   1. `flag` — the raw --backend / --registry value (this command)
+ *   2. UNIWEB_REGISTER_URL env — session-wide override (CI / local dev)
+ *   3. `siteBackend` — the site's bound backend from deploy.yml (site verbs)
+ *   4–6. the logged-in session origin > ~/.uniweb/config.json > the default
+ *        (uniweb.app) — all via getRegistryApiBaseUrl()
  *
  * @param {string} [flag] - the raw value of --backend / --registry, if supplied
+ * @param {object} [opts]
+ * @param {string} [opts.siteBackend] - a site's deploy.yml-bound backend origin
  * @returns {string} a bare origin with no trailing slash
  */
-export function resolveBackendOrigin(flag) {
-  if (flag) {
-    try { return new URL(flag).origin } catch { /* not a URL — fall through */ }
-  }
+export function resolveBackendOrigin(flag, { siteBackend } = {}) {
+  const norm = (v) => { try { return new URL(v).origin } catch { return null } }
+  if (flag) { const o = norm(flag); if (o) return o }
+  const env = process.env.UNIWEB_REGISTER_URL
+  if (env) { const o = norm(env); if (o) return o }
+  if (siteBackend) { const o = norm(siteBackend); if (o) return o }
   return getRegistryApiBaseUrl()
 }
 
@@ -74,6 +80,7 @@ export class BackendClient {
    * @param {object} [opts]
    * @param {string} [opts.origin] - explicit origin (wins over originFlag/env)
    * @param {string} [opts.originFlag] - raw --backend/--registry value to resolve
+   * @param {string} [opts.siteBackend] - a site's deploy.yml-bound backend (site verbs)
    * @param {string} [opts.token] - explicit bearer (wins over env + stored session)
    * @param {() => Promise<string>} [opts.getToken] - injected bearer resolver (tests, or
    *        callers with their own auth); used when no explicit token/env is present
@@ -81,8 +88,8 @@ export class BackendClient {
    * @param {string} [opts.command] - label for the login prompt ('Pushing', 'Registering', …)
    * @param {typeof fetch} [opts.fetchImpl] - injectable fetch (tests)
    */
-  constructor({ origin, originFlag, token, getToken, args = [], command = 'This command', fetchImpl } = {}) {
-    this.origin = (origin || resolveBackendOrigin(originFlag)).replace(/\/+$/, '')
+  constructor({ origin, originFlag, siteBackend, token, getToken, args = [], command = 'This command', fetchImpl } = {}) {
+    this.origin = (origin || resolveBackendOrigin(originFlag, { siteBackend })).replace(/\/+$/, '')
     this._token = token || process.env.UNIWEB_TOKEN || null
     this._getToken = getToken || null
     this._args = args
@@ -103,6 +110,19 @@ export class BackendClient {
       this._token = await this._getToken()
       return this._token
     }
+    // Origin-mismatch guard: a usable session authed against a DIFFERENT origin
+    // than this command targets means the bearer will be rejected — warn once
+    // and point at the fix (the stored token IS for `stored.origin`, not here).
+    if (!this._warnedOriginMismatch) {
+      this._warnedOriginMismatch = true
+      try {
+        const stored = await readRegistryAuth()
+        if (stored?.token && !isExpired(stored) && stored.origin &&
+            stored.origin.replace(/\/+$/, '') !== this.origin) {
+          console.error(`\x1b[33m⚠\x1b[0m Logged in to ${stored.origin}, but this command targets ${this.origin} — the session may be rejected. Run \`uniweb login --backend ${this.origin}\`, or pass --token.`)
+        }
+      } catch { /* advisory only */ }
+    }
     this._token = await ensureRegistryAuth({ apiBase: this.origin, command: this._command, args: this._args })
     return this._token
   }
@@ -208,19 +228,29 @@ export class BackendClient {
   }
 
   /**
-   * ASSUMED endpoint (not built yet — kb/framework/plans/shipping-verbs-and-freshness.md §6.5).
-   * GET /dev/registry/foundation/{scope}/{name} → { latest_version } for a foundation's
-   * latest registered version, or null on 404 / any failure (callers degrade gracefully).
-   * A bare/unscoped name → null (only `@org/name` can be looked up).
+   * GET /dev/registry/{scope}/{name} → the latest registered foundation version
+   * + its content digest, or null on 404 / any failure (callers degrade).
+   *
+   * The bare `{scope}/{name}` path resolves the latest foundation version (the
+   * data-schema sibling is `/dev/registry/data-schemas/{scope}/{name}`). The
+   * backend returns `version` (+ schema ids); we normalize it to `latest_version`
+   * for callers and tolerate either key. `digest` is the framework-computed
+   * fingerprint the backend stores OPAQUE and echoes here (null when the version
+   * carries none) — the freshness signal for publish/status (shipping-model.md
+   * §4.1). A bare/unscoped name → null (only `@org/name` can be looked up).
    * @param {string} scopedName
-   * @returns {Promise<{ latest_version: string }|null>}
+   * @returns {Promise<{ latest_version: string|null, digest: string|null }|null>}
    */
   async readFoundationLatest(scopedName) {
     const m = /^@([^/]+)\/([^@/]+)/.exec(String(scopedName || ''))
     if (!m) return null
     try {
-      const res = await this.request(`/dev/registry/foundation/${encodeURIComponent(m[1])}/${encodeURIComponent(m[2])}`)
-      return res.ok ? await res.json().catch(() => null) : null
+      const res = await this.request(`/dev/registry/${encodeURIComponent(m[1])}/${encodeURIComponent(m[2])}`)
+      if (!res.ok) return null
+      const body = await res.json().catch(() => null)
+      if (!body) return null
+      // The read returns `version`; callers use `latest_version`. Tolerate both.
+      return { ...body, latest_version: body.latest_version ?? body.version ?? null }
     } catch {
       return null
     }
@@ -331,16 +361,40 @@ export class BackendClient {
   }
 
   /**
-   * ASSUMED endpoint (not built yet — kb/framework/plans/shipping-verbs-and-freshness.md §6.5).
-   * GET /dev/site/{uuid}/status → the site's publish lifecycle:
+   * GET /dev/site/status/{uuid} → the site's publish lifecycle (Contract 3,
+   * shipped backend-side — collab backend-framework-b220):
    *   { published: boolean, last_pushed_at?: string, last_published_at?: string, draft_dirty?: boolean }
-   * `draft_dirty` = the synced draft differs from what's currently live. null on 404 / any failure.
+   * `draft_dirty` = never-published, or the synced draft changed since the last
+   * publish ("pushed but not published"). The path is VERB-FIRST (`status/{uuid}`)
+   * to match the lane (`publish/{uuid}`, `content/push/{uuid}`, `folder/pull/{uuid}`),
+   * not the `{uuid}/status` the shipping-verbs §8 sketch assumed. null on
+   * 404 (unknown/not-yours) / 401 / any failure — `status --remote` degrades to local.
    * @param {string} uuid - the site-content uuid
    * @returns {Promise<object|null>}
    */
   async siteStatus(uuid) {
     try {
-      const res = await this.request(`/dev/site/${encodeURIComponent(uuid)}/status`)
+      const res = await this.request(`/dev/site/status/${encodeURIComponent(uuid)}`)
+      return res.ok ? await res.json().catch(() => null) : null
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * ASSUMED endpoint (not built yet — kb/framework/build/payment-handoff-plan.md).
+   * GET /dev/site/{uuid}/can-go-live — the pre-go-live payment gate:
+   *   { ok: true }                                          // already paid → proceed
+   *   { payment_required: true, checkout_url, wait_token? } // open the URL, settle, retry
+   * The framework is provider-agnostic: it only opens `checkout_url` and waits.
+   * null on 404 / any failure → the caller PROCEEDS (degrade: publish ships
+   * before payment lands; same posture as siteStatus on a missing route).
+   * @param {string} uuid - the site-content uuid
+   * @returns {Promise<object|null>}
+   */
+  async canGoLive(uuid) {
+    try {
+      const res = await this.request(`/dev/site/${encodeURIComponent(uuid)}/can-go-live`)
       return res.ok ? await res.json().catch(() => null) : null
     } catch {
       return null

package/src/backend/foundation-bring-along.js

@@ -0,0 +1,229 @@
+/**
+ * Bring-the-foundation-along — the freshness loop `uniweb publish` runs before
+ * it makes a site live (shipping-model.md §4).
+ *
+ * A publish must never ship a site pointing at stale or missing foundation code
+ * (the footgun: a site goes live referencing a version the catalog doesn't
+ * have). So when the site references a LOCAL foundation, publish fingerprints it
+ * and reconciles with the catalog. Three cases (§4):
+ *
+ *   | version not yet registered    | release it, then publish        |
+ *   | registered, code unchanged    | skip the release (digest match) |
+ *   | registered, code CHANGED      | warn / prompt — never silent    |
+ *
+ * The freshness signal is the backend-stored, framework-computed digest (§4.1):
+ * no local state, multi-machine-safe. When the site references a published
+ * registry ref or a URL there's nothing to bring along. When the backend
+ * doesn't expose the stored digest yet, the compare DEGRADES to "ask" (same
+ * posture as `status --remote` on a 404).
+ *
+ * "Release" here is literally `uniweb register` run in the foundation directory
+ * — same build-if-stale → schema submit → code upload → digest the standalone
+ * verb does, so there is exactly one foundation-release path.
+ */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+import { detectFoundationType } from '@uniweb/build'
+import { computeFoundationDigest } from '../utils/code-upload.js'
+import { readFlagValue } from '../utils/args.js'
+import { isNonInteractive } from '../utils/interactive.js'
+
+/**
+ * Resolve the site's LOCAL foundation — the one publish should bring along — or
+ * null when the site references a published registry ref / URL (the catalog
+ * already has it; nothing to do). Uses the SAME resolver the build uses
+ * (`detectFoundationType`), so "which foundation" never drifts between them.
+ *
+ * @param {string} siteDir
+ * @param {object} siteYml - parsed site.yml
+ * @returns {{ dir: string, scopedName: string|null, version: string|null }|null}
+ */
+export function resolveLocalFoundation(siteDir, siteYml) {
+  const decl = siteYml?.foundation
+  if (!decl) return null
+  let info
+  try {
+    info = detectFoundationType(decl, siteDir)
+  } catch {
+    // Unresolved declaration — the site build will surface the canonical
+    // error; bring-along simply has nothing local to act on.
+    return null
+  }
+  if (!info || info.type !== 'local' || !info.path) return null
+  return {
+    dir: info.path,
+    scopedName: foundationScopedName(info.path),
+    version: readPkgField(info.path, 'version'),
+  }
+}
+
+// The foundation's scoped catalog name (`@org/name`) from its package.json — an
+// already-scoped `name`, else `uniweb.scope` + a bare `name`. Null when neither
+// yields a scoped name (then we can't look up the registered version, so the
+// caller treats the foundation as "release it and let register pick the scope").
+function foundationScopedName(dir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+    const name = pkg?.name
+    if (typeof name === 'string' && name.startsWith('@')) return name
+    const scope = pkg?.uniweb?.scope
+    if (scope && name) return `${String(scope).replace(/\/+$/, '')}/${name}`
+    return null
+  } catch {
+    return null
+  }
+}
+
+function readPkgField(dir, field) {
+  try {
+    return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))?.[field] || null
+  } catch {
+    return null
+  }
+}
+
+// Forward the origin + auth flags so the spawned `uniweb register` / `build`
+// hits the SAME backend with the SAME session as the publish that called it.
+function forwardedFlags(args) {
+  const out = []
+  for (const name of ['--backend', '--registry', '--token']) {
+    const v = readFlagValue(args, name)
+    if (v) out.push(name, v)
+  }
+  if (isNonInteractive(args)) out.push('--non-interactive')
+  return out
+}
+
+/**
+ * Decide + (maybe) act on the site's local foundation before go-live.
+ *
+ * @param {object} o
+ * @param {import('./client.js').BackendClient} o.client
+ * @param {string} o.siteDir
+ * @param {object} o.siteYml
+ * @param {string[]} o.args
+ * @param {object} o.say - { ok, info, warn, err, dim } reporters
+ * @param {(q: string, def?: boolean) => Promise<boolean>} o.confirm
+ * @param {string} o.cliBin - the CLI entry (process.argv[1]) to re-spawn
+ * @param {boolean} [o.dryRun]
+ * @returns {Promise<{ released: boolean, proceed: boolean, ref: string|null }>}
+ *   proceed:false → the caller should abort the publish (user declined). `ref`
+ *   is the pinned `@scope/name@version` to stamp on the pushed site — read AFTER
+ *   any release, so it reflects the released version + the scope register
+ *   derived. Delivery is version-pinned end-to-end (the gateway serves a
+ *   foundation only by a concrete version, no latest-resolution at serve time —
+ *   collab framework-backend-5c3e), so an unversioned local ref MUST be pinned
+ *   on the wire or the live site points at code the gateway can't serve. null
+ *   when the site already references a registry ref / URL (no override needed)
+ *   or no scoped ref can be formed.
+ */
+export async function bringFoundationAlong({ client, siteDir, siteYml, args, say, confirm, cliBin, dryRun = false }) {
+  const local = resolveLocalFoundation(siteDir, siteYml)
+  if (!local) {
+    // Published registry ref / URL — the catalog (or the URL host) already
+    // serves the code, and site.yml already pins the version. Nothing to bring
+    // along, and no ref override (forward the site.yml ref verbatim).
+    return { released: false, proceed: true, ref: null }
+  }
+
+  const label = local.scopedName || local.version ? `${local.scopedName || 'foundation'}${local.version ? `@${local.version}` : ''}` : 'the local foundation'
+  const skipPrompts = args.includes('--yes') || args.includes('--force') || args.includes('--no-verify')
+
+  // The pinned ref to stamp on the pushed site — read at RETURN time (after any
+  // release), so it reflects the released version + the scope register derived.
+  // null when no scoped ref can be formed (then the site.yml ref is forwarded).
+  const pinnedRef = () => {
+    const s = foundationScopedName(local.dir)
+    const v = readPkgField(local.dir, 'version')
+    return s && v ? `${s}@${v}` : null
+  }
+
+  // Dry-run reports the intent WITHOUT touching the network — it must not force
+  // a login (the digest read is auth-gated). The real run does the compare.
+  if (dryRun) {
+    say.dim(`Foundation  : ${label} — local; would release if changed or not yet registered`)
+    return { released: false, proceed: true, ref: null }
+  }
+
+  // Ask the catalog what it has. Null → not registered (or the backend can't
+  // answer / no scoped name to look up) → release.
+  const reg = local.scopedName ? await client.readFoundationLatest(local.scopedName) : null
+
+  if (!reg) {
+    say.info(`Releasing the foundation ${label} (not yet registered)…`)
+    return { released: releaseFoundation(local, args, cliBin, say), proceed: true, ref: pinnedRef() }
+  }
+
+  // Registered — fingerprint the local build and compare. Build first so the
+  // digest reflects current source (idempotent: a no-op when already fresh).
+  buildFoundation(local, cliBin)
+  const localDigest = computeFoundationDigest(join(local.dir, 'dist'))
+
+  if (reg.digest && localDigest && reg.digest === localDigest) {
+    say.dim(`Foundation  : ${label} — unchanged since release (digest matches); nothing to release.`)
+    return { released: false, proceed: true, ref: pinnedRef() }
+  }
+
+  // A different version locally → a new version to release.
+  if (local.version && local.version !== reg.latest_version) {
+    say.info(`Releasing the foundation ${label} (new version; registered latest is ${reg.latest_version})…`)
+    return { released: releaseFoundation(local, args, cliBin, say), proceed: true, ref: pinnedRef() }
+  }
+
+  // Same version, but the digest differs or the backend can't confirm it.
+  if (!reg.digest) {
+    // Degrade: the backend doesn't return the stored digest yet, so we can't
+    // be sure the registered version matches local. Offer to re-deliver.
+    say.warn(`Can't verify the registered ${label} matches your local copy (backend returned no digest).`)
+    if (skipPrompts || isNonInteractive(args)) {
+      say.dim('Proceeding without re-releasing — pass nothing to re-deliver, or bump the version to publish a change.')
+      return { released: false, proceed: true, ref: pinnedRef() }
+    }
+    const reRelease = await confirm(`Re-release ${label} to be sure its code is current?`, false)
+    if (reRelease) return { released: releaseFoundation(local, args, cliBin, say), proceed: true, ref: pinnedRef() }
+    return { released: false, proceed: true, ref: pinnedRef() }
+  }
+
+  // Case 3 (§4): the foundation was edited but the version wasn't bumped. The
+  // registered version is immutable, so we never silently ship the old code —
+  // the deliberate release gate is a version bump (§3.1).
+  say.warn(`Your local ${label} differs from the registered version ${reg.latest_version}, but the version wasn't bumped.`)
+  say.dim('A registered version is immutable. Bump the foundation\'s version to release the change, then re-run `uniweb publish`.')
+  if (skipPrompts || isNonInteractive(args)) {
+    say.dim(`Proceeding with the already-registered ${reg.latest_version}.`)
+    return { released: false, proceed: true, ref: pinnedRef() }
+  }
+  const proceed = await confirm(`Publish with the already-registered ${reg.latest_version} anyway?`, false)
+  if (!proceed) {
+    say.info('Aborted — bump the foundation version, then re-run `uniweb publish`.')
+    return { released: false, proceed: false, ref: null }
+  }
+  return { released: false, proceed: true, ref: pinnedRef() }
+}
+
+// Build the foundation so its dist/ can be fingerprinted. Idempotent — the
+// foundation build no-ops when already fresh.
+function buildFoundation(local, cliBin) {
+  execFileSync('node', [cliBin, 'build', '--target', 'foundation'], {
+    cwd: local.dir,
+    stdio: 'inherit',
+    env: process.env,
+  })
+}
+
+// Release = `uniweb register` in the foundation directory (the one foundation
+// release path). Returns true on success; throws to the caller on failure so
+// publish stops before going live with missing code.
+function releaseFoundation(local, args, cliBin, say) {
+  console.log('')
+  execFileSync('node', [cliBin, 'register', ...forwardedFlags(args)], {
+    cwd: local.dir,
+    stdio: 'inherit',
+    env: process.env,
+  })
+  console.log('')
+  return true
+}

package/src/backend/payment-handoff.js

@@ -0,0 +1,105 @@
+/**
+ * Payment handoff — the one piece of `uniweb publish` that's three-way
+ * (framework + backend + the `uniweb.app` web app). Design: payment-handoff-plan.md.
+ *
+ * The intent: `uniweb publish` on an unpaid (or newly-charged) site should just
+ * handle it — open a browser to `uniweb.app`, let the user pay, and continue.
+ * An already-paid site never opens a browser.
+ *
+ * The framework's ENTIRE payment knowledge is "open this URL, wait for done" —
+ * PROVIDER-AGNOSTIC. The CLI opens whatever `checkout_url` the backend hands it;
+ * the app drives the provider (Stripe or anything else) and settles with the
+ * backend. We reuse `awaitBrowserCallback` (the same loopback `uniweb login`
+ * uses) for the open + wait.
+ *
+ * DEGRADES: when the backend exposes no can-go-live route (404 / any failure),
+ * `canGoLive` returns null and we PROCEED — so publish ships before the payment
+ * route lands (same posture as `status --remote` on a missing endpoint). Live
+ * acceptance is the three-way test.
+ */
+
+import { randomBytes } from 'node:crypto'
+
+import { awaitBrowserCallback } from '../utils/registry-auth.js'
+import { isNonInteractive } from '../utils/interactive.js'
+
+// Append query params to a backend-supplied URL without disturbing its own.
+function withParams(url, params) {
+  const u = new URL(url)
+  for (const [k, v] of Object.entries(params)) {
+    if (v != null) u.searchParams.set(k, String(v))
+  }
+  return u.toString()
+}
+
+/**
+ * Settle payment for a site before go-live, if the backend says it's needed.
+ *
+ * @param {object} o
+ * @param {import('./client.js').BackendClient} o.client
+ * @param {string|null} o.uuid - the site-content uuid (null before the first push mints it)
+ * @param {string[]} o.args
+ * @param {object} o.say - { ok, info, warn, err, dim } reporters
+ * @param {boolean} [o.dryRun]
+ * @returns {Promise<{ proceed: boolean }>} proceed:false → the caller aborts go-live.
+ */
+export async function settlePaymentIfNeeded({ client, uuid, args, say, dryRun = false }) {
+  // No uuid yet (a first publish mints it on push) → nothing to check here; the
+  // post-push go-live is the moment the backend gates on payment.
+  if (!uuid) return { proceed: true }
+
+  // Dry-run reports the intent WITHOUT touching the network — the can-go-live
+  // read is auth-gated and must not force a login on a dry-run.
+  if (dryRun) {
+    say.dim(`Payment     : would check whether go-live needs payment for ${uuid}`)
+    return { proceed: true }
+  }
+
+  const verdict = await client.canGoLive(uuid)
+  // Degrade (no route) or already-paid → proceed.
+  if (!verdict || verdict.ok || !verdict.payment_required) return { proceed: true }
+
+  const checkoutUrl = verdict.checkout_url
+  if (!checkoutUrl) {
+    say.warn('The backend reports payment is required but returned no checkout URL — proceeding.')
+    return { proceed: true }
+  }
+
+  if (dryRun) {
+    say.dim(`Payment     : required — would open ${checkoutUrl}`)
+    return { proceed: true }
+  }
+
+  if (isNonInteractive(args)) {
+    say.err('Payment is required to publish this site, and the CLI is non-interactive.')
+    say.dim(`Complete it in a browser, then re-run: ${checkoutUrl}`)
+    return { proceed: false }
+  }
+
+  // The CSRF nonce the app echoes back on the done-signal redirect. The
+  // wait_token (when present) lets the app correlate the session backend-side.
+  const state = randomBytes(16).toString('hex')
+  say.info('Payment required — completing it in your browser…')
+  try {
+    await awaitBrowserCallback({
+      buildUrl: (redirectUri) =>
+        withParams(checkoutUrl, { redirect_uri: redirectUri, state, wait_token: verdict.wait_token }),
+      validate: (params) => {
+        if (params.get('error')) return { error: params.get('error') }
+        if (params.get('state') !== state) return { error: 'state mismatch — please retry.' }
+        return { value: true } // ok=1 / any non-error return = the app settled with the backend
+      },
+      openingLabel: 'Opening uniweb.app to complete payment…',
+      waitingLabel: 'Waiting for payment to complete (5 min)…',
+      timeoutMs: 5 * 60 * 1000,
+      okTitle: 'Payment complete',
+      errTitle: 'Payment failed',
+    })
+  } catch (err) {
+    say.err(`Payment was not completed: ${err.message}`)
+    say.dim('Re-run `uniweb publish` once payment is done.')
+    return { proceed: false }
+  }
+  say.ok('Payment complete.')
+  return { proceed: true }
+}

package/src/backend/site-sync.js

@@ -3,7 +3,7 @@
  * packages, submit them over the two directional lanes (site-content first, then the
  * folder keyed by the site's uuid), back-fill the minted uuids into the source files,
  * and persist the send-only-changed cache. Extracted from the push command so
- * `uniweb deploy` (the composite path) reuses the exact same lane submission.
+ * `uniweb publish` (the composite path) reuses the exact same lane submission.
  *
  * The command keeps flag parsing, the emit, and the `-o`/`--dry-run` preview;
  * everything from "the packages are built, now POST them" lives here. Logging is
@@ -162,7 +162,7 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
       res = await doRequest()
     } catch (err) {
       error(`Could not reach the backend at ${client.origin}: ${err.message}`)
-      note('Set the origin with --registry <url> or UNIWEB_REGISTER_URL.')
+      note('Set the origin with --backend <url> or UNIWEB_REGISTER_URL.')
       return null
     }
     if (!res.ok) {