uniweb 0.13.17 → 0.14.0

package/src/utils/asset-upload.js

@@ -1,9 +1,8 @@
 /**
- * Site asset delivery — the asset lane for `uniweb publish` (channel
- * framework-backend-f90d). After the link build processes a site's media into
- * `dist/assets/`, those bytes are delivered to the backend's content-addressed
- * asset store, and the publish step rewrites the content's local refs to durable
- * serve URLs:
+ * Site asset delivery — the asset lane for `uniweb publish`. After the link
+ * build processes a site's media into `dist/assets/`, those bytes are delivered
+ * to the backend's content-addressed asset store, and the publish step rewrites
+ * the content's local refs to durable serve URLs:
  *
  *   1. PLAN   — POST {apiBase}/dev/assets with the file list ({ path,
  *               content_type, size, sha256 }). `sha256` is REQUIRED — it is the
@@ -25,8 +24,6 @@
  * mirrors the foundation code lane (utils/code-upload.js); the one structural
  * difference is that the backend MINTS the per-asset id, so the plan response is
  * what the deploy step rewrites content references to.
- *
- * Contract: kb/framework/build/delivery-lane.md §Assets.
  */
 
 import { createHash } from 'node:crypto'
@@ -62,7 +59,7 @@ export function collectSiteAssets(distDir) {
           size: st.size,
           sha256: createHash('sha256').update(bytes).digest('hex'),
           localUrl: `/assets/${rel}`,
-          diskPath: full,
+          diskPath: full
         })
       }
     }
@@ -96,25 +93,77 @@ export function collectSiteAssets(distDir) {
  * @param {(msg: string) => void} [opts.onProgress]
  * @returns {Promise<{ mode: string, uploaded: string[], skipped: string[], failed: Array<{path, status, detail}>, assetsByLocalUrl: Record<string, { id: string, ext: string, serveUrl?: string }> }>}
  */
-export async function uploadSiteAssets({ apiBase, token, distDir, files, onProgress = () => {} }) {
+export async function uploadSiteAssets({
+  apiBase,
+  token,
+  distDir,
+  files,
+  siteUuid = null,
+  onProgress = () => {}
+}) {
   const list = files || collectSiteAssets(distDir)
   if (!list.length) {
-    return { mode: 'none', uploaded: [], skipped: [], failed: [], assetsByLocalUrl: {} }
+    return {
+      mode: 'none',
+      uploaded: [],
+      skipped: [],
+      failed: [],
+      assetsByLocalUrl: {}
+    }
   }
 
   const origin = apiBase.replace(/\/$/, '')
   const planRes = await fetch(`${origin}/dev/assets`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`
+    },
     body: JSON.stringify({
-      files: list.map(({ path, content_type, size, sha256 }) => ({ path, content_type, size, sha256 })),
-    }),
+      // The owner these bytes are charged to. Storage is metered against the
+      // owning entity and reclaimed by deleting it, so an upload with no owner is
+      // charged and can never be freed — there is nothing to delete. Callers
+      // create the site first precisely so this is never null; it stays optional
+      // only so a backend predating the field still works.
+      //
+      // The wire key is `entity`, not `site`, and deliberately so: it names the
+      // entity the upload is FOR. On this lane that is always the site-content
+      // entity — hence the local `siteUuid`, which is the more informative name
+      // here — but the visual app sends an article on the same route. A field
+      // called `site` would be a lie for half its callers.
+      ...(siteUuid ? { entity: siteUuid } : {}),
+      files: list.map(({ path, content_type, size, sha256 }) => ({
+        path,
+        content_type,
+        size,
+        sha256
+      }))
+    })
   })
   if (!planRes.ok) {
     const detail = await planRes.text().catch(() => '')
-    throw new Error(
+    // The plan refuses with an RFC7807 body carrying a machine-readable `reason`.
+    // The message keeps its historical shape so anything reading it still works,
+    // but the PARSED body has to survive the throw: flattening it to a string
+    // here is what made "branch on `reason`" unimplementable and left the old
+    // caller no choice but a status regex. Callers read `err.problem`;
+    // `describeAssetRefusal` in backend/site-media.js turns it into user-facing
+    // lines.
+    let problem = null
+    if (detail) {
+      try {
+        const parsed = JSON.parse(detail)
+        if (parsed && typeof parsed === 'object') problem = parsed
+      } catch {
+        /* not a problem document — prose refusal, or an upstream error page */
+      }
+    }
+    const err = new Error(
       `Asset plan failed: HTTP ${planRes.status} ${planRes.statusText}${detail ? ` — ${detail.slice(0, 300)}` : ''}`
     )
+    err.status = planRes.status
+    err.problem = problem
+    throw err
   }
   const plan = await planRes.json()
   const mode = plan.mode || 'direct'
@@ -135,7 +184,11 @@ export async function uploadSiteAssets({ apiBase, token, distDir, files, onProgr
     // ⇒ false (older backend) → falls through to the upload path below.
     if (up.present) {
       skipped.push(src.path)
-      assetsByLocalUrl[src.localUrl] = { id: up.id, ext: String(up.ext || '').replace(/^\./, ''), serveUrl: up.serve_url }
+      assetsByLocalUrl[src.localUrl] = {
+        id: up.id,
+        ext: String(up.ext || '').replace(/^\./, ''),
+        serveUrl: up.serve_url
+      }
       continue
     }
 
@@ -149,7 +202,11 @@ export async function uploadSiteAssets({ apiBase, token, distDir, files, onProgr
     try {
       // The plan's url may be origin-relative (direct mode → the backend) or
       // absolute (presigned → storage); new URL() resolves both.
-      putRes = await fetch(new URL(up.url, origin), { method: up.method || 'PUT', headers, body: src.bytes ?? readFileSync(src.diskPath) })
+      putRes = await fetch(new URL(up.url, origin), {
+        method: up.method || 'PUT',
+        headers,
+        body: src.bytes ?? readFileSync(src.diskPath)
+      })
     } catch (err) {
       failed.push({ path: src.path, status: 0, detail: err.message })
       continue
@@ -157,9 +214,17 @@ export async function uploadSiteAssets({ apiBase, token, distDir, files, onProgr
     if (putRes.ok) {
       uploaded.push(src.path)
       // Authoritative id + ext from the plan; mapped only on a successful PUT.
-      assetsByLocalUrl[src.localUrl] = { id: up.id, ext: String(up.ext || '').replace(/^\./, ''), serveUrl: up.serve_url }
+      assetsByLocalUrl[src.localUrl] = {
+        id: up.id,
+        ext: String(up.ext || '').replace(/^\./, ''),
+        serveUrl: up.serve_url
+      }
     } else {
-      failed.push({ path: src.path, status: putRes.status, detail: await putRes.text().catch(() => '') })
+      failed.push({
+        path: src.path,
+        status: putRes.status,
+        detail: await putRes.text().catch(() => '')
+      })
     }
   }
 
@@ -167,10 +232,13 @@ export async function uploadSiteAssets({ apiBase, token, distDir, files, onProgr
 }
 
 // Build a durable asset serve URL from /dev/config's assetBase. Origin-relative
-// (`/gateway/asset/` in dev) → prepend the backend origin; absolute (a prod CDN)
-// → used verbatim. Shape: {assetBase}dist/{id}/base.{ext} — basename literally
-// `base`, {ext} the source extension the plan echoed.
+// → prepend the backend origin; absolute (a CDN host) → used verbatim. Shape:
+// {assetBase}dist/{id}/base.{ext} — basename literally `base`, {ext} the source
+// extension the plan echoed. The root itself is never assumed: it is whatever
+// discovery returned.
 export function buildAssetUrl(origin, assetBase, id, ext) {
-  const base = /^https?:\/\//.test(assetBase) ? assetBase : `${origin}${assetBase}`
+  const base = /^https?:\/\//.test(assetBase)
+    ? assetBase
+    : `${origin}${assetBase}`
   return `${base.replace(/\/$/, '')}/dist/${id}/base.${ext}`
 }

package/src/utils/code-upload.js

@@ -16,9 +16,13 @@
  *               loadable version (practical atomicity — there is no server
  *               confirm step by design).
  *
- * In direct mode the entry is fetched back from the anonymous serve route
- * (GET /gateway/foundation/{scope}/{name}/{version}/{path}) and compared
- * byte-for-byte — the e2e proof that the version is live.
+ * When the plan tells us where the version will be readable, the entry is
+ * fetched back from that location and compared byte-for-byte — the e2e proof
+ * that the version is live. The location is ALWAYS read from the plan's
+ * `serve_base`, never derived: where a backend serves uploaded code is its
+ * own business, and a producer that reconstructs the path is both coupled to
+ * it and wrong wherever a delivery tier mints the URL instead. No
+ * `serve_base` simply means "not verifiable from here" — not a fallback guess.
  *
  * Rules encoded here (the backend validates too — reject, never repair):
  *   - paths are dist/-relative, '/'-separated, URL-safe verbatim
@@ -59,7 +63,7 @@ const CONTENT_TYPES = {
   avif: 'image/avif',
   ico: 'image/x-icon',
   txt: 'text/plain',
-  html: 'text/html',
+  html: 'text/html'
 }
 
 export function contentTypeFor(path) {
@@ -95,7 +99,7 @@ export function collectDistFiles(distDir) {
           path: rel,
           content_type: contentTypeFor(rel),
           size: st.size,
-          sha256: createHash('sha256').update(bytes).digest('hex'),
+          sha256: createHash('sha256').update(bytes).digest('hex')
         })
       }
     }
@@ -144,25 +148,25 @@ export function computeFoundationDigest(distDir) {
   // it in explicitly — a schema-only change is still a foundation change.
   const schemaPath = join(distDir, 'meta', 'schema.json')
   if (existsSync(schemaPath)) {
-    hashes.push(createHash('sha256').update(readFileSync(schemaPath)).digest('hex'))
+    hashes.push(
+      createHash('sha256').update(readFileSync(schemaPath)).digest('hex')
+    )
   }
   if (!hashes.length) return null
   hashes.sort()
-  return 'sha256:' + createHash('sha256').update(hashes.join('\n')).digest('hex')
+  return (
+    'sha256:' + createHash('sha256').update(hashes.join('\n')).digest('hex')
+  )
 }
 
-/**
- * The gateway serve URL for a file of a registered foundation version.
- * Mirrors the backend storage convention: scope WITHOUT the '@'.
- * Prefer the plan response's `serve_base` when present.
+/*
+ * There is deliberately no serve-URL builder here. A previous version exported
+ * `gatewayUrl()`, which reconstructed the backend's serve path from the ref —
+ * mirroring its storage convention, scope-without-the-'@' and all. That was
+ * wrong twice over: it encoded another service's route layout in a public
+ * package, and it can only ever be right on the one deployment shape where the
+ * backend also serves the bytes. Read `serve_base` from the upload plan.
  */
-export function gatewayUrl(apiBase, name, version, path) {
-  const m = /^@([^/]+)\/(.+)$/.exec(name)
-  const scope = m ? m[1] : ''
-  const base = m ? m[2] : name
-  const origin = apiBase.replace(/\/$/, '')
-  return `${origin}/gateway/foundation/${scope}/${base}/${version}/${path}`
-}
 
 /**
  * Deliver a foundation's code: plan, upload (entry last), verify (direct
@@ -185,17 +189,26 @@ export async function uploadFoundationCode({
   version,
   distDir,
   files,
-  onProgress = () => {},
+  onProgress = () => {}
 }) {
   const list = files || collectDistFiles(distDir)
   if (!list.length) {
-    return { mode: 'none', uploaded: [], failed: [], verified: null, serveBase: null }
+    return {
+      mode: 'none',
+      uploaded: [],
+      failed: [],
+      verified: null,
+      serveBase: null
+    }
   }
 
   const origin = apiBase.replace(/\/$/, '')
   const planRes = await fetch(`${origin}/dev/registry/code-uploads`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`
+    },
     body: JSON.stringify({
       name,
       version,
@@ -205,9 +218,9 @@ export async function uploadFoundationCode({
         size,
         // Optional integrity hint (ignored by the v1 backend; flows so a
         // future checksum-bearing presign needs no CLI change).
-        sha256,
-      })),
-    }),
+        sha256
+      }))
+    })
   })
   if (!planRes.ok) {
     const body = await planRes.text().catch(() => '')
@@ -223,14 +236,19 @@ export async function uploadFoundationCode({
   // The ONE mode-aware bit: direct-mode PUTs are bearer-authed backend
   // routes; presigned URLs are self-authorizing and must NOT carry a
   // bearer (foreign auth headers can break signed-request validation).
-  const authHeaders = plan.mode === 'direct' ? { Authorization: `Bearer ${token}` } : {}
+  const authHeaders =
+    plan.mode === 'direct' ? { Authorization: `Bearer ${token}` } : {}
 
   const uploaded = []
   const failed = []
   for (const file of uploadOrder(list)) {
     const target = targets.get(file.path)
     if (!target) {
-      failed.push({ path: file.path, status: 0, detail: 'no upload target in plan' })
+      failed.push({
+        path: file.path,
+        status: 0,
+        detail: 'no upload target in plan'
+      })
       continue
     }
     const bytes = readFileSync(join(distDir, file.path))
@@ -239,8 +257,12 @@ export async function uploadFoundationCode({
         method: target.method || 'PUT',
         // x-uniweb-sha256: optional integrity guard — direct mode verifies
         // the received bytes and 400s on mismatch (corruption-in-flight).
-        headers: { ...(target.headers || {}), ...authHeaders, 'x-uniweb-sha256': file.sha256 },
-        body: bytes,
+        headers: {
+          ...(target.headers || {}),
+          ...authHeaders,
+          'x-uniweb-sha256': file.sha256
+        },
+        body: bytes
       })
       if (res.ok) {
         uploaded.push(file.path)
@@ -249,7 +271,7 @@ export async function uploadFoundationCode({
         failed.push({
           path: file.path,
           status: res.status,
-          detail: (await res.text().catch(() => '')).slice(0, 200),
+          detail: (await res.text().catch(() => '')).slice(0, 200)
         })
       }
     } catch (err) {
@@ -257,17 +279,20 @@ export async function uploadFoundationCode({
     }
   }
 
-  // Direct mode: prove the version is live — fetch the entry back and
-  // compare bytes (the channel's e2e proof, made a default).
+  // Prove the version is live — fetch the entry back and compare bytes.
+  // Gated on `serveBase`, NOT on the plan's mode: the question is only ever
+  // "did the backend tell us where to look", and inferring a location from the
+  // mode is the coupling this lane used to carry. A plan without a serve_base
+  // (a delivery tier owns the URL) leaves `verified` null.
   let verified = null
   const entry = list.find((f) => f.path === ENTRY_PATH)
-  if (plan.mode === 'direct' && entry && !failed.length) {
+  if (serveBase && entry && !failed.length) {
     try {
-      // serve_base is origin-relative in direct mode — resolve against the
-      // registry origin before fetching.
-      const url = serveBase
-        ? new URL(`${serveBase.replace(/\/$/, '')}/${ENTRY_PATH}`, origin).toString()
-        : gatewayUrl(origin, name, version, ENTRY_PATH)
+      // serve_base may be origin-relative — resolve against the backend origin.
+      const url = new URL(
+        `${serveBase.replace(/\/$/, '')}/${ENTRY_PATH}`,
+        origin
+      ).toString()
       const res = await fetch(url)
       if (res.ok) {
         const served = Buffer.from(await res.arrayBuffer())

package/src/utils/config.js

@@ -83,15 +83,27 @@ function readSessionOrigin() {
 export function getRegistryApiBaseUrl() {
   const fromEnv = process.env.UNIWEB_REGISTER_URL
   if (fromEnv) {
-    try { return new URL(fromEnv).origin } catch { /* fall through */ }
+    try {
+      return new URL(fromEnv).origin
+    } catch {
+      /* fall through */
+    }
   }
   const fromSession = readSessionOrigin()
   if (fromSession) {
-    try { return new URL(fromSession).origin } catch { return fromSession }
+    try {
+      return new URL(fromSession).origin
+    } catch {
+      return fromSession
+    }
   }
   const fromCfg = readCliConfig().registryApiUrl
   if (fromCfg) {
-    try { return new URL(fromCfg).origin } catch { return fromCfg }
+    try {
+      return new URL(fromCfg).origin
+    } catch {
+      return fromCfg
+    }
   }
   return 'https://uniweb.app'
 }
@@ -199,7 +211,7 @@ export async function writeRootPackageJson(rootDir, pkg) {
  */
 export function computeRootScripts(sites, pm = 'pnpm') {
   const scripts = {
-    build: 'uniweb build',
+    build: 'uniweb build'
   }
 
   if (sites.length === 0) {
@@ -218,7 +230,11 @@ export function computeRootScripts(sites, pm = 'pnpm') {
     // Subsequent sites get qualified dev:{name}/preview:{name}
     for (let i = 1; i < sites.length; i++) {
       scripts[`dev:${sites[i].name}`] = `uniweb dev ${sites[i].name}`
-      scripts[`preview:${sites[i].name}`] = filterCmd(pm, sites[i].name, 'preview')
+      scripts[`preview:${sites[i].name}`] = filterCmd(
+        pm,
+        sites[i].name,
+        'preview'
+      )
     }
   }
 
@@ -262,8 +278,8 @@ export async function resolveGlob(rootDir, pattern) {
       const { readdirSync } = await import('node:fs')
       const entries = readdirSync(fullPath, { withFileTypes: true })
       return entries
-        .filter(e => e.isDirectory() && !e.name.startsWith('.'))
-        .map(e => join(baseDir, e.name))
+        .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+        .map((e) => join(baseDir, e.name))
     } catch {
       return []
     }
@@ -276,9 +292,14 @@ export async function resolveGlob(rootDir, pattern) {
     try {
       const entries = readdirSync(rootDir, { withFileTypes: true })
       return entries
-        .filter(e => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')
-        .filter(e => existsSync(join(rootDir, e.name, suffix)))
-        .map(e => join(e.name, suffix))
+        .filter(
+          (e) =>
+            e.isDirectory() &&
+            !e.name.startsWith('.') &&
+            e.name !== 'node_modules'
+        )
+        .filter((e) => existsSync(join(rootDir, e.name, suffix)))
+        .map((e) => join(e.name, suffix))
     } catch {
       return []
     }

package/src/utils/dep-survey.js

@@ -25,7 +25,12 @@ import { getWorkspacePackages } from './workspace.js'
  * @returns {string}
  */
 export function stripVersionRange(spec) {
-  return (spec || '').replace(/^[\^~>=<\s]+/, '').trim().split(/\s+/)[0] || ''
+  return (
+    (spec || '')
+      .replace(/^[\^~>=<\s]+/, '')
+      .trim()
+      .split(/\s+/)[0] || ''
+  )
 }
 
 /**
@@ -76,9 +81,17 @@ export async function surveyWorkspaceDeps(workspaceDir) {
     const pkgPath = join(pkgDir, 'package.json')
     if (!existsSync(pkgPath)) continue
     let pkg
-    try { pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) } catch { continue }
+    try {
+      pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    } catch {
+      continue
+    }
 
-    for (const sectionName of ['dependencies', 'devDependencies', 'peerDependencies']) {
+    for (const sectionName of [
+      'dependencies',
+      'devDependencies',
+      'peerDependencies'
+    ]) {
       const section = pkg[sectionName]
       if (!section) continue
       for (const [name, current] of Object.entries(section)) {
@@ -87,10 +100,23 @@ export async function surveyWorkspaceDeps(workspaceDir) {
         if (!target) continue
         const cmp = compareSemver(target, current)
         let status
-        if (cmp > 0) { status = 'behind'; anyDrift = true }
-        else if (cmp < 0) { status = 'ahead'; anyAhead = true }
-        else { status = 'aligned' }
-        rows.push({ relDir: relDir || '(root)', section: sectionName, name, current, target, status })
+        if (cmp > 0) {
+          status = 'behind'
+          anyDrift = true
+        } else if (cmp < 0) {
+          status = 'ahead'
+          anyAhead = true
+        } else {
+          status = 'aligned'
+        }
+        rows.push({
+          relDir: relDir || '(root)',
+          section: sectionName,
+          name,
+          current,
+          target,
+          status
+        })
       }
     }
   }

package/src/utils/destination-prompt.js

@@ -30,14 +30,14 @@ export const UNIWEB_DESTINATION = {
   value: { kind: 'uniweb' },
   title: 'Uniweb Cloud · paid, dynamic + visual editing',
   description:
-    'Sync + dynamic SSR, visual editing for content authors, foundation propagation. Runs `uniweb publish`.',
+    'Sync + dynamic SSR, visual editing for content authors, foundation propagation. Runs `uniweb publish`.'
 }
 
 export const EXPORT_DESTINATION = {
   value: { kind: 'export' },
   title: 'Somewhere else · export a folder',
   description:
-    'Builds a self-contained dist/ you upload yourself. Runs `uniweb export`.',
+    'Builds a self-contained dist/ you upload yourself. Runs `uniweb export`.'
 }
 
 /**
@@ -49,16 +49,20 @@ export async function buildDestinationChoices() {
   const { listAdapters, getAdapter } = await import('@uniweb/build/hosts')
 
   const adapters = listAdapters()
-    .map(name => getAdapter(name))
-    .filter(a => a.display?.wizard !== false)
+    .map((name) => getAdapter(name))
+    .filter((a) => a.display?.wizard !== false)
     // Never offer a door that doesn't open.
-    .filter(a => typeof a.deploy === 'function' || typeof a.initCi === 'function')
+    .filter(
+      (a) => typeof a.deploy === 'function' || typeof a.initCi === 'function'
+    )
     .sort((a, b) => (a.display?.order ?? 999) - (b.display?.order ?? 999))
 
-  const choices = adapters.map(a => ({
+  const choices = adapters.map((a) => ({
     value: { kind: 'adapter', host: a.name },
-    title: `${a.display?.title || a.name} · ${a.display?.qualifier || ''}`.trim().replace(/ ·\s*$/, ''),
-    description: a.display?.summary || '',
+    title: `${a.display?.title || a.name} · ${a.display?.qualifier || ''}`
+      .trim()
+      .replace(/ ·\s*$/, ''),
+    description: a.display?.summary || ''
   }))
 
   return [...choices, UNIWEB_DESTINATION, EXPORT_DESTINATION]
@@ -87,15 +91,13 @@ async function promptForAction(adapter) {
     {
       value: 'ci',
       title: 'Set it up to deploy on every push · recommended',
-      description:
-        `Writes a GitHub Actions workflow. One-time setup — after this, pushing to the default branch deploys.${previews}`,
+      description: `Writes a GitHub Actions workflow. One-time setup — after this, pushing to the default branch deploys.${previews}`
     },
     {
       value: 'deploy',
       title: 'Upload from this machine now',
-      description:
-        `Builds dist/ here and pushes it with ${adapter.display?.pushWith || 'the host CLI'}.`,
-    },
+      description: `Builds dist/ here and pushes it with ${adapter.display?.pushWith || 'the host CLI'}.`
+    }
   ])
 }
 
@@ -110,17 +112,25 @@ async function promptForAction(adapter) {
  *   null when the user cancels.
  * @throws {Error} When non-interactive — the caller prints the guidance.
  */
-export async function promptForDestination({ args = [], preselect = null } = {}) {
+export async function promptForDestination({
+  args = [],
+  preselect = null
+} = {}) {
   if (isNonInteractive(args)) {
-    throw new Error('Cannot prompt for a destination when running non-interactively.')
+    throw new Error(
+      'Cannot prompt for a destination when running non-interactively.'
+    )
   }
 
   let choices = await buildDestinationChoices()
 
   // Float the remembered target so Enter does the obvious thing.
   if (preselect) {
-    const idx = choices.findIndex(c => c.value.kind === 'adapter' && c.value.host === preselect)
-    if (idx > 0) choices = [choices[idx], ...choices.filter((_, i) => i !== idx)]
+    const idx = choices.findIndex(
+      (c) => c.value.kind === 'adapter' && c.value.host === preselect
+    )
+    if (idx > 0)
+      choices = [choices[idx], ...choices.filter((_, i) => i !== idx)]
   }
 
   const picked = await promptSelect('Where should this site go?', choices)