uniweb 1.31.11 → 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.11",
3
+ "version": "1.31.13",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -42,14 +42,14 @@
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
44
  "@uniweb/content-writer": "~1.3.1",
45
- "@uniweb/schemas": "~1.7.1",
46
45
  "@uniweb/core": "~1.6.12",
47
- "@uniweb/semantic-parser": "~1.13.2"
46
+ "@uniweb/schemas": "~1.7.1",
47
+ "@uniweb/semantic-parser": "~1.13.3"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.20.9",
50
+ "@uniweb/build": "~1.20.10",
51
51
  "@uniweb/content-reader": "~1.5.9",
52
- "@uniweb/semantic-parser": "~1.13.2"
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.
@@ -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 directory: `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 nothing to configure: a local build, `uniweb dev` included, reads the type from the package of the workspace that defines it (a foundation whose name gives the `@acme` scope, with the type in its own `schemas/`), or from a library the foundation bundles whose package.json gives that scope (`uniweb guide foundation` § Libraries). Two packages defining it stop the build, naming both. A type no such package defines comes from `schemas.config.js` (`'@acme/member': '../elsewhere/member.yml'`, or the scope's directory), which wins over both, 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 type a library defines is registered from the library, first (`uniweb guide foundation` § Libraries). 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. Two sites whose `paths: { records: … }` name one folder are not that: each push sends the folder's records as its own, two of each on the backend. 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 nothing to configure: a local build, `uniweb dev` included, reads the type from the package of the workspace that defines it (a foundation whose name gives the `@acme` scope, with the type in its own `schemas/`), or from a library the foundation bundles whose package.json gives that scope (`uniweb guide foundation` § Libraries). Two packages defining it stop the build, naming both. A type no such package defines comes from `schemas.config.js` (`'@acme/member': '../elsewhere/member.yml'`, or the scope's directory), which wins over both, 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 type a library defines is registered from the library, first (`uniweb guide foundation` § Libraries). 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. That site can be in another repository checked out beside this one: the foundation then reads the type through `schemas.config.js` or a schemas package, and the push reads the records' ids from that site's committed `sync.json`. Two sites whose `paths: { records: … }` name one folder are not that: each push sends the folder's records as its own, two of each on the backend. 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 } }
@@ -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.')
@@ -116,7 +116,7 @@ import {
116
116
  readItemBaseVersions
117
117
  } from '../backend/site-sync.js'
118
118
  import { resolveWorkspace } from '../backend/workspace.js'
119
- import { siteRoots, sentRoots, laneRoots, writableMounts, refusedMountLines, heldMountLines } from '../utils/site-roots.js'
119
+ import { siteRoots, sentRoots, laneRoots, writableMounts, refusedMountLines, heldMountLines, levelsAboveRepository } from '../utils/site-roots.js'
120
120
  import {
121
121
  repoOf,
122
122
  mergeInProgress,
@@ -1201,7 +1201,8 @@ export async function pull(args = [], deps = {}) {
1201
1201
  return { repo: m.repo, at: m.at, roots: [m.root], segment: m.segment, rev: force ? m.repo.head : own ?? m.repo.head, parent: force ? m.repo.head : own }
1202
1202
  })
1203
1203
  try {
1204
- standIn = openStandIn(repo, { roots, rev: onto, nested })
1204
+ // As far above the repository as the site's paths reach, so a mount beside it resolves there too.
1205
+ standIn = openStandIn(repo, { roots, rev: onto, nested, above: levelsAboveRepository(siteDir, repo, onto) })
1205
1206
  } catch (err) {
1206
1207
  error(`Could not merge the site: ${err.message}.`)
1207
1208
  return { exitCode: 1 }
@@ -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-10T20:35:09.553Z",
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"
@@ -36,7 +36,7 @@
36
36
  "version": "1.2.16"
37
37
  },
38
38
  "@uniweb/runtime": {
39
- "version": "1.5.8"
39
+ "version": "1.5.9"
40
40
  },
41
41
  "@uniweb/scene": {
42
42
  "version": "1.0.1"
@@ -45,16 +45,16 @@
45
45
  "version": "1.7.1"
46
46
  },
47
47
  "@uniweb/scholar": {
48
- "version": "1.1.0"
48
+ "version": "1.1.1"
49
49
  },
50
50
  "@uniweb/semantic-parser": {
51
- "version": "1.13.2"
51
+ "version": "1.13.3"
52
52
  },
53
53
  "@uniweb/snapshot": {
54
54
  "version": "1.1.2"
55
55
  },
56
56
  "@uniweb/templates": {
57
- "version": "1.2.11"
57
+ "version": "1.2.13"
58
58
  },
59
59
  "@uniweb/theming": {
60
60
  "version": "1.3.2"
@@ -21,7 +21,7 @@ import yaml from 'js-yaml'
21
21
  import { siteContentRoots } from '@uniweb/build/uwx'
22
22
  import { mountEntriesOf } from '@uniweb/build/site'
23
23
  import { mountHolding } from './mounted-repositories.js'
24
- import { repoOf } from './sync-point.js'
24
+ import { fileAt, repoOf } from './sync-point.js'
25
25
 
26
26
  function readSiteYml(siteDir) {
27
27
  try {
@@ -64,6 +64,65 @@ export function laneRoots(siteDir) {
64
64
  }
65
65
  }
66
66
 
67
+ /**
68
+ * ⭐ HOW FAR ABOVE ITS REPOSITORY THE SITE REACHES: the most directories above the repository's top
69
+ * that one of the site's relative paths climbs, `site.yml`'s `paths:` and its `file:` and `link:`
70
+ * dependencies, as this copy holds them and as `rev` does. A pull's stand-in mirrors that far up
71
+ * (`openStandIn`), so a records or pages mount in a repository beside the site's resolves there as in
72
+ * the project. ⛔ Until 2026-11-10 none did: a records mount there stopped every pull, and `status`,
73
+ * with "not a directory here", and a pages mount there failed the pull's re-bank, so the next push
74
+ * sent the whole site again.
75
+ *
76
+ * @param {string} siteDir
77
+ * @param {object|null} repo - `repoOf(siteDir)`
78
+ * @param {string|null} [rev] - the commit the stand-in is filled from
79
+ * @returns {number}
80
+ */
81
+ export function levelsAboveRepository(siteDir, repo, rev = null) {
82
+ if (!repo) return 0
83
+ const depth = repo.prefix.split('/').filter(Boolean).length
84
+ const climbOf = (path) => {
85
+ const p = typeof path === 'string' ? path.trim() : ''
86
+ if (!p || isAbsolute(p)) return 0
87
+ let level = depth
88
+ let low = depth
89
+ for (const segment of p.split(/[\\/]+/)) {
90
+ if (segment === '..') low = Math.min(low, --level)
91
+ else if (segment && segment !== '.') level++
92
+ }
93
+ return Math.max(0, -low)
94
+ }
95
+ const parsed = (text, parse) => {
96
+ try {
97
+ return text == null ? null : parse(String(text))
98
+ } catch {
99
+ return null // unreadable: it names no path
100
+ }
101
+ }
102
+ const here = (name) => {
103
+ try {
104
+ return readFileSync(join(siteDir, name), 'utf8')
105
+ } catch {
106
+ return null
107
+ }
108
+ }
109
+ const copies = [[here('site.yml'), here('package.json')]]
110
+ if (rev) copies.push([fileAt(repo, rev, 'site.yml'), fileAt(repo, rev, 'package.json')])
111
+ const paths = []
112
+ for (const [siteYml, packageJson] of copies) {
113
+ for (const value of Object.values(parsed(siteYml, (t) => yaml.load(t))?.paths || {})) {
114
+ paths.push(typeof value === 'string' ? value : value?.path)
115
+ }
116
+ const pkg = parsed(packageJson, (t) => JSON.parse(t))
117
+ for (const field of ['dependencies', 'devDependencies', 'optionalDependencies']) {
118
+ for (const spec of Object.values(pkg?.[field] || {})) {
119
+ if (typeof spec === 'string' && /^(file|link):/.test(spec)) paths.push(spec.replace(/^(file|link):/, ''))
120
+ }
121
+ }
122
+ }
123
+ return Math.max(0, ...paths.map(climbOf))
124
+ }
125
+
67
126
  /**
68
127
  * The submodules that hold a mounted folder, each by its path relative to the site: the commit the
69
128
  * site's repository records for one is the site's to commit, and `uniweb status` reads a pin that
@@ -42,6 +42,7 @@ import {
42
42
  mkdtempSync,
43
43
  readdirSync,
44
44
  readFileSync,
45
+ realpathSync,
45
46
  rmSync,
46
47
  statSync,
47
48
  symlinkSync,
@@ -49,7 +50,7 @@ import {
49
50
  writeFileSync
50
51
  } from 'node:fs'
51
52
  import { tmpdir } from 'node:os'
52
- import { join, dirname, posix } from 'node:path'
53
+ import { join, basename, dirname, posix, sep } from 'node:path'
53
54
 
54
55
  export const SYNC_TRAILER = 'Uniweb-Sync'
55
56
  export const SITE_TRAILER = 'Uniweb-Site'
@@ -460,6 +461,13 @@ export function nestedBase(repo, siteBase, { at, sub, roots }) {
460
461
  * site's `sync.json` and `.uniweb/`, which are copies (written there, and taken back by the
461
462
  * caller). The stand-in lives outside the project.
462
463
  *
464
+ * ⭐ AND WHAT IS AROUND THE REPOSITORY, `above` directories up: the repository stands that deep,
465
+ * under directories named as its parents, each holding links to what is beside it there. So a path
466
+ * leading out of the repository, a records or pages mount in a repository beside it, resolves as in
467
+ * the project too. With `above` 0 the stand-in is the repository's alone. ⛔ Until 2026-11-10 it
468
+ * always was: such a path resolved under the temporary folder, which stopped every pull of a site
469
+ * mounting another repository's records ("not a directory here").
470
+ *
463
471
  * ⛔ CLOSE IT. `close()` unlinks every link it made before removing the rest — a recursive
464
472
  * remove that followed one would delete the project's own files.
465
473
  *
@@ -481,9 +489,11 @@ export function nestedBase(repo, siteBase, { at, sub, roots }) {
481
489
  * each submodule a writable mount is in: its `repoOf`, its path from the site repository's top,
482
490
  * the mounted folders in it (relative to its own top), the commit they are filled from, and the
483
491
  * one a commit of them is made onto (null: none, an unrelated history)
492
+ * @param {number} [opts.above] - how many directories above the repository's top to mirror: as far
493
+ * as the site's relative paths climb (`levelsAboveRepository`, `utils/site-roots.js`)
484
494
  * @returns {{ siteDir: string, commit: Function, changes: Function, placeIgnored: Function, close: Function }}
485
495
  */
486
- export function openStandIn(repo, { roots, rev, nested = [] }) {
496
+ export function openStandIn(repo, { roots, rev, nested = [], above = 0 }) {
487
497
  // ⭐ A root is named relative to the site and held by the repository, so one outside the site's
488
498
  // folder — a mounted folder elsewhere in the repository — is filled and committed like the rest.
489
499
  // One outside the repository is in no commit of it. ⛔ Until 2026-11-04 every root leading out of
@@ -494,7 +504,19 @@ export function openStandIn(repo, { roots, rev, nested = [] }) {
494
504
  throw new Error(`the content root \`${r}\` is outside the site's repository, so a pull cannot merge it`)
495
505
  }
496
506
  })
497
- const root = mkdtempSync(join(tmpdir(), 'uniweb-stand-in-'))
507
+ const base = mkdtempSync(join(tmpdir(), 'uniweb-stand-in-'))
508
+ // The directories above the repository the stand-in mirrors, nearest first, each with the name of
509
+ // the one below it on the way down; `base` stands for the farthest, and the repository's own stand-in
510
+ // is named as it is, under them.
511
+ const around = []
512
+ for (let real = repo.top; around.length < above && dirname(real) !== real; real = dirname(real)) {
513
+ around.push({ dir: dirname(real), child: basename(real) })
514
+ }
515
+ let root = base
516
+ for (let k = around.length - 1; k >= 0; k--) {
517
+ around[k].stand = root
518
+ root = join(root, around[k].child)
519
+ }
498
520
  const indexDir = mkdtempSync(join(tmpdir(), 'uniweb-stand-in-index-'))
499
521
  const env = { GIT_INDEX_FILE: join(indexDir, 'index') }
500
522
  const at = (args, opts = {}) =>
@@ -523,7 +545,7 @@ export function openStandIn(repo, { roots, rev, nested = [] }) {
523
545
  /* already gone */
524
546
  }
525
547
  }
526
- rmSync(root, { recursive: true, force: true })
548
+ rmSync(base, { recursive: true, force: true })
527
549
  rmSync(indexDir, { recursive: true, force: true })
528
550
  }
529
551
 
@@ -597,6 +619,34 @@ export function openStandIn(repo, { roots, rev, nested = [] }) {
597
619
  } else link(real, stand, name)
598
620
  }
599
621
  }
622
+ // What is beside the repository, and beside each directory above it, as far up as `around` goes.
623
+ const realBase = realpathSync(base)
624
+ for (const { dir, child, stand } of around) {
625
+ mkdirSync(stand, { recursive: true })
626
+ let names = []
627
+ try {
628
+ names = readdirSync(dir)
629
+ } catch {
630
+ continue // unreadable: nothing resolves through it in the project either
631
+ }
632
+ for (const name of names) {
633
+ if (name === child) continue
634
+ let target
635
+ try {
636
+ target = realpathSync(join(dir, name))
637
+ } catch {
638
+ continue
639
+ }
640
+ // ⛔ Never the stand-in itself, nor a folder holding it: a link back into it is a loop.
641
+ if (target === realBase || realBase.startsWith(`${target}${sep}`)) continue
642
+ try {
643
+ link(join(dir, name), join(stand, name), name)
644
+ } catch {
645
+ // One the system will not link (macOS refuses a protected folder, `TemporaryItems`) is left
646
+ // out: only a path through it would miss it, as every such path did before.
647
+ }
648
+ }
649
+ }
600
650
  mirror(repo.top, root, '')
601
651
  if (sitePath) mkdirSync(join(root, sitePath), { recursive: true })
602
652