uniweb 1.30.2 → 1.31.1

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.30.2",
3
+ "version": "1.31.1",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -42,12 +42,12 @@
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
44
  "@uniweb/content-writer": "~1.3.1",
45
- "@uniweb/core": "~1.6.9",
46
45
  "@uniweb/semantic-parser": "~1.13.2",
47
- "@uniweb/schemas": "~1.6.11"
46
+ "@uniweb/schemas": "~1.7.0",
47
+ "@uniweb/core": "~1.6.9"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.19.2",
50
+ "@uniweb/build": "~1.20.1",
51
51
  "@uniweb/content-reader": "~1.5.9",
52
52
  "@uniweb/semantic-parser": "~1.13.2"
53
53
  },
@@ -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 any registered data schema, by its full name** — `data: { members: '@acme/member' }`, `schema: '@acme/member'` in `queries.yml`. A scope is a namespace that keeps names from colliding, not a limit on who uses a type. So a type another foundation registers 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`). A register names such a type and sends no definition of it. A local build still needs the file: `schemas.config.js` routes that type, `'@acme/member': '../hub/src/schemas/member.yml'`, or its scope's folder. 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
@@ -1432,15 +1439,24 @@ export function writeHeldTypes(siteDir, backend, folderDoc) {
1432
1439
  * The backend keeps them, in no folder, until they are deleted (`utils/retired-records.js`). A
1433
1440
  * retired record placed again (a move undone) is dropped from the list.
1434
1441
  *
1442
+ * ⭐ ONLY THIS COPY'S OWN RECORDS. A record of another site's directory, mounted here
1443
+ * (`site.yml::paths`), is placed by reference to the entity its owner's push made. This copy never
1444
+ * sent it, and a pull leaves its file to the owner, so the `records` map, which every push and pull
1445
+ * writes for the records they carry, never holds it. Leaving the folder, it is the owner's to
1446
+ * retire. ⛔ Until 2026-11-08 it was retired here too, and one uuid the caller may not administer
1447
+ * refuses the whole delete before anything is deleted [backend, 2026-11-08].
1448
+ *
1435
1449
  * ⚠️ Nothing is known before a copy first banks its types, so a copy banked before 2026-11-04
1436
1450
  * retires nothing on its first push after that.
1437
1451
  *
1438
1452
  * @returns {string[]} the uuids this push retired
1439
1453
  */
1440
1454
  export function retireUnplaced(siteDir, backend, { before, after }) {
1441
- const prior = readBackendState(siteDir, backend).retired || {}
1455
+ const state = readBackendState(siteDir, backend)
1456
+ const prior = state.retired || {}
1457
+ const own = new Set(Object.values(state.records || {}))
1442
1458
  const now = Object.fromEntries(Object.entries(prior).filter(([uuid]) => !(uuid in after)))
1443
- const retired = Object.keys(before).filter((uuid) => !(uuid in after))
1459
+ const retired = Object.keys(before).filter((uuid) => !(uuid in after) && own.has(uuid))
1444
1460
  for (const uuid of retired) now[uuid] = before[uuid]
1445
1461
  setBackendMap(siteDir, backend, 'retired', now)
1446
1462
  return retired
@@ -1672,59 +1688,36 @@ function recordSiteWorkspace(siteDir, backend, owner) {
1672
1688
  }
1673
1689
 
1674
1690
  /**
1675
- * Turn a typed site-create refusal into a sentence, or null to fall through to the
1676
- * generic HTTP line.
1677
- *
1678
- * ⭐ Why this exists separately from `describeAssetRefusal`. The asset lane grew a
1679
- * typed describer because a raw status dump is useless to the person who has to act
1680
- * on it; the create lane had the same hole and nobody had met it, because until the
1681
- * backend shipped account capacity a create could not be refused for space at all.
1682
- * So this is the same fix on the second door, written before anyone hits it rather
1683
- * than after.
1684
- *
1685
- * ⛔ Branch on `reason`, never on the status. `507` alone cannot be told from any
1686
- * other 507 and carries none of the numbers a user needs, and `detail` is prose the
1687
- * backend may reword.
1688
- *
1689
- * ⚖️ The wording deliberately DIVERGES from the asset lane's on one point. There the
1690
- * allowance belongs to the site's owner, who may not be the person pushing. Here
1691
- * there is no site yet, so the only workspace in play is the one the site would be
1692
- * created in — one named with `--org` included. Saying "the site owner's workspace"
1693
- * would be incoherent for a site that does not exist.
1694
- *
1695
- * @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
1696
1706
  * @returns {string|null}
1697
1707
  */
1698
- function describeCreateRefusal(body) {
1699
- if (!body) return null
1700
- let p
1701
- try {
1702
- p = JSON.parse(body)
1703
- } catch {
1704
- return null // prose refusal, or an upstream error page
1705
- }
1706
- if (!p || typeof p !== 'object' || typeof p.reason !== 'string') return null
1707
-
1708
- const attach = describeAttachRefusal(p)
1709
- if (attach) return [attach.headline, ...attach.steps].join('\n ')
1710
-
1711
- if (p.reason === 'storage_quota_exceeded') {
1712
- const parts = []
1713
- const used = humanBytes(p.used_bytes)
1714
- const limit = humanBytes(p.limit_bytes)
1715
- const needed = humanBytes(p.needed_bytes)
1716
- if (used && limit) parts.push(`${used} of ${limit} used`)
1717
- if (needed) parts.push(`a new site needs ${needed}`)
1718
- return (
1719
- 'storage quota reached — the workspace this site would belong to has no room for it' +
1720
- (parts.length ? ` (${parts.join('; ')})` : '') +
1721
- '. Quota is returned by deleting a site or entity, not by editing content.'
1722
- )
1723
- }
1724
- // An unrecognised typed reason still beats a status dump: name it, and let the
1725
- // backend's own prose follow when it sent any.
1726
- const detail = typeof p.detail === 'string' ? p.detail : ''
1727
- 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
+ )
1728
1721
  }
1729
1722
 
1730
1723
  /**
@@ -1785,103 +1778,65 @@ export function describeAttachRefusal(problem) {
1785
1778
  }
1786
1779
 
1787
1780
  /**
1788
- * Guarantee the site EXISTS on the backend before anything is uploaded against it.
1789
- *
1790
- * Ordering is the point, and it is load-bearing rather than incidental. Uploaded
1791
- * bytes are metered against an owning entity and reclaimed by deleting it, so an
1792
- * upload made before any site exists is charged and can never be freed — there is
1793
- * nothing to delete. Creating the site first turns the artifact of a failed first
1794
- * publish from *unfreeable bytes* into *an empty site*, which costs nothing to
1795
- * keep and can be cleared. (The reverse ordering was justified by a claim that
1796
- * `ensureItemUuids` mints on the backend, which it does not — see push.js.)
1797
- *
1798
- * A no-op when the site already has a uuid on this backend (sync.json), so only the
1799
- * first publish of a site pays for it. The uuid is written back immediately, keeping the window in
1800
- * which a crash could strand a site as small as one file write.
1801
- *
1802
- * @returns {Promise<{ uuid: string|null, created: boolean, reason?: string }>}
1803
- * `uuid: null` means the site could not be created; the caller decides whether
1804
- * 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
1805
1809
  */
1806
- export async function ensureSiteExists({
1807
- client,
1808
- siteDir,
1809
- name,
1810
- foundation,
1811
- note
1812
- }) {
1813
- // One read serves both the binding check and the create's defaults, so callers
1814
- // that have no reason to hold site.yml (push) need not load it just to pass it
1815
- // back. An explicit argument still wins — publish supplies the PINNED foundation
1816
- // ref from the bring-along, which site.yml may not carry.
1817
- 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
1818
1816
  try {
1819
- const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
1820
- if (y && typeof y === 'object') siteYml = y
1817
+ name = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))?.name ?? null
1821
1818
  } catch {
1822
- /* unreadable site.yml — treat as un-synced and let the create decide */
1823
- }
1824
- const known = readBackendState(siteDir, client.origin).site?.uuid
1825
- if (known) {
1826
- return { uuid: known, created: false, org: readSiteWorkspace(siteDir, client.origin) }
1819
+ /* unreadable site.yml — the emit says why */
1827
1820
  }
1828
-
1829
- // Both are required by the create. Catching it here turns a 400 into a sentence
1830
- // naming the file and the key — the difference between "fix this line of
1831
- // site.yml" and reading a status code.
1832
- const siteName = name ?? siteYml.name
1833
- const siteFoundation = foundation ?? siteYml.foundation
1834
- const missing = [!siteName && 'name', !siteFoundation && 'foundation'].filter(
1835
- Boolean
1836
- )
1837
- if (missing.length) {
1838
- return {
1839
- uuid: null,
1840
- created: false,
1841
- reason: `site.yml is missing ${missing.join(' and ')} — the backend requires ${missing.length > 1 ? 'them' : 'it'} to create a site`
1842
- }
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: [] }
1843
1824
  }
1844
-
1845
- let res
1825
+ let pkg
1846
1826
  try {
1847
- // The owner is the workspace the client names — the command's (`workspace.js`).
1848
- res = await client.createSite({
1849
- name: siteName,
1850
- foundation: siteFoundation
1851
- })
1827
+ pkg = await emit()
1852
1828
  } catch (err) {
1853
- return { uuid: null, created: false, reason: err.message }
1854
- }
1855
- if (!res?.ok) {
1856
- const body = await res?.text?.().catch(() => '')
1857
- return {
1858
- uuid: null,
1859
- created: false,
1860
- // 404 here means the backend predates the route, which is a materially
1861
- // different problem from being refused — say which.
1862
- reason:
1863
- res?.status === 404
1864
- ? 'this backend has no /dev/site route (it predates the empty-site create)'
1865
- : (describeCreateRefusal(body) ??
1866
- `HTTP ${res?.status} ${res?.statusText || ''}${body ? ` — ${body.slice(0, 200)}` : ''}`)
1867
- }
1829
+ report.error(`Could not build the sync package: ${err.message}`)
1830
+ return { uuid: null, created: false, finalizedTotal: 0, wrote: [] }
1868
1831
  }
1869
- const payload = await res.json().catch(() => null)
1870
- const minted = extractMintedSiteUuid(payload)
1871
- if (!minted) {
1872
- return {
1873
- uuid: null,
1874
- created: false,
1875
- reason: 'the create returned no site uuid'
1876
- }
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: [] }
1877
1837
  }
1878
- writeSiteEntityUuid(siteDir, client.origin, minted)
1879
- // Stamp the cache with the site it now describes, so a push that fails after
1880
- // this point cannot leave a cache pointing at a different site with no way to
1881
- // detect it.
1882
- updateSyncCache(siteDir, client.origin, { siteUuid: minted })
1883
- const org = await recordAndDescribeOwner({ client, siteDir, payload, note })
1884
- 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 || [] }
1885
1840
  }
1886
1841
 
1887
1842
  /**
@@ -2429,6 +2384,9 @@ export async function pushSyncPackages({
2429
2384
 
2430
2385
  const wrote = []
2431
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
2432
2390
  // Records sent as drafts that the backend stored enabled — reported at the end.
2433
2391
  let draftsNotKept = []
2434
2392
  // ⭐ THE COMMIT THIS PUSH IS MADE FROM — sent with each lane, so the backend can name it on
@@ -2467,11 +2425,12 @@ export async function pushSyncPackages({
2467
2425
  return null
2468
2426
  }
2469
2427
  if (!res.ok) {
2428
+ refused = true
2470
2429
  const body = await res.text().catch(() => '')
2471
2430
  // Two unrelated conflicts share HTTP 409, so branch on the machine-readable
2472
2431
  // `reason` — never on `detail`, which is prose the backend may reword.
2473
2432
  let problem = null
2474
- 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) {
2475
2434
  try {
2476
2435
  problem = JSON.parse(body)
2477
2436
  } catch {
@@ -2487,6 +2446,12 @@ export async function pushSyncPackages({
2487
2446
  for (const step of attach.steps) note(step)
2488
2447
  return null
2489
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
+ }
2490
2455
  // The package carried no identity for records the backend already stores, so
2491
2456
  // applying it would replace every one of them. `ensureItemUuids` is supposed
2492
2457
  // to make this unreachable, so reaching it means that recovery failed — say so
@@ -2651,7 +2616,8 @@ export async function pushSyncPackages({
2651
2616
  return null
2652
2617
  }
2653
2618
  error(`${label} push rejected: HTTP ${res.status} ${res.statusText}`)
2654
- 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') {
2655
2621
  note(
2656
2622
  "Credentials weren't accepted — log in again (`uniweb login --server <url>`), or check UNIWEB_TOKEN."
2657
2623
  )
@@ -2726,6 +2692,16 @@ export async function pushSyncPackages({
2726
2692
  note([problem.title, problem.detail].filter(Boolean).join(' — '))
2727
2693
  return null
2728
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
+ }
2729
2705
  if (body) note(body.slice(0, 800))
2730
2706
  return null
2731
2707
  }
@@ -2991,7 +2967,7 @@ export async function pushSyncPackages({
2991
2967
  undefined,
2992
2968
  { reportTemplate: true, sent: siteContent.buffer }
2993
2969
  )
2994
- if (payload === null) return { exitCode: 1, finalizedTotal, wrote }
2970
+ if (payload === null) return { exitCode: 1, finalizedTotal, wrote, refused }
2995
2971
  const minted = extractMintedSiteUuid(payload)
2996
2972
  if (!minted) {
2997
2973
  error(
@@ -3004,12 +2980,10 @@ export async function pushSyncPackages({
3004
2980
  updateSyncCache(siteDir, client.origin, { siteUuid: minted })
3005
2981
  boundSiteUuid = minted
3006
2982
  wrote.push('recorded the site in sync.json')
3007
- // The OTHER create path (a media-less push never reaches `ensureSiteExists`,
3008
- // which is gated on the site having local media). Both mint a site, so both
3009
- // owe the same record — recording it in only one place would make the recorded
3010
- // owner present or absent depending on whether the site happens to have images.
3011
- // The backend echoes `org`/`hosts_free` top-level here too, beside `report`
3012
- // 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).
3013
2987
  const createdOrg = await recordAndDescribeOwner({ client, siteDir, payload, note })
3014
2988
  if (createdOrg)
3015
2989
  wrote.push(`recorded its owner (${createdOrg}) in sync.json`)
@@ -1686,7 +1686,7 @@ export function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, sho
1686
1686
  * ⭐ WHAT DOCTOR CHECKS IS WHERE YOU STAND, by the rule `dev` and `status` read the folder you stand in
1687
1687
  * (`pick-site.js::siteAround`): in a site, that site and what it is built from, its foundation and its
1688
1688
  * extensions; in a foundation, the site beside it when that site is built from it, else that foundation;
1689
- * elsewhere, the whole workspace. ⛔ Until 2026-11-09 the site beside a foundation was checked whatever
1689
+ * elsewhere, the whole workspace. ⛔ Until 2026-11-08 the site beside a foundation was checked whatever
1690
1690
  * it was built from, so in `shop/src` beside a site on another foundation, nothing checked `shop/src`.
1691
1691
  * ⛔ Until 2026-11-08 only the sites were narrowed: run in one site, doctor reported on every foundation
1692
1692
  * in the workspace before the site's own checks, which were hard to find among them.
@@ -1753,8 +1753,8 @@ export async function checkTypesDefinedTwice({ workspaceDir, checkedDirs, issues
1753
1753
  info(`[${id}] ${t.ref} is defined in ${t.files.length} places${t.differ ? ', and they differ' : ''}`)
1754
1754
  for (const f of t.files) log(` ${relative(workspaceDir, f)}`)
1755
1755
  log(
1756
- ` A registered data schema is usable by any foundation by its full name, so keep one definition and name ` +
1757
- `it in full in the others (${colors.green}${t.ref}${colors.reset}); schemas.config.js gives a local build its file.`
1756
+ ` Any foundation can use a data schema by its full name, so keep one definition and name it in full in the ` +
1757
+ `others (${colors.green}${t.ref}${colors.reset}): in this workspace their build finds its file, with nothing to configure.`
1758
1758
  )
1759
1759
  }
1760
1760
  }