uniweb 0.13.17 → 0.14.0

package/src/commands/push.js

@@ -55,7 +55,7 @@
 import { writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { emitSyncPackages } from '@uniweb/build/uwx'
-import { uploadSiteMedia, isStorageRefusal } from '../backend/site-media.js'
+import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
 import {
@@ -65,16 +65,26 @@ import {
   readItemBaseVersions,
   readItemUuids,
   ensureItemUuids,
-  pushSyncPackages,
+  ensureSiteExists,
+  clearRemoteSyncStateIfUnbound,
+  pushSyncPackages
 } from '../backend/site-sync.js'
 
 // Re-exported for downstream importers (pull.js, push.test.js) that read these
 // helpers from this module — their canonical home is now ../backend/site-sync.js.
-export { extractMintedSiteUuid, makeModelResolver } from '../backend/site-sync.js'
+export {
+  extractMintedSiteUuid,
+  makeModelResolver
+} from '../backend/site-sync.js'
 
 const colors = {
-  reset: '\x1b[0m', bright: '\x1b[1m', dim: '\x1b[2m',
-  red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', blue: '\x1b[36m',
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[36m'
 }
 const log = console.log
 const success = (m) => log(`${colors.green}✓${colors.reset} ${m}`)
@@ -86,7 +96,8 @@ function flagValue(args, name) {
   const eq = args.find((a) => a.startsWith(`${name}=`))
   if (eq) return eq.slice(name.length + 1)
   const i = args.indexOf(name)
-  if (i !== -1 && args[i + 1] && !args[i + 1].startsWith('-')) return args[i + 1]
+  if (i !== -1 && args[i + 1] && !args[i + 1].startsWith('-'))
+    return args[i + 1]
   return null
 }
 
@@ -116,7 +127,7 @@ export async function push(args = []) {
     siteBackend,
     token: tokenFlag,
     args,
-    command: 'Syncing',
+    command: 'Syncing'
   })
 
   // Build BOTH directional packages (the producer side). Each carries its own
@@ -140,18 +151,51 @@ export async function push(args = []) {
   // push exists to avoid. `publish` uploaded and rewrote; push dropped
   // `localAssets` on the floor.
   //
-  // Ordering is deliberate: BEFORE `ensureItemUuids`, which mints uuids on the
-  // backend. A refusal here then leaves nothing minted and nothing submitted.
+  // The upload runs before `ensureItemUuids`, and the reason once recorded here —
+  // "BEFORE `ensureItemUuids`, which mints uuids on the backend, so a refusal
+  // leaves nothing minted" — is FALSE. `ensureItemUuids` mints nothing: it reads a
+  // local cache, and if that is empty it reads `site.yml::$uuid` and returns
+  // immediately when there is none (the first-push case). Its only backend call is
+  // a GET (`pullSiteContent`); its only write is a local file. So this ordering is
+  // not protecting what that comment claimed, and is under review — an upload is a
+  // durable, metered write, which makes uploading first the thing that leaves bytes
+  // behind when a later step fails.
   //
   // The probe emit runs WITHOUT `priorHashes`, so it surfaces every local ref
   // rather than only the changed ones. That is not waste — the lane is
   // content-addressed with a `present` skip-list, so unchanged bytes are a no-op
   // PUT. It is also what makes the storage rule fall out of the mechanism instead
-  // of needing a special case: a content-only push presents the same plan as last
-  // time, every file is already present, zero new bytes are requested, and no
-  // quota check can refuse it. Only a push that genuinely ADDS bytes can be
+  // of needing a special case: a content-only push adds no new stored content, so
+  // a quota has nothing to refuse. Only a push that genuinely ADDS bytes can be
   // blocked.
   //
+  // Two claims live here and only ONE is a guarantee, per the backend's asset
+  // accounting model:
+  //   - "moves zero bytes" is the COMMON CASE, not a property. `present` is an
+  //     optimization: a failed presence probe degrades to all-absent, so unchanged
+  //     bytes may be re-PUT. It is never a false positive, so skipping stays safe.
+  //   - "is never refused for storage" IS a property, because metering is
+  //     IDEMPOTENT per (workspace, asset) and recorded at PLAN time. Presenting an
+  //     asset already on this workspace's books charges nothing, so a push that
+  //     changes only content meters nothing and cannot be refused.
+  //
+  // ⚠️ "unchanged bytes skip the transfer" is TRUE. "…and are therefore FREE" is
+  // NOT — do not write it into a message, a summary, or a comment. Every upload is
+  // chargeable; deduplication is the backend's storage optimization, not the user's
+  // discount, so an asset another workspace already uploaded comes back
+  // `present: true`, never PUTs, and is STILL charged to this one. What is free is
+  // copying URLs around (duplicating a site, a snapshot, a backup).
+  //
+  // Consequently `needed_bytes` = "assets not yet on this workspace's books", which
+  // can be NON-ZERO with zero transfers — so a push can print no `↑` line at all and
+  // still be refused. A refusal message must talk about assets new to the workspace,
+  // never "the files being uploaded", and must not size itself from what moved.
+  //
+  // Two framings were proposed and WITHDRAWN in-channel; do not reintroduce either:
+  // "charged on distinct stored content", and "the quota fails open on a
+  // presence-probe failure" (retired — `needed_bytes` reads the ledger, not the
+  // probe, so the property no longer depends on that error path behaving).
+  //
   // It also has to be this emit that carries `assetRewrite` below: the push cache
   // stores hashes of the REWRITTEN content, so the emit compared against it must
   // rewrite too, or every entity reads as changed forever.
@@ -161,7 +205,7 @@ export async function push(args = []) {
     try {
       const probe = await emitSyncPackages(siteDir, {
         ...(foundationDir ? { foundationDir } : {}),
-        resolveModel: makeModelResolver({ client, offline: false }),
+        resolveModel: makeModelResolver({ client, offline: false })
       })
       mediaRefs = probe.localAssets || []
     } catch (err) {
@@ -169,53 +213,89 @@ export async function push(args = []) {
       return { exitCode: 2 }
     }
     if (mediaRefs.length) {
+      // The site has to exist before its bytes do — an upload with no owning
+      // entity is charged and cannot be freed, because freeing means deleting the
+      // owner. A no-op once `$uuid` is set, so only a never-synced site pays.
+      const dropped = clearRemoteSyncStateIfUnbound(siteDir)
+      if (dropped.length) {
+        note(
+          `Cleared stale sync state from a previous site (${dropped.join(', ')}).`
+        )
+      }
+      const site = await ensureSiteExists({ client, siteDir, asOrg, note })
+      if (!site.uuid) {
+        error(`Could not create the site on the backend: ${site.reason}`)
+        note('Nothing was uploaded and nothing was charged.')
+        return { exitCode: 1 }
+      }
       info('Uploading media…')
       try {
-        const { map, failed } = await uploadSiteMedia(client, siteDir, mediaRefs, {
-          onProgress: (m) => note(`  ${m}`),
-          warn: (m) => note(`! ${m}`),
-        })
+        const { map, failed } = await uploadSiteMedia(
+          client,
+          siteDir,
+          mediaRefs,
+          {
+            siteUuid: site.uuid,
+            onProgress: (m) => note(`  ${m}`),
+            warn: (m) => note(`! ${m}`)
+          }
+        )
         // Bytes that did not land must not be pushed around: the content would go
         // up still naming the local path, so the teammate sees the broken image
         // this whole change exists to prevent, and the only trace is a warning. A
         // missing FILE is a different thing — already broken before us, warned by
         // the uploader, and not worth blocking a push over.
         if (failed.length) {
-          error(`${failed.length} asset(s) failed to upload — nothing was pushed.`)
+          error(
+            `${failed.length} asset(s) failed to upload — nothing was pushed.`
+          )
           for (const f of failed) note(`  ${f.path} (HTTP ${f.status})`)
           return { exitCode: 1 }
         }
         if (Object.keys(map).length) assetRewrite = map
-        note(`${Object.keys(map).length}/${mediaRefs.length} media ref(s) → serve URL`)
+        note(
+          `${Object.keys(map).length}/${mediaRefs.length} media ref(s) → serve URL`
+        )
       } catch (err) {
-        if (isStorageRefusal(err)) {
-          error('Storage quota reached — this push adds media that does not fit.')
-          note('  A push that changes only content costs no storage and still works.')
-          note('  Remove or shrink the new assets, or raise the plan limit, then re-run.')
-          note(`  ${err.message}`)
-          return { exitCode: 1 }
+        // Typed plan refusals get their own account. Note the storage one must not
+        // be phrased from what moved — see describeAssetRefusal's rule 1; a push can
+        // print no `↑` line at all and still be refused.
+        const refusal = describeAssetRefusal(err)
+        if (refusal) {
+          error(refusal.headline)
+          for (const line of refusal.notes) note(line)
+        } else {
+          error(`Media upload failed: ${err.message}`)
         }
-        error(`Media upload failed: ${err.message}`)
         return { exitCode: 1 }
       }
     }
   }
 
-  const itemUuids = (output || dryRun)
-    ? readItemUuids(siteDir)
-    : await ensureItemUuids({ client, siteDir, note })
+  const itemUuids =
+    output || dryRun
+      ? readItemUuids(siteDir)
+      : await ensureItemUuids({ client, siteDir, note })
   let pkg
   try {
     pkg = await emitSyncPackages(siteDir, {
       ...(foundationDir ? { foundationDir } : {}),
-      resolveModel: makeModelResolver({ client, offline: Boolean(output) || dryRun }),
+      resolveModel: makeModelResolver({
+        client,
+        offline: Boolean(output) || dryRun
+      }),
       priorHashes,
       sendAll,
       itemUuids,
       // Both grains are dropped together by --force: one flag, one meaning,
       // no partial-force mode.
-      ...(force ? {} : { baseVersions: readBaseVersions(siteDir), itemBaseVersions: readItemBaseVersions(siteDir) }),
-      ...(assetRewrite ? { assetRewrite } : {}),
+      ...(force
+        ? {}
+        : {
+            baseVersions: readBaseVersions(siteDir),
+            itemBaseVersions: readItemBaseVersions(siteDir)
+          }),
+      ...(assetRewrite ? { assetRewrite } : {})
     })
   } catch (err) {
     error(`Could not build the sync package: ${err.message}`)
@@ -225,36 +305,53 @@ export async function push(args = []) {
   log('')
   for (const w of warnings) note(`! ${w}`)
 
-  const totalEntities = (siteContent?.entityCount || 0) + (collections?.entityCount || 0)
+  const totalEntities =
+    (siteContent?.entityCount || 0) + (collections?.entityCount || 0)
 
   // Nothing changed since the last push — the backend is already up to date.
   if (totalEntities === 0) {
-    success(`Nothing to push — ${skipped} entit${skipped === 1 ? 'y' : 'ies'} unchanged since the last push.`)
+    success(
+      `Nothing to push — ${skipped} entit${skipped === 1 ? 'y' : 'ies'} unchanged since the last push.`
+    )
     return { exitCode: 0 }
   }
-  if (siteContent) info(`${colors.bright}site-content${colors.reset} → ${siteContent.models.join(', ')}`)
+  if (siteContent)
+    info(
+      `${colors.bright}site-content${colors.reset} → ${siteContent.models.join(', ')}`
+    )
   if (collections) {
     const n = collections.entityCount
-    info(`${colors.bright}collections${colors.reset} (${n} entit${n === 1 ? 'y' : 'ies'}) → ${collections.models.join(', ')}`)
+    info(
+      `${colors.bright}collections${colors.reset} (${n} entit${n === 1 ? 'y' : 'ies'}) → ${collections.models.join(', ')}`
+    )
   }
   if (skipped) note(`${skipped} unchanged, skipped`)
 
   // Preview paths — no submit, no auth. Two lanes → up to two files / two routes.
   if (output) {
     const base = output.replace(/\.uwx$/, '')
-    if (siteContent) writeFileSync(resolve(`${base}.site-content.uwx`), siteContent.buffer)
-    if (collections) writeFileSync(resolve(`${base}.collections.uwx`), collections.buffer)
-    const lanes = [siteContent && 'site-content', collections && 'collections'].filter(Boolean)
+    if (siteContent)
+      writeFileSync(resolve(`${base}.site-content.uwx`), siteContent.buffer)
+    if (collections)
+      writeFileSync(resolve(`${base}.collections.uwx`), collections.buffer)
+    const lanes = [
+      siteContent && 'site-content',
+      collections && 'collections'
+    ].filter(Boolean)
     success(`Wrote ${lanes.join(' + ')} .uwx — not submitted`)
     return { exitCode: 0 }
   }
   if (dryRun) {
     if (siteContent) {
       const verb = siteContentUuid ? 'update' : 'create'
-      info(`Dry run — would ${verb} content at ${colors.dim}${client.origin}${colors.reset}`)
+      info(
+        `Dry run — would ${verb} content at ${colors.dim}${client.origin}${colors.reset}`
+      )
     }
     if (collections) {
-      info(`Dry run — would push the folder at ${colors.dim}${client.origin}${colors.reset}`)
+      info(
+        `Dry run — would push the folder at ${colors.dim}${client.origin}${colors.reset}`
+      )
     }
     return { exitCode: 0 }
   }
@@ -266,7 +363,12 @@ export async function push(args = []) {
     siteDir,
     pkg,
     asOrg,
-    report: { info, note, error, dim: (s) => `${colors.dim}${s}${colors.reset}` },
+    report: {
+      info,
+      note,
+      error,
+      dim: (s) => `${colors.dim}${s}${colors.reset}`
+    }
   })
   if (result.exitCode !== 0) return { exitCode: result.exitCode }
   success(

package/src/commands/refresh.js

@@ -39,19 +39,29 @@ import { join } from 'node:path'
 import yaml from 'js-yaml'
 
 import { resolveSiteDir } from './deploy.js'
-import { isGitRepo, hasRemote, pullRemote, headProvenance } from '../utils/git.js'
+import {
+  isGitRepo,
+  hasRemote,
+  pullRemote,
+  headProvenance
+} from '../utils/git.js'
 import { probeUnpushed } from '../backend/site-sync.js'
 
 const c = {
-  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
-  cyan: '\x1b[36m', green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m',
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m'
 }
 const say = {
   ok: (m) => console.log(`${c.green}✓${c.reset} ${m}`),
   info: (m) => console.log(`${c.cyan}→${c.reset} ${m}`),
   warn: (m) => console.log(`${c.yellow}⚠${c.reset} ${m}`),
   err: (m) => console.error(`${c.red}✗${c.reset} ${m}`),
-  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`)
 }
 
 // Forward a flag AND its value to the delegated verb. `--backend http://x` is two
@@ -65,7 +75,8 @@ function collectPassthrough(args, names) {
     const name = names.find((n) => a === n || a.startsWith(`${n}=`))
     if (!name) continue
     out.push(a)
-    if (a === name && args[i + 1] && !args[i + 1].startsWith('-')) out.push(args[++i])
+    if (a === name && args[i + 1] && !args[i + 1].startsWith('-'))
+      out.push(args[++i])
   }
   return out
 }
@@ -119,7 +130,11 @@ export async function refresh(args = [], deps = {}) {
       // order to address them in.
       return { exitCode: 1 }
     }
-    say.dim(r.changed ? 'Took new commits from the remote.' : 'Already up to date with the remote.')
+    say.dim(
+      r.changed
+        ? 'Took new commits from the remote.'
+        : 'Already up to date with the remote.'
+    )
     consulted.push('git')
   }
 
@@ -133,7 +148,11 @@ export async function refresh(args = [], deps = {}) {
     const pull = deps.pull || (await import('./pull.js')).pull
     // `--merge` rather than a plain pull: an author editing a different part of the
     // same section is not a conflict, and should not be presented as one.
-    const passthrough = collectPassthrough(args, ['--backend', '--registry', '--token'])
+    const passthrough = collectPassthrough(args, [
+      '--backend',
+      '--registry',
+      '--token'
+    ])
     const res = await pull(['--merge', ...passthrough])
     conflicts = res?.merge?.conflicted?.length ?? 0
     if (res?.exitCode && !conflicts) {
@@ -151,14 +170,20 @@ export async function refresh(args = [], deps = {}) {
   for (const s of skipped) say.dim(`Skipped: ${s}`)
 
   const git = headProvenance(siteDir)
-  if (git) say.dim(`Commit : ${git.sha.slice(0, 8)}${git.dirty ? ' (working tree has changes)' : ''}`)
+  if (git)
+    say.dim(
+      `Commit : ${git.sha.slice(0, 8)}${git.dirty ? ' (working tree has changes)' : ''}`
+    )
 
   // What is still yours to send. The point of a milestone check is knowing both
   // directions, not just that you took what was waiting.
   if (!skipBackend && siteContentUuid(siteDir)) {
     try {
       const probe = await probeUnpushed(siteDir)
-      if (probe.changed) say.dim(`Unpushed: ${probe.changed} entit${probe.changed === 1 ? 'y' : 'ies'} changed locally`)
+      if (probe.changed)
+        say.dim(
+          `Unpushed: ${probe.changed} entit${probe.changed === 1 ? 'y' : 'ies'} changed locally`
+        )
     } catch {
       /* the probe is a courtesy; never fail a refresh over it */
     }
@@ -166,7 +191,9 @@ export async function refresh(args = [], deps = {}) {
 
   console.log('')
   if (conflicts) {
-    say.err(`${conflicts} file(s) need you to resolve conflicts before pushing.`)
+    say.err(
+      `${conflicts} file(s) need you to resolve conflicts before pushing.`
+    )
     return { exitCode: 1 }
   }
   say.ok('Up to date.')