uniweb 0.13.17 → 0.14.0

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

@@ -56,7 +56,7 @@ export function resolveLocalFoundation(siteDir, siteYml) {
   return {
     dir: info.path,
     scopedName: foundationScopedName(info.path),
-    version: readPkgField(info.path, 'version'),
+    version: readPkgField(info.path, 'version')
   }
 }
 
@@ -79,7 +79,10 @@ function foundationScopedName(dir) {
 
 function readPkgField(dir, field) {
   try {
-    return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))?.[field] || null
+    return (
+      JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))?.[field] ||
+      null
+    )
   } catch {
     return null
   }
@@ -120,7 +123,16 @@ function forwardedFlags(args) {
  *   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 }) {
+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
@@ -129,8 +141,14 @@ export async function bringFoundationAlong({ client, siteDir, siteYml, args, say
     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')
+  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.
@@ -144,17 +162,25 @@ export async function bringFoundationAlong({ client, siteDir, siteYml, args, say
   // 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`)
+    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
+  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() }
+    return {
+      released: releaseFoundation(local, args, cliBin, say),
+      proceed: true,
+      ref: pinnedRef()
+    }
   }
 
   // Registered — fingerprint the local build and compare. Build first so the
@@ -163,42 +189,71 @@ export async function bringFoundationAlong({ client, siteDir, siteYml, args, say
   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.`)
+    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() }
+    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).`)
+    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.')
+      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() }
+    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`.')
+  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)
+  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`.')
+    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() }
@@ -210,7 +265,7 @@ function buildFoundation(local, cliBin) {
   execFileSync('node', [cliBin, 'build', '--target', 'foundation'], {
     cwd: local.dir,
     stdio: 'inherit',
-    env: process.env,
+    env: process.env
   })
 }
 
@@ -222,7 +277,7 @@ function releaseFoundation(local, args, cliBin, say) {
   execFileSync('node', [cliBin, 'register', ...forwardedFlags(args)], {
     cwd: local.dir,
     stdio: 'inherit',
-    env: process.env,
+    env: process.env
   })
   console.log('')
   return true

package/src/backend/payment-handoff.js

@@ -37,13 +37,20 @@ function withParams(url, params) {
  *
  * @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|null} o.uuid - the site-content uuid (null only on a dry run; a
+ *   real publish creates the site before anything uploads, so it is set by here)
  * @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 }) {
+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 }
@@ -51,17 +58,22 @@ export async function settlePaymentIfNeeded({ client, uuid, args, say, dryRun =
   // 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}`)
+    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 }
+  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.')
+    say.warn(
+      'The backend reports payment is required but returned no checkout URL — proceeding.'
+    )
     return { proceed: true }
   }
 
@@ -71,7 +83,9 @@ export async function settlePaymentIfNeeded({ client, uuid, args, say, dryRun =
   }
 
   if (isNonInteractive(args)) {
-    say.err('Payment is required to publish this site, and the CLI is non-interactive.')
+    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 }
   }
@@ -83,17 +97,22 @@ export async function settlePaymentIfNeeded({ client, uuid, args, say, dryRun =
   try {
     await awaitBrowserCallback({
       buildUrl: (redirectUri) =>
-        withParams(checkoutUrl, { redirect_uri: redirectUri, state, wait_token: verdict.wait_token }),
+        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.' }
+        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',
+      errTitle: 'Payment failed'
     })
   } catch (err) {
     say.err(`Payment was not completed: ${err.message}`)

package/src/backend/site-media.js

@@ -23,7 +23,10 @@ import { contentTypeFor } from '../utils/code-upload.js'
  * @param {object} client - BackendClient (origin + uploadSiteAssets + discover)
  * @param {string} siteDir - the site root (site-root refs resolve under public/)
  * @param {string[]} refs - site-root local asset refs (`/images/x.png`)
- * @param {{ onProgress?: (m: string) => void, warn?: (m: string) => void }} [opts]
+ * @param {{ siteUuid?: string|null, onProgress?: (m: string) => void, warn?: (m: string) => void }} [opts]
+ *   `siteUuid` is the owner the uploaded bytes are charged to. Callers create the
+ *   site before uploading precisely so this is set — an unowned upload is charged
+ *   and cannot be freed, because freeing means deleting the owning entity.
  * @returns {Promise<{ map: Record<string,string>, missing: string[], failed: Array<{path:string,status:number,detail?:string}> }>}
  *   `map` is ref → serve URL for refs that resolved AND uploaded. The two failure
  *   kinds are reported SEPARATELY because callers must treat them differently:
@@ -32,7 +35,12 @@ import { contentTypeFor } from '../utils/code-upload.js'
  *   store — a transport or QUOTA refusal, and shipping content that still points at
  *   the local path would publish a broken image while only warning about it.
  */
-export async function uploadSiteMedia(client, siteDir, refs, { onProgress, warn } = {}) {
+export async function uploadSiteMedia(
+  client,
+  siteDir,
+  refs,
+  { siteUuid = null, onProgress, warn } = {}
+) {
   if (!refs?.length) return { map: {}, missing: [], failed: [] }
 
   const files = []
@@ -51,40 +59,160 @@ export async function uploadSiteMedia(client, siteDir, refs, { onProgress, warn
       size: bytes.length,
       sha256: createHash('sha256').update(bytes).digest('hex'),
       localUrl: ref, // the rewrite key — the original content ref
-      diskPath: resolved,
+      diskPath: resolved
     })
   }
   if (!files.length) return { map: {}, missing, failed: [] }
 
-  const result = await client.uploadSiteAssets({ files, onProgress })
+  const result = await client.uploadSiteAssets({ files, siteUuid, onProgress })
   const failed = result.failed || []
-  for (const f of failed) warn?.(`local-media: upload failed for ${f.path} (HTTP ${f.status})`)
+  for (const f of failed)
+    warn?.(`local-media: upload failed for ${f.path} (HTTP ${f.status})`)
 
   const config = await client.discover()
   const map = {}
   for (const ref of refs) {
     const entry = result.assetsByLocalUrl[ref]
-    if (entry) map[ref] = entry.serveUrl || buildAssetUrl(client.origin, config.assetBase, entry.id, entry.ext)
+    if (entry)
+      map[ref] =
+        entry.serveUrl ||
+        buildAssetUrl(client.origin, config.assetBase, entry.id, entry.ext)
   }
   return { map, missing, failed }
 }
 
+// ─── Asset-plan refusals ──────────────────────────────────────────────────────
+//
+// There is deliberately NO status-based refusal predicate here, and re-adding
+// one would be a mistake. None of the statuses such a heuristic would match
+// means what it looks like —
+//   507  reserved for `storage_quota_exceeded`, but status alone cannot tell it
+//        from any other 507, and carries none of the numbers a user needs;
+//   402  never from assets — it is the publish billing-consent gate, so matching it
+//        labels a billing refusal a storage problem and tells the user to free space
+//        they do not need;
+//   413  comes from the upload PUT, which collects into `failed[]` and never throws,
+//        so it cannot reach a catch around the plan.
+// The plan's caps (64 MiB/file, 512 MiB/plan, 1024 files) refuse with `400`, which
+// a 402/413/507 predicate never matched at all.
+//
+// Branch on `reason` instead — never on status, never on `detail` (prose, subject to
+// rewording). Same house style as the push-staleness `reason: "stale_base"` in
+// site-sync.js.
+
+const KIB = 1024
+function humanBytes(n) {
+  if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) return null
+  if (n < KIB) return `${n} B`
+  const units = ['KiB', 'MiB', 'GiB', 'TiB']
+  let v = n / KIB
+  let i = 0
+  while (v >= KIB && i < units.length - 1) {
+    v /= KIB
+    i++
+  }
+  return `${v >= 10 || Number.isInteger(v) ? Math.round(v) : v.toFixed(1)} ${units[i]}`
+}
+
+// Append `label: <bytes>` when the value is a usable number. A refusal that omits an
+// extra still produces a useful message — never print `undefined` at a user.
+function pushBytes(lines, label, n) {
+  const h = humanBytes(n)
+  if (h) lines.push(`  ${label}: ${h}`)
+}
+
 /**
- * Is this asset-lane error the backend refusing on storage grounds?
+ * Turn an asset-plan refusal into user-facing lines, or null when this is not a
+ * refusal we recognise (including every refusal shipped today, which is still
+ * prose — the typed `reason` values are agreed but NOT YET EMITTED). Null means
+ * "fall through to the generic error", so this degrades rather than swallowing.
  *
- * The plan step throws `Asset plan failed: HTTP <status>` for any non-2xx, so a quota
- * refusal is currently indistinguishable from any other rejection except by status.
- * These three are the plausible spellings — 402 (payment required), 413 (payload too
- * large), 507 (insufficient storage).
+ * Two wording rules are load-bearing and come from the ratified accounting model,
+ * not from taste:
  *
- * DELIBERATELY a heuristic, and it should not stay one: the backend owes a typed
- * error carrying used / limit / needed so the CLI can say what a push costs and what
- * is left. Until that contract exists this at least turns an opaque HTTP number into
- * the right advice. See the collab charter in the handoff.
+ *   1. **Never size a storage refusal from what was transferred.** `needed_bytes` is
+ *      "assets not yet on this workspace's books", which can be non-zero with ZERO
+ *      transfers — another workspace already uploaded the same bytes, so they come
+ *      back `present: true`, never PUT, and are charged here anyway. A push can print
+ *      no `↑` line at all and still be refused, so the message must talk about assets
+ *      new to the workspace, never "the files being uploaded".
+ *   2. **Never advise removing an image to free space.** Freeing is
+ *      entity-deletion-granular: editing an image out of live content frees nothing.
+ *      Only deleting the entity (or the site) it was uploaded for returns quota.
+ *      The predicate this replaced said "remove or shrink assets, then re-run" —
+ *      advice that is now simply wrong.
  *
- * @param {Error} err
- * @returns {boolean}
+ * @param {Error & { problem?: object|null }} err
+ * @returns {{ headline: string, notes: string[] } | null}
  */
-export function isStorageRefusal(err) {
-  return /Asset plan failed: HTTP (402|413|507)\b/.test(err?.message || '')
+export function describeAssetRefusal(err) {
+  const reason = err?.problem?.reason
+  if (typeof reason !== 'string') return null
+  const p = err.problem
+  const notes = []
+
+  switch (reason) {
+    case 'storage_quota_exceeded': {
+      pushBytes(notes, 'Used', p.used_bytes)
+      pushBytes(notes, 'Limit', p.limit_bytes)
+      // Rule 1: this is what the workspace must take on, not what would transfer.
+      pushBytes(notes, 'This publish adds', p.needed_bytes)
+      notes.push(
+        'Assets already on its books cost nothing to re-present, so a change'
+      )
+      notes.push('that touches only content is never refused here.')
+      // Rule 2.
+      notes.push(
+        'Quota is returned by deleting the site or entity an asset was uploaded'
+      )
+      notes.push('for — removing an image from content does not free it.')
+      // Rule 3: the allowance belongs to whoever OWNS the site, not to whoever is
+      // pushing — an asset is charged to the workspace of the entity it is for, so
+      // a push to an org site spends the org's allowance whatever context the
+      // pusher acts in. "Your storage" would be wrong for every contributor who is
+      // not the owner, and wrong in the direction that sends them looking through
+      // their own files for space that was never theirs.
+      return {
+        headline:
+          "Storage quota reached — the site owner's workspace cannot take on more assets.",
+        notes
+      }
+    }
+    case 'asset_file_too_large': {
+      const path = typeof p.path === 'string' ? p.path : null
+      pushBytes(notes, 'Size', p.size_bytes)
+      pushBytes(notes, 'Per-file limit', p.limit_bytes)
+      return {
+        headline: `Asset too large${path ? `: ${path}` : ''}`,
+        notes: [...notes, 'Shrink or re-encode the file, then re-run.']
+      }
+    }
+    case 'asset_plan_too_large': {
+      pushBytes(notes, 'This publish', p.requested_bytes)
+      pushBytes(notes, 'Per-publish limit', p.limit_bytes)
+      return {
+        headline: 'Too many bytes in one publish.',
+        notes: [
+          ...notes,
+          'Split the media across publishes, or shrink the largest files.'
+        ]
+      }
+    }
+    case 'asset_plan_too_many_files': {
+      if (Number.isFinite(p.files)) notes.push(`  Files: ${p.files}`)
+      if (Number.isFinite(p.limit))
+        notes.push(`  Per-publish limit: ${p.limit}`)
+      return {
+        headline: 'Too many asset files in one publish.',
+        notes: [...notes, 'Split the media across publishes.']
+      }
+    }
+    default:
+      // An unrecognised reason is still more useful than nothing, but we do not
+      // invent advice for it — surface it and let the generic detail follow.
+      return {
+        headline: `Asset upload refused by the backend (${reason}).`,
+        notes: []
+      }
+  }
 }