uniweb 1.31.0 → 1.31.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.31.0",
3
+ "version": "1.31.2",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -43,13 +43,13 @@
43
43
  "tar": "^7.5.21",
44
44
  "@uniweb/core": "~1.6.9",
45
45
  "@uniweb/semantic-parser": "~1.13.2",
46
- "@uniweb/schemas": "~1.7.0",
47
- "@uniweb/content-writer": "~1.3.1"
46
+ "@uniweb/content-writer": "~1.3.1",
47
+ "@uniweb/schemas": "~1.7.0"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.20.0",
51
50
  "@uniweb/semantic-parser": "~1.13.2",
52
- "@uniweb/content-reader": "~1.5.9"
51
+ "@uniweb/content-reader": "~1.5.9",
52
+ "@uniweb/build": "~1.20.2"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -136,7 +136,7 @@ data: {
136
136
 
137
137
  `single`/`whole` are refused over a schema whose root is a list (`@std/nav`, `@std/form`). A `whole` key its source cannot answer whole is `null`. An optional `schemas.config.js` routes a scope to a folder: `export default { '@acme': '../shared/acme-schemas' }` — a routed scope wins, has no package fallback, and `@/`/`@uniweb` are never routable. Worked examples: `development/schemas-in-practice.md`.
138
138
 
139
- **Any foundation can use a data schema another defines, by its full name** — `data: { members: '@acme/member' }`, `schema: '@acme/member'` in `queries.yml`. No backend is involved, and in a workspace nothing to configure: a local build, `uniweb dev` included, reads the type from the foundation whose name gives the `@acme` scope and whose own `schemas/` defines it. Two packages of the workspace defining it stop the build, naming both. A type outside the workspace comes from `schemas.config.js` (`'@acme/member': '../elsewhere/member.yml'`, or the scope's folder), which wins over the workspace, or an installed `@acme/schemas` package. A scope is a namespace that keeps names from colliding, not a limit on who uses a type. So a type another foundation defines is named, never copied: a copy of its file is a second definition of the same type, which `doctor` points out where the two foundations' names give one scope (`type-defined-twice`). Registering, which only a site with a backend does, names such a type and sends no definition of it. A site can hold another site's records of a type too: `paths: { 'records/acme/member': '../../hub/site/records/acme/member' }` in its `site.yml` reads them as its own, a push adds them by reference rather than as copies once their own site has pushed them, and a pull leaves those files alone. A site's records of it sit in `records/acme/member/`; in `records/member/` they'd be the foundation's own `@/member`.
139
+ **Any foundation can use a data schema another defines, by its full name** — `data: { members: '@acme/member' }`, `schema: '@acme/member'` in `queries.yml`. No backend is involved, and in a workspace nothing to configure: a local build, `uniweb dev` included, reads the type from the foundation whose name gives the `@acme` scope and whose own `schemas/` defines it. Two packages of the workspace defining it stop the build, naming both. A type outside the workspace comes from `schemas.config.js` (`'@acme/member': '../elsewhere/member.yml'`, or the scope's folder), which wins over the workspace, or an installed `@acme/schemas` package. A scope is a namespace that keeps names from colliding, not a limit on who uses a type. So a type another foundation defines is named, never copied: a copy of its file is a second definition of the same type, which `doctor` points out where the two foundations' names give one scope (`type-defined-twice`). Registering, which only a site with a backend does, names such a type and sends no definition of it. A push also needs one of the site's foundations to declare the type, as a section type's data key or a schema of its own: the backend refuses a query whose type none of them declares, since nothing there would render it. A site can hold another site's records of a type too: `paths: { 'records/acme/member': '../../hub/site/records/acme/member' }` in its `site.yml` reads them as its own, a push adds them by reference rather than as copies once their own site has pushed them, and a pull leaves those files alone. A site's records of it sit in `records/acme/member/`; in `records/member/` they'd be the foundation's own `@/member`.
140
140
 
141
141
  ```jsx
142
142
  function Article({ content, block }) { // data: { article: { schema: '@std/article', single: true } }
@@ -666,7 +666,7 @@ export class BackendClient {
666
666
 
667
667
  /**
668
668
  * GET /dev/registry/data-schemas/{scope}/{name} — a Model declaration, or
669
- * null on 404 (the caller then says "register it first"). Accepts `@scope/name`
669
+ * null on 404 (the caller then says to register the foundation that defines it). Accepts `@scope/name`
670
670
  * and bare `name`.
671
671
  * @param {string} modelName
672
672
  * @returns {Promise<object|null>}
@@ -765,46 +765,15 @@ export class BackendClient {
765
765
 
766
766
  // ── Site sync (push / pull) ─────────────────────────────────────────────────────
767
767
 
768
- /**
769
- * POST /dev/site — CREATE an EMPTY site and return its site-content uuid.
770
- *
771
- * The uuid exists before any content or asset does, which is the whole point:
772
- * uploaded bytes are metered against an owning entity and freed by deleting it,
773
- * so an upload with no site to charge is billed and can never be reclaimed.
774
- * Creating the site first is what makes a failed first publish leave a clearable
775
- * empty site instead of unfreeable bytes.
776
- *
777
- * A thin re-projection of the same op the app's blank-site create uses, so the
778
- * two lanes cannot drift. Adoption of `foundation` is best-effort — an
779
- * unreleased ref leaves the resolved ref null and the site still exists — but
780
- * the field itself is required and cannot be blank.
781
- *
782
- * NOT idempotent: two calls mint two sites (a name is not a unique key, by
783
- * design). Callers must guard on the site's uuid for this backend (sync.json) and
784
- * write the result back immediately — see `ensureSiteExists`.
785
- *
786
- * The owner is the workspace the client names (`setWorkspace`) — the create is where
787
- * that choice is made, once.
788
- *
789
- * @param {{ name: string, foundation: string }} opts
790
- * @returns {Promise<Response>} `{ site_content_uuid }`
791
- */
792
- async createSite({ name, foundation } = {}) {
793
- return this.request('/dev/site', {
794
- method: 'POST',
795
- // Both fields are REQUIRED: `info.name` is `required: true` on the model
796
- // (and is a plain string — an identity label, never a `{lang: …}` map, since
797
- // a localized value can vanish under locale projection and a name must always
798
- // render), and a site must resolve to a foundation. Adoption of the ref is
799
- // best-effort on the backend, but the field itself cannot be blank — so send
800
- // whatever the site declares and let the backend judge it.
801
- body: JSON.stringify({ name, foundation })
802
- })
803
- }
804
-
805
768
  /**
806
769
  * POST /dev/site/content — CREATE a site from its content lane (.uwx zip). `source`: the
807
770
  * commit the content came from (`SOURCE_HEADER`).
771
+ *
772
+ * The site is created only with content the backend takes: a refused create made none
773
+ * (measured 2026-11-09), which is why every first push creates its site here
774
+ * (`createSiteFromItsContent`). Its owner is the workspace the client names
775
+ * (`setWorkspace`). NOT idempotent: two calls make two sites, so the caller records the
776
+ * uuid it mints at once (`pushSyncPackages`).
808
777
  */
809
778
  async createSiteContent(buffer, { source } = {}) {
810
779
  return this.request('/dev/site/content', {
@@ -516,7 +516,8 @@ export function extractFinalized(payload) {
516
516
  // envelope the update/folder lanes return (the site entity is submitted alone, so its
517
517
  // minted uuid is the first finalized entry). Returns null if none is present.
518
518
  export function extractMintedSiteUuid(payload) {
519
- // `POST /dev/site` (the empty-site create) answers with the snake_case spelling;
519
+ // `POST /dev/site` (the empty-site create, which no command makes since 2026-11-09) answered
520
+ // with the snake_case spelling;
520
521
  // the content-lane CREATE has historically used the others. Both are the same
521
522
  // identity — the uuid `/dev/site/content/pull/{uuid}` accepts.
522
523
  if (typeof payload?.site_content_uuid === 'string')
@@ -546,7 +547,7 @@ function changedSummary(finalized) {
546
547
 
547
548
  // Resolve a Model NOT defined by the local foundation by reading its declaration (the
548
549
  // `@uniweb/data-schema` form) from the backend via the client. Cached per run; HTTP
549
- // 404 → null (the emitter then says "register it first"). The bearer is acquired lazily
550
+ // 404 → null (the emitter then says to register the foundation that defines it). The bearer is acquired lazily
550
551
  // by the client, so a fully-local sync never authenticates.
551
552
  //
552
553
  // `offline` (set for `-o` / `--dry-run`, and for `status`) never touches the backend — an
@@ -555,11 +556,15 @@ function changedSummary(finalized) {
555
556
  // reads, per backend — so a clone, whose foundation is not in the project to declare them, can
556
557
  // still compare offline. ⛔ Until 2026-09-26 nothing was kept, and `uniweb status` in a clone
557
558
  // could not resolve a Model ("… could not be resolved").
559
+ //
560
+ // The resolver carries `offline`, so the emitter's "could not be resolved" says this run
561
+ // never asked the backend instead of saying the backend has no such Model
562
+ // (`@uniweb/build`'s `uwx/records.js::unresolvedExplicit`).
558
563
  export function makeModelResolver({ client, offline = false, siteDir = null, backend = null }) {
559
564
  const origin = backend ?? client?.origin ?? null
560
565
  const kept = siteDir && origin ? keptModels(siteDir, origin) : {}
561
566
  const cache = new Map()
562
- return async (modelName) => {
567
+ const resolve = async (modelName) => {
563
568
  if (cache.has(modelName)) return cache.get(modelName)
564
569
  let decl
565
570
  if (offline) {
@@ -571,6 +576,8 @@ export function makeModelResolver({ client, offline = false, siteDir = null, bac
571
576
  cache.set(modelName, decl)
572
577
  return decl
573
578
  }
579
+ resolve.offline = Boolean(offline)
580
+ return resolve
574
581
  }
575
582
 
576
583
  /**
@@ -715,8 +722,8 @@ const readMap = (siteDir, backend, key) => {
715
722
  * The guidance is `uniweb forget --server <url>` now, which removes the uuid and the
716
723
  * maps together, so following it no longer leads here.
717
724
  *
718
- * Call this BEFORE `ensureSiteExists`, which mints a uuid and would otherwise make
719
- * the clone look bound before the check runs.
725
+ * Call this BEFORE the site is created (`createSiteFromItsContent`), which mints a uuid and
726
+ * would otherwise make the clone look bound before the check runs.
720
727
  */
721
728
  /**
722
729
  * Drop the five remote-derived maps unconditionally, stamping the site they now
@@ -1681,59 +1688,36 @@ function recordSiteWorkspace(siteDir, backend, owner) {
1681
1688
  }
1682
1689
 
1683
1690
  /**
1684
- * Turn a typed site-create refusal into a sentence, or null to fall through to the
1685
- * generic HTTP line.
1686
- *
1687
- * ⭐ Why this exists separately from `describeAssetRefusal`. The asset lane grew a
1688
- * typed describer because a raw status dump is useless to the person who has to act
1689
- * on it; the create lane had the same hole and nobody had met it, because until the
1690
- * backend shipped account capacity a create could not be refused for space at all.
1691
- * So this is the same fix on the second door, written before anyone hits it rather
1692
- * than after.
1693
- *
1694
- * ⛔ Branch on `reason`, never on the status. `507` alone cannot be told from any
1695
- * other 507 and carries none of the numbers a user needs, and `detail` is prose the
1696
- * backend may reword.
1697
- *
1698
- * ⚖️ The wording deliberately DIVERGES from the asset lane's on one point. There the
1699
- * allowance belongs to the site's owner, who may not be the person pushing. Here
1700
- * there is no site yet, so the only workspace in play is the one the site would be
1701
- * created in — one named with `--org` included. Saying "the site owner's workspace"
1702
- * would be incoherent for a site that does not exist.
1703
- *
1704
- * @param {string} body - the raw response body
1691
+ * A site create refused for space, as a sentence with the numbers — or null for any other problem.
1692
+ *
1693
+ * A site costs against its workspace's allowance before any content moves, so a create can be
1694
+ * refused for space with a typed `507` (`storage_quota_exceeded`, account capacity). `POST /dev/site`
1695
+ * did so; the content lane's create, the only one a push makes, did not when measured on a local
1696
+ * uniwebd on 2026-11-09. Said in either case, wherever the backend refuses.
1697
+ *
1698
+ * ⛔ Branch on `reason`, never on the status. `507` alone cannot be told from any other 507 and
1699
+ * carries none of the numbers a user needs, and `detail` is prose the backend may reword.
1700
+ *
1701
+ * ⚖️ The wording deliberately DIVERGES from the asset lane's on one point. There the allowance
1702
+ * belongs to the site's owner, who may not be the person pushing. Here there is no site yet, so the
1703
+ * only workspace in play is the one the site would be created in — one named with `--org` included.
1704
+ *
1705
+ * @param {object|null} p - the parsed problem document
1705
1706
  * @returns {string|null}
1706
1707
  */
1707
- function describeCreateRefusal(body) {
1708
- if (!body) return null
1709
- let p
1710
- try {
1711
- p = JSON.parse(body)
1712
- } catch {
1713
- return null // prose refusal, or an upstream error page
1714
- }
1715
- if (!p || typeof p !== 'object' || typeof p.reason !== 'string') return null
1716
-
1717
- const attach = describeAttachRefusal(p)
1718
- if (attach) return [attach.headline, ...attach.steps].join('\n ')
1719
-
1720
- if (p.reason === 'storage_quota_exceeded') {
1721
- const parts = []
1722
- const used = humanBytes(p.used_bytes)
1723
- const limit = humanBytes(p.limit_bytes)
1724
- const needed = humanBytes(p.needed_bytes)
1725
- if (used && limit) parts.push(`${used} of ${limit} used`)
1726
- if (needed) parts.push(`a new site needs ${needed}`)
1727
- return (
1728
- 'storage quota reached — the workspace this site would belong to has no room for it' +
1729
- (parts.length ? ` (${parts.join('; ')})` : '') +
1730
- '. Quota is returned by deleting a site or entity, not by editing content.'
1731
- )
1732
- }
1733
- // An unrecognised typed reason still beats a status dump: name it, and let the
1734
- // backend's own prose follow when it sent any.
1735
- const detail = typeof p.detail === 'string' ? p.detail : ''
1736
- return `the backend refused the site create (${p.reason})${detail ? ` — ${detail}` : ''}`
1708
+ export function describeStorageRefusal(p) {
1709
+ if (!p || typeof p !== 'object' || p.reason !== 'storage_quota_exceeded') return null
1710
+ const parts = []
1711
+ const used = humanBytes(p.used_bytes)
1712
+ const limit = humanBytes(p.limit_bytes)
1713
+ const needed = humanBytes(p.needed_bytes)
1714
+ if (used && limit) parts.push(`${used} of ${limit} used`)
1715
+ if (needed) parts.push(`a new site needs ${needed}`)
1716
+ return (
1717
+ 'storage quota reached — the workspace this site would belong to has no room for it' +
1718
+ (parts.length ? ` (${parts.join('; ')})` : '') +
1719
+ '. Quota is returned by deleting a site or entity, not by editing content.'
1720
+ )
1737
1721
  }
1738
1722
 
1739
1723
  /**
@@ -1794,103 +1778,65 @@ export function describeAttachRefusal(problem) {
1794
1778
  }
1795
1779
 
1796
1780
  /**
1797
- * Guarantee the site EXISTS on the backend before anything is uploaded against it.
1798
- *
1799
- * Ordering is the point, and it is load-bearing rather than incidental. Uploaded
1800
- * bytes are metered against an owning entity and reclaimed by deleting it, so an
1801
- * upload made before any site exists is charged and can never be freed — there is
1802
- * nothing to delete. Creating the site first turns the artifact of a failed first
1803
- * publish from *unfreeable bytes* into *an empty site*, which costs nothing to
1804
- * keep and can be cleared. (The reverse ordering was justified by a claim that
1805
- * `ensureItemUuids` mints on the backend, which it does not — see push.js.)
1806
- *
1807
- * A no-op when the site already has a uuid on this backend (sync.json), so only the
1808
- * first publish of a site pays for it. The uuid is written back immediately, keeping the window in
1809
- * which a crash could strand a site as small as one file write.
1810
- *
1811
- * @returns {Promise<{ uuid: string|null, created: boolean, reason?: string }>}
1812
- * `uuid: null` means the site could not be created; the caller decides whether
1813
- * that is fatal (it is, for any flow that uploads).
1781
+ * ⭐ A SITE'S FIRST PUSH CREATES IT FROM ITS CONTENT, before a byte is uploaded against it.
1782
+ *
1783
+ * The content lane's create (`POST /dev/site/content`) checks the content and creates the site in
1784
+ * one step: measured on a local uniwebd on 2026-11-09, a create it refused (`undeclared_type`) left
1785
+ * the workspace's sites as they were, and this copy recorded nothing. So a first push the backend
1786
+ * refuses leaves no site and no uploaded bytes behind, and the media go up only once the site exists
1787
+ * to own them: uploaded bytes are metered against an owning entity and freed by deleting it.
1788
+ *
1789
+ * ⛔ Until 2026-11-09 a first push with media, and every first publish, made an EMPTY site
1790
+ * (`POST /dev/site`) and uploaded to it before sending any content. A content push refused after
1791
+ * that left the site created and empty, and this copy, holding its uuid and no base, stopped the next
1792
+ * push until `--force` (`untakenBase`).
1793
+ *
1794
+ * The content goes up naming its media as written, by their local paths, and the records stay
1795
+ * behind: the caller uploads the media against the uuid this returns, then pushes again, which sends
1796
+ * the media's serve URLs and the records. No hash is banked here, so that push compares nothing
1797
+ * against this one and sends every entity as it is then.
1798
+ *
1799
+ * A no-op when this backend already holds the site (`sync.json`).
1800
+ *
1801
+ * @param {object} p
1802
+ * @param {import('./client.js').BackendClient} p.client
1803
+ * @param {string} p.siteDir
1804
+ * @param {() => Promise<object>} p.emit - the sync packages, built as the push sends them but
1805
+ * without the media's serve URLs
1806
+ * @param {{ info: Function, note: Function, error: Function, dim?: Function }} p.report - as `pushSyncPackages` takes it
1807
+ * @returns {Promise<{ uuid: string|null, created: boolean, refused?: boolean, finalizedTotal: number, wrote: string[] }>}
1808
+ * `uuid: null`: not created, and already said why; `refused`: the backend refused the content
1814
1809
  */
1815
- export async function ensureSiteExists({
1816
- client,
1817
- siteDir,
1818
- name,
1819
- foundation,
1820
- note
1821
- }) {
1822
- // One read serves both the binding check and the create's defaults, so callers
1823
- // that have no reason to hold site.yml (push) need not load it just to pass it
1824
- // back. An explicit argument still wins — publish supplies the PINNED foundation
1825
- // ref from the bring-along, which site.yml may not carry.
1826
- let siteYml = {}
1810
+ export async function createSiteFromItsContent({ client, siteDir, emit, report }) {
1811
+ const known = readBackendState(siteDir, client.origin).site?.uuid
1812
+ if (known) return { uuid: known, created: false, finalizedTotal: 0, wrote: [] }
1813
+ // A site's name is required to create it (`info.name`, a plain string). Said as the line of
1814
+ // site.yml to fix, before a create that would be refused.
1815
+ let name = null
1827
1816
  try {
1828
- const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
1829
- if (y && typeof y === 'object') siteYml = y
1817
+ name = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))?.name ?? null
1830
1818
  } catch {
1831
- /* unreadable site.yml — treat as un-synced and let the create decide */
1832
- }
1833
- const known = readBackendState(siteDir, client.origin).site?.uuid
1834
- if (known) {
1835
- return { uuid: known, created: false, org: readSiteWorkspace(siteDir, client.origin) }
1819
+ /* unreadable site.yml — the emit says why */
1836
1820
  }
1837
-
1838
- // Both are required by the create. Catching it here turns a 400 into a sentence
1839
- // naming the file and the key — the difference between "fix this line of
1840
- // site.yml" and reading a status code.
1841
- const siteName = name ?? siteYml.name
1842
- const siteFoundation = foundation ?? siteYml.foundation
1843
- const missing = [!siteName && 'name', !siteFoundation && 'foundation'].filter(
1844
- Boolean
1845
- )
1846
- if (missing.length) {
1847
- return {
1848
- uuid: null,
1849
- created: false,
1850
- reason: `site.yml is missing ${missing.join(' and ')} — the backend requires ${missing.length > 1 ? 'them' : 'it'} to create a site`
1851
- }
1821
+ if (typeof name !== 'string' || !name.trim()) {
1822
+ report.error('site.yml has no `name:`, which the backend requires to create a site: it is the site’s name in the app.')
1823
+ return { uuid: null, created: false, finalizedTotal: 0, wrote: [] }
1852
1824
  }
1853
-
1854
- let res
1825
+ let pkg
1855
1826
  try {
1856
- // The owner is the workspace the client names — the command's (`workspace.js`).
1857
- res = await client.createSite({
1858
- name: siteName,
1859
- foundation: siteFoundation
1860
- })
1827
+ pkg = await emit()
1861
1828
  } catch (err) {
1862
- return { uuid: null, created: false, reason: err.message }
1863
- }
1864
- if (!res?.ok) {
1865
- const body = await res?.text?.().catch(() => '')
1866
- return {
1867
- uuid: null,
1868
- created: false,
1869
- // 404 here means the backend predates the route, which is a materially
1870
- // different problem from being refused — say which.
1871
- reason:
1872
- res?.status === 404
1873
- ? 'this backend has no /dev/site route (it predates the empty-site create)'
1874
- : (describeCreateRefusal(body) ??
1875
- `HTTP ${res?.status} ${res?.statusText || ''}${body ? ` — ${body.slice(0, 200)}` : ''}`)
1876
- }
1829
+ report.error(`Could not build the sync package: ${err.message}`)
1830
+ return { uuid: null, created: false, finalizedTotal: 0, wrote: [] }
1877
1831
  }
1878
- const payload = await res.json().catch(() => null)
1879
- const minted = extractMintedSiteUuid(payload)
1880
- if (!minted) {
1881
- return {
1882
- uuid: null,
1883
- created: false,
1884
- reason: 'the create returned no site uuid'
1885
- }
1832
+ report.note('The site is created from its content first; its media go up once the backend has taken it.')
1833
+ const result = await pushSyncPackages({ client, siteDir, pkg: { ...pkg, records: null, hashes: {} }, report })
1834
+ if (result.exitCode !== 0) {
1835
+ if (result.refused) report.note('The backend creates a site only with content it takes, so no site was created.')
1836
+ return { uuid: null, created: false, refused: Boolean(result.refused), finalizedTotal: 0, wrote: [] }
1886
1837
  }
1887
- writeSiteEntityUuid(siteDir, client.origin, minted)
1888
- // Stamp the cache with the site it now describes, so a push that fails after
1889
- // this point cannot leave a cache pointing at a different site with no way to
1890
- // detect it.
1891
- updateSyncCache(siteDir, client.origin, { siteUuid: minted })
1892
- const org = await recordAndDescribeOwner({ client, siteDir, payload, note })
1893
- return { uuid: minted, created: true, org }
1838
+ const uuid = result.boundSiteUuid || readBackendState(siteDir, client.origin).site?.uuid || null
1839
+ return { uuid, created: Boolean(uuid), finalizedTotal: result.finalizedTotal || 0, wrote: result.wrote || [] }
1894
1840
  }
1895
1841
 
1896
1842
  /**
@@ -2438,6 +2384,9 @@ export async function pushSyncPackages({
2438
2384
 
2439
2385
  const wrote = []
2440
2386
  let finalizedTotal = 0
2387
+ // Whether the backend answered a lane with a refusal, rather than the request failing on the way:
2388
+ // a refused create made no site (`createSiteFromItsContent`).
2389
+ let refused = false
2441
2390
  // Records sent as drafts that the backend stored enabled — reported at the end.
2442
2391
  let draftsNotKept = []
2443
2392
  // ⭐ THE COMMIT THIS PUSH IS MADE FROM — sent with each lane, so the backend can name it on
@@ -2476,11 +2425,12 @@ export async function pushSyncPackages({
2476
2425
  return null
2477
2426
  }
2478
2427
  if (!res.ok) {
2428
+ refused = true
2479
2429
  const body = await res.text().catch(() => '')
2480
2430
  // Two unrelated conflicts share HTTP 409, so branch on the machine-readable
2481
2431
  // `reason` — never on `detail`, which is prose the backend may reword.
2482
2432
  let problem = null
2483
- if ((res.status === 409 || res.status === 400 || res.status === 403 || res.status === 413 || res.status === 422) && body) {
2433
+ if ((res.status === 409 || res.status === 400 || res.status === 403 || res.status === 413 || res.status === 422 || res.status === 507) && body) {
2484
2434
  try {
2485
2435
  problem = JSON.parse(body)
2486
2436
  } catch {
@@ -2496,6 +2446,12 @@ export async function pushSyncPackages({
2496
2446
  for (const step of attach.steps) note(step)
2497
2447
  return null
2498
2448
  }
2449
+ // A site the workspace has no room for (`storage_quota_exceeded`) — said with the numbers.
2450
+ const space = describeStorageRefusal(problem)
2451
+ if (space) {
2452
+ error(`${label} push refused — ${space}`)
2453
+ return null
2454
+ }
2499
2455
  // The package carried no identity for records the backend already stores, so
2500
2456
  // applying it would replace every one of them. `ensureItemUuids` is supposed
2501
2457
  // to make this unreachable, so reaching it means that recovery failed — say so
@@ -2660,7 +2616,8 @@ export async function pushSyncPackages({
2660
2616
  return null
2661
2617
  }
2662
2618
  error(`${label} push rejected: HTTP ${res.status} ${res.statusText}`)
2663
- if (res.status === 401 || res.status === 403) {
2619
+ // A typed 403 says its own cause (a plan's limit, say), which is not the credentials.
2620
+ if ((res.status === 401 || res.status === 403) && typeof problem?.reason !== 'string') {
2664
2621
  note(
2665
2622
  "Credentials weren't accepted — log in again (`uniweb login --server <url>`), or check UNIWEB_TOKEN."
2666
2623
  )
@@ -2735,6 +2692,16 @@ export async function pushSyncPackages({
2735
2692
  note([problem.title, problem.detail].filter(Boolean).join(' — '))
2736
2693
  return null
2737
2694
  }
2695
+ // ⭐ A CREATE REFUSED FOR A REASON IT TYPES — a plan's limit, content the backend will not take —
2696
+ // is named, with the backend's own prose, rather than shown as its raw document. The create is the
2697
+ // lane with no site yet (`boundUuid`).
2698
+ if (!boundUuid && typeof problem?.reason === 'string') {
2699
+ note(
2700
+ `The backend refused the site create (${problem.reason})` +
2701
+ (typeof problem.detail === 'string' && problem.detail ? `: ${problem.detail}` : '.')
2702
+ )
2703
+ return null
2704
+ }
2738
2705
  if (body) note(body.slice(0, 800))
2739
2706
  return null
2740
2707
  }
@@ -3000,7 +2967,7 @@ export async function pushSyncPackages({
3000
2967
  undefined,
3001
2968
  { reportTemplate: true, sent: siteContent.buffer }
3002
2969
  )
3003
- if (payload === null) return { exitCode: 1, finalizedTotal, wrote }
2970
+ if (payload === null) return { exitCode: 1, finalizedTotal, wrote, refused }
3004
2971
  const minted = extractMintedSiteUuid(payload)
3005
2972
  if (!minted) {
3006
2973
  error(
@@ -3013,12 +2980,10 @@ export async function pushSyncPackages({
3013
2980
  updateSyncCache(siteDir, client.origin, { siteUuid: minted })
3014
2981
  boundSiteUuid = minted
3015
2982
  wrote.push('recorded the site in sync.json')
3016
- // The OTHER create path (a media-less push never reaches `ensureSiteExists`,
3017
- // which is gated on the site having local media). Both mint a site, so both
3018
- // owe the same record — recording it in only one place would make the recorded
3019
- // owner present or absent depending on whether the site happens to have images.
3020
- // The backend echoes `org`/`hosts_free` top-level here too, beside `report`
3021
- // and `site` (NOT beside `finalized`, which lives at report.finalized).
2983
+ // The site is created here, by its content, on every first push and publish
2984
+ // (`createSiteFromItsContent`), so its owner is recorded here too. The backend
2985
+ // echoes `org`/`hosts_free` top-level, beside `report` and `site` (NOT beside
2986
+ // `finalized`, which lives at report.finalized).
3022
2987
  const createdOrg = await recordAndDescribeOwner({ client, siteDir, payload, note })
3023
2988
  if (createdOrg)
3024
2989
  wrote.push(`recorded its owner (${createdOrg}) in sync.json`)
@@ -32,7 +32,7 @@ import {
32
32
  findPublicFavicon
33
33
  } from '@uniweb/build/site'
34
34
  import { listAdapters } from '@uniweb/build/hosts'
35
- import { RUNTIME_KEYS, writeSiteConfig } from '@uniweb/build/uwx'
35
+ import { RUNTIME_KEYS, writeSiteConfig, readBlueprint, refuseUnreadableBlueprint, blueprintWarnings, siteDeclaredTypes, siteSelfScope, BLUEPRINT_FILE } from '@uniweb/build/uwx'
36
36
  import { getCliVersion } from '../versions.js'
37
37
  import { readAgentsVersion } from '../utils/agents-stamp.js'
38
38
  import { writeJsonPreservingStyle } from '../utils/json-file.js'
@@ -1257,6 +1257,41 @@ export async function checkSiteAddress({ sitePath, siteName, siteYml, workspaceD
1257
1257
  log(` ${colors.dim}${without}${colors.reset}`)
1258
1258
  }
1259
1259
 
1260
+ /**
1261
+ * `blueprint.yml` — how a backend started from the site begins. What a build and a push would refuse
1262
+ * is an error; a line a backend would leave out — a type none of the site's foundations declares — a
1263
+ * warning, as the push says it; and a blueprint whose types could not be checked here, a note saying
1264
+ * why, since a clean report would otherwise read as checked.
1265
+ */
1266
+ export async function checkBlueprint({ sitePath, siteName, siteYml, issues }) {
1267
+ let blueprint
1268
+ try {
1269
+ blueprint = readBlueprint(sitePath)
1270
+ refuseUnreadableBlueprint(blueprint, { siteYml })
1271
+ } catch (err) {
1272
+ const id = 'blueprint-unreadable'
1273
+ const message = err.message.replace(/^\[uniweb\] /, '')
1274
+ issues.push({ id, type: 'error', site: siteName, message })
1275
+ error(`[${id}] ${message}`)
1276
+ return
1277
+ }
1278
+ if (!blueprint) return
1279
+ const scope = await siteSelfScope(sitePath)
1280
+ const declared = await siteDeclaredTypes(sitePath, siteYml, { scope })
1281
+ for (const line of blueprintWarnings(blueprint, { scope, declared })) {
1282
+ const id = 'blueprint-leaves-out'
1283
+ issues.push({ id, type: 'warn', site: siteName, message: line })
1284
+ warn(`[${id}] ${line}`)
1285
+ }
1286
+ const namesTypes = ['access', 'publicQueries'].some((key) => blueprint[key] && Object.keys(blueprint[key]).length)
1287
+ if (namesTypes && !declared.types) {
1288
+ const id = 'blueprint-types-unchecked'
1289
+ const message = `${BLUEPRINT_FILE}: its types were not checked against the site's foundations — ${declared.unread.join('; ')}`
1290
+ issues.push({ id, type: 'info', site: siteName, message })
1291
+ info(`[${id}] ${message}`)
1292
+ }
1293
+ }
1294
+
1260
1295
  // What a link preview draws, from the platforms' own pages, read 2026-10-27. Facebook
1261
1296
  // (developers.facebook.com/docs/sharing/webmasters/images): 1.91:1 shows the whole image, at least
1262
1297
  // 1200×630 for high-resolution screens and 600×315 for a large card, 8 MB at most. LinkedIn
@@ -2268,6 +2303,8 @@ async function runDoctor(args = []) {
2268
2303
  await checkFormSubmitTarget({ sitePath, siteName, siteYml, issues })
2269
2304
  checkAgentsBlock({ siteName, siteYml, issues })
2270
2305
  checkTrackingBlock({ siteName, siteYml, issues })
2306
+ // How a backend started from the site begins: what a push would refuse, and what a backend would leave out.
2307
+ await checkBlueprint({ sitePath, siteName, siteYml, issues })
2271
2308
 
2272
2309
  // `public/<DATA_DIR>/` is the build's output directory and nothing else —
2273
2310
  // `records/` is the only supported way to provide structured data. That makes the mapping a bijection: every entry there should be backed
@@ -108,7 +108,7 @@ import {
108
108
  ensureRegisteredFoundation,
109
109
  recoverUnbankedIdentity,
110
110
  keepTranslationsOfEdits,
111
- ensureSiteExists,
111
+ createSiteFromItsContent,
112
112
  refuseUnsendableRecords,
113
113
  clearRemoteSyncStateIfUnbound,
114
114
  untakenBase,
@@ -382,8 +382,8 @@ export async function publish(args = []) {
382
382
  }
383
383
 
384
384
  // ⭐ THE WORKSPACE THIS PUBLISH WORKS IN — the one chosen with the login, unless this
385
- // command names another (`workspace.js`). Resolved up front: `ensureSiteExists` below
386
- // creates the site in it, and a site the backend keeps elsewhere is refused.
385
+ // command names another (`workspace.js`). Resolved up front: a first publish creates the site
386
+ // in it (`createSiteFromItsContent`), and a site the backend keeps elsewhere is refused.
387
387
  const ws = await resolveWorkspace({ client, args, offline: dryRun })
388
388
  if (ws.refused) {
389
389
  say.err('This publish works in one workspace, and none is chosen.')
@@ -700,31 +700,89 @@ export async function publish(args = []) {
700
700
  `Cleared stale sync state from a previous site (${droppedState.join(', ')}).`
701
701
  )
702
702
  }
703
- // 3b. Make sure the SITE EXISTS before a single byte is uploaded.
704
- //
705
- // Uploaded bytes are metered against an owning entity and reclaimed by
706
- // deleting it. Uploading before the site exists therefore produces bytes
707
- // that are charged and can never be freed — there is nothing to delete —
708
- // so a repeatedly-failing first publish would burn quota with no recovery
709
- // short of support. Creating the site first makes the artifact of a failed
710
- // publish an EMPTY SITE instead: it costs nothing to keep and the owner can
711
- // clear it. A no-op once `sync.json` holds this backend's site uuid, so only
712
- // a first publish pays.
703
+ // publish rides the same gated push as `uniweb push`: if an app author has
704
+ // edited since this clone last synced, the push is refused rather than
705
+ // overwriting them, and nothing goes live. `--force` drops the precondition.
706
+ const forced = args.includes('--force')
707
+ let assetRewrite = null
708
+ let assetIds = null
709
+ // ⭐ THE PACKAGE AS THIS PUBLISH SENDS IT, read from this copy's state when it is built: once to
710
+ // create the site (3b), and once to push it (5), after the media and the identity the create banked.
711
+ const emitOptionsNow = async () => ({
712
+ backend: client.origin,
713
+ // The keys this deployment's Sections take — see deploymentFields.
714
+ ...fields,
715
+ // Placement identity for the folder — see writeFolderItemUuids.
716
+ folderItemUuids: readFolderItemUuids(siteDir, client.origin),
717
+ // Identity for the records' list items — see readRecordItemUuids.
718
+ recordItemUuids: readRecordItemUuids(siteDir, client.origin),
719
+ ...(foundationDir ? { foundationDir } : {}),
720
+ resolveModel,
721
+ priorHashes: readSyncCache(siteDir, client.origin),
722
+ // Per-item identity, recovered from the backend when this clone has never seen it.
723
+ // Without it the backend re-mints every page and section row (see readItemUuids).
724
+ itemUuids: await ensureItemUuids({ client, siteDir, note: (m) => say.dim(m) }),
725
+ ...(forced
726
+ ? {}
727
+ : {
728
+ baseVersions: readBaseVersions(siteDir, client.origin),
729
+ itemBaseVersions: readItemBaseVersions(siteDir, client.origin),
730
+ // What a pull held is left out while its files still say it — see `uniweb push`.
731
+ heldUnits: readHeldUnits(siteDir, client.origin)
732
+ }),
733
+ // Stamp the PINNED foundation ref (`@scope/name@version`) from the bring-along
734
+ // on the site-content entity — the one key `injectInfo` carries since the
735
+ // data-bundle URL went (2026-08-18). Delivery is version-pinned end-to-end (a
736
+ // foundation is delivered only by a concrete version, agreed with backend and
737
+ // measured end to end on 2026-06-25), so pinning the released version on the
738
+ // wire is required when site.yml uses an unversioned local ref; injectInfo
739
+ // overrides info.foundation. A registry/URL ref → fnd.ref is null → the
740
+ // site.yml ref is forwarded verbatim (already pinned).
741
+ // ⛔ DO NOT STAMP A FILE MAP INTO `info` HERE. `injectInfo` WINS the merge
742
+ // (`sync-package.js`: `{...siteDoc.info, ...injectInfo}`), so any name stamped
743
+ // here silently replaces what the author's document carries under it, and the
744
+ // store validator accepts it — nothing errors at any layer. This was written
745
+ // about `info.data`, which carried the site's `fetch:` block until 2026-09-09;
746
+ // that moved to `settings.fetch`, and the warning holds for any name.
747
+ //
748
+ // A file map needs a name nothing else claims (`static_data` / `data_files`
749
+ // were proposed) AND a consumer that reads it — neither settled. Until then
750
+ // the schema-less data goes as 4c sends it: one object per file, no bundle.
751
+ ...(fnd.ref ? { injectInfo: { foundation: fnd.ref } } : {}),
752
+ ...(Object.keys(ext.pins).length ? { injectExtensions: ext.pins } : {}),
753
+ ...(assetRewrite ? { assetRewrite } : {}),
754
+ ...(assetIds ? { assetIds } : {})
755
+ })
756
+ const report = {
757
+ info: (m) => say.info(m),
758
+ note: (m) => say.dim(m),
759
+ error: (m) => say.err(m),
760
+ dim: (x) => `${c.dim}${x}${c.reset}`
761
+ }
762
+ // 3b. The site exists before a single byte is uploaded against it, and a first publish
763
+ // creates it FROM ITS CONTENT (`createSiteFromItsContent`): the backend takes the content
764
+ // or creates nothing, so a publish it refuses leaves no site and no uploaded bytes behind.
765
+ // Uploaded bytes are metered against an owning entity and freed by deleting it, so they go
766
+ // up only once it exists. A no-op once `sync.json` holds this backend's site uuid.
713
767
  //
714
- // This ordering is load-bearing, not incidental — the asset plan requires an
715
- // owner. A test asserts the create precedes the upload.
716
- const site = await ensureSiteExists({
768
+ // ⛔ Until 2026-11-09 this made an EMPTY site first (`POST /dev/site`). A content push the
769
+ // backend refused then left that site behind, empty, and this copy could not push again
770
+ // without `--force`. A test asserts the create precedes the upload.
771
+ const site = await createSiteFromItsContent({
717
772
  client,
718
773
  siteDir,
719
- name: siteYml.name,
720
- foundation: fnd.ref || siteYml.foundation,
721
- note: (m) => say.dim(m)
774
+ emit: async () => emitSyncPackages(siteDir, await emitOptionsNow()),
775
+ report
722
776
  })
723
777
  if (!site.uuid) {
724
- say.err(`Could not create the site on the backend: ${site.reason}`)
725
- say.dim('Nothing was uploaded and nothing was charged.')
778
+ say.dim('No media or record data was uploaded.')
779
+ reportWriteBacks(commitWriteBacks(siteDir, client.origin, { complete: false, released }), { note: say.dim })
726
780
  return { exitCode: 1 }
727
781
  }
782
+ // What a first publish has sent by now, when an upload then fails: said, since it is not nothing.
783
+ const sentSoFar = () =>
784
+ site.created &&
785
+ say.dim('The site was created with its content, which names its media by their local paths until a push uploads them.')
728
786
 
729
787
  // 4. Gather the schema-less data files BEFORE uploading media, since their
730
788
  // records can carry local media too. (No search index rides here since
@@ -734,8 +792,6 @@ export async function publish(args = []) {
734
792
 
735
793
  // 4b. Upload ALL local media (entity refs + ball refs) on one asset lane →
736
794
  // the ref→serveUrl map; rewrite the entity content AND the ball with it.
737
- let assetRewrite = null
738
- let assetIds = null
739
795
  // …and each file record's file (`@uniweb/file` — `{ ref, path, contentType }`, already located).
740
796
  const mediaRefs = [...new Set([...localAssets, ...ballAssets]), ...(probe.localFiles || [])]
741
797
  if (mediaRefs.length) {
@@ -758,6 +814,7 @@ export async function publish(args = []) {
758
814
  if (failed.length) {
759
815
  say.err(`${failed.length} asset(s) failed to upload — not publishing.`)
760
816
  for (const f of failed) say.dim(` ${f.path} (HTTP ${f.status})`)
817
+ sentSoFar()
761
818
  return { exitCode: 1 }
762
819
  }
763
820
  if (Object.keys(map).length) assetRewrite = map
@@ -787,6 +844,7 @@ export async function publish(args = []) {
787
844
  } else {
788
845
  say.err(`Media upload failed: ${err.message}`)
789
846
  }
847
+ sentSoFar()
790
848
  return { exitCode: 1 }
791
849
  }
792
850
  }
@@ -849,6 +907,7 @@ export async function publish(args = []) {
849
907
  `${r.failed.length} data file(s) failed to upload — not publishing.`
850
908
  )
851
909
  for (const f of r.failed) say.dim(` ${f.path} (HTTP ${f.status})`)
910
+ sentSoFar()
852
911
  return { exitCode: 1 }
853
912
  }
854
913
  say.dim(`Record data : ${r.uploaded.length} file(s) [${r.mode}]`)
@@ -856,6 +915,7 @@ export async function publish(args = []) {
856
915
  // The workspace this publish works in, refused — said as itself, as at every other door.
857
916
  if (err instanceof WorkspaceMismatchError) {
858
917
  say.err(err.message)
918
+ sentSoFar()
859
919
  return { exitCode: 1 }
860
920
  }
861
921
  // A typed plan refusal gets its own account (quota, or whatever else the
@@ -869,6 +929,7 @@ export async function publish(args = []) {
869
929
  } else {
870
930
  say.err(`Record data upload failed: ${err.message}`)
871
931
  }
932
+ sentSoFar()
872
933
  return { exitCode: 1 }
873
934
  }
874
935
 
@@ -877,35 +938,6 @@ export async function publish(args = []) {
877
938
  // the pinned foundation ref and rewriting local media refs to serve URLs.
878
939
  // (It stamped `info.data_bundle` until 2026-08-18; the ball is gone and
879
940
  // collection data now lands at its serving tail, so nothing records it.)
880
- const priorHashes = readSyncCache(siteDir, client.origin)
881
- // Per-item identity, recovered from the backend when this clone has never seen it.
882
- // Without it the backend re-mints every page and section row (see readItemUuids).
883
- const itemUuids = await ensureItemUuids({
884
- client,
885
- siteDir,
886
- note: (m) => say.dim(m)
887
- })
888
- // Stamp the PINNED foundation ref (`@scope/name@version`) from the bring-along
889
- // on the site-content entity — the one key `injectInfo` carries since the
890
- // data-bundle URL went (2026-08-18). Delivery is version-pinned end-to-end (a
891
- // foundation is delivered only by a concrete version, agreed with backend and
892
- // measured end to end on 2026-06-25), so pinning the released version on the
893
- // wire is required when site.yml uses an unversioned local ref; injectInfo
894
- // overrides info.foundation. A registry/URL ref → fnd.ref is null → the
895
- // site.yml ref is forwarded verbatim (already pinned).
896
- // ⛔ DO NOT STAMP A FILE MAP INTO `info` HERE. `injectInfo` WINS the merge
897
- // (`sync-package.js`: `{...siteDoc.info, ...injectInfo}`), so any name stamped
898
- // here silently replaces what the author's document carries under it, and the
899
- // store validator accepts it — nothing errors at any layer. This was written
900
- // about `info.data`, which carried the site's `fetch:` block until 2026-09-09;
901
- // that moved to `settings.fetch`, and the warning holds for any name.
902
- //
903
- // A file map needs a name nothing else claims (`static_data` / `data_files`
904
- // were proposed) AND a consumer that reads it — neither settled. Until then
905
- // the schema-less data goes as 4c sends it: one object per file, no bundle.
906
- const injectInfo = {
907
- ...(fnd.ref ? { foundation: fnd.ref } : {})
908
- }
909
941
  // ⭐ WHAT THE SITE HAS — read before the push, for the language selection. Only this
910
942
  // read sees a decision the owner made in the app since this clone last synced. It
911
943
  // reads this backend's site, from sync.json; a never-synced site has none.
@@ -948,10 +980,6 @@ export async function publish(args = []) {
948
980
  }
949
981
  }
950
982
 
951
- // publish rides the same gated push as `uniweb push`: if an app author has
952
- // edited since this clone last synced, the push is refused rather than
953
- // overwriting them, and nothing goes live. `--force` drops the precondition.
954
- const forced = args.includes('--force')
955
983
  // A foundation named by catalog ref — a clone's: its kept registered version types a query named
956
984
  // for a data key (`ensureRegisteredFoundation`).
957
985
  await ensureRegisteredFoundation({
@@ -960,31 +988,7 @@ export async function publish(args = []) {
960
988
  siteUuid: readBackendState(siteDir, client.origin).site?.uuid,
961
989
  ref: siteYml?.foundation
962
990
  })
963
- const emitOptions = {
964
- backend: client.origin,
965
- // The keys this deployment's Sections take — see deploymentFields.
966
- ...fields,
967
- // Placement identity for the folder — see writeFolderItemUuids.
968
- folderItemUuids: readFolderItemUuids(siteDir, client.origin),
969
- // Identity for the records' list items — see readRecordItemUuids.
970
- recordItemUuids: readRecordItemUuids(siteDir, client.origin),
971
- ...(foundationDir ? { foundationDir } : {}),
972
- resolveModel,
973
- priorHashes,
974
- itemUuids,
975
- ...(forced
976
- ? {}
977
- : {
978
- baseVersions: readBaseVersions(siteDir, client.origin),
979
- itemBaseVersions: readItemBaseVersions(siteDir, client.origin),
980
- // What a pull held is left out while its files still say it — see `uniweb push`.
981
- heldUnits: readHeldUnits(siteDir, client.origin)
982
- }),
983
- ...(Object.keys(injectInfo).length ? { injectInfo } : {}),
984
- ...(Object.keys(ext.pins).length ? { injectExtensions: ext.pins } : {}),
985
- ...(assetRewrite ? { assetRewrite } : {}),
986
- ...(assetIds ? { assetIds } : {})
987
- }
991
+ const emitOptions = await emitOptionsNow()
988
992
  let pkg
989
993
  try {
990
994
  pkg = await emitSyncPackages(siteDir, emitOptions)
@@ -1011,12 +1015,6 @@ export async function publish(args = []) {
1011
1015
  // here, at publish, and never at push: syncing records does not depend on it.
1012
1016
  const notAsked = recordsNotAsked({ siteYml, shown: pkg.recordsShown })
1013
1017
  if (notAsked) say.warn(notAsked)
1014
- const report = {
1015
- info: (m) => say.info(m),
1016
- note: (m) => say.dim(m),
1017
- error: (m) => say.err(m),
1018
- dim: (s) => `${c.dim}${s}${c.reset}`
1019
- }
1020
1018
  const pushResult = await pushSyncPackages({
1021
1019
  client,
1022
1020
  siteDir,
@@ -1218,6 +1218,8 @@ export async function pull(args = [], deps = {}) {
1218
1218
  let notTaken = false
1219
1219
  // The languages the backend holds text in that the site does not list: not written (`documentLanguages`).
1220
1220
  let outsideLanguages = []
1221
+ // A `blueprint.yml` the pull left as it was, and why (`@uniweb/build/uwx`, `writePulledBlueprint`).
1222
+ let blueprintKept = null
1221
1223
  try {
1222
1224
  if (siteDoc) {
1223
1225
  // Re-base the page attribution. The pulled document IS the backend's own
@@ -1294,6 +1296,7 @@ export async function pull(args = [], deps = {}) {
1294
1296
  mountRoutes = report.mountRoutes || []
1295
1297
  mountedMoved = mountedPagesMoved(mountedPages, pulledVersions, priorVersions)
1296
1298
  outsideLanguages = report.outsideLanguages || []
1299
+ blueprintKept = report.config?.blueprint?.file === 'kept' ? report.config.blueprint.note : null
1297
1300
  // ⭐ WHAT IT HELD, AS THE FILES KEEP IT — where each held page is in the files it wrote into, the
1298
1301
  // stand-in in a repository, and what they say there — for a push to leave out while they still
1299
1302
  // say it (`readHeldUnits`). Replaced by each pull that takes the site's content. In the stand-in's
@@ -1703,6 +1706,8 @@ export async function pull(args = [], deps = {}) {
1703
1706
  // ⭐ A mounted folder's pages are as current as its repository, which no pull moves.
1704
1707
  for (const line of await behindLines(siteDir)) note(line)
1705
1708
  }
1709
+ // ⭐ Said, since the file and the site now differ: the file is the author's, and the next push sends it.
1710
+ if (blueprintKept) note(blueprintKept)
1706
1711
  // ⭐ Said, because the text is not in a translation file: one would make the language the site's,
1707
1712
  // and the next publish would ask to serve it (`uwx/source-locale.js`). It is kept for the push to
1708
1713
  // send back (`locales/_kept.json`), since a language removed in the app keeps its translations.
@@ -100,7 +100,7 @@ import {
100
100
  recoverUnbankedIdentity,
101
101
  ensureItemUuids,
102
102
  refuseUnsendableRecords,
103
- ensureSiteExists,
103
+ createSiteFromItsContent,
104
104
  clearRemoteSyncStateIfUnbound,
105
105
  untakenBase,
106
106
  keepTranslationsOfEdits,
@@ -384,16 +384,7 @@ export async function push(args = [], deps = {}) {
384
384
  )
385
385
  }
386
386
  }
387
- const priorHashes = readSyncCache(siteDir, client.origin)
388
- // Per-item identity, without which the backend reads every record as new and
389
- // recreates every page and section row.
390
- //
391
- // An offline preview (`-o` / `--dry-run`) still stamps from the CACHE — that is a
392
- // local file read, so it stays offline, and it keeps the emitted `.uwx` faithful
393
- // to what a real push would send. Only the network RECOVERY is skipped, so a
394
- // preview never reaches the backend. (Emitting `{}` here instead would make the
395
- // preview quietly unrepresentative, which is the one thing `-o` exists to avoid.)
396
- // Local media rides the SAME asset lane `publish` uses, and it rides it FIRST.
387
+ // Local media rides the SAME asset lane `publish` uses, before the content that names it.
397
388
  //
398
389
  // Push is the collaboration verb: a teammate opens the site in the visual app
399
390
  // right after it. Content that still points at `/images/hero.png` — bytes the
@@ -401,15 +392,14 @@ export async function push(args = [], deps = {}) {
401
392
  // push exists to avoid. `publish` uploaded and rewrote; push dropped
402
393
  // `localAssets` on the floor.
403
394
  //
404
- // The upload runs before `ensureItemUuids`, and the reason once recorded here —
405
- // "BEFORE `ensureItemUuids`, which mints uuids on the backend, so a refusal
406
- // leaves nothing minted" — is FALSE. `ensureItemUuids` mints nothing: it reads a
407
- // local map, and if that is empty it reads this backend's site uuid from sync.json
408
- // and returns immediately when there is none (the first-push case). Its only backend call is
409
- // a GET (`pullSiteContent`); its only write is a local file. So this ordering is
410
- // not protecting what that comment claimed, and is under review — an upload is a
411
- // durable, metered write, which makes uploading first the thing that leaves bytes
412
- // behind when a later step fails.
395
+ // ⭐ A SITE'S FIRST PUSH IS THE EXCEPTION, and the reason is the same metering. Bytes need an
396
+ // owner to be freed, and until 2026-11-09 the owner was an empty site made for them, so a
397
+ // content push the backend refused left that site behind, empty, and this copy unable to push
398
+ // without `--force`. Now the site is created FROM ITS CONTENT (`createSiteFromItsContent`):
399
+ // the backend takes the content or creates nothing, the media go up once it has, and the
400
+ // content goes again with their serve URLs, seconds later, on a site nobody has opened yet.
401
+ // So a refused first push leaves no site and no bytes. A later push still uploads before
402
+ // its content, and bytes it sent stay on the site's books if the content is then refused.
413
403
  //
414
404
  // The probe emit runs WITHOUT `priorHashes`, so it surfaces every local ref
415
405
  // rather than only the changed ones. That is not waste — the lane is
@@ -470,6 +460,59 @@ export async function push(args = [], deps = {}) {
470
460
 
471
461
  let assetRewrite = null
472
462
  let assetIds = null
463
+ const resolveModel = makeModelResolver({ client, offline: Boolean(output) || dryRun, siteDir })
464
+ // ⭐ THE PACKAGE AS THIS PUSH SENDS IT, read from this copy's state when it is built. A site's
465
+ // first push builds it twice, to create the site and again once the media went up, and the
466
+ // identity, bases and hashes the first one banks are what the second one sends.
467
+ const emitOptionsNow = async () => ({
468
+ backend: client.origin,
469
+ // Placement identity for the folder — see writeFolderItemUuids.
470
+ folderItemUuids: readFolderItemUuids(siteDir, client.origin),
471
+ // Identity for the `queries` section — see readQueryUuids. Keyed by
472
+ // name, because a declaration has no file for a path-keyed map to hold.
473
+ queryUuids: readQueryUuids(siteDir, client.origin),
474
+ // The keys this deployment's Sections take — see deploymentFields.
475
+ ...fields,
476
+ // Identity for the records' list items — see readRecordItemUuids.
477
+ recordItemUuids: readRecordItemUuids(siteDir, client.origin),
478
+ ...(foundationDir ? { foundationDir } : {}),
479
+ resolveModel,
480
+ priorHashes: readSyncCache(siteDir, client.origin),
481
+ sendAll,
482
+ // Per-item identity, without which the backend reads every record as new and recreates
483
+ // every page and section row. An offline preview (`-o` / `--dry-run`) still stamps from the
484
+ // CACHE, a local read, so the emitted `.uwx` is faithful to what a push would send; only the
485
+ // network RECOVERY is skipped. `ensureItemUuids` mints nothing: on a first push, with no site
486
+ // uuid for this backend, it returns at once.
487
+ itemUuids: output || dryRun ? readItemUuids(siteDir, client.origin) : await ensureItemUuids({ client, siteDir, note }),
488
+ // The PINNED foundation ref from the bring-along above, stamped over the
489
+ // authored `site.yml` string. Delivery is version-pinned end to end, so an
490
+ // unpinned local name on the wire names code no host can serve. Absent when
491
+ // the site already references a registry ref or URL — then site.yml's own
492
+ // value rides verbatim. The create of a site carries it too, since it is this emit.
493
+ ...(fnd.ref ? { injectInfo: { foundation: fnd.ref } } : {}),
494
+ // Both grains are dropped together by --force: one flag, one meaning,
495
+ // no partial-force mode.
496
+ ...(force
497
+ ? {}
498
+ : {
499
+ baseVersions: readBaseVersions(siteDir, client.origin),
500
+ itemBaseVersions: readItemBaseVersions(siteDir, client.origin),
501
+ // ⭐ What a pull held is left out while its files still say what they said, so the backend
502
+ // keeps the app's version (`readHeldUnits`). `--force` sends it with everything else.
503
+ heldUnits: readHeldUnits(siteDir, client.origin)
504
+ }),
505
+ ...(assetRewrite ? { assetRewrite } : {}),
506
+ ...(assetIds ? { assetIds } : {})
507
+ })
508
+ const report = {
509
+ info,
510
+ note,
511
+ error,
512
+ dim: (s) => `${colors.dim}${s}${colors.reset}`
513
+ }
514
+ // What creating the site sent, when this push created it (`createSiteFromItsContent`).
515
+ let created = null
473
516
  if (!output && !dryRun) {
474
517
  let mediaRefs = []
475
518
  let refusals = []
@@ -481,7 +524,7 @@ export async function push(args = [], deps = {}) {
481
524
  // Placement identity for the folder — see writeFolderItemUuids.
482
525
  folderItemUuids: readFolderItemUuids(siteDir, client.origin),
483
526
  ...(foundationDir ? { foundationDir } : {}),
484
- resolveModel: makeModelResolver({ client, offline: false, siteDir }),
527
+ resolveModel,
485
528
  // What a pull held, for a page that changed since to stop the push before anything goes up.
486
529
  ...(force ? {} : { heldUnits: readHeldUnits(siteDir, client.origin) })
487
530
  })
@@ -499,31 +542,27 @@ export async function push(args = [], deps = {}) {
499
542
  // …and so does a page a pull held whose files changed since (`refuseChangedHeld`).
500
543
  if (refuseChangedHeld(held, { error, note })) return { exitCode: 1 }
501
544
  if (mediaRefs.length) {
502
- // The site has to exist before its bytes do — an upload with no owning
503
- // entity is charged and cannot be freed, because freeing means deleting the
504
- // owner. A no-op once `sync.json` holds this backend's site uuid, so only a
505
- // never-synced site pays.
506
- // ⛔ The PINNED ref, not site.yml's. The create is a THIRD writer of this
507
- // value — the emit below stamps it via `injectInfo`, publish passes it here,
508
- // and push did neither until 2026-08-19: it sent the authored alias (`src`),
509
- // which names a foundation no deployment can resolve. A site created that way
510
- // keeps the bad ref, and the backend's create guard now refuses it outright
511
- // (channel backend↔framework, their measurement).
512
- //
513
- // ⭐ Same shape as the send-only-changed defect fixed this morning, and missed
514
- // for the same reason: the rule was applied at the writers under discussion and
515
- // a third caller of the same value was never enumerated.
516
- const site = await ensureSiteExists({
545
+ // The site has to exist before its bytes do — an upload with no owning entity is
546
+ // charged and cannot be freed, because freeing means deleting the owner. A site's
547
+ // first push creates it from its content, so a push the backend refuses leaves no site
548
+ // and no bytes (`createSiteFromItsContent`); a no-op once `sync.json` holds this
549
+ // backend's site uuid.
550
+ const site = await createSiteFromItsContent({
517
551
  client,
518
552
  siteDir,
519
- note,
520
- ...(fnd.ref ? { foundation: fnd.ref } : {})
553
+ emit: async () => emitSyncPackages(siteDir, await emitOptionsNow()),
554
+ report
521
555
  })
522
556
  if (!site.uuid) {
523
- error(`Could not create the site on the backend: ${site.reason}`)
524
- note('Nothing was uploaded and nothing was charged.')
557
+ note('No media was uploaded.')
558
+ reportWriteBacks(commitWriteBacks(siteDir, client.origin, { complete: false, released }), { note })
525
559
  return { exitCode: 1 }
526
560
  }
561
+ if (site.created) created = site
562
+ // What a first push has sent by now, when the media then fail: said, since it is not nothing.
563
+ const sentSoFar = () =>
564
+ site.created &&
565
+ note('The site was created with its content, which names its media by their local paths until a push uploads them.')
527
566
  info('Uploading media…')
528
567
  try {
529
568
  const { map, ids, served, failed } = await uploadSiteMedia(
@@ -543,9 +582,11 @@ export async function push(args = [], deps = {}) {
543
582
  // the uploader, and not worth blocking a push over.
544
583
  if (failed.length) {
545
584
  error(
546
- `${failed.length} asset(s) failed to upload — nothing was pushed.`
585
+ `${failed.length} asset(s) failed to upload — ${site.created ? 'nothing else was pushed.' : 'nothing was pushed.'}`
547
586
  )
548
587
  for (const f of failed) note(` ${f.path} (HTTP ${f.status})`)
588
+ sentSoFar()
589
+ reportWriteBacks(commitWriteBacks(siteDir, client.origin, { complete: false, released }), { note })
549
590
  return { exitCode: 1 }
550
591
  }
551
592
  if (Object.keys(map).length) assetRewrite = map
@@ -574,15 +615,13 @@ export async function push(args = [], deps = {}) {
574
615
  } else {
575
616
  error(`Media upload failed: ${err.message}`)
576
617
  }
618
+ sentSoFar()
619
+ reportWriteBacks(commitWriteBacks(siteDir, client.origin, { complete: false, released }), { note })
577
620
  return { exitCode: 1 }
578
621
  }
579
622
  }
580
623
  }
581
624
 
582
- const itemUuids =
583
- output || dryRun
584
- ? readItemUuids(siteDir, client.origin)
585
- : await ensureItemUuids({ client, siteDir, note })
586
625
  // A foundation named by catalog ref — a clone's: its kept registered version types a query named
587
626
  // for a data key (`ensureRegisteredFoundation`). Offline, only what is already kept.
588
627
  if (!output && !dryRun) {
@@ -597,46 +636,7 @@ export async function push(args = [], deps = {}) {
597
636
  // each held one it no longer lists (`statedServices`) — and the backend decides per
598
637
  // service. Said here: what the file asks that will not be sent as written.
599
638
  announceServices({ siteYml, say: { warn }, supports: await foundationSupports(siteDir, siteYml) })
600
- const emitOptions = {
601
- backend: client.origin,
602
- // Placement identity for the folder — see writeFolderItemUuids.
603
- folderItemUuids: readFolderItemUuids(siteDir, client.origin),
604
- // Identity for the `queries` section — see readQueryUuids. Keyed by
605
- // name, because a declaration has no file for a path-keyed map to hold.
606
- queryUuids: readQueryUuids(siteDir, client.origin),
607
- // The keys this deployment's Sections take — see deploymentFields.
608
- ...fields,
609
- // Identity for the records' list items — see readRecordItemUuids.
610
- recordItemUuids: readRecordItemUuids(siteDir, client.origin),
611
- ...(foundationDir ? { foundationDir } : {}),
612
- resolveModel: makeModelResolver({
613
- client,
614
- offline: Boolean(output) || dryRun,
615
- siteDir
616
- }),
617
- priorHashes,
618
- sendAll,
619
- itemUuids,
620
- // The PINNED foundation ref from the bring-along above, stamped over the
621
- // authored `site.yml` string. Delivery is version-pinned end to end, so an
622
- // unpinned local name on the wire names code no host can serve. Absent when
623
- // the site already references a registry ref or URL — then site.yml's own
624
- // value rides verbatim.
625
- ...(fnd.ref ? { injectInfo: { foundation: fnd.ref } } : {}),
626
- // Both grains are dropped together by --force: one flag, one meaning,
627
- // no partial-force mode.
628
- ...(force
629
- ? {}
630
- : {
631
- baseVersions: readBaseVersions(siteDir, client.origin),
632
- itemBaseVersions: readItemBaseVersions(siteDir, client.origin),
633
- // ⭐ What a pull held is left out while its files still say what they said, so the backend
634
- // keeps the app's version (`readHeldUnits`). `--force` sends it with everything else.
635
- heldUnits: readHeldUnits(siteDir, client.origin)
636
- }),
637
- ...(assetRewrite ? { assetRewrite } : {}),
638
- ...(assetIds ? { assetIds } : {})
639
- }
639
+ const emitOptions = await emitOptionsNow()
640
640
  let pkg
641
641
  try {
642
642
  pkg = await emitSyncPackages(siteDir, emitOptions)
@@ -733,27 +733,17 @@ export async function push(args = [], deps = {}) {
733
733
 
734
734
  // Submit both lanes, back-fill the minted uuids, and persist the send-only-changed
735
735
  // cache. Shared with `uniweb publish` via ../backend/site-sync.js.
736
- const result = await pushSyncPackages({
737
- client,
738
- siteDir,
739
- pkg,
740
- report: {
741
- info,
742
- note,
743
- error,
744
- dim: (s) => `${colors.dim}${s}${colors.reset}`
745
- }
746
- })
736
+ const result = await pushSyncPackages({ client, siteDir, pkg, report })
747
737
  // What the push wrote into the files is committed, whatever became of the lanes.
748
738
  const written = commitWriteBacks(siteDir, client.origin, { complete: result.complete, released })
749
739
  if (result.exitCode !== 0) {
750
740
  reportWriteBacks(written, { note })
751
741
  return { exitCode: result.exitCode }
752
742
  }
753
- success(
754
- `Pushed ${result.finalizedTotal} entit${result.finalizedTotal === 1 ? 'y' : 'ies'}` +
755
- (result.wrote.length ? ` — ${result.wrote.join(', ')}` : '')
756
- )
743
+ // A first push created the site before this, so what that sent counts too.
744
+ const total = (created?.finalizedTotal || 0) + result.finalizedTotal
745
+ const wrote = [...(created?.wrote || []), ...result.wrote]
746
+ success(`Pushed ${total} entit${total === 1 ? 'y' : 'ies'}` + (wrote.length ? ` — ${wrote.join(', ')}` : ''))
757
747
  reportWriteBacks(written, { note })
758
748
  // ⭐ The records this push took out of the site's folder are off the live site already (it reads
759
749
  // its folder as it stands): offer to delete them from the backend (ruled 2026-11-04).
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-09T18:42:57.806Z",
3
+ "generatedAt": "2026-11-09T22:12:50.994Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
- "version": "1.6.10"
6
+ "version": "1.7.0"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.20.0"
9
+ "version": "1.20.2"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.9"
@@ -54,7 +54,7 @@
54
54
  "version": "1.1.2"
55
55
  },
56
56
  "@uniweb/templates": {
57
- "version": "1.2.10"
57
+ "version": "1.2.11"
58
58
  },
59
59
  "@uniweb/theming": {
60
60
  "version": "1.3.2"
@@ -253,7 +253,7 @@ export async function uploadSiteData({
253
253
  * swallowing).
254
254
  *
255
255
  * ⭐ The THIRD door, and the last to get one. `/dev/assets` has
256
- * `describeAssetRefusal`, `POST /dev/site` has `describeCreateRefusal`, and this
256
+ * `describeAssetRefusal`, a site create has `describeStorageRefusal`, and this
257
257
  * lane threw prose with the JSON inlined until 2026-09-01 — which is the failure
258
258
  * the other two describers exist to prevent, so leaving it was just an untreated
259
259
  * instance of a solved problem.