uniweb 0.36.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,13 +41,13 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
+    "@uniweb/core": "^0.16.0",
     "@uniweb/kit": "^0.15.2",
-    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/runtime": "^0.13.5",
-    "@uniweb/core": "^0.16.0"
+    "@uniweb/semantic-parser": "^1.4.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.32.0",
+    "@uniweb/build": "^0.33.0",
     "@uniweb/content-reader": "^1.2.4",
     "@uniweb/semantic-parser": "^1.4.0"
   },

package/src/commands/publish.js

@@ -95,7 +95,10 @@ import {
   reportPaymentRefusal
 } from '../backend/payment-handoff.js'
 import { reportSchemalessQueries } from '../utils/schemaless-report.js'
-import { uploadSiteData } from '../utils/site-data-upload.js'
+import {
+  uploadSiteData,
+  describeDataRefusal
+} from '../utils/site-data-upload.js'
 
 const c = {
   reset: '\x1b[0m',
@@ -456,7 +459,12 @@ export async function publish(args = []) {
   // destructive — a placeholder file, created meaning to fill it in — so the count
   // is reported and confirmed before anything is sent.
   {
-    const guard = await guardEmptyRecords({ siteDir, args, warn: say.warn, note: say.dim })
+    const guard = await guardEmptyRecords({
+      siteDir,
+      args,
+      warn: say.warn,
+      note: say.dim
+    })
     if (!guard.ok) return { exitCode: 1 }
   }
 
@@ -602,28 +610,56 @@ export async function publish(args = []) {
   //     does not exist, which is the failure this work kept catching in others.
   //     `client.discover()` is the mechanism if that changes — `DISCOVERY_DEFAULTS`
   //     makes an absent key non-breaking by construction.
-  if (ball) {
-    say.info('Uploading schema-less record data…')
-    try {
-      const r = await uploadSiteData({
-        apiBase: client.origin,
-        token: await client.token(),
-        siteUuid: site.uuid,
-        ball,
-        onProgress: (m) => say.dim(`  ${m}`)
-      })
-      if (r.failed.length) {
-        // A file whose bytes did not land must not be published: the site would
-        // serve a stale copy or 404, and the only trace would be a warning.
-        say.err(`${r.failed.length} data file(s) failed to upload — not publishing.`)
-        for (const f of r.failed) say.dim(`  ${f.path} (HTTP ${f.status})`)
-        return { exitCode: 1 }
-      }
-      say.dim(`Record data     : ${r.uploaded.length} file(s) [${r.mode}]`)
-    } catch (err) {
-      say.err(`Record data upload failed: ${err.message}`)
+  //
+  // ⛔ UNCONDITIONAL — `if (ball)` was here until 2026-09-01 and it was the bug.
+  //
+  //     `collectSchemalessData` returns null for an empty set, so a publish that
+  //     carried no schema-less data sent NO PLAN AT ALL. The backend reconciles a
+  //     site's data usage against this manifest, and a request that never arrives
+  //     is not a manifest saying "none" — it is silence, indistinguishable from a
+  //     publish that never happened. So deleting your LAST schema-less collection
+  //     — the exact operation the reconcile exists to make free — was the one
+  //     operation that could not be expressed, and the site kept paying for it
+  //     until the whole site was deleted.
+  //
+  // ⭐ The general shape, worth more than the fix: an EMPTY set and NO set are
+  //    different statements, and an `if (x)` guard collapses them into one. The
+  //    cost is always paid by whoever is downstream trying to tell them apart.
+  //
+  // Both halves agreed in channel backend-framework-82f2 (2026-09-01); the
+  // backend's route accepts an empty `files` array as of the same exchange.
+  say.info('Uploading schema-less record data…')
+  try {
+    const r = await uploadSiteData({
+      apiBase: client.origin,
+      token: await client.token(),
+      siteUuid: site.uuid,
+      ball,
+      onProgress: (m) => say.dim(`  ${m}`)
+    })
+    if (r.failed.length) {
+      // A file whose bytes did not land must not be published: the site would
+      // serve a stale copy or 404, and the only trace would be a warning.
+      say.err(
+        `${r.failed.length} data file(s) failed to upload — not publishing.`
+      )
+      for (const f of r.failed) say.dim(`  ${f.path} (HTTP ${f.status})`)
       return { exitCode: 1 }
     }
+    say.dim(`Record data     : ${r.uploaded.length} file(s) [${r.mode}]`)
+  } catch (err) {
+    // A typed plan refusal gets its own account (quota, or whatever else the
+    // backend names); anything else falls through to the raw message. Same
+    // treatment the asset plan and the site create already get — this was the
+    // last door still printing the problem document at the user verbatim.
+    const refusal = describeDataRefusal(err)
+    if (refusal) {
+      say.err(refusal.headline)
+      for (const line of refusal.notes) say.dim(line)
+    } else {
+      say.err(`Record data upload failed: ${err.message}`)
+    }
+    return { exitCode: 1 }
   }
 
   // 5. Push the site (content + folder) over the send-only-changed cache —
@@ -680,9 +716,7 @@ export async function publish(args = []) {
         ? { baseVersions, itemBaseVersions: readItemBaseVersions(siteDir) }
         : {}),
       ...(Object.keys(injectInfo).length ? { injectInfo } : {}),
-      ...(Object.keys(ext.pins).length
-        ? { injectExtensions: ext.pins }
-        : {}),
+      ...(Object.keys(ext.pins).length ? { injectExtensions: ext.pins } : {}),
       ...(assetRewrite ? { assetRewrite } : {}),
       ...(assetIds ? { assetIds } : {})
     })

package/src/commands/update.js

@@ -257,7 +257,15 @@ export function printSurvey(
         statusText = `${colors.dim}aligned${colors.reset}`
       } else if (row.status === 'behind') {
         icon = `${colors.yellow}✗${colors.reset}`
-        statusText = `${colors.yellow}behind${colors.reset}`
+        // ⛔ `behind` alone was the whole message, in one colour, for every
+        // distance. In 0.x the minor slot is where our breaking changes live
+        // (`publish.js` derives it from a breaking marker and nothing else), so
+        // `^0.14.1 → ^0.16.0` is two releases a consumer must act on and
+        // `^0.15.0 → ^0.15.2` is not — and the table said the same thing about
+        // both. Naming the class is the difference between a list and a signal.
+        statusText = row.breaking
+          ? `${colors.red}${row.bump} · BREAKING${colors.reset}`
+          : `${colors.yellow}${row.bump}${colors.reset}`
       } else {
         icon = `${colors.cyan}↑${colors.reset}`
         statusText = `${colors.cyan}ahead of CLI${colors.reset}`
@@ -272,6 +280,35 @@ export function printSurvey(
       `  ${colors.dim}(${alignedCount} other${alignedCount === 1 ? '' : 's'} already aligned — ${colors.reset}${colors.cyan}--verbose${colors.reset}${colors.dim} to list)${colors.reset}`
     )
   }
+
+  // ⭐ **A summary, because the table scrolls and `--yes` does not stop.** The
+  // per-row label above is invisible to the case that matters most: a CI or an
+  // agent running `update --yes`, where nobody reads a table and the only
+  // artifact is a log. This block names the packages, so "what did that
+  // upgrade cross?" is answerable afterwards from the log alone.
+  //
+  // ⚖️ It reports; it does not gate. Crossing a 0.x minor IS the ordinary way
+  // to take a Uniweb update — gating it would gate nearly every real upgrade
+  // and make the verb useless. The decision stays the operator's; what changed
+  // is that they can now make it knowingly.
+  const breakingRows = report.rows.filter((r) => r.breaking)
+  if (breakingRows.length > 0) {
+    const names = [...new Set(breakingRows.map((r) => r.name))]
+    log('')
+    log(
+      `${colors.red}⚠${colors.reset}  ${colors.bright}${names.length} package${names.length === 1 ? '' : 's'} cross${names.length === 1 ? 'es' : ''} a breaking boundary:${colors.reset}`
+    )
+    for (const name of names) {
+      const r = breakingRows.find((x) => x.name === name)
+      log(`     ${colors.red}${name}${colors.reset}  ${r.current} → ${r.target}  ${colors.dim}(${r.bump})${colors.reset}`)
+    }
+    log(
+      `   ${colors.dim}In 0.x the minor slot is where breaking changes go, so these are releases${colors.reset}`
+    )
+    log(
+      `   ${colors.dim}you may need to act on. Read their changelogs before shipping.${colors.reset}`
+    )
+  }
   log('')
 }
 

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-02T03:17:32.722Z",
+  "generatedAt": "2026-09-02T16:36:26.382Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.2.2",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.32.0",
+      "version": "0.33.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -119,7 +119,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.18",
+      "version": "0.8.19",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/utils/dep-survey.js

@@ -33,6 +33,53 @@ export function stripVersionRange(spec) {
   )
 }
 
+/**
+ * How far a bump moves, in the terms our versioning actually uses.
+ *
+ * ⭐ **In 0.x the MINOR slot is the breaking one, and it is the only channel we
+ * have.** `scripts/framework/publish.js` derives a package's bump from its own
+ * commits: a breaking marker means minor, everything else patch. So
+ * `^0.14.1 → ^0.16.0` is two breaking releases and `^0.15.0 → ^0.15.2` is not —
+ * and until 2026-09-02 `update` printed both as `behind`, in the same colour,
+ * and `--yes` applied them without a word.
+ *
+ * That is the one signal the version scheme exists to send, discarded by the
+ * command we tell every project to run — `AGENTS.md` ships that instruction
+ * into every scaffold. The `flows` lane crossed `@uniweb/core` `^0.14.1 →
+ * ^0.15.0` this way and learned it afterwards, from a changelog.
+ *
+ * @param {string} from - the currently declared range or version
+ * @param {string} to   - the version the matrix carries
+ * @returns {'patch'|'minor'|'major'|'none'}
+ */
+export function bumpClass(from, to) {
+  const [aMaj = 0, aMin = 0, aPat = 0] = stripVersionRange(from).split('.').map(Number)
+  const [bMaj = 0, bMin = 0, bPat = 0] = stripVersionRange(to).split('.').map(Number)
+  if (bMaj !== aMaj) return 'major'
+  if (bMin !== aMin) return 'minor'
+  if (bPat !== aPat) return 'patch'
+  return 'none'
+}
+
+/**
+ * Is this crossing one a consumer must act on?
+ *
+ * A major always is. A minor is **when the major is 0**, because that is where
+ * our scheme puts breaking changes — and npm agrees, which is the check that
+ * makes this more than our own convention: `^0.14.1` admits `0.14.x` and
+ * refuses `0.15.0`, so the range itself already treats the slot as a wall.
+ *
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function isBreakingBump(from, to) {
+  const cls = bumpClass(from, to)
+  if (cls === 'major') return true
+  if (cls !== 'minor') return false
+  return Number(stripVersionRange(to).split('.')[0]) === 0
+}
+
 /**
  * Compare two version specs (range prefix tolerated). Returns 1 / -1 / 0.
  * @param {string} a
@@ -115,7 +162,12 @@ export async function surveyWorkspaceDeps(workspaceDir) {
           name,
           current,
           target,
-          status
+          status,
+          // Classified here rather than at print time so every consumer of a
+          // survey row gets the same answer — the report, the summary, and any
+          // gate a caller applies.
+          bump: status === 'behind' ? bumpClass(current, target) : 'none',
+          breaking: status === 'behind' && isBreakingBump(current, target)
         })
       }
     }

package/src/utils/site-data-upload.js

@@ -51,6 +51,7 @@
  */
 
 import { createHash } from 'node:crypto'
+import { humanBytes } from './bytes.js'
 
 /**
  * Plan + upload a site's static collection data files.
@@ -72,10 +73,23 @@ export async function uploadSiteData({
   ball,
   onProgress = () => {}
 }) {
+  // ⛔ An EMPTY set still posts a plan, and that is the whole point of this lane
+  // being a manifest rather than a stream of files.
+  //
+  // The backend reconciles a site's data usage against what this plan declares:
+  // whatever is not in the manifest is gone, so deleting a collection stops
+  // costing on the next publish. ⭐ A plan with zero files is a STATEMENT that
+  // there are none; the ABSENCE of a request says nothing at all. Returning
+  // early here — which this did until 2026-09-01 — made "the user deleted their
+  // last schema-less collection" unexpressible on the wire, so that site kept
+  // paying for bytes it no longer served until the whole site was deleted.
+  // Nothing looked wrong at either end: no error, no warning, just a request
+  // that was never sent.
+  //
+  // Agreed both sides in channel backend-framework-82f2; the backend's plan
+  // route accepted an empty `files` array in the same exchange (it was a 400
+  // before, which is what made the omission look like the only option).
   const entries = Object.entries(ball?.data || {})
-  if (!entries.length) {
-    return { mode: 'none', uploaded: [], failed: [], serveBase: null }
-  }
 
   // One plan for the whole set. The per-request file cap counts a plan, so
   // splitting would evade it rather than respect it; if a set ever exceeds it,
@@ -129,9 +143,25 @@ export async function uploadSiteData({
   )
   if (!planRes.ok) {
     const body = await planRes.text().catch(() => '')
-    throw new Error(
+    // The PARSED problem document has to survive the throw. Flattening it into
+    // the message is what left the other two doors unable to branch on `reason`
+    // and printing raw JSON at users; this lane was the last one still doing it.
+    // Callers read `err.problem`; `describeDataRefusal` turns it into lines.
+    let problem = null
+    if (body) {
+      try {
+        const parsed = JSON.parse(body)
+        if (parsed && typeof parsed === 'object') problem = parsed
+      } catch {
+        /* not a problem document — prose refusal, or an upstream error page */
+      }
+    }
+    const err = new Error(
       `site data-uploads plan rejected: HTTP ${planRes.status}${body ? ` — ${body.slice(0, 300)}` : ''}`
     )
+    err.status = planRes.status
+    err.problem = problem
+    throw err
   }
 
   const plan = await planRes.json()
@@ -149,7 +179,11 @@ export async function uploadSiteData({
     if (!target) {
       // A file the plan did not answer for is unaddressable. Report it; never
       // invent a location for it.
-      failed.push({ path: f.path, status: 0, detail: 'no upload target in plan' })
+      failed.push({
+        path: f.path,
+        status: 0,
+        detail: 'no upload target in plan'
+      })
       continue
     }
     try {
@@ -182,3 +216,65 @@ export async function uploadSiteData({
     serveBase: plan.serve_base || null
   }
 }
+
+/**
+ * Turn a typed data-uploads refusal into user-facing lines, or null when there is
+ * no typed `reason` (⇒ fall through to the generic message, degrading rather than
+ * swallowing).
+ *
+ * ⭐ The THIRD door, and the last to get one. `/dev/assets` has
+ * `describeAssetRefusal`, `POST /dev/site` has `describeCreateRefusal`, and this
+ * lane threw prose with the JSON inlined until 2026-09-01 — which is the failure
+ * the other two describers exist to prevent, so leaving it was just an untreated
+ * instance of a solved problem.
+ *
+ * ⛔ Branch on `reason`, never the status: `507` alone cannot be told from any
+ * other `507` and carries none of the numbers, and `detail` is prose the backend
+ * may reword.
+ *
+ * ⚖️ **The advice DIVERGES from the asset lane's, and that divergence is the whole
+ * reason this is a separate function rather than a reused one.** On the asset lane
+ * removing an image frees nothing — freeing is entity-deletion-granular. Here the
+ * publish declares the COMPLETE set of schema-less data files every time, so
+ * dropping a collection and re-publishing is a real way to stop paying for it.
+ * Telling a data user "editing content frees nothing" would be false, and telling
+ * an asset user "just remove it" would be worse.
+ *
+ * @param {Error & { problem?: object|null }} err
+ * @returns {{ headline: string, notes: string[] } | null}
+ */
+export function describeDataRefusal(err) {
+  const p = err?.problem
+  const reason = p?.reason
+  if (typeof reason !== 'string') return null
+
+  if (reason === 'storage_quota_exceeded') {
+    const notes = []
+    const used = humanBytes(p.used_bytes)
+    const limit = humanBytes(p.limit_bytes)
+    const needed = humanBytes(p.needed_bytes)
+    if (used) notes.push(`  Used: ${used}`)
+    if (limit) notes.push(`  Limit: ${limit}`)
+    if (needed) notes.push(`  This publish adds: ${needed}`)
+    notes.push(
+      'Every publish declares the full set of schema-less data files, so removing'
+    )
+    notes.push(
+      'a collection and re-publishing stops it counting. Deleting a site or entity'
+    )
+    notes.push('frees space too.')
+    return {
+      headline:
+        "Storage quota reached — the site owner's workspace cannot take on more record data.",
+      notes
+    }
+  }
+
+  // An unrecognised reason still beats a status dump: name it, and let the
+  // backend's own prose follow when it sent any.
+  const detail = typeof p.detail === 'string' ? p.detail : ''
+  return {
+    headline: `Record data upload refused by the backend (${reason}).`,
+    notes: detail ? [`  ${detail}`] : []
+  }
+}