@uniweb/build 1.15.6 → 1.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -35,7 +35,7 @@
35
35
 
36
36
  import { foldOpenGraph } from './open-graph.js'
37
37
  import { isAuthoredPreview } from './authored-preview.js'
38
- import { join, relative, extname, basename, dirname, parse } from 'node:path'
38
+ import { join, relative, extname, basename, dirname, parse, sep } from 'node:path'
39
39
  import { restoreAssetRefs } from './asset-map.js'
40
40
  import { mapPageRefs, pageRefIndex, pageRefPages, writtenPageRef } from './page-refs.js'
41
41
  import { siteFileKeys, siteTree, writtenRefs } from './located-media.js'
@@ -46,9 +46,11 @@ import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
46
46
  import { createHash } from 'node:crypto'
47
47
  import yaml from 'js-yaml'
48
48
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
49
- import { writeSiteConfig, writeThemeFile, writeIfChanged, writeSectionFile, writeMergedYaml } from './project-writer.js'
49
+ import { writeSiteConfig, writeSitePaths, writeThemeFile, writeIfChanged, writeSectionFile, writeMergedYaml } from './project-writer.js'
50
+ import { mountEntriesOf } from '../site/mount-entries.js'
50
51
  import { declarationsToQueriesYml } from './records-project.js'
51
52
  import { buildRouteOf } from './site.js'
53
+ import { SINGLE_SECTION } from './route-mode.js'
52
54
  import { fileLinkTargets } from '../site/file-links.js'
53
55
  import { DEFAULT_SECTION_TYPE } from '@uniweb/core/section-type'
54
56
  import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
@@ -101,10 +103,18 @@ function renameInPlace(from, to, report) {
101
103
  // Place the item identified by `uuid` at `targetAbs`: if the index recorded it at
102
104
  // a different path, relocate it there first (git-mv-style), then record its new
103
105
  // path in the fresh index. No-op without a ctx (standalone callers / no uuid).
104
- function placeByUuid(ctx, uuid, targetAbs) {
106
+ //
107
+ // ⛔ Only a file to a file, and a folder to a folder: a page moved between a folder-mode `.md` file and
108
+ // a page folder changes its form, so it is written new where it lands and its old form pruned. Until
109
+ // 2026-11-04 the `.md` file was renamed to the page folder's path, and the pull stopped on it (ENOTDIR).
110
+ function placeByUuid(ctx, uuid, targetAbs, { folder = false } = {}) {
105
111
  if (!ctx || !uuid) return
106
112
  const oldRel = ctx.oldIndex[uuid]
107
- if (oldRel) renameInPlace(join(ctx.siteRoot, oldRel), targetAbs, ctx.report)
113
+ const from = oldRel ? join(ctx.siteRoot, oldRel) : null
114
+ if (from && existsSync(from)) {
115
+ if (statSync(from).isDirectory() === folder) renameInPlace(from, targetAbs, ctx.report)
116
+ else if (from !== targetAbs) ctx.formerly?.add(from) // its old form, for the prune to take
117
+ }
108
118
  ctx.newIndex[uuid] = relative(ctx.siteRoot, targetAbs)
109
119
  }
110
120
 
@@ -884,13 +894,13 @@ function nestSays(nest, list) {
884
894
  // now, which is also what the layout prune below already did.
885
895
 
886
896
  // Delete the section files in `pageDir` whose stableId isn't in `keep`.
887
- function pruneOrphanSectionFiles(pageDir, keep, report) {
897
+ function pruneOrphanSectionFiles(pageDir, keep, report, kept = null) {
888
898
  if (!existsSync(pageDir)) return
889
899
  for (const entry of readdirSync(pageDir)) {
890
900
  if (!isMarkdownFile(entry)) continue
891
901
  if (keep.has(basename(entry, extname(entry)))) continue
892
902
  const p = join(pageDir, entry)
893
- if (!statSync(p).isFile()) continue
903
+ if (kept?.has(p) || !statSync(p).isFile()) continue
894
904
  unlinkSync(p)
895
905
  report.deleted.push(p)
896
906
  }
@@ -908,9 +918,10 @@ function pruneOrphanPageFiles(levelDir, keep, report, routePrefix, ctx) {
908
918
  return
909
919
  }
910
920
  for (const { file, name } of folderModePageFiles(entries).files) {
911
- if (keep.has(file)) continue
921
+ if (keep.has(file) || ctx?.kept?.has(join(levelDir, file))) continue
912
922
  const route = routePrefix ? `${routePrefix}/${name}` : name
913
- if (!ctx?.seen?.has(route)) continue
923
+ // A page the app moved out of this level as a page folder is its old form, seen or not (`placeByUuid`).
924
+ if (!ctx?.seen?.has(route) && !ctx?.formerly?.has(join(levelDir, file))) continue
914
925
  const p = join(levelDir, file)
915
926
  if (!statSync(p).isFile()) continue
916
927
  unlinkSync(p)
@@ -956,17 +967,49 @@ function projectPages(pages, pagesDir, sourceLocale, report, prune, ctx) {
956
967
  // level cannot hold as a file is not written there (`cannot`): a page folder below it, with nothing in
957
968
  // its `page.yml`, is read in folder mode, its sections as pages. A folder-mode folder is a folder.
958
969
  // ⛔ Until 2026-11-04 every page went to its slug's folder: `pages/2-about/` came back as `about/`.
970
+ //
971
+ // In a folder-mode level a route is a folder only where the files keep one in folder mode, where it is
972
+ // or where the app moved it from (`oldForm`), or, new to them, where its `mode` is `single-section`. A
973
+ // page folder is no form there: a parametric page, or a page its file cannot hold, is `cannot`.
959
974
  function placeOf(ctx, record, route, levelDir, levelMode, sourceLocale) {
960
975
  const found = ctx.files?.page(route)
961
976
  if (found) return found
962
- if (levelMode === 'pages' && record.mode !== 'folder' && !record.is_dynamic) {
963
- const name = unwrapLocalized(record.slug, sourceLocale)
964
- const what = mdPageCannotHold(record, { name, sourceLocale })
965
- return what.length ? { kind: 'cannot', what } : { kind: 'md', file: join(levelDir, `${name}.md`), dir: levelDir }
977
+ if (levelMode === 'pages') {
978
+ if (record.is_dynamic) return { kind: 'cannot', what: ['a parametric page, which a route of single-section pages holds none of'] }
979
+ const was = oldForm(ctx, record)
980
+ if (was ? was !== 'pages' : record.mode !== SINGLE_SECTION) {
981
+ const name = unwrapLocalized(record.slug, sourceLocale)
982
+ const what = mdPageCannotHold(record, { name, sourceLocale })
983
+ return what.length ? { kind: 'cannot', what } : { kind: 'md', file: join(levelDir, `${name}.md`), dir: levelDir }
984
+ }
966
985
  }
967
986
  return { kind: 'folder', dir: join(levelDir, pageDirName(record, sourceLocale)) }
968
987
  }
969
988
 
989
+ // The form the files kept a route in before the app moved it, by the rename index this copy wrote: an
990
+ // `.md` page (`md`), or a folder read in folder mode (`pages`) or page mode (`sections`) where it was.
991
+ // Null for a route new to them. Read before the move (`placeByUuid`), which takes the old place away.
992
+ function oldForm(ctx, record) {
993
+ const rel = record?.$uuid ? ctx?.oldIndex?.[record.$uuid] : null
994
+ const old = rel ? join(ctx.siteRoot, rel) : null
995
+ if (!old || !existsSync(old)) return null
996
+ if (!statSync(old).isDirectory()) return 'md'
997
+ return folderModeOf(old, ctx.files?.levelMode(dirname(old)) ?? 'sections')
998
+ }
999
+
1000
+ // ⭐ A FOLDER'S FORM IS ITS FILES' WHERE THEY HOLD IT — folder mode (`pages`) or page mode (`sections`):
1001
+ // a mount's route by the mount, a folder the files hold by its own config, one the app moved by the form
1002
+ // it had. Only a route new to the files takes the form its `mode` asks for, a route the app made. ⛔ Until
1003
+ // 2026-11-04 every folder took its `mode`'s form, so a stored route in another spelling would have had
1004
+ // a `page.yml` written beside its `folder.yml`.
1005
+ function formOf(ctx, record, route, place, levelMode) {
1006
+ if (place.mount) return place.mount.mode
1007
+ if (ctx.files?.page(route) === place) return ctx.files.levelMode(place.dir) ?? folderModeOf(place.dir, levelMode)
1008
+ const was = oldForm(ctx, record)
1009
+ if (was === 'pages' || was === 'sections') return was
1010
+ return record.mode === SINGLE_SECTION ? 'pages' : 'sections'
1011
+ }
1012
+
970
1013
  // ⭐ A FOLDER-MODE `.md` PAGE, WRITTEN BACK IN PLACE: the file is the page and its one section, so the
971
1014
  // section is written into it as any section file is (`sectionRecordToFile`) — its text, its params —
972
1015
  // and its frontmatter's `hidden:` says the page's. One the file cannot hold (`mdPageCannotHold`) is
@@ -1027,16 +1070,14 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1027
1070
  const slug = unwrapLocalized(record.slug, sourceLocale) // localized {lang:value} → canonical
1028
1071
  const route = routePrefix ? `${routePrefix}/${slug}` : slug
1029
1072
  let place = placeOf(ctx, record, route, pagesDir, levelMode, sourceLocale)
1030
- // ⛔ A writable mount's route takes its form from its files: one the app made a page where they keep
1031
- // a folder, or the reverse, cannot be written — its pages are the shape that form gives them.
1032
- if (place.mount && record.mode !== (place.mount.mode === 'pages' ? 'folder' : 'page')) {
1033
- place = { kind: 'cannot', what: [record.mode === 'folder' ? 'a folder where its files keep a page' : 'a page where its files keep a folder'] }
1034
- }
1073
+ // A mount's own route the files cannot say where the app put it (`followMountRoutes`).
1074
+ if (ctx.heldMounts?.has(record.$uuid)) place = { kind: 'cannot', what: ['a mounted route where a mount cannot sit, or by a name another page holds'] }
1035
1075
  ctx.places?.set(record, place)
1036
1076
  // ⭐ A PAGE THE PULL MAY NOT OR CANNOT WRITE IS LEFT ALONE — a mount's, a route the files give two
1037
1077
  // pages for (`page-files.js`), a page its folder-mode level cannot hold as a file. Its children too:
1038
1078
  // a mount's are the mount's.
1039
1079
  if (place.kind === 'mounted' || place.kind === 'twice' || place.kind === 'cannot') {
1080
+ keepWhereTheFilesAre(ctx, subtreeUuids(record))
1040
1081
  report.leftAlone?.push(...subtreeRoutes(record, route, sourceLocale))
1041
1082
  // ⭐ Each with its items, for the pull to bank by its outcome: a mount's page lets the folder win, and
1042
1083
  // one the files cannot hold is held at the version this copy last agreed on.
@@ -1078,18 +1119,29 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1078
1119
  // ⭐ A writable mount's own route is where the site's `paths:` puts it, never where a rename index
1079
1120
  // last saw it: no move is made, and none recorded.
1080
1121
  const mount = place.mount ?? null
1122
+ // Its form, read before the move takes its old place away.
1123
+ const form = formOf(ctx, record, route, place, levelMode)
1124
+ ctx.forms?.set(record, form)
1081
1125
  // Relocate the whole page dir if this uuid moved to a new slug, then record it.
1082
- if (!mount) placeByUuid(ctx, record.$uuid, pageDir)
1126
+ if (!mount) placeByUuid(ctx, record.$uuid, pageDir, { folder: true })
1083
1127
 
1084
1128
  let sectionsArray = []
1085
1129
  let filesGiveOrder = false
1086
1130
  let filesGiveTopOrder = false
1087
- if (record.mode === 'page' && Array.isArray(record.page_sections)) {
1131
+ if (form === 'sections' && Array.isArray(record.page_sections)) {
1088
1132
  const r = pageSectionsToFiles({ pageDir, pageSections: record.page_sections, ctx, pageContext })
1089
1133
  sectionsArray = r.sections
1090
1134
  filesGiveOrder = r.filesGiveOrder
1091
1135
  filesGiveTopOrder = r.filesGiveTopOrder
1092
1136
  report.sections.push(...r.written)
1137
+ } else if (Array.isArray(record.page_sections) && record.page_sections.length) {
1138
+ // ⛔ A route of single-section pages holds no section of its own: its folder's `.md` files are its
1139
+ // pages. One the app gives it is held, and the route and its pages are written as they are. Until
1140
+ // 2026-11-04 it was dropped, and the next push removed it from the site.
1141
+ const uuids = record.page_sections.flatMap((s) => subtreeUuids(s))
1142
+ keepWhereTheFilesAre(ctx, uuids)
1143
+ report.held?.push({ route, uuids, what: ['a section, which a route of single-section pages holds none of'] })
1144
+ report.leftAlone?.push(route)
1093
1145
  }
1094
1146
 
1095
1147
  if (mount) {
@@ -1104,7 +1156,7 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1104
1156
  continue
1105
1157
  }
1106
1158
 
1107
- const ymlName = record.mode === 'folder' ? 'folder.yml' : 'page.yml'
1159
+ const ymlName = form === 'pages' ? 'folder.yml' : 'page.yml'
1108
1160
  const ymlPath = join(pageDir, ymlName)
1109
1161
  // Merge (not full-dump) so author-added keys survive a pull; the projector
1110
1162
  // owns only PAGE_YML_MANAGED_KEYS.
@@ -1113,8 +1165,10 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1113
1165
  const yml = pageRecordToYml(record, sectionsArray, sourceLocale, existing, { isRoot: !routePrefix, slug: pageSlug, filesGiveOrder, filesGiveTopOrder })
1114
1166
  // ⭐ A `page.yml` with nothing to say is not created: the build reads an empty one as none
1115
1167
  // (`content-collector.js::readFolderConfig`). ⛔ Until 2026-10-08 a pull wrote `{}` into every page
1116
- // whose folder had none. An empty `folder.yml` is written still — its presence is folder mode.
1117
- if (ymlName === 'page.yml' && Object.keys(yml).length === 0 && !existsSync(ymlPath)) {
1168
+ // whose folder had none. An empty `folder.yml` is written only where its presence is what puts the
1169
+ // folder in folder mode: not in a folder-mode level, where the folder is in folder mode without it.
1170
+ // ⛔ Until 2026-11-04 a pull of what was pushed wrote one into every such folder.
1171
+ if (Object.keys(yml).length === 0 && !existsSync(ymlPath) && (ymlName === 'page.yml' || levelMode === 'pages')) {
1118
1172
  writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon, folderModeOf(pageDir, levelMode))
1119
1173
  continue
1120
1174
  }
@@ -1141,6 +1195,111 @@ function subtreeUuids(record) {
1141
1195
  return out
1142
1196
  }
1143
1197
 
1198
+ // ⭐ WHAT A PULL LEAVES ALONE STAYS WHERE THE FILES KEEP IT. A page the app moved where the files cannot
1199
+ // hold it is not written there, so its files at the old place are the files' version of it, and the prune
1200
+ // must keep them: found by the rename index this copy wrote, else, for a page, by the route its sync state
1201
+ // last saw it at (`ctx.itemRoutes`). ⛔ Until 2026-11-04 the prune took them: a page of two sections moved
1202
+ // into a folder of single-section pages was held there and deleted where it was.
1203
+ function keepWhereTheFilesAre(ctx, uuids) {
1204
+ if (!ctx?.kept) return
1205
+ for (const uuid of uuids) {
1206
+ const old = ctx.oldIndex[uuid]
1207
+ if (old) {
1208
+ ctx.kept.add(join(ctx.siteRoot, old))
1209
+ ctx.newIndex[uuid] ??= old
1210
+ continue
1211
+ }
1212
+ const route = ctx.itemRoutes?.get(uuid)
1213
+ const place = route == null ? null : ctx.files?.page(route)
1214
+ if (place?.kind === 'md') ctx.kept.add(place.file)
1215
+ else if (place?.dir) ctx.kept.add(place.dir)
1216
+ }
1217
+ }
1218
+
1219
+ // Whether a folder is, or holds, a path the prune must keep (`keepWhereTheFilesAre`).
1220
+ function holdsKept(ctx, dir) {
1221
+ for (const path of ctx?.kept ?? []) if (path === dir || path.startsWith(dir + sep)) return true
1222
+ return false
1223
+ }
1224
+
1225
+ // Each page's route by its item, as this copy's sync state last saw it: `pages/<route>/page.yml` (or
1226
+ // `folder.yml`), a parametric segment by its name, as `seenPageRoutes` reads them.
1227
+ function itemRoutesOf(items) {
1228
+ const out = new Map()
1229
+ for (const [key, uuid] of Object.entries(items || {})) {
1230
+ const m = key.match(/^pages\/(.+)\/(?:page|folder)\.yml$/)
1231
+ if (m && typeof uuid === 'string') out.set(uuid, m[1].split('/').map((seg) => seg.match(/^\[(.+)\]$/)?.[1] ?? seg).join('/'))
1232
+ }
1233
+ return out
1234
+ }
1235
+
1236
+ // A mount's segment, as `resolveMounts` takes one: a simple name, with no dot or underscore before it.
1237
+ const MOUNT_SEGMENT = /^[^/._][^/]*$/
1238
+
1239
+ /**
1240
+ * ⭐ A MOUNT'S OWN ROUTE, RENAMED OR REMOVED IN THE APP, is said where the files say that route: its
1241
+ * key in `site.yml`'s `paths:`, and its local folder. Renamed, both follow; removed, the mount leaves
1242
+ * the site, its key and its local folder, where the pull prunes. The mounted folder is never touched:
1243
+ * nothing asked for its files to go, and `paths:` still points where it did. A route the files cannot
1244
+ * say — moved below another page, where a mount cannot sit, or renamed to a name another page holds —
1245
+ * is held whole. The route is known by its item, as the backend knows it (`sync.json`'s `items`), so
1246
+ * one this copy never saw is no mount's.
1247
+ * ⛔ Until 2026-11-04 a renamed one was written as a new page of the site's own: a copy of every
1248
+ * mounted page beside the mount, under the new name, which the next push sent too. A removed one was
1249
+ * left, and the next push put it back.
1250
+ *
1251
+ * @returns {{ siteYml: object, renamed: Map<string, string>, held: Set<string> }} the site config as it
1252
+ * now stands, each mount's segment renamed to its new one, and the items of the routes held
1253
+ */
1254
+ function followMountRoutes({ siteRoot, siteYml, pagesDir, document, backend, sourceLocale, prune, report }) {
1255
+ const out = { siteYml, renamed: new Map(), held: new Set() }
1256
+ const declared = mountEntriesOf(siteYml?.paths)
1257
+ const items = backend ? readBackendState(siteRoot, backend).items || {} : {}
1258
+ if (!declared.length || !Object.keys(items).length) return out
1259
+ const roots = document?.pages || []
1260
+ const slugOf = (record) => unwrapLocalized(record?.slug, sourceLocale)
1261
+ const anywhere = (records, uuid) => (records || []).some((r) => r?.$uuid === uuid || anywhere(r?.$children, uuid))
1262
+ let paths = { ...siteYml.paths }
1263
+ let changed = false
1264
+ for (const [segment] of declared) {
1265
+ if (roots.some((r) => slugOf(r) === segment)) continue // where it was
1266
+ const uuid = items[`pages/${segment}/folder.yml`] ?? items[`pages/${segment}/page.yml`]
1267
+ if (typeof uuid !== 'string') continue
1268
+ const record = roots.find((r) => r?.$uuid === uuid)
1269
+ const stub = join(pagesDir, segment)
1270
+ if (record) {
1271
+ const to = slugOf(record)
1272
+ if (typeof to !== 'string' || !MOUNT_SEGMENT.test(to) || `pages/${to}` in paths || existsSync(join(pagesDir, to))) {
1273
+ out.held.add(uuid)
1274
+ continue
1275
+ }
1276
+ // The key renamed where it stands, its value as written.
1277
+ paths = Object.fromEntries(Object.entries(paths).map(([key, value]) => [key === `pages/${segment}` ? `pages/${to}` : key, value]))
1278
+ if (existsSync(stub)) {
1279
+ renameSync(stub, join(pagesDir, to))
1280
+ report.renamed.push({ from: stub, to: join(pagesDir, to) })
1281
+ }
1282
+ out.renamed.set(segment, to)
1283
+ report.mountRoutes.push({ from: segment, to })
1284
+ changed = true
1285
+ } else if (anywhere(roots, uuid)) {
1286
+ out.held.add(uuid)
1287
+ } else if (prune) {
1288
+ delete paths[`pages/${segment}`]
1289
+ if (existsSync(stub)) {
1290
+ rmSync(stub, { recursive: true, force: true })
1291
+ report.deleted.push(stub)
1292
+ }
1293
+ report.mountRoutes.push({ from: segment, to: null })
1294
+ changed = true
1295
+ }
1296
+ }
1297
+ if (!changed) return out
1298
+ writeSitePaths(siteRoot, paths)
1299
+ out.siteYml = readAuthoredYaml(join(siteRoot, 'site.yml'))
1300
+ return out
1301
+ }
1302
+
1144
1303
  // ⭐ THE PAGES THE SITE'S FILES ARE, for the links a file writes as files (`site/file-links.js`): each page
1145
1304
  // of the document at the files the file map keeps it in — an `.md` page's own, a page folder's section
1146
1305
  // files as the writer finds them — so a pull reads a file's links as the push does, and writes them back
@@ -1157,7 +1316,7 @@ function pageFileTargets(ctx, pages, sourceLocale) {
1157
1316
  if (place?.kind === 'md' && record.page_sections?.length === 1) {
1158
1317
  const section = record.page_sections[0]
1159
1318
  files.push({ file: place.file, id: recordStableId(section), content: contentOf(section) })
1160
- } else if (place?.kind === 'folder' && record.mode === 'page') {
1319
+ } else if (place?.kind === 'folder' && (place.mount ? place.mount.mode : ctx.files.levelMode(place.dir)) === 'sections') {
1161
1320
  const bases = sectionFileBases(record.page_sections || [])
1162
1321
  const visit = (list, child) => {
1163
1322
  for (const section of list || []) {
@@ -1283,7 +1442,7 @@ function reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage = n
1283
1442
  return { md: false, dirName: place.mount.segment, name: place.mount.segment, readOrder: () => config.read().order, writeOrder: (n) => config.write({ order: n }) }
1284
1443
  }
1285
1444
  const dirName = place?.kind === 'folder' ? basename(place.dir) : pageDirName(r, sourceLocale)
1286
- const yml = join(pagesDir, dirName, r.mode === 'folder' ? 'folder.yml' : 'page.yml')
1445
+ const yml = join(pagesDir, dirName, ctx?.forms?.get(r) === 'pages' ? 'folder.yml' : 'page.yml')
1287
1446
  return { md: false, dirName, name: parseNumericPrefix(dirName).name, readOrder: () => readAuthoredYaml(yml)?.order, writeOrder: (n) => writeMergedYaml(yml, { order: n }, ['order']) }
1288
1447
  })
1289
1448
  if (level.length < 2) return
@@ -1389,15 +1548,22 @@ function prunePagesTree(pages, pagesDir, sourceLocale, report, ctx = null, route
1389
1548
  // Left alone by pass 1 — and an `.md` page has nothing below it — so nothing of it is pruned.
1390
1549
  if (place.kind !== 'folder') continue
1391
1550
  const pageDir = place.dir
1392
- if (record.mode === 'page') {
1551
+ if (ctx?.forms?.get(record) === 'sections') {
1393
1552
  // The files pass 1 wrote into — the author's own names among them — else the names it would give.
1394
1553
  const keep = ctx?.sectionFiles?.get(pageDir) || collectSectionFileBases(record.page_sections)
1395
- if (keep.size > 0) pruneOrphanSectionFiles(pageDir, keep, report)
1554
+ if (keep.size > 0) pruneOrphanSectionFiles(pageDir, keep, report, ctx?.kept)
1396
1555
  }
1397
1556
  // A writable mount's pages are in the mounted folder (`page-files.js`).
1398
1557
  if (place.mount) prunePagesTree(record.$children || [], place.mount.dir, sourceLocale, report, ctx, route, place.mount.childMode)
1399
1558
  else prunePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, folderModeOf(pageDir, levelMode))
1400
1559
  }
1560
+ // A page the app moved that changed form, as this level kept it (`placeByUuid`): it goes, even from a
1561
+ // level left with no page of its own, since the page itself was written where it lands.
1562
+ for (const p of ctx?.formerly ?? []) {
1563
+ if (dirname(p) !== pagesDir || !existsSync(p) || holdsKept(ctx, p) || ctx.files?.holds?.(p)) continue
1564
+ rmSync(p, { recursive: true, force: true })
1565
+ report.deleted.push(p)
1566
+ }
1401
1567
  if (incomingDirs.size === 0 && incomingFiles.size === 0) return
1402
1568
  if (levelMode === 'pages') pruneOrphanPageFiles(pagesDir, incomingFiles, report, routePrefix, ctx)
1403
1569
  // A mounted route's local folder is never an orphan, whatever the document holds: what it
@@ -1405,7 +1571,7 @@ function prunePagesTree(pages, pagesDir, sourceLocale, report, ctx = null, route
1405
1571
  if (!routePrefix) for (const segment of ctx?.files?.mounted ?? []) incomingDirs.add(segment)
1406
1572
  // ⛔ Nor is a folder that holds a folder-mode page, whatever the document holds: until 2026-11-04 a
1407
1573
  // document without that folder's own page removed it whole, its `.md` pages with it.
1408
- pruneOrphanPageDirs(pagesDir, incomingDirs, report, (dir) => Boolean(ctx?.files?.holds?.(dir)))
1574
+ pruneOrphanPageDirs(pagesDir, incomingDirs, report, (dir) => Boolean(ctx?.files?.holds?.(dir)) || holdsKept(ctx, dir))
1409
1575
  }
1410
1576
 
1411
1577
  /**
@@ -1685,16 +1851,16 @@ function seenPageRoutes(items) {
1685
1851
  * @param {string} [params.sectionType] - the type a section that names none renders with on this
1686
1852
  * site, which the push filled in and a section's file leaves out — `siteDefaultSectionType`,
1687
1853
  * read by the caller since it reads the foundation's source
1688
- * @param {string[]} [params.writableMounts] - the segments of the mounts the caller may write into. A
1689
- * mount is written only where the site declares it `writable: true` and it is named here — a
1690
- * pull names those the site's repository holds — so a caller that names none writes no mount
1854
+ * @param {string[]} [params.writableMounts] - the segments of the mounts the caller may write into: a
1855
+ * pull names each one it can merge into, a folder of the site's repository or of a submodule.
1856
+ * A caller that names none writes no mount
1691
1857
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
1692
1858
  */
1693
1859
  export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), prune = false, keepAuthoredFoundation = false, scope, dataModel = null, sectionType = DEFAULT_SECTION_TYPE, writableMounts = [] }) {
1694
1860
  // Before anything is written: a pull that would leave content out of the files stops here.
1695
1861
  refuseContentFilesCannotHold(document, sourceLocale)
1696
1862
 
1697
- const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [], leftAlone: [], held: [], mountedPages: [] }
1863
+ const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [], leftAlone: [], held: [], mountedPages: [], mountRoutes: [] }
1698
1864
 
1699
1865
  // Collects target-locale translations of localized scalars as they're projected;
1700
1866
  // flushed to locales/{locale}.json at the end (the manifest stays derivable).
@@ -1734,15 +1900,26 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1734
1900
 
1735
1901
  // Where the tree goes is what this project's own `site.yml` says — the file the next push and the
1736
1902
  // build read, and one a document never writes `paths` into. See `siteContentDirs`.
1737
- const siteYml = readAuthoredYaml(join(siteRoot, 'site.yml'))
1903
+ let siteYml = readAuthoredYaml(join(siteRoot, 'site.yml'))
1738
1904
  const { pagesDir, layoutDir: layoutBaseDir } = siteContentDirs(siteRoot, siteYml)
1905
+ // A mount's own route renamed or removed in the app, said in `paths:` before any page is placed.
1906
+ const mountRoutes = followMountRoutes({ siteRoot, siteYml, pagesDir, document, backend, sourceLocale, prune, report })
1907
+ siteYml = mountRoutes.siteYml
1908
+ ctx.heldMounts = mountRoutes.held
1909
+ // A writable mount stays one under its new name.
1910
+ const writable = (writableMounts || []).map((segment) => mountRoutes.renamed.get(segment) ?? segment)
1739
1911
  // ⭐ WHERE EACH PAGE IS KEPT — found in the files by the build's rules (`page-files.js`), so a page
1740
1912
  // is written where it lives: a numbered folder, a folder-mode `.md` file, a writable mount's folder.
1741
1913
  // A read-only mount's pages, and a route the files give two pages for, are neither written nor
1742
1914
  // pruned. Each record's place, once decided, is the one every pass below reads (`places`).
1743
1915
  // The pages this copy has seen the backend hold, by route: a prune deletes an `.md` page only then.
1744
- ctx.seen = seenPageRoutes(backend ? readBackendState(siteRoot, backend).items : null)
1745
- ctx.files = sitePageFiles(siteYml, pagesDir, { seen: ctx.seen, siteRoot, writable: writableMounts })
1916
+ const items = backend ? readBackendState(siteRoot, backend).items : null
1917
+ ctx.seen = seenPageRoutes(items)
1918
+ ctx.itemRoutes = itemRoutesOf(items)
1919
+ ctx.kept = new Set()
1920
+ ctx.formerly = new Set()
1921
+ ctx.forms = new Map()
1922
+ ctx.files = sitePageFiles(siteYml, pagesDir, { seen: ctx.seen, siteRoot, writable })
1746
1923
  ctx.places = new Map()
1747
1924
  ctx.fileLinks = pageFileTargets(ctx, document?.pages, sourceLocale)
1748
1925
  // The tree a key names its file by: pages and layout wherever `paths:` puts them, and each mount
@@ -1761,7 +1938,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1761
1938
  // A homepage marked `index: true` in its own config — where the push read it (`buildPageData`) —
1762
1939
  // is left marked there alone: a site.yml that names none is not given an `index:` it never had.
1763
1940
  const homePlace = ctx.places.get(home)
1764
- const homeConfig = homePlace?.mount ? mountRouteConfig(homePlace.mount).read() : homePlace?.kind === 'folder' ? readAuthoredYaml(join(homePlace.dir, home.mode === 'folder' ? 'folder.yml' : 'page.yml')) : null
1941
+ const homeConfig = homePlace?.mount ? mountRouteConfig(homePlace.mount).read() : homePlace?.kind === 'folder' ? readAuthoredYaml(join(homePlace.dir, ctx.forms.get(home) === 'pages' ? 'folder.yml' : 'page.yml')) : null
1765
1942
  const marksItself = homeConfig?.index === true
1766
1943
  if (root.homepage !== ctx.homepage && !(marksItself && root.homepage === undefined)) {
1767
1944
  const listed = Array.isArray(root.pages) ? parseWildcardArray(root.pages) : null
package/src/uwx/site.js CHANGED
@@ -47,6 +47,7 @@
47
47
 
48
48
  import { readdir, readFile } from 'node:fs/promises'
49
49
  import { dataBlockModels } from '../i18n/data-models.js'
50
+ import { SINGLE_SECTION } from './route-mode.js'
50
51
  import { existsSync } from 'node:fs'
51
52
  import { join, parse, relative } from 'node:path'
52
53
  import {
@@ -67,6 +68,7 @@ import {
67
68
  assertRouteFolder,
68
69
  resolveMounts,
69
70
  layerMountedFolder,
71
+ refusePageInFolderMode,
70
72
  folderModePageFiles,
71
73
  folderModeChildren,
72
74
  rootOrderConfig,
@@ -480,7 +482,7 @@ function buildPageData(config, ctx) {
480
482
  // unless the local folder declares one, and the children read from the mount. ⛔ Until 2026-10-23
481
483
  // this lane read no mount, so a mounted route was pushed as an empty container (a local stub) or
482
484
  // not at all (none) — measured 2026-09-18 on a documentation site: 49 pages built, 2 pushed.
483
- async function orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts = null) {
485
+ async function orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts = null, siteRoot = dirPath) {
484
486
  const entries = await readdir(dirPath, { withFileTypes: true })
485
487
  const local = new Map()
486
488
  for (const e of entries) {
@@ -493,6 +495,7 @@ async function orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts =
493
495
  const localConfig = localPath ? await readFolderConfig(localPath, inheritedMode) : null
494
496
  const mountedConfig = mountPath ? await readFolderConfig(mountPath, 'pages') : null
495
497
  const { dirConfig, dirMode, childMode } = layerMountedFolder(dirName, localConfig, mountedConfig, inheritedMode)
498
+ refusePageInFolderMode(inheritedMode, dirMode, relative(siteRoot, localPath ?? mountPath))
496
499
  folders.push({
497
500
  dirName,
498
501
  name: parseNumericPrefix(dirName).name,
@@ -508,12 +511,10 @@ async function orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts =
508
511
  })
509
512
  }
510
513
  // Explicit order, then numeric-prefix filename order, then the parent's `pages:` wildcard —
511
- // one function, which the pull reproduces a level's order with too (`site-project.js`).
512
- // ⚠️ It does NOT match the build's own page-folder sort in one case, and the note that said
513
- // "mirror content-collector's pageFolders sort" here read as if it did: the collector compares
514
- // a level's folder names whole, as strings, and matches `pages:` against them whole, where
515
- // this strips a numeric prefix (`2-about` is `about`, and `10-` sorts after `2-`). Only a level
516
- // with numbered page folders can tell them apart, and which rule is right for them is open.
514
+ // one function, which the pull reproduces a level's order with too (`site-project.js`), on the
515
+ // comparison the build sorts a level's folders with (`compareFolders`). A folder's number orders it
516
+ // and is no part of its name (`2-about` is `about`, and `10-` sorts after `2-`), on every lane
517
+ // [Diego, 2026-11-04]. ⛔ Until then the build kept the number in the route, `/2-about`.
517
518
  return orderFolders(folders, parentConfig?.pages)
518
519
  }
519
520
 
@@ -833,7 +834,7 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
833
834
  const { siteRoot, siteIndex, sourceLocale, translations, pageFields } = ctx
834
835
  const files = inheritedMode === 'pages' ? await folderModePageRecords(ctx, dirPath, parentConfig, isRoot) : []
835
836
  const made = []
836
- const folders = await orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts)
837
+ const folders = await orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts, siteRoot)
837
838
  // A folder inside a `[...path]` folder can never be reached, and `[dir]` /
838
839
  // `[path]` would name a route variable — refused here as the collector refuses
839
840
  // them, so a site that cannot build cannot sync either (ruled 2026-09-11).
@@ -852,7 +853,11 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
852
853
  // ONE page whose sections were its `.md` files while the build rendered each as a
853
854
  // page of its own. Nothing warned, and a pull then wrote a `page.yml` into the
854
855
  // folder, converting the author's own site to the wrong shape.
855
- const mode = f.internalMode === 'pages' ? 'folder' : 'page'
856
+ // ⭐ WHAT ITS PAGES MAY HOLD, not how the files hold them: `single-section` where they are a folder-mode
857
+ // folder's `.md` files, one section each, else `page`. The mode its PAGES are read in (`childMode`), so
858
+ // a page above a mounted folder of `.md` pages says it too, with its own sections. The app reads it to
859
+ // offer no second section there. ⛔ Until 2026-11-04 it was the folder's own mode, spelled `folder`.
860
+ const mode = f.childMode === 'pages' ? SINGLE_SECTION : 'page'
856
861
  const slugPath = parentSlugPath ? `${parentSlugPath}/${slug}` : slug
857
862
 
858
863
  const data = buildPageData(f.config, {
@@ -882,7 +887,7 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
882
887
  }
883
888
 
884
889
  // A folder-mode folder has no sections: its `.md` files are pages, sent among its children.
885
- if (mode === 'page') {
890
+ if (f.internalMode !== 'pages') {
886
891
  const sections = await collectPageSectionsNested(f.path, siteRoot, f.config, ctx.media)
887
892
  if (sections.length > 0) record.page_sections = sections
888
893
  }
@@ -29,7 +29,8 @@ import { buildFolderEntity } from './folder.js'
29
29
  import { siteProjectToDocument } from './site.js'
30
30
  import { siteSourceLocale } from './source-locale.js'
31
31
  import { siteSelfScope, refuseOrgOption } from './self-scope.js'
32
- import { stampUnitUuids, collectUnitUuids } from './site-diff.js'
32
+ import { stampUnitUuids, collectUnitUuids, computeUnitHashes } from './site-diff.js'
33
+ import { leaveHeldOut } from './held-units.js'
33
34
  import { emitEntitySyncPackage } from './entity-document.js'
34
35
  import { recordQueriesShown } from './shown-records.js'
35
36
  import { isLocalAssetPath } from '../site/assets.js'
@@ -245,6 +246,13 @@ function rewriteEntityAssets(node, map, ids, bare = null) {
245
246
  * stamped onto the site-content document so the backend matches our items
246
247
  * instead of re-minting them (which deletes and recreates every page and
247
248
  * section row). Sourced from a pull or a push response, cached by the caller.
249
+ * @param {Object<string,string>} [opts.heldUnits] - unit path → hash: what a pull held, where the
250
+ * files keep it (`held-units.js::heldUnitsOf`). Those whose files still say it are left out
251
+ * of the site-content document (`heldLeftOut`); when any changed, none is, and the result's
252
+ * `heldChanged` names them. Omit to send them, as `--force` does.
253
+ * @param {boolean} [opts.unitHashes] - also return each unit of the files' document, before any
254
+ * media is rewritten, by path: its hash and its `$uuid` from `opts.itemUuids`
255
+ * (`unitHashes`, `unitUuids`), for a pull to record what it held.
248
256
  * @param {Object<string,Object<string,string>>} [opts.recordItemUuids] - record `$uuid` → the
249
257
  * identity of its list items, as a previous push or pull banked it
250
258
  * (`record-items.js`); stamped onto each record the backend holds, so a re-sent
@@ -395,9 +403,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
395
403
 
396
404
  // `queryUuids` — identity for the `queries` section, keyed by query
397
405
  // NAME because a declaration has no file of its own (see queriesNested).
398
- const siteDoc = includeSite
399
- ? await siteProjectToDocument(siteRoot, {
400
- media,
406
+ const docOpts = includeSite
407
+ ? {
401
408
  sourceLocale,
402
409
  // Whose $uuid belongs on this wire document — see siteProjectToDocument.
403
410
  ...(opts.backend ? { backend: opts.backend } : {}),
@@ -416,8 +423,9 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
416
423
  ...(Array.isArray(opts.queryFields) ? { queryFields: opts.queryFields } : {}),
417
424
  ...(Array.isArray(opts.pageFields) ? { pageFields: opts.pageFields } : {}),
418
425
  ...(Array.isArray(opts.settingsFields) ? { settingsFields: opts.settingsFields } : {})
419
- })
426
+ }
420
427
  : null
428
+ const siteDoc = includeSite ? await siteProjectToDocument(siteRoot, { ...docOpts, media }) : null
421
429
  // Deploy-derived `info` fields are stamped here — NOT authored in site.yml, so they
422
430
  // ride the wire but never project back on pull. They are part of the hashed content,
423
431
  // so a changed value correctly re-fires the site-content lane.
@@ -563,6 +571,21 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
563
571
  recordItemIdentity.unknown += n.unknown
564
572
  }
565
573
 
574
+ // ⭐ WHAT A PULL HELD STAYS AS THE APP HAS IT (`held-units.js`): a held unit whose files still say what
575
+ // they said at the pull is not sent, and one whose files changed is named for the caller to stop on.
576
+ // Compared on the document the files give before any media is rewritten (`plain`), which `unitHashes`
577
+ // hands a pull to record. A walk of its own, made only when a pull held something.
578
+ const heldUnits = opts.heldUnits && typeof opts.heldUnits === 'object' && Object.keys(opts.heldUnits).length ? opts.heldUnits : null
579
+ const plain = siteDoc && (heldUnits || opts.unitHashes) ? await siteProjectToDocument(siteRoot, { ...docOpts, media: null }) : null
580
+ const held = heldUnits ? leaveHeldOut(siteDoc, { held: heldUnits, plain, sourceLocale }) : { left: [], changed: [] }
581
+ let unitHashes = null
582
+ let unitUuids = null
583
+ if (plain && opts.unitHashes) {
584
+ stampUnitUuids(plain, opts.itemUuids && typeof opts.itemUuids === 'object' ? opts.itemUuids : {}, sourceLocale)
585
+ unitHashes = computeUnitHashes(plain, sourceLocale)
586
+ unitUuids = collectUnitUuids(plain, sourceLocale)
587
+ }
588
+
566
589
  const siteEntity = siteDoc
567
590
  ? { id: siteDoc.$id, model: siteDoc.$schema, file: 'entities/site-content.json', document: siteDoc }
568
591
  : null
@@ -702,5 +725,13 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
702
725
  // leaves the backend's folder exactly as it is — no records directory, or one holding files
703
726
  // that are not records — so a caller can say so where the backend still holds records.
704
727
  sendsFolder: folder !== null,
728
+ // What a pull held (`opts.heldUnits`): the paths this push left out, its files unchanged, and the paths
729
+ // that changed since the pull, for a caller that submits to stop on — none is left out then.
730
+ heldLeftOut: held.left,
731
+ heldChanged: held.changed,
732
+ // With `opts.unitHashes`: each unit of the files' document before any media is rewritten, by path —
733
+ // its hash, and its `$uuid` from `opts.itemUuids` — for a pull to record what it held (`held-units.js`).
734
+ unitHashes,
735
+ unitUuids,
705
736
  }
706
737
  }