uniweb 1.31.12 → 1.31.13

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.12",
3
+ "version": "1.31.13",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -41,15 +41,15 @@
41
41
  "js-yaml": "^4.3.2",
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
- "@uniweb/semantic-parser": "~1.13.3",
44
+ "@uniweb/content-writer": "~1.3.1",
45
45
  "@uniweb/core": "~1.6.12",
46
46
  "@uniweb/schemas": "~1.7.1",
47
- "@uniweb/content-writer": "~1.3.1"
47
+ "@uniweb/semantic-parser": "~1.13.3"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/semantic-parser": "~1.13.3",
50
+ "@uniweb/build": "~1.20.10",
51
51
  "@uniweb/content-reader": "~1.5.9",
52
- "@uniweb/build": "~1.20.9"
52
+ "@uniweb/semantic-parser": "~1.13.3"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -98,7 +98,7 @@ publicQueries: # what visitors who aren't signed in may read
98
98
  '@/vehicle': { whole: true, where: { status: { in: [available, pending] } } } # whole is required; false = briefs
99
99
  ```
100
100
 
101
- - **Applied once**, when a backend is started from the site: its own, a clone's of a template, or one started again after it was destroyed. Then the operator changes these in the backend's administration. An edited file is pushed and pulled with the site, and reaches no backend already running.
101
+ - **Applied once**, when a backend is started from the site: its own, a clone's of a template, or one started again after it was destroyed. Then the operator changes these in the backend's administration. An edited file is pushed and pulled with the site, and reaches no backend already running: once the site's has started, a push or publish that sends a change says so, and so does `uniweb status`.
102
102
  - A type not listed stays closed. Name types as `queries.yml` does: `@/vehicle` for the foundation's own, sent in its scope.
103
103
  - A build, a push and `uniweb doctor` refuse a malformed file, naming the key; a push refuses whole. A type none of the site's foundations declares only warns: a backend started from the site leaves that line out, and the publish says so. `where`, `sort` and `limit` are the backend's to judge, and one it refuses is left out the same way.
104
104
  - A team's `all: edit` reaches the entries once the member confirms it is them (below); a team's `add` and `members: edit` need no confirming. Who is in a team, and roles, are never the file's.
@@ -0,0 +1,123 @@
1
+ /**
2
+ * ⭐ A CHANGED `blueprint.yml` NEVER REACHES A BACKEND ALREADY STARTED FROM THE SITE — and the CLI says
3
+ * so: at the push that sends one (`push`, `publish`, and `sync` through push), and in `uniweb status`.
4
+ *
5
+ * The file says how a backend started from the site begins (`@uniweb/build`'s `uwx/blueprint.js`). It
6
+ * is applied once, when that backend starts, and from then on the site's owner changes the running
7
+ * backend in its administration. A push still checks the file and carries it with the site, and a pull
8
+ * writes it back, so a changed file is accepted without a word. A person who changed it expects the
9
+ * running backend to follow, and nothing else tells them it doesn't.
10
+ *
11
+ * ⭐ ONE RULE, read off the site's status (`GET /dev/site/status/{uuid}`, its `backend_state`):
12
+ *
13
+ * no key a backend older than the field, which says nothing either way: say nothing, and
14
+ * never read it as `null`
15
+ * `null` no backend has been started from this site, so the file is how its next one
16
+ * begins: say nothing
17
+ * any other a backend has been started from it (running, being started, stopped, destroyed, or
18
+ * a state a backend names later), and a changed file no longer reaches it
19
+ *
20
+ * ⛔ NO PROMISE OF ANOTHER BACKEND. A publish starts a backend only where the state reads `null`, so
21
+ * one that was destroyed is not started again by it. Nothing here says the file will found one, and
22
+ * nothing reads a state's name past `null`.
23
+ *
24
+ * ⛔ THE STATE BEFORE THE PUSH. A publish can start the site's first backend once its push has landed,
25
+ * and that start takes the blueprint the push just stored. Read after the publish, the state would say
26
+ * `provisioning` about a change that did reach it. So `push` and `publish` judge by the status they
27
+ * read before sending.
28
+ *
29
+ * "Changed" means what the push sends against what the site held before it, compared as a pull
30
+ * compares them (`sameBlueprint`): the status carries the stored request whole, the `backend` row's
31
+ * `config.blueprint` included, with its types in full (measured 2026-11-10 on a local backend). A push
32
+ * that sends no blueprint says nothing.
33
+ */
34
+
35
+ import * as uwx from '@uniweb/build/uwx'
36
+ import { BLUEPRINT_FILE, readBlueprint, siteSelfScope } from '@uniweb/build/uwx'
37
+
38
+ // ⛔ AN OLDER `@uniweb/build` EXPORTS NONE OF THESE (they came with build `753d745`), and this CLI is its
39
+ // peer, so a project can run it over one. A named import would stop `push`, `publish` and `status` from
40
+ // loading at all, so they are read off the namespace: without them nothing here is said, and the verbs
41
+ // work as they did before.
42
+ const { blueprintForWire, liftBlueprint, sameBlueprint } = uwx
43
+ const COMPARABLE = [blueprintForWire, liftBlueprint, sameBlueprint].every((fn) => typeof fn === 'function')
44
+
45
+ /**
46
+ * Whether a backend has been started from the site, by its status: `true` or `false`, or `null` when
47
+ * the status says nothing (none was read, or it comes from a backend older than `backend_state`).
48
+ *
49
+ * @param {object|null} status - the site's status reply
50
+ * @returns {boolean|null}
51
+ */
52
+ export function backendStarted(status) {
53
+ if (!status || typeof status !== 'object' || !Object.hasOwn(status, 'backend_state')) return null
54
+ return status.backend_state !== null
55
+ }
56
+
57
+ /** The blueprint the site holds, by its status: its `backend` row's, or undefined for none. */
58
+ const heldBlueprint = (status) => liftBlueprint(status?.services).blueprint
59
+
60
+ const STARTED = `${BLUEPRINT_FILE} is how a backend started from this site begins, and this site's backend has started`
61
+
62
+ /** Where the change is made instead — by a person, in a browser. */
63
+ const ADMINISTRATION = "What a running backend allows, the site's owner changes in the backend's administration."
64
+
65
+ /**
66
+ * Whether a push's `services` rows carry a blueprint, so that `sentBlueprintNote` has something to
67
+ * judge: a push asks the site's status only then.
68
+ *
69
+ * @param {object[]|null} sent - the `services` rows the push sends; null when it sends no site content
70
+ * @returns {boolean}
71
+ */
72
+ export function sendsBlueprint(sent) {
73
+ return COMPARABLE && Array.isArray(sent) && liftBlueprint(sent).blueprint !== undefined
74
+ }
75
+
76
+ /**
77
+ * What a push or a publish says after sending a blueprint the site did not hold, when the site's
78
+ * backend has started: the lines to print, the first the headline. Null when there is nothing to say.
79
+ *
80
+ * @param {object} p
81
+ * @param {object|null} p.status - the site's status, read BEFORE the push sent anything
82
+ * @param {object[]|null} p.sent - the `services` rows the push sends; null when it sends no site content
83
+ * @returns {string[]|null}
84
+ */
85
+ export function sentBlueprintNote({ status, sent }) {
86
+ if (!sendsBlueprint(sent) || backendStarted(status) !== true) return null
87
+ if (sameBlueprint(liftBlueprint(sent).blueprint, heldBlueprint(status))) return null
88
+ return [`${STARTED}: the change just sent doesn't reach it.`, ADMINISTRATION]
89
+ }
90
+
91
+ /**
92
+ * `hosting.blueprint`, for `uniweb status`: a site that keeps a blueprint here and whose backend has
93
+ * started. `ok` while the file, as a push would send it, says what the site holds; `attention` when it
94
+ * says something else. Null when there is nothing to say: no file, a backend that says nothing, none
95
+ * started, or a file a push would refuse, which `doctor` names.
96
+ *
97
+ * @param {object} p
98
+ * @param {string} p.siteDir
99
+ * @param {object|null} p.status - the site's status reply
100
+ * @returns {Promise<object|null>}
101
+ */
102
+ export async function blueprintCheck({ siteDir, status }) {
103
+ if (!COMPARABLE || backendStarted(status) !== true) return null
104
+ let local
105
+ try {
106
+ const file = readBlueprint(siteDir)
107
+ if (!file) return null
108
+ local = blueprintForWire(file, await siteSelfScope(siteDir))
109
+ } catch {
110
+ return null
111
+ }
112
+ const differs = !sameBlueprint(local, heldBlueprint(status))
113
+ const detail = { backend_state: status.backend_state, differs }
114
+ return differs
115
+ ? {
116
+ id: 'hosting.blueprint',
117
+ state: 'attention',
118
+ summary: `${STARTED}: the file here differs from what the site holds, and a push of it doesn't reach that backend.`,
119
+ lines: [ADMINISTRATION],
120
+ detail
121
+ }
122
+ : { id: 'hosting.blueprint', state: 'ok', summary: `${STARTED}: a change to the file doesn't reach it.`, detail }
123
+ }
@@ -976,45 +976,6 @@ export class BackendClient {
976
976
  })
977
977
  }
978
978
 
979
- /**
980
- * GET /dev/site/status/{uuid} → the site's publish lifecycle (Contract 3,
981
- * shipped backend-side — collab backend↔framework):
982
- * { published: boolean, last_pushed_at?: string, last_published_at?: string, draft_dirty?: boolean }
983
- * `draft_dirty` = never-published, or the synced draft changed since the last
984
- * publish ("pushed but not published"). Since 2026-10-13 it also carries `editors`:
985
- * who has the site open in the app right now, and on what — `uniweb status` shows
986
- * it (`describeEditors`, commands/status.js).
987
- *
988
- * ⭐ **The backend also serves a LIVE-SITE record here** (shipped 2026-08-29), and
989
- * `uniweb status` reads part of it: the address it shows (`visitor_url`, else
990
- * `last_published_url` — `liveAddress`), and the foundation and runtime its `--json`
991
- * detail carries. Nothing reads the rest yet:
992
- *
993
- * last_published_url · last_published_foundation · last_published_extensions
994
- * last_published_runtime · last_published_runtime_floor · last_published_runtime_resolution
995
- * visitor_url — where visitors go: the custom domain while one is active (2026-10-28)
996
- *
997
- * Three things about it that a reader will otherwise get wrong:
998
- *
999
- * ⛔ `runtime_resolution` is `resolved` or `pinned:<reason>` (`operator` / `unknown_floor` /
1000
- * `no_foundations`). **A pin is a first-class answer, not a failure** — most sites are pinned
1001
- * at any moment, and an "old" runtime still satisfies the site's floor. Never surface
1002
- * `pinned:*` as an error state.
1003
- * ⛔ `extensions` is there because a site's code surface is the primary foundation **plus N
1004
- * extensions**; reading the primary alone describes a site nobody has.
1005
- * ⛔ `last_*` is deliberate on every one. `unpublish` LEAVES the URL populated (the static site
1006
- * may still be reachable), so beside `published: bool` a bare `published_url` would read as a
1007
- * liveness claim and be wrong exactly when it matters. And **nothing back-fills** — a site
1008
- * published before this reports them absent, which means "published before we recorded it",
1009
- * never "has no foundation".
1010
- *
1011
- * The path is VERB-FIRST (`status/{uuid}`)
1012
- * to match the lane (`publish/{uuid}`, `content/push/{uuid}`, `folder/pull/{uuid}`),
1013
- * not the `{uuid}/status` the shipping-verbs §8 sketch assumed. null on
1014
- * 404 (unknown/not-yours) / 401 / any failure — `uniweb status` says what it could not tell.
1015
- * @param {string} uuid - the site-content uuid
1016
- * @returns {Promise<object|null>}
1017
- */
1018
979
  /**
1019
980
  * Whether the backend holds the site `uuid` names — `live`, `gone` or `unknown`, kept
1020
981
  * apart — for a script that must decide, before any push, whether a binding still
@@ -1083,6 +1044,50 @@ export class BackendClient {
1083
1044
  }
1084
1045
  }
1085
1046
 
1047
+ /**
1048
+ * GET /dev/site/status/{uuid} → the site's publish lifecycle:
1049
+ * { published: boolean, last_pushed_at?: string, last_published_at?: string, draft_dirty?: boolean }
1050
+ * `draft_dirty` = never-published, or the synced draft changed since the last
1051
+ * publish ("pushed but not published"). Since 2026-10-13 it also carries `editors`:
1052
+ * who has the site open in the app right now, and on what — `uniweb status` shows
1053
+ * it (`describeEditors`, commands/status.js).
1054
+ *
1055
+ * ⭐ **And the backend started from the site**, `backend_state` (2026-11-09): `null` until
1056
+ * one is started, then its lifecycle state as the backend last saw it. The key is always
1057
+ * there on a backend that knows it, so no key is an older backend, never "none started".
1058
+ * Read with `services`, the stored request whole (each row's `config` included), to say
1059
+ * when a changed `blueprint.yml` no longer reaches that backend (`backend/blueprint-reach.js`).
1060
+ *
1061
+ * ⭐ **The backend also serves a LIVE-SITE record here** (shipped 2026-08-29), and
1062
+ * `uniweb status` reads part of it: the address it shows (`visitor_url`, else
1063
+ * `last_published_url` — `liveAddress`), and the foundation and runtime its `--json`
1064
+ * detail carries. Nothing reads the rest yet:
1065
+ *
1066
+ * last_published_url · last_published_foundation · last_published_extensions
1067
+ * last_published_runtime · last_published_runtime_floor · last_published_runtime_resolution
1068
+ * visitor_url — where visitors go: the custom domain while one is active (2026-10-28)
1069
+ *
1070
+ * Three things about it that a reader will otherwise get wrong:
1071
+ *
1072
+ * ⛔ `runtime_resolution` is `resolved` or `pinned:<reason>` (`operator` / `unknown_floor` /
1073
+ * `no_foundations`). **A pin is a first-class answer, not a failure** — most sites are pinned
1074
+ * at any moment, and an "old" runtime still satisfies the site's floor. Never surface
1075
+ * `pinned:*` as an error state.
1076
+ * ⛔ `extensions` is there because a site's code surface is the primary foundation **plus N
1077
+ * extensions**; reading the primary alone describes a site nobody has.
1078
+ * ⛔ `last_*` is deliberate on every one. `unpublish` LEAVES the URL populated (the static site
1079
+ * may still be reachable), so beside `published: bool` a bare `published_url` would read as a
1080
+ * liveness claim and be wrong exactly when it matters. And **nothing back-fills** — a site
1081
+ * published before this reports them absent, which means "published before we recorded it",
1082
+ * never "has no foundation".
1083
+ *
1084
+ * The path is VERB-FIRST (`status/{uuid}`)
1085
+ * to match the lane (`publish/{uuid}`, `content/push/{uuid}`, `folder/pull/{uuid}`),
1086
+ * not the `{uuid}/status` the shipping-verbs §8 sketch assumed. null on
1087
+ * 404 (unknown/not-yours) / 401 / any failure — `uniweb status` says what it could not tell.
1088
+ * @param {string} uuid - the site-content uuid
1089
+ * @returns {Promise<object|null>}
1090
+ */
1086
1091
  async siteStatus(uuid) {
1087
1092
  try {
1088
1093
  const res = await this.request(
@@ -98,6 +98,16 @@ function entityDocFromUwx(buf) {
98
98
  return null
99
99
  }
100
100
 
101
+ /**
102
+ * The site-content document a package sends, or null when its site-content lane sends nothing.
103
+ *
104
+ * @param {object} pkg - from `emitSyncPackages`
105
+ * @returns {object|null}
106
+ */
107
+ export function sentSiteDocument(pkg) {
108
+ return pkg?.siteContent ? entityDocFromUwx(pkg.siteContent.buffer) : null
109
+ }
110
+
101
111
  // What a `.uwx`'s entries inflate to, summed — the quantity a backend's package limit counts.
102
112
  // null for anything that is not a readable `.uwx`.
103
113
  function inflatedSizeOfUwx(buf) {
@@ -117,8 +117,10 @@ import {
117
117
  deployRecordAtRest,
118
118
  reportWriteBacks,
119
119
  pushSyncPackages,
120
- readSiteWorkspace
120
+ readSiteWorkspace,
121
+ sentSiteDocument
121
122
  } from '../backend/site-sync.js'
123
+ import { sentBlueprintNote } from '../backend/blueprint-reach.js'
122
124
  import { repoOf } from '../utils/sync-point.js'
123
125
  import { commitBeforeSending } from '../backend/commit-before-sending.js'
124
126
  import { mountsBeforeSending } from '../backend/mounts-before-sending.js'
@@ -1015,6 +1017,10 @@ export async function publish(args = []) {
1015
1017
  // here, at publish, and never at push: syncing records does not depend on it.
1016
1018
  const notAsked = recordsNotAsked({ siteYml, shown: pkg.recordsShown })
1017
1019
  if (notAsked) say.warn(notAsked)
1020
+ // ⭐ A CHANGED BLUEPRINT REACHES NO BACKEND ALREADY STARTED FROM THE SITE — judged by the status read
1021
+ // before the push, since this publish's go-live may start the site's first backend with what it
1022
+ // sends (`backend/blueprint-reach.js`).
1023
+ const blueprintNote = sentBlueprintNote({ status, sent: sentSiteDocument(pkg)?.services ?? null })
1018
1024
  const pushResult = await pushSyncPackages({
1019
1025
  client,
1020
1026
  siteDir,
@@ -1024,6 +1030,10 @@ export async function publish(args = []) {
1024
1030
  // What the push wrote into the files is committed, whatever became of the lanes.
1025
1031
  reportWriteBacks(commitWriteBacks(siteDir, client.origin, { complete: pushResult.complete, released }), { note: say.dim })
1026
1032
  if (pushResult.exitCode !== 0) return { exitCode: pushResult.exitCode }
1033
+ if (blueprintNote) {
1034
+ say.warn(blueprintNote[0])
1035
+ for (const line of blueprintNote.slice(1)) say.dim(line)
1036
+ }
1027
1037
  const siteUuid = pushResult.boundSiteUuid
1028
1038
  if (!siteUuid) {
1029
1039
  say.err('Push did not yield a site uuid — cannot go live.')
@@ -109,8 +109,10 @@ import {
109
109
  reportWriteBacks,
110
110
  holdUnchangedPush,
111
111
  pushSyncPackages,
112
- readSiteWorkspace
112
+ readSiteWorkspace,
113
+ sentSiteDocument
113
114
  } from '../backend/site-sync.js'
115
+ import { sendsBlueprint, sentBlueprintNote } from '../backend/blueprint-reach.js'
114
116
  import { commitBeforeSending } from '../backend/commit-before-sending.js'
115
117
  import { mountsBeforeSending } from '../backend/mounts-before-sending.js'
116
118
  import { resolveWorkspace, describeWorkspace, previewWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
@@ -734,6 +736,16 @@ export async function push(args = [], deps = {}) {
734
736
  return { exitCode: 0 }
735
737
  }
736
738
 
739
+ // ⭐ A CHANGED BLUEPRINT REACHES NO BACKEND ALREADY STARTED FROM THE SITE: said once the push lands,
740
+ // judged by the site's status before anything is sent (`backend/blueprint-reach.js`). Asked only
741
+ // when the push sends a blueprint, to a site the backend holds.
742
+ const sent = sentSiteDocument(pkg)?.services ?? null
743
+ const boundUuid = readBackendState(siteDir, client.origin).site?.uuid
744
+ const blueprintNote =
745
+ boundUuid && sendsBlueprint(sent)
746
+ ? sentBlueprintNote({ status: await client.siteStatus(boundUuid).catch(() => null), sent })
747
+ : null
748
+
737
749
  // Submit both lanes, back-fill the minted uuids, and persist the send-only-changed
738
750
  // cache. Shared with `uniweb publish` via ../backend/site-sync.js.
739
751
  const result = await pushSyncPackages({ client, siteDir, pkg, report })
@@ -747,6 +759,10 @@ export async function push(args = [], deps = {}) {
747
759
  const total = (created?.finalizedTotal || 0) + result.finalizedTotal
748
760
  const wrote = [...(created?.wrote || []), ...result.wrote]
749
761
  success(`Pushed ${total} entit${total === 1 ? 'y' : 'ies'}` + (wrote.length ? ` — ${wrote.join(', ')}` : ''))
762
+ if (blueprintNote) {
763
+ warn(blueprintNote[0])
764
+ for (const line of blueprintNote.slice(1)) note(line)
765
+ }
750
766
  reportWriteBacks(written, { note })
751
767
  // ⭐ The records this push took out of the site's folder are off the live site already (it reads
752
768
  // its folder as it stands): offer to delete them from the backend (ruled 2026-11-04).
@@ -62,6 +62,7 @@ import { describeWorkspace, resolveWorkspace, SOURCE_LABEL } from '../backend/wo
62
62
  import { BackendClient, resolveBackendOrigin } from '../backend/client.js'
63
63
  import { readAppChanges } from '../backend/app-changes.js'
64
64
  import { liveAddress } from '../backend/live-address.js'
65
+ import { blueprintCheck } from '../backend/blueprint-reach.js'
65
66
  import { probePull } from './pull.js'
66
67
  import { readOrgFlag } from '../utils/args.js'
67
68
  import { listSyncedBackends, readBackendState } from '@uniweb/build/uwx'
@@ -1627,6 +1628,9 @@ const NOT_REPORTED_AS_LIVE = new Set(['google', ...AD_PLATFORMS])
1627
1628
  * file with those is how to tell it is stale, by the backend's own contract.
1628
1629
  *
1629
1630
  * ⛔ A request is never said as what the site has: what is live is the backend's to say.
1631
+ *
1632
+ * And `hosting.blueprint` after it, for a site whose backend has started: a changed
1633
+ * `blueprint.yml` no longer reaches that backend (`backend/blueprint-reach.js`).
1630
1634
  */
1631
1635
  async function servicesCheck({ siteDir, siteYml, site }) {
1632
1636
  const { readServicesRequest } = await import('@uniweb/build/uwx')
@@ -1669,6 +1673,8 @@ async function servicesCheck({ siteDir, siteYml, site }) {
1669
1673
  if (offHere.length) {
1670
1674
  lines.push(`site.yml turns off ${list(offHere)}, which the live site has — a request the owner settles; a paid service stays on until its subscription changes.`)
1671
1675
  }
1676
+ // `hosting.blueprint`: once the site's backend has started, a changed blueprint.yml no longer reaches it.
1677
+ const blueprint = await blueprintCheck({ siteDir, status: site })
1672
1678
  return {
1673
1679
  checks: [
1674
1680
  {
@@ -1677,7 +1683,8 @@ async function servicesCheck({ siteDir, siteYml, site }) {
1677
1683
  summary: live.length ? `Services on the live site: ${list(live)}.` : site.published ? 'No services on the live site.' : 'No services live — the site is not.',
1678
1684
  lines,
1679
1685
  detail: { asked, requested, live }
1680
- }
1686
+ },
1687
+ ...(blueprint ? [blueprint] : [])
1681
1688
  ],
1682
1689
  proposals
1683
1690
  }
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-11T02:16:44.434Z",
3
+ "generatedAt": "2026-11-11T03:49:06.860Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.7.0"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.20.9"
9
+ "version": "1.20.10"
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.12"
57
+ "version": "1.2.13"
58
58
  },
59
59
  "@uniweb/theming": {
60
60
  "version": "1.3.2"