uniweb 1.26.7 → 1.26.9

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.26.7",
3
+ "version": "1.26.9",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -41,14 +41,14 @@
41
41
  "js-yaml": "^4.3.2",
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
+ "@uniweb/content-writer": "~1.3.1",
44
45
  "@uniweb/core": "~1.6.4",
45
46
  "@uniweb/semantic-parser": "~1.13.2",
46
- "@uniweb/schemas": "~1.6.7",
47
- "@uniweb/content-writer": "~1.3.1"
47
+ "@uniweb/schemas": "~1.6.8"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.15.5",
51
- "@uniweb/content-reader": "~1.5.8",
50
+ "@uniweb/build": "~1.15.6",
51
+ "@uniweb/content-reader": "~1.5.9",
52
52
  "@uniweb/semantic-parser": "~1.13.2"
53
53
  },
54
54
  "peerDependenciesMeta": {
@@ -73,9 +73,13 @@ fields:
73
73
  # schemas/course.yml
74
74
  fields:
75
75
  lessons: { ref: '@/lesson', many: true, sold_with: true } # a buyer of the course reads its lessons (up to three steps)
76
+
77
+ # schemas/inquiry.yml
78
+ fields:
79
+ email: { type: email, required: true, visitor_fills: true } # a site's visitor may fill it, with no account
76
80
  ```
77
81
 
78
- `readable_with` (`read` | `edit` | `admin`, only on a reference) is one step; a backend refuses adding it to a field entries already fill. `grantable: false` keeps entries from being shared with a person or team. `sold_with` only on a reference; an unmarked one carries nothing.
82
+ `readable_with` (`read` | `edit` | `admin`, only on a reference) is one step; a backend refuses adding it to a field entries already fill. `grantable: false` keeps entries from being shared with a person or team. `sold_with` only on a reference; an unmarked one carries nothing. `visitor_fills: true` marks a field a site's visitor may fill, and a type with one takes visitors' submissions, confirmed by email. Mark it per field, on a top-level section's fields only. The build refuses it on files, on a reference with `readable_with`/`sold_with`, and in a section that leaves a `required` field unmarked.
79
83
 
80
84
  ## Acting as an administrator
81
85
 
@@ -239,7 +239,7 @@ extensions: ['@acme/fx@0.3.1']
239
239
 
240
240
  **Routes:** folders map 1:1 to routes; `pages:` controls order only. The site root is the exception: the first of `pages:` sets `/`, else `index:`, declared in `site.yml` or in the pages directory's own `folder.yml`/`page.yml`, with `site.yml` winning. A folder with `page.yml` but no markdown is a structural group (`hasContent: false`); visiting it redirects to the first descendant with content.
241
241
 
242
- **Mounted folders:** a local folder for a mounted route says how *this site* presents it. Keep `layout:`, `title:` and SEO in a `folder.yml` there; the mounted repo's own `folder.yml` supplies ordering and title where the stub is silent. A `page.yml` with markdown of its own makes a real page above the mounted pages — a landing page for the branch. A mount is one level under `pages/`, and a subfolder in the local folder isn't read, since the branch's pages come from the mount; the build says so. What a site can't do from outside a repo it mounts: leave a file out, title or order a nested folder, or use a `README.md` as a page — those are the mounted repo's to do. A relative link to a markdown file (`./deploying.md#setup`), which is how docs in a repo link to each other, leads to the page that file became; the build names one that leads nowhere. A mount that is its own repository (a submodule, or a clone beside the site) takes its edits as commits there, and `uniweb refresh` takes its latest; a push or publish stops on one that is behind its remote or holds uncommitted changes, and `--mounts-as-is` sends it as it is.
242
+ **Mounted folders:** a local folder for a mounted route says how *this site* presents it. Keep `layout:`, `title:` and SEO in a `folder.yml` there; the mounted repo's own `folder.yml` supplies ordering and title where the stub is silent. A `page.yml` with markdown of its own makes a real page above the mounted pages — a landing page for the branch. A mount is one level under `pages/`, and a subfolder in the local folder isn't read, since the branch's pages come from the mount; the build says so. What a site can't do from outside a repo it mounts: leave a file out, title or order a nested folder, or use a `README.md` as a page — those are the mounted repo's to do. A relative link to a markdown file (`./deploying.md#setup`), which is how docs in a repo link to each other, leads to the page that file became; the build names one that leads nowhere. A mount that is its own repository (a submodule, or a clone beside the site) takes its edits as commits there, and `uniweb refresh` takes its latest; a push or publish stops on one that is behind its remote or holds uncommitted changes, and `--mounts-as-is` sends it as it is. A pull leaves a mounted folder as it is and names each page an author changed in the app, which the next push undoes; `pages/docs: { path: ../docs, writable: true }` has a pull write those edits into the folder instead, where the site's own repository holds it or a submodule of it does (a commit there, to push before the site's repository), and stop on a writable mount anywhere else.
243
243
 
244
244
  **Visibility flags:** `hidden: true` is a draft (not published; `uniweb dev` previews it; on a page it takes the pages below with it; on a section it's also kept from the component's params and takes its children with it); `hideIn: ['*']` or `[header]` controls nav placement only; `knowledge: true` is a different audience (below). An authored `pages/404/` needs no flag — `hidden: true` there makes it a draft and the site falls back to the generic 404.
245
245
 
@@ -27,7 +27,7 @@ import {
27
27
  unmergedPaths,
28
28
  mergeInProgress
29
29
  } from '../utils/sync-point.js'
30
- import { siteContentRoots } from '../utils/git.js'
30
+ import { sentRoots } from '../utils/site-roots.js'
31
31
  import { humanBytes } from '../utils/bytes.js'
32
32
  import {
33
33
  describeRequestError,
@@ -1095,8 +1095,9 @@ export function holdUnchangedPush(siteDir, backend) {
1095
1095
  return repo.head
1096
1096
  }
1097
1097
 
1098
- /** What a push sends from the files: the site's content, and its media (`public/`). */
1099
- export const sentRoots = (siteDir) => [...siteContentRoots(siteDir), 'public']
1098
+ // What a push sends from the files — the site's content, its media (`public/`) and the mounted folders
1099
+ // its repository holds — is `utils/site-roots.js`'s to say; re-exported for the readers that ask here.
1100
+ export { sentRoots }
1100
1101
 
1101
1102
  /**
1102
1103
  * ⛔ IN A REPOSITORY, A PUSH SENDS WHAT IS COMMITTED. The commit a push is made from is where
@@ -1104,6 +1105,11 @@ export const sentRoots = (siteDir) => [...siteContentRoots(siteDir), 'public']
1104
1105
  * the push sends must be what that commit holds. Returns the refusal, or null: outside a
1105
1106
  * repository nothing is kept to merge from.
1106
1107
  *
1108
+ * ⭐ A page folder mounted from elsewhere in the same repository (`paths: { pages/<segment> }`) is
1109
+ * one of `sentRoots`, so it is held to its commits like the site's pages. ⛔ Until 2026-11-04 no
1110
+ * mount was: its uncommitted edits went out with the push, which named HEAD (measured that day).
1111
+ * A mount that is a repository of its own is held to its commits by `mounts-before-sending.js`.
1112
+ *
1107
1113
  * ⛔ Until 2026-10-18 a push sent uncommitted edits on top of HEAD and recorded HEAD. Measured
1108
1114
  * against a real backend: an edit pushed that way and undone before the next pull came back
1109
1115
  * with it — exit 0, no conflict, reported as the backend's change. Every such push also had
@@ -2183,12 +2189,12 @@ export async function entityHashes(siteDir, backend = null, { declarations, fiel
2183
2189
  * @param {Map<string,object>} [opts.declarations] - the Models the pull read, by name — so a
2184
2190
  * site whose foundation is not in the project (a clone's) can be re-banked offline
2185
2191
  */
2186
- export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, declarations, fields = null, contentTaken = false } = {}) {
2192
+ export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, declarations, fields = null, contentTaken = false, contentAgreed = true } = {}) {
2187
2193
  // ⛔ With the keys this deployment's Sections take, when the caller has them (`deploymentFields`):
2188
2194
  // they shape the document the next push sends (`typed_by_data_key`, `og_title`), so a hash banked
2189
2195
  // without them marks a clone's first push as changed. Until 2026-09-26 a pull banked none.
2190
2196
  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true, declarations, fields })
2191
- writeSyncCache(siteDir, backend, onlyWhatThePullTook(siteDir, backend, pkg, recordDocs), pkg.applied || {})
2197
+ writeSyncCache(siteDir, backend, onlyWhatThePullTook(siteDir, backend, pkg, recordDocs, { contentAgreed }), pkg.applied || {})
2192
2198
  // ⭐ And the local unit base, from what this copy would send for the content the pull took, so a
2193
2199
  // refusal after a pull can tell this copy's edits from the backend's. ⛔ Until 2026-10-30 a pull
2194
2200
  // left it empty, and the next refusal said "No record of your last sync" just after one.
@@ -2227,8 +2233,12 @@ export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, de
2227
2233
  *
2228
2234
  * @param {object[]|undefined} recordDocs - the record documents the pull took
2229
2235
  */
2230
- function onlyWhatThePullTook(siteDir, backend, pkg, recordDocs) {
2236
+ function onlyWhatThePullTook(siteDir, backend, pkg, recordDocs, { contentAgreed = true } = {}) {
2231
2237
  const hashes = { ...(pkg.hashes || {}) }
2238
+ // ⭐ A site whose files do not hold some page as the backend does — a mounted page the app changed,
2239
+ // one held because its file cannot say the change — is not agreed: its hash is not banked, so the next
2240
+ // push sends it, the folder winning where it is read-only and the gate keeping a held page's.
2241
+ if (!contentAgreed) for (const key of Object.keys(hashes)) if (key.startsWith('@uniweb/site-content ')) delete hashes[key]
2232
2242
  const prior = readSyncCache(siteDir, backend)
2233
2243
  const keep = (key) => {
2234
2244
  if (Object.hasOwn(prior, key)) hashes[key] = prior[key]
@@ -71,7 +71,8 @@ import {
71
71
  statSync
72
72
  } from 'node:fs'
73
73
  import { createInterface } from 'node:readline/promises'
74
- import { join, dirname, relative, resolve } from 'node:path'
74
+ import { join, dirname, relative, resolve, posix } from 'node:path'
75
+ import { execFileSync } from 'node:child_process'
75
76
  import yaml from 'js-yaml'
76
77
  import { downloadMissingAssets, downloadFileRecords } from '../backend/asset-download.js'
77
78
  import {
@@ -112,7 +113,7 @@ import {
112
113
  readItemBaseVersions
113
114
  } from '../backend/site-sync.js'
114
115
  import { resolveWorkspace } from '../backend/workspace.js'
115
- import { siteContentRoots, siteLaneRoots } from '../utils/git.js'
116
+ import { siteRoots, sentRoots, laneRoots, writableMounts, refusedMountLines } from '../utils/site-roots.js'
116
117
  import {
117
118
  repoOf,
118
119
  mergeInProgress,
@@ -127,6 +128,9 @@ import {
127
128
  openStandIn,
128
129
  fileAt,
129
130
  mergeSyncPoint,
131
+ mergeStopper,
132
+ nestedBase,
133
+ recordNestedPins,
130
134
  takeSyncPoint,
131
135
  snapshotFiles,
132
136
  changedInFiles,
@@ -134,7 +138,7 @@ import {
134
138
  readSyncPoint,
135
139
  writeSyncPoint
136
140
  } from '../utils/sync-point.js'
137
- import { behindLines } from '../utils/mounted-repositories.js'
141
+ import { behindLines, mountedRepositories } from '../utils/mounted-repositories.js'
138
142
  import { isNonInteractive } from '../utils/interactive.js'
139
143
  import {
140
144
  BackendClient,
@@ -504,6 +508,24 @@ function filesUnder(siteDir, roots) {
504
508
  return out
505
509
  }
506
510
 
511
+ // ⭐ A VERSION IS BANKED FOR WHAT THE FILES TOOK, OR CHOSE NOT TO TAKE. A page held because its file
512
+ // cannot say the app's change keeps the version this copy last agreed on, so the per-item gate keeps the
513
+ // backend's copy while the file is unchanged and refuses a push that changed it. One this copy never agreed
514
+ // on keeps the backend's: there is no agreement to hold. A mount's page takes the backend's, so the next
515
+ // push puts the folder's back.
516
+ export function agreedVersions(pulled, heldPages, prior) {
517
+ const out = { ...pulled }
518
+ for (const { uuids } of heldPages || []) for (const u of uuids || []) if (prior?.[u]) out[u] = prior[u]
519
+ return out
520
+ }
521
+
522
+ // The mounted pages the backend holds at another version than this copy last agreed on, by route.
523
+ export function mountedPagesMoved(mountedPages, pulled, prior) {
524
+ return (mountedPages || [])
525
+ .filter(({ uuids }) => (uuids || []).some((u) => prior?.[u] && pulled?.[u] && prior[u] !== pulled[u]))
526
+ .map(({ route }) => route)
527
+ }
528
+
507
529
  /**
508
530
  * Outside git, refuse a pull that would overwrite unsaved work. Returns a result object to
509
531
  * return from `pull`, or null to proceed.
@@ -515,7 +537,7 @@ function filesUnder(siteDir, roots) {
515
537
  * terminal to ask, refused here, and `uniweb clone` could not finish.
516
538
  */
517
539
  async function checkWorkingTree(siteDir, args) {
518
- const roots = siteContentRoots(siteDir)
540
+ const roots = siteRoots(siteDir, { media: false })
519
541
  const written = readWritten(siteDir)
520
542
  if (filesUnder(siteDir, roots).every((f) => isPullOutput(siteDir, f, written))) return null
521
543
  // A folder the repository around it ignores is outside git too — said as such, since a
@@ -759,6 +781,34 @@ export async function pull(args = [], deps = {}) {
759
781
  const blocked = await checkWorkingTree(siteDir, args)
760
782
  if (blocked) return blocked
761
783
  }
784
+ // ⭐ A MOUNT IS WRITTEN WHERE THE SITE SAYS `writable: true` AND THIS COPY CAN MERGE IT
785
+ // (`writableMounts`). One it cannot stops the pull before anything is asked or taken: left read-only,
786
+ // the app's edits to it would be undone by the next push, which is what the declaration asks to avoid.
787
+ const mounts = writableMounts(siteDir)
788
+ if (mounts.refused.length) {
789
+ if (probe) return { exitCode: 1, probe: null }
790
+ error(`${mounts.refused.length === 1 ? 'A mount' : `${mounts.refused.length} mounts`} marked writable cannot be written by a pull:`)
791
+ for (const m of mounts.refused) for (const line of refusedMountLines(m)) note(line)
792
+ return { exitCode: 1 }
793
+ }
794
+ // …and a submodule one is in merges too, so it is stopped by what would stop the site's merge.
795
+ if (repo && !dryRun && !probe) {
796
+ for (const m of mounts.submodules) {
797
+ const where = `${m.at}, the submodule pages/${m.segment} is mounted from`
798
+ if (mergeInProgress(m.repo)) {
799
+ error(`A merge is in progress in ${where}.`)
800
+ note('Finish it there (`git commit`) or abandon it (`git merge --abort`), then pull.')
801
+ return { exitCode: 1 }
802
+ }
803
+ const unsettled = unmergedPaths(m.repo)
804
+ if (unsettled.length) {
805
+ error(`${unsettled.length} file(s) in ${where} are in conflict:`)
806
+ for (const p of unsettled.slice(0, 12)) note(` ${p}`)
807
+ note('Settle them there first — `git status` says how — then pull.')
808
+ return { exitCode: 1 }
809
+ }
810
+ }
811
+ }
762
812
  // ⭐ THE BACKEND YOU ARE LOGGED IN TO is where this goes *[Diego, 2026-09-21]*, for every
763
813
  // backend verb (resolveBackendOrigin). Only UNIWEB_SERVER — the automation
764
814
  // override — outranks it, and nothing talks to a backend the user is not logged in to:
@@ -916,9 +966,15 @@ export async function pull(args = [], deps = {}) {
916
966
  let sections = 0
917
967
  let records = 0
918
968
  let deleted = 0
919
- // Pages written in files a pull does not write back — a mount's, a folder-mode folder's `.md`
920
- // pages (`@uniweb/build`'s `git-authored.js`). Said, since an app edit to one does not come back.
969
+ // The pages a pull does not write — a mount's, a folder-mode `.md` page given what its file cannot
970
+ // hold, a route the files give two pages for (`@uniweb/build`'s `page-files.js`). Said, since an app
971
+ // edit to one does not come back; each `.md` page with what it could not hold.
921
972
  let leftAlone = 0
973
+ // Its pages by outcome (`@uniweb/build`'s report): held at the version this copy last agreed on,
974
+ // and a mount's, which the folder wins.
975
+ let heldPages = []
976
+ let mountedPages = []
977
+ let mountedMoved = []
922
978
  // Set when the folder lane carried records this pull did not place — see the ⛔
923
979
  // where it is set.
924
980
  let recordsNotPlaced = null
@@ -932,6 +988,8 @@ export async function pull(args = [], deps = {}) {
932
988
  // only while the sync point it was banked with is.
933
989
  const cache = readPullCache(siteDir)
934
990
  const held = repo ? readSyncPoint(siteDir, client.origin) : null
991
+ // The versions this copy agreed on before this pull — what a held page keeps (`agreedVersions`).
992
+ const priorVersions = readItemBaseVersions(siteDir, client.origin)
935
993
  const cacheHolds = etagsHold(siteDir, client.origin, repo)
936
994
  let etagContent = cache.content
937
995
  let etagFolder = cache.folder
@@ -1082,11 +1140,15 @@ export async function pull(args = [], deps = {}) {
1082
1140
  // the base as its merge base. `--force`, and a history with no sync point, write onto
1083
1141
  // HEAD instead: the first to take the backend's whole, the second so a file both sides
1084
1142
  // hold alike merges without a word.
1085
- const roots = [...siteContentRoots(siteDir), 'public']
1143
+ const roots = sentRoots(siteDir)
1086
1144
  let base = null
1087
1145
  let onto = null
1088
1146
  let standIn = null
1089
1147
  let siteMovedFrom = null
1148
+ // ⭐ Each writable mount in a submodule, merged in the submodule's own history from the commit the
1149
+ // site's base records for it (`nestedBase`). With no base there, it is filled from its checkout and
1150
+ // committed onto nothing, as the site is with none: a file both hold alike merges without a word.
1151
+ let nested = []
1090
1152
  if (repo && projected) {
1091
1153
  // The bases this copy knows of itself — then what the backend names, per lane.
1092
1154
  const known = [
@@ -1095,14 +1157,14 @@ export async function pull(args = [], deps = {}) {
1095
1157
  // What a sync point the branch no longer holds — a merge abandoned — was made onto.
1096
1158
  ...madeOnto(repo, held, { origin: client.origin, siteUuid: siteContentUuid })
1097
1159
  ]
1098
- const laneRoots = siteLaneRoots(siteDir)
1160
+ const rootsOfLanes = laneRoots(siteDir)
1099
1161
  const taken = (lane) => lane && !lane.notModified && !lane.refused
1100
1162
  base = baseFor(repo, {
1101
1163
  known,
1102
1164
  // ⛔ What each lane the backend answered names is a base only where every lane holds it (`baseFor`).
1103
1165
  lanes: [
1104
- ...(taken(content) ? [{ source: content.source, roots: laneRoots.content }] : []),
1105
- ...(taken(folderLane) ? [{ source: folderLane.source, roots: laneRoots.records }] : [])
1166
+ ...(taken(content) ? [{ source: content.source, roots: rootsOfLanes.content }] : []),
1167
+ ...(taken(folderLane) ? [{ source: folderLane.source, roots: rootsOfLanes.records }] : [])
1106
1168
  ],
1107
1169
  origin: client.origin,
1108
1170
  siteUuid: siteContentUuid
@@ -1113,8 +1175,12 @@ export async function pull(args = [], deps = {}) {
1113
1175
  onto = force || !base ? repo.head : base
1114
1176
  // Why there is no base, when it is a move. Read now: the sync point this pull makes names the new path.
1115
1177
  if (!base) siteMovedFrom = movedFrom(repo, { origin: client.origin, siteUuid: siteContentUuid })
1178
+ nested = mounts.submodules.map((m) => {
1179
+ const own = force || !base ? null : nestedBase(repo, base, { at: m.at, sub: m.repo, roots: [m.root] })
1180
+ 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 }
1181
+ })
1116
1182
  try {
1117
- standIn = openStandIn(repo, { roots, rev: onto })
1183
+ standIn = openStandIn(repo, { roots, rev: onto, nested })
1118
1184
  } catch (err) {
1119
1185
  error(`Could not merge the site: ${err.message}.`)
1120
1186
  return { exitCode: 1 }
@@ -1186,7 +1252,9 @@ export async function pull(args = [], deps = {}) {
1186
1252
  // So a query's `@acme/member` comes back as the author's `@/member`.
1187
1253
  scope: pullScope,
1188
1254
  dataModel,
1189
- sectionType
1255
+ sectionType,
1256
+ // The mounts it may write into, each one the site declares writable (above).
1257
+ writableMounts: mounts.writable
1190
1258
  })
1191
1259
  wrote.push(...report.pages, ...report.sections, ...report.layout)
1192
1260
  removed.push(
@@ -1197,6 +1265,9 @@ export async function pull(args = [], deps = {}) {
1197
1265
  sections += report.sections.length
1198
1266
  deleted += report.deleted.length
1199
1267
  leftAlone += report.leftAlone?.length || 0
1268
+ heldPages = report.held || []
1269
+ mountedPages = report.mountedPages || []
1270
+ mountedMoved = mountedPagesMoved(mountedPages, pulledVersions, priorVersions)
1200
1271
  outsideLanguages = report.outsideLanguages || []
1201
1272
  }
1202
1273
 
@@ -1293,6 +1364,10 @@ export async function pull(args = [], deps = {}) {
1293
1364
  probe: {
1294
1365
  files: standIn.changes(),
1295
1366
  itemsBehind,
1367
+ // By route: the mounted pages the backend moved, which the next push puts back, and the pages
1368
+ // held because their files cannot say what the app made of them.
1369
+ mountedMoved,
1370
+ held: heldPages.map(({ route, what }) => ({ route, what })),
1296
1371
  recordsNotPlaced: Boolean(recordsNotPlaced),
1297
1372
  ...(base ? {} : { noBase: true, movedFrom: siteMovedFrom })
1298
1373
  }
@@ -1339,7 +1414,8 @@ export async function pull(args = [], deps = {}) {
1339
1414
  recordDocs: pulledRecordDocs,
1340
1415
  ...(declarations.size ? { declarations } : {}),
1341
1416
  fields,
1342
- contentTaken: Boolean(siteDoc)
1417
+ contentTaken: Boolean(siteDoc),
1418
+ contentAgreed: !heldPages.length && !mountedMoved.length
1343
1419
  })
1344
1420
  } catch (err) {
1345
1421
  note(`! could not re-bank the sync cache: ${err.message}`)
@@ -1379,9 +1455,43 @@ export async function pull(args = [], deps = {}) {
1379
1455
  } else {
1380
1456
  // The files as they are, to tell what the pull changes in them from what they held.
1381
1457
  const files = snapshotFiles(repo)
1382
- const result = force
1383
- ? takeSyncPoint(repo, made.commit, { roots, message: takenFrom(client.origin) })
1384
- : mergeSyncPoint(repo, made.commit, { message: mergedFrom(client.origin) })
1458
+ // ⭐ EVERY REPOSITORY'S MERGE IS CHECKED BEFORE ANY IS MADE — each writable mount's submodule,
1459
+ // then the site's: one that cannot take its merge leaves every other as it was. Then each
1460
+ // submodule's is made, then the site's, whose commit records the one made in each.
1461
+ const subs = (made.nested || [])
1462
+ .filter((n) => n.commit)
1463
+ .map((n) => ({ ...n, segment: nested.find((x) => x.at === n.at)?.segment, before: n.repo.head, files: snapshotFiles(n.repo) }))
1464
+ let result = null
1465
+ if (!force) {
1466
+ for (const n of subs) {
1467
+ const stopped = mergeStopper(n.repo, n.commit)
1468
+ if (stopped) {
1469
+ result = { ...stopped, where: n.at }
1470
+ break
1471
+ }
1472
+ }
1473
+ if (!result) result = mergeStopper(repo, made.commit, { roots })
1474
+ }
1475
+ if (!result) {
1476
+ for (const n of subs) {
1477
+ n.result = force
1478
+ ? takeSyncPoint(n.repo, n.commit, { roots: n.roots, message: 'Take the edits made in the app' })
1479
+ : mergeSyncPoint(n.repo, n.commit, { message: 'Merge the edits made in the app' })
1480
+ if (!n.result.ok) {
1481
+ result = { ...n.result, where: n.at }
1482
+ break
1483
+ }
1484
+ }
1485
+ }
1486
+ if (!result) {
1487
+ result = force
1488
+ ? takeSyncPoint(repo, made.commit, { roots, message: takenFrom(client.origin) })
1489
+ : mergeSyncPoint(repo, made.commit, { message: mergedFrom(client.origin), roots })
1490
+ }
1491
+ // A path in a submodule, as the person reads it: from the site's folder.
1492
+ const fromSite = (p) => posix.relative(repo.path === '.' ? '.' : repo.path, p) || '.'
1493
+ const there = result.where ? ` in ${fromSite(result.where)}, a submodule a writable mount is in` : ''
1494
+ const named = (p) => (result.where ? fromSite(posix.join(result.where, p)) : p)
1385
1495
  if (!result.ok) {
1386
1496
  // ⛔ A merge that could not be made took nothing: the files are as they were, and
1387
1497
  // nothing of this pull is recorded as taken.
@@ -1389,24 +1499,46 @@ export async function pull(args = [], deps = {}) {
1389
1499
  restore(syncFile, before.sync)
1390
1500
  restore(cacheFile, before.cache)
1391
1501
  if (result.reason === 'untracked') {
1392
- error(`Not merged — the backend's content would overwrite ${result.paths.length} file(s) that are not committed:`)
1393
- for (const p of result.paths.slice(0, 12)) note(` ${p}`)
1502
+ error(`Not merged — the backend's content would overwrite ${result.paths.length} file(s)${there} that are not committed:`)
1503
+ for (const p of result.paths.slice(0, 12)) note(` ${named(p)}`)
1394
1504
  if (result.paths.length > 12) note(` … and ${result.paths.length - 12} more`)
1395
1505
  note('Commit them, or move them aside, then pull again.')
1396
1506
  } else if (result.reason === 'merge-in-progress') {
1397
- error('A merge is in progress here.')
1507
+ error(`A merge is in progress${there || ' here'}.`)
1398
1508
  note('Finish it (`git commit`) or abandon it (`git merge --abort`), then pull.')
1399
1509
  } else if (result.reason === 'unmerged') {
1400
- error(`${result.paths.length} file(s) here are in conflict:`)
1401
- for (const p of result.paths.slice(0, 12)) note(` ${p}`)
1510
+ error(`${result.paths.length} file(s)${there || ' here'} are in conflict:`)
1511
+ for (const p of result.paths.slice(0, 12)) note(` ${named(p)}`)
1402
1512
  note('Settle them first — `git status` says how — then pull.')
1403
1513
  } else {
1404
- error("Could not merge the backend's content:")
1514
+ error(`Could not merge the backend's content${there}:`)
1405
1515
  for (const line of String(result.detail).split('\n').slice(0, 8)) note(` ${line}`)
1406
1516
  }
1407
1517
  } else {
1408
1518
  merge.conflicted = result.conflicted || []
1409
1519
  merge.stashKept = Boolean(result.stashKept)
1520
+ // ⭐ Each submodule's merge, recorded as the site's pin (`recordNestedPins`).
1521
+ if (subs.length) {
1522
+ const recorded = recordNestedPins(
1523
+ repo,
1524
+ subs.map((n) => ({ at: n.at, repo: n.repo, conflicted: n.result.conflicted || [] })),
1525
+ { message: (at, head) => `${repo.path}: ${at} at ${head.slice(0, 7)}, with the edits made in the app` }
1526
+ )
1527
+ if (recorded.error) note(`! The site's pin of a submodule is not recorded: ${recorded.error}`)
1528
+ const siteNow = unmergedPaths(repo)
1529
+ if (recorded.concluded && siteNow.length) merge.stashKept = true
1530
+ merge.conflicted = [...siteNow, ...subs.flatMap((n) => (n.result.conflicted || []).map((p) => posix.join(n.at, p)))]
1531
+ merge.nested = subs.map((n) => ({
1532
+ at: n.at,
1533
+ segment: n.segment,
1534
+ files: n.files,
1535
+ before: n.before,
1536
+ repo: n.repo,
1537
+ conflicted: n.result.conflicted || [],
1538
+ stashKept: Boolean(n.result.stashKept),
1539
+ pin: recorded.pins.find((p) => p.at === n.at)
1540
+ }))
1541
+ }
1410
1542
  // Whether anything was set aside for the merge: the files as they were, against HEAD.
1411
1543
  merge.setAside = files !== repo.head
1412
1544
  merge.noBase = !force && !base
@@ -1414,9 +1546,15 @@ export async function pull(args = [], deps = {}) {
1414
1546
  merge.changed = changedInFiles(repo, {
1415
1547
  from: repo.head,
1416
1548
  files,
1549
+ roots,
1417
1550
  staged: merge.conflicted.length > 0 && !merge.stashKept,
1418
1551
  skip: merge.conflicted
1419
1552
  })
1553
+ // …and what each submodule's merge changed in its folders, from the site's folder.
1554
+ for (const n of merge.nested || []) {
1555
+ const changed = changedInFiles(n.repo, { from: n.before, files: n.files, staged: n.conflicted.length > 0 && !n.stashKept, skip: n.conflicted })
1556
+ merge.changed.push(...changed.map(([st, p]) => [st, fromSite(posix.join(n.at, p))]))
1557
+ }
1420
1558
  writeSyncPoint(siteDir, client.origin, made.commit)
1421
1559
  }
1422
1560
  }
@@ -1462,7 +1600,7 @@ export async function pull(args = [], deps = {}) {
1462
1600
  // again, asking the backend to delete it. The folder lane's are not kept — that lane
1463
1601
  // is gated by its entity version. (Both were merged into one map until 2026-10-07.)
1464
1602
  if (pulledVersions && content && !content.notModified && !content.refused) {
1465
- writeItemBaseVersions(siteDir, client.origin, pulledVersions)
1603
+ writeItemBaseVersions(siteDir, client.origin, agreedVersions(pulledVersions, heldPages, priorVersions))
1466
1604
  }
1467
1605
  // Persist the ETags so the next pull is conditional (304 when unchanged). The
1468
1606
  // folder's is DROPPED when records were not placed, so the next pull fetches
@@ -1483,9 +1621,23 @@ export async function pull(args = [], deps = {}) {
1483
1621
  else success(summary)
1484
1622
  if (leftAlone) {
1485
1623
  note(
1486
- `Left as written: ${leftAlone} page(s) whose files a pull does not write — a mounted folder's, or a folder-mode folder's \`.md\` pages. ` +
1624
+ `Left as written: ${leftAlone} page(s) a pull does not write — a mounted folder's, a \`.md\` page given what its file cannot say, or two pages on one route. ` +
1487
1625
  'An edit made to one in the app does not come back here, and the next push sends the file.'
1488
1626
  )
1627
+ if (mountedMoved.length) {
1628
+ note(
1629
+ `The backend holds a newer version of ${mountedMoved.length} mounted page(s), changed in the app: the next push puts the folder's back. ` +
1630
+ 'To keep a change, make it in the mounted folder, or mark its mount `writable: true` in site.yml.'
1631
+ )
1632
+ for (const route of mountedMoved) note(` /${route}`)
1633
+ }
1634
+ if (heldPages.length) {
1635
+ note(
1636
+ `Held: ${heldPages.length} page(s) whose files cannot say what the app made of them. The site keeps the app's version and the files keep theirs; ` +
1637
+ 'a push leaves it, and one that changes such a page is refused. Undo it in the app, or give the page a folder of its own with a page.yml, and pull again.'
1638
+ )
1639
+ for (const { route, what } of heldPages) note(` /${route}: ${what.join(', ')}`)
1640
+ }
1489
1641
  // ⭐ A mounted folder's pages are as current as its repository, which no pull moves.
1490
1642
  for (const line of await behindLines(siteDir)) note(line)
1491
1643
  }
@@ -1552,6 +1704,43 @@ export async function pull(args = [], deps = {}) {
1552
1704
  )
1553
1705
  }
1554
1706
  }
1707
+ // ⭐ A SUBMODULE'S NEW COMMITS ARE ITS OWN REPOSITORY'S, which no push of the site sends: its remote
1708
+ // must hold them before the site's remote holds the commit that names them, or a clone of the site
1709
+ // cannot check it out. The pull pushes neither; it says what to push, in that order.
1710
+ if (merge.nested?.length) {
1711
+ const surveyed = await mountedRepositories(siteDir)
1712
+ for (const n of merge.nested) {
1713
+ const dir = posix.relative(repo.path === '.' ? '.' : repo.path, n.at) || '.'
1714
+ // Each command as it runs from here.
1715
+ const abs = join(repo.top, n.at)
1716
+ const rel = relative(process.cwd(), abs) || '.'
1717
+ const here = rel.length <= abs.length ? rel : abs
1718
+ if (n.conflicted.length) {
1719
+ note(`${dir} is a submodule: settle its conflicts and commit there, then record it here (\`git add ${here}\`) and commit.`)
1720
+ continue
1721
+ }
1722
+ const follows = surveyed.find((m) => m.segment === n.segment)?.follows
1723
+ // The branch: its remote's own default when `.gitmodules` names none — what this checkout
1724
+ // recorded of it, so nothing is asked of the remote.
1725
+ let branch = follows?.branch ?? null
1726
+ if (follows && !branch) {
1727
+ try {
1728
+ branch = execFileSync('git', ['symbolic-ref', '--short', '-q', `refs/remotes/${follows.remote}/HEAD`], { cwd: join(repo.top, n.at), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim().replace(`${follows.remote}/`, '') || null
1729
+ } catch {
1730
+ branch = null
1731
+ }
1732
+ }
1733
+ const push = !follows
1734
+ ? null
1735
+ : follows.upstream
1736
+ ? `git -C ${here} push`
1737
+ : `git -C ${here} push ${follows.remote} HEAD:${branch ?? '<branch>'}`
1738
+ note(
1739
+ `${dir} is a submodule, and the app's edits are a commit in it, which its remote does not hold yet: push it there before you push this repository` +
1740
+ (push ? ` — \`${push}\`.` : '.')
1741
+ )
1742
+ }
1743
+ }
1555
1744
  }
1556
1745
  // Unresolved conflicts are a non-zero exit, the way a conflicted `git merge` is.
1557
1746
  // The pull itself worked; there is work left for a human. This is what makes a
@@ -64,6 +64,7 @@ import {
64
64
  } from '../utils/git.js'
65
65
  import { ignoringRepo } from '../utils/sync-point.js'
66
66
  import { mountedRepositories, takeLatest, describeTaken } from '../utils/mounted-repositories.js'
67
+ import { writableMounts } from '../utils/site-roots.js'
67
68
  import { probeUnpushed } from '../backend/site-sync.js'
68
69
  import { resolveBackendOrigin } from '../backend/client.js'
69
70
  import { readBackendState } from '@uniweb/build/uwx'
@@ -181,10 +182,12 @@ export async function refresh(args = [], deps = {}) {
181
182
  skipped.push(`mounts (${skipGit ? '--no-git' : '--no-mounts'})`)
182
183
  } else if (mounts.length) {
183
184
  say.info(`Taking the latest of ${mounts.length === 1 ? 'the page folder' : `${mounts.length} page folders`} mounted from ${mounts.length === 1 ? 'another repository' : 'other repositories'}…`)
185
+ // A mount a pull writes into takes its latest by merging, as the site does (`takeLatest`).
186
+ const writable = new Set(writableMounts(siteDir).writable)
184
187
  for (const m of mounts) {
185
- const r = await takeLatest(siteDir, m)
188
+ const r = await takeLatest(siteDir, m, { merge: writable.has(m.segment) })
186
189
  say.dim(describeTaken(m, r))
187
- if (r.error || ['edits', 'no-answer', 'off-branch'].includes(r.kind)) mountsLeft.push(m)
190
+ if (r.error || ['edits', 'no-answer', 'off-branch', 'conflict'].includes(r.kind)) mountsLeft.push(m)
188
191
  }
189
192
  consulted.push('mounts')
190
193
  }