uniweb 1.0.0 → 1.0.2

package/src/templates/validator.js

@@ -0,0 +1,155 @@
+/**
+ * Template validation — reads template.json and finds the content directories
+ *
+ * ⛔ Two things this used to do are retired [2026-10-08]:
+ *   - `compatible` (alias `uniweb`), a CLI version range a template declared. It
+ *     was checked only when a caller passed the CLI's version, and none ever
+ *     did. An official template now comes from the release its CLI was
+ *     published with (resolver.js), so it cannot be newer than that CLI.
+ *   - Unwrapping a package folder that keeps its code under `src/` — the layout of
+ *     the v0.7 releases (`foundation/src/foundation.js`). Such a folder is now
+ *     REFUSED, naming the fix (validateTemplate). ⛔ The unwrap went in 0.88.0
+ *     with a note that the official templates were flat, but its condition was any
+ *     `src/main.js` too, and `extensions/effects/` still relied on it: 0.88.0
+ *     copied that folder nested, and every project made from `extensions` failed
+ *     to build, saying only that it found no section types. The template is flat
+ *     since templates 0.18.6.
+ */
+
+import fs from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Validation error with structured details
+ */
+export class ValidationError extends Error {
+  constructor(message, code, details = {}) {
+    super(message)
+    this.name = 'ValidationError'
+    this.code = code
+    this.details = details
+  }
+}
+
+export const ErrorCodes = {
+  MISSING_TEMPLATE_JSON: 'MISSING_TEMPLATE_JSON',
+  INVALID_TEMPLATE_JSON: 'INVALID_TEMPLATE_JSON',
+  MISSING_CONTENT_DIR: 'MISSING_CONTENT_DIR',
+  MISSING_REQUIRED_FIELD: 'MISSING_REQUIRED_FIELD',
+  NESTED_PACKAGE_CODE: 'NESTED_PACKAGE_CODE'
+}
+
+/**
+ * Validate a template directory structure and metadata
+ *
+ * @param {string} templateRoot - Path to the template root (contains template.json)
+ * @returns {Object} Parsed and validated template metadata
+ */
+export async function validateTemplate(templateRoot) {
+  // Check for template.json
+  const metadataPath = path.join(templateRoot, 'template.json')
+  if (!existsSync(metadataPath)) {
+    throw new ValidationError(
+      `Missing template.json in ${templateRoot}`,
+      ErrorCodes.MISSING_TEMPLATE_JSON,
+      { path: templateRoot }
+    )
+  }
+
+  // Parse template.json
+  let metadata
+  try {
+    const content = await fs.readFile(metadataPath, 'utf8')
+    metadata = JSON.parse(content)
+  } catch (err) {
+    throw new ValidationError(
+      `Invalid template.json: ${err.message}`,
+      ErrorCodes.INVALID_TEMPLATE_JSON,
+      { path: metadataPath, error: err.message }
+    )
+  }
+
+  // Check required fields
+  if (!metadata.name) {
+    throw new ValidationError(
+      'template.json missing required field: name',
+      ErrorCodes.MISSING_REQUIRED_FIELD,
+      { field: 'name' }
+    )
+  }
+
+  // Format 2: content template — foundation/ and/or site/ directories alongside template.json
+  const contentDirs = resolveContentDirs(templateRoot, metadata)
+
+  if (contentDirs.length === 0) {
+    throw new ValidationError(
+      `No content directories found in ${templateRoot}. Templates need foundation/ and/or site/ directories alongside template.json.`,
+      ErrorCodes.MISSING_CONTENT_DIR,
+      { path: templateRoot }
+    )
+  }
+
+  // A foundation or extension folder is copied over the package the CLI
+  // scaffolds, as it is. Code kept under src/ would land beside the scaffold's
+  // own empty sections/, and the project would fail to build saying only that it
+  // found no section types — so it stops here, saying what to move.
+  for (const { type, name, dir } of contentDirs) {
+    if (type !== 'foundation' && type !== 'extension') continue
+    if (['main.js', 'foundation.js'].some((file) => existsSync(path.join(dir, 'src', file)))) {
+      throw new ValidationError(
+        `The template's ${name}/ keeps its code in ${name}/src/, a layout this CLI does not scaffold. ` +
+          `A foundation or extension folder holds main.js, sections/ and styles.css at its root: ` +
+          `move ${name}/src/'s contents up into ${name}/.`,
+        ErrorCodes.NESTED_PACKAGE_CODE,
+        { dir }
+      )
+    }
+  }
+
+  return {
+    ...metadata,
+    format: 2,
+    contentDirs,
+    metadataPath
+  }
+}
+
+/**
+ * Resolve content directories from a format 2 template
+ *
+ * @param {string} templateRoot - Root of the template (contains template.json)
+ * @param {Object} metadata - Parsed template.json
+ * @returns {Array<Object>} Content directories: [{ type, name, dir, foundation? }]
+ */
+export function resolveContentDirs(templateRoot, metadata) {
+  const dirs = []
+
+  if (metadata.packages) {
+    // Multi-package template: iterate declared packages
+    for (const pkg of metadata.packages) {
+      const dir = path.join(templateRoot, pkg.name)
+      if (existsSync(dir)) {
+        dirs.push({
+          type: pkg.type,
+          name: pkg.name,
+          dir,
+          ...(pkg.foundation ? { foundation: pkg.foundation } : {})
+        })
+      }
+    }
+  } else {
+    // Standard template: look for foundation/ and site/
+    const foundationDir = path.join(templateRoot, 'foundation')
+    if (existsSync(foundationDir)) {
+      dirs.push({ type: 'foundation', name: 'foundation', dir: foundationDir })
+    }
+
+    const siteDir = path.join(templateRoot, 'site')
+    if (existsSync(siteDir)) {
+      dirs.push({ type: 'site', name: 'site', dir: siteDir })
+    }
+  }
+
+  return dirs
+}

package/src/utils/agents-stamp.js

@@ -0,0 +1,110 @@
+/**
+ * AGENTS.md version stamp utilities
+ *
+ * The stamp is an HTML comment on the first line: <!-- uniweb-agents v0.8.32 -->
+ * Used by `doctor` (freshness check) and `update` (regeneration).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { getCliVersion } from '../versions.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+const STAMP_PATTERN = /^<!-- uniweb-agents v([\d.]+) -->/
+
+/**
+ * Read the version stamp from an AGENTS.md file
+ * @param {string} filePath - Absolute path to AGENTS.md
+ * @returns {string|null} Version string or null if no stamp
+ */
+export function readAgentsVersion(filePath) {
+  if (!existsSync(filePath)) return null
+  try {
+    const firstLine = readFileSync(filePath, 'utf8').split('\n')[0]
+    const match = firstLine.match(STAMP_PATTERN)
+    return match ? match[1] : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Generate AGENTS.md content with version stamp
+ * @returns {string} Full AGENTS.md content with stamp
+ */
+export function generateAgentsContent() {
+  const partialsDir = join(__dirname, '..', '..', 'partials')
+  const agentsContent = readFileSync(join(partialsDir, 'agents.md'), 'utf8')
+  return `<!-- uniweb-agents v${getCliVersion()} -->\n${agentsContent}\n`
+}
+
+/**
+ * ⭐ THE ONE PART OF AGENTS.md A PROJECT KEEPS: its project-notes blocks. `update` rewrites the
+ * file from this CLI's partial, so a note written anywhere else in it is lost on the next version.
+ * A block runs from a `<!-- project-notes:start -->` line to a `<!-- project-notes:end -->` line,
+ * and is carried over verbatim, at the end of the new file. ⛔ Until 2026-10-01 nothing was kept.
+ *
+ * A marker is a line of its own, outside a code fence — so the partial can name the markers in a
+ * sentence without its own text being taken for a block.
+ */
+export const PROJECT_NOTES_START = '<!-- project-notes:start -->'
+export const PROJECT_NOTES_END = '<!-- project-notes:end -->'
+
+const MARKER_LINE = /^<!--\s*project-notes:(start|end)\s*-->$/
+const FENCE_LINE = /^(`{3,}|~{3,})/
+
+/**
+ * The project-notes blocks of an AGENTS.md, in order, each from its start line to its end line.
+ *
+ * @param {string} text
+ * @returns {{ blocks: string[] } | { error: string }} an error when the markers do not pair up —
+ *   where a block ends would be a guess, and a wrong one loses notes
+ */
+export function readProjectNotes(text) {
+  const blocks = []
+  let block = null
+  let fence = null
+  let lineNumber = 0
+  for (const line of String(text ?? '').split(/(?<=\n)/)) {
+    lineNumber++
+    const trimmed = line.trim()
+    const fenceMark = trimmed.match(FENCE_LINE)?.[1]
+    if (fenceMark && (!fence || fenceMark.startsWith(fence))) fence = fence ? null : fenceMark
+    const marker = !fence && !fenceMark ? trimmed.match(MARKER_LINE)?.[1] : null
+
+    if (marker === 'start') {
+      if (block) return { error: `a second ${PROJECT_NOTES_START} on line ${lineNumber}, before the first one's ${PROJECT_NOTES_END}` }
+      block = [line]
+    } else if (marker === 'end') {
+      if (!block) return { error: `${PROJECT_NOTES_END} on line ${lineNumber} has no ${PROJECT_NOTES_START} before it` }
+      block.push(line)
+      blocks.push(block.join('').replace(/\s+$/, ''))
+      block = null
+    } else if (block) {
+      block.push(line)
+    }
+  }
+  if (block) return { error: `${PROJECT_NOTES_START} has no ${PROJECT_NOTES_END} after it` }
+  return { blocks }
+}
+
+/**
+ * AGENTS.md as `update` writes it: this CLI's partial, stamped, and the project-notes blocks of the
+ * file it replaces after it.
+ *
+ * @param {string|null} existing - the current AGENTS.md, or null when there is none
+ * @returns {{ content: string, kept: number } | { error: string }}
+ */
+export function refreshAgentsContent(existing) {
+  const fresh = generateAgentsContent()
+  if (existing == null) return { content: fresh, kept: 0 }
+  const notes = readProjectNotes(existing)
+  if (notes.error) return notes
+  if (!notes.blocks.length) return { content: fresh, kept: 0 }
+  return {
+    content: `${fresh.replace(/\s+$/, '')}\n\n${notes.blocks.join('\n\n')}\n`,
+    kept: notes.blocks.length,
+  }
+}

package/src/utils/args.js

@@ -0,0 +1,126 @@
+/**
+ * argv parsing helpers shared across CLI commands.
+ */
+
+/**
+ * Read `--flag value` from argv. Accepts both `--flag value` and
+ * `--flag=value`.
+ *
+ * Returns:
+ *   - undefined when the flag is absent
+ *   - null when the flag is present without a value (last arg, next is
+ *     another flag, or `--flag=` empty form)
+ *   - string when the flag carries a value
+ *
+ * The three-state return lets callers distinguish "not given" (e.g.,
+ * fall back to a default) from "given but empty" (e.g., trigger an
+ * interactive prompt).
+ *
+ * @param {string[]} args
+ * @param {string} name — Including the leading dashes, e.g. '--host'.
+ * @returns {string | null | undefined}
+ */
+/**
+ * The workspace a site command names — `--org @acme` — and, on a site's first push or
+ * publish, the org it is created under.
+ *
+ * ⛔ `--as-org` is RETIRED (2026-09-23). It mirrored the wire's `?as_org=`, which the
+ * `x-uniweb-workspace` header replaced; `flag-guard.js` refuses it and names `--org`.
+ *
+ * @param {string[]} args
+ * @returns {string|null|undefined}
+ */
+export function readOrgFlag(args) {
+  return readFlagValue(args, '--org')
+}
+
+/**
+ * Every `--flag` / `-f` token in `args` that `known` does not list.
+ *
+ * The CLI reads flags by scanning argv for a literal, so an unrecognized flag is
+ * not an error — it is *invisible*, and whatever it was meant to change silently
+ * keeps its default. The sharp cases were `--backend` and `--token`, which aimed a
+ * command and chose its identity; both left the backend commands on 2026-09-21
+ * (the login does both now), and the guard names the login when either is passed.
+ *
+ * Scanning rules, chosen to avoid false positives (a wrong rejection is worse than
+ * a missed one — it breaks a working command):
+ *  - only tokens beginning with `-` are candidates; a VALUE is never one unless it
+ *    itself looks like a flag, which `readFlagValue` already refuses to consume;
+ *  - `--flag=value` is checked on the name half;
+ *  - a bare `--` ends flag scanning, the POSIX convention;
+ *  - a lone `-` is a value (stdin), not a flag.
+ *
+ * @param {string[]} args
+ * @param {string[]} known - every flag this command accepts, with dashes
+ * @returns {string[]} the unrecognized tokens, in order, deduped
+ */
+export function findUnknownFlags(args, known) {
+  const set = new Set(known)
+  const out = []
+  for (const raw of args) {
+    if (raw === '--') break
+    if (raw === '-' || !raw.startsWith('-')) continue
+    const name = raw.split('=')[0]
+    if (set.has(name) || out.includes(name)) continue
+    out.push(name)
+  }
+  return out
+}
+
+/** Levenshtein distance, small and iterative — used only for a suggestion. */
+function editDistance(a, b) {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0]
+    prev[0] = i
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = prev[j]
+      prev[j] = Math.min(
+        prev[j] + 1,
+        prev[j - 1] + 1,
+        diag + (a[i - 1] === b[j - 1] ? 0 : 1)
+      )
+      diag = tmp
+    }
+  }
+  return prev[b.length]
+}
+
+/**
+ * The closest known flag to `flag`, or null when nothing is close enough.
+ * The threshold scales with length so `--forcee` → `--force` is offered while two
+ * unrelated short flags are not.
+ * @param {string} flag
+ * @param {string[]} known
+ * @returns {string|null}
+ */
+export function didYouMean(flag, known) {
+  let best = null
+  let bestD = Infinity
+  for (const k of known) {
+    const d = editDistance(flag, k)
+    if (d < bestD) {
+      bestD = d
+      best = k
+    }
+  }
+  const limit = Math.max(2, Math.floor(flag.length / 3))
+  return best && bestD <= limit ? best : null
+}
+
+export function readFlagValue(args, name) {
+  const eqPrefix = name + '='
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === name) {
+      const next = args[i + 1]
+      if (next === undefined || next.startsWith('--')) return null
+      return next
+    }
+    if (args[i].startsWith(eqPrefix)) {
+      const v = args[i].slice(eqPrefix.length)
+      return v === '' ? null : v
+    }
+  }
+  return undefined
+}

package/src/utils/asset-upload.js

@@ -0,0 +1,270 @@
+/**
+ * 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
+ *               content address. The response carries one entry per file
+ *               ({ path, id, ext, present?, method, url, headers }) plus mode:
+ *               'direct' (dev — URLs point back at the backend) or 'presigned'
+ *               (prod — storage PUTs). `id` is the lowercase-hex sha256 of the
+ *               bytes; we READ it from the response (never depend on id == sha256)
+ *               so the client stays correct if the derivation ever changes.
+ *   2. UPLOAD — PUT each NEW file's raw bytes to its URL with the given headers.
+ *               Order is irrelevant (unlike code-upload, there is no "entry").
+ *               Skip-list: an entry the plan marks `present: true` is already in
+ *               the content-addressed store, so we SKIP the PUT but still record
+ *               its id+ext for the rewrite. Absent `present` ⇒ false — an older
+ *               backend without the flag uploads everything (today's behavior).
+ *
+ * Assets are content-addressed and global WITHIN ONE BACKEND: identical bytes →
+ * same id → dedup across that backend's sites and idempotent re-deploys (a
+ * re-PUT is a cheap no-op). This 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.
+ *
+ * ⛔ **"Global" is the DEDUP SCOPE, not a claim about other backends.** An id,
+ * and the presence of the bytes behind it, are facts about the backend that
+ * answered the PLAN and about nothing else — where a backend keeps them is its
+ * own business and not a shape this lane models. ⚠️ This said only "GLOBAL" until
+ * 2026-09-20 and was read as "the same id works on any backend", which made
+ * `assets.json` look portable in a multi-backend design. It is not: `sync.json`
+ * keeps asset ids per backend (`backends.<origin>.assets`), and the backend ORIGIN
+ * is the segregation value the CLI has.
+ *
+ * ⚠️ Do not infer portability from `id` looking like the sha256 either — we read
+ * it from the response precisely so the derivation is never load-bearing here.
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { contentTypeFor } from './code-upload.js'
+import { fetchWithRetry, isTransientStatus } from './fetch-retry.js'
+
+/**
+ * Walk a built site's `dist/assets/` and produce the upload file list. `path` is
+ * POSIX-relative to distDir (e.g. `assets/hero-ab12cd34.webp`); `localUrl` is how
+ * the built content references the asset (`/assets/...`) — the rewrite key.
+ * Returns `[]` when there is no `assets/` dir (an image-free site).
+ *
+ * @param {string} distDir - the site's built dist/ directory
+ * @returns {Array<{ path: string, content_type: string, size: number, sha256: string, localUrl: string, diskPath: string }>}
+ */
+export function collectSiteAssets(distDir) {
+  const assetsDir = join(distDir, 'assets')
+  if (!existsSync(assetsDir)) return []
+  const files = []
+  const walk = (dir, prefix) => {
+    for (const name of readdirSync(dir).sort()) {
+      const full = join(dir, name)
+      const rel = prefix ? `${prefix}/${name}` : name
+      const st = statSync(full)
+      if (st.isDirectory()) {
+        walk(full, rel)
+      } else if (st.isFile()) {
+        const bytes = readFileSync(full)
+        files.push({
+          path: `assets/${rel}`,
+          content_type: contentTypeFor(name),
+          size: st.size,
+          sha256: createHash('sha256').update(bytes).digest('hex'),
+          localUrl: `/assets/${rel}`,
+          diskPath: full
+        })
+      }
+    }
+  }
+  walk(assetsDir, '')
+  return files
+}
+
+/**
+ * Deliver a site's assets: plan, then PUT each NEW file. Returns the rewrite map
+ * (`localUrl → { id, ext, serveUrl }`) — populated for files that uploaded
+ * successfully OR that the plan reports already `present`, so a partial failure
+ * never injects a broken serve URL into content. Throws only on a plan-level
+ * failure; per-file PUT failures surface in `failed`.
+ *
+ * `serveUrl` is the backend's canonical, ready-built serve URL for the asset (the
+ * plan entry's `serve_url`; content-addressed, lane-independent). Callers embed it
+ * verbatim — origin-relative forms included. Nothing composes one: see the note at
+ * the foot of this file for why the reconstruction helper was removed.
+ *
+ * Skip-list (content-addressed dedup): a plan entry with `present: true` is
+ * already in the global store — we don't re-PUT it, but we DO record its id+ext
+ * so the rewrite covers every asset. A backend that omits the flag (absent ⇒
+ * false) uploads everything, exactly as before.
+ *
+ * @param {object} opts
+ * @param {string} opts.apiBase  - backend origin (e.g. http://localhost:8080)
+ * @param {string} opts.token    - bearer (same session as deploy/register)
+ * @param {string} opts.distDir  - the site's built dist/ directory
+ * @param {Array}  [opts.files]  - pre-collected list (default: collectSiteAssets)
+ * @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,
+  siteUuid = null,
+  onProgress = () => {}
+}) {
+  const list = files || collectSiteAssets(distDir)
+  if (!list.length) {
+    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}`
+    },
+    body: JSON.stringify({
+      // 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(() => '')
+    // 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'
+  const uploads = Array.isArray(plan.uploads) ? plan.uploads : []
+  const byPath = new Map(list.map((f) => [f.path, f]))
+
+  const uploaded = []
+  const skipped = []
+  const failed = []
+  const assetsByLocalUrl = {}
+
+  for (const up of uploads) {
+    const src = byPath.get(up.path)
+    if (!src) continue // backend echoed a path we didn't send — ignore
+
+    // Skip-list: the bytes are already in the content-addressed store. No PUT,
+    // but still record id+ext so the rewrite covers this asset. `present` absent
+    // ⇒ 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
+      }
+      continue
+    }
+
+    const headers = { ...(up.headers || {}), 'x-uniweb-sha256': src.sha256 }
+    // Direct-mode PUTs are authed requests to the backend; presigned URLs are
+    // self-signed, so a foreign auth header can break the SigV4 target. This is
+    // the only mode-aware line in the client (same rule as code-upload).
+    if (mode !== 'presigned') headers.Authorization = `Bearer ${token}`
+    onProgress(`↑ ${src.path}`)
+    let putRes
+    try {
+      // The plan's url may be origin-relative (direct mode → the backend) or
+      // absolute (presigned → storage); new URL() resolves both.
+      // ⭐ **Retried.** A single connection-level failure used to fail the whole
+      // verb after every other file had already gone up. The PUT is idempotent
+      // here — same bytes, same target, verified by `x-uniweb-sha256` on receipt
+      // — so repeating it is safe by construction, which is why this opts in to
+      // `retryOnStatus` rather than inheriting it.
+      //
+      // ⚠️ 120s per attempt, not the helper's 30s default: this bounds the time
+      // to send a whole BODY, and aborting a legitimately slow upload only to
+      // retry it is worse than not timing out at all.
+      putRes = await fetchWithRetry(new URL(up.url, origin), {
+        method: up.method || 'PUT',
+        headers,
+        body: src.bytes ?? readFileSync(src.diskPath)
+      }, { timeoutMs: 120_000, retryOnStatus: isTransientStatus })
+    } catch (err) {
+      failed.push({ path: src.path, status: 0, detail: err.message })
+      continue
+    }
+    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
+      }
+    } else {
+      failed.push({
+        path: src.path,
+        status: putRes.status,
+        detail: await putRes.text().catch(() => '')
+      })
+    }
+  }
+
+  return { mode, uploaded, skipped, failed, assetsByLocalUrl }
+}
+
+// ⛔ `buildAssetUrl(origin, assetBase, id, ext)` was removed 2026-08-17. Do not
+// bring it back.
+//
+// It composed `{assetBase}dist/{id}/base.{ext}` — i.e. it encoded the BACKEND's
+// path layout inside a published CLI, on a release cadence the backend cannot
+// move, defaulting to one hardcoded production host for every deployment. Read
+// the plan entry's `serve_url` instead. It is part of the asset-plan contract:
+// present on EVERY entry, on both the direct and presigned lanes, including
+// entries the plan reports as already `present` — the backend covers that with a
+// test of its own (confirmed 2026-08-17).
+//
+// An entry without one is UNADDRESSABLE — fail, never guess. A composed location
+// is silently wrong wherever the deployment does not match the guess; a missing
+// one is visibly missing.

package/src/utils/bytes.js

@@ -0,0 +1,30 @@
+/**
+ * Byte formatting for refusal messages.
+ *
+ * Lives on its own because TWO lanes now print a storage refusal — the asset plan
+ * (`backend/site-media.js`) and the site create (`backend/site-sync.js`) — and the
+ * numbers must read identically in both. A second copy would drift in units or
+ * rounding, and a user comparing "you have 1.1 GiB" against "this needs 100 MB"
+ * cannot tell a real gap from a formatting difference.
+ */
+
+const KIB = 1024
+
+/**
+ * `1073741824` → `1 GiB`. Returns null for anything that is not a usable byte
+ * count, so a refusal that omits an extra prints nothing rather than `undefined`.
+ * @param {unknown} n
+ * @returns {string|null}
+ */
+export 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]}`
+}