@uniweb/build 1.15.5 → 1.15.6

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 } from 'node:path'
38
+ import { join, relative, extname, basename, dirname, parse } 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'
@@ -49,6 +49,7 @@ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
49
49
  import { writeSiteConfig, writeThemeFile, writeIfChanged, writeSectionFile, writeMergedYaml } from './project-writer.js'
50
50
  import { declarationsToQueriesYml } from './records-project.js'
51
51
  import { buildRouteOf } from './site.js'
52
+ import { fileLinkTargets } from '../site/file-links.js'
52
53
  import { DEFAULT_SECTION_TYPE } from '@uniweb/core/section-type'
53
54
  import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
54
55
  import { authorableDeclaration, DECLARATION_KEYS } from '../site/fetch-shapes.js'
@@ -59,10 +60,10 @@ import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
59
60
  import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
60
61
  import { documentLanguages, documentSourceLocale } from './source-locale.js'
61
62
  import { siteContentDirs } from './site-dirs.js'
62
- import { gitAuthoredPages } from './git-authored.js'
63
+ import { sitePageFiles, mdPageCannotHold, folderModeOf } from './page-files.js'
63
64
  import { layoutAreaRoute, readLayoutFolderSync, DEFAULT_LAYOUT } from '../site/layout-folder.js'
64
65
  import { layoutNameKey } from '@uniweb/core/layout-name'
65
- import { orderFolders, rootOrderConfig, parseNumericPrefix, parseWildcardArray, composeLocalizedRoute, stripAtPrefix, compareFilenames } from '../site/content-collector.js'
66
+ import { orderFolders, rootOrderConfig, parseNumericPrefix, parseWildcardArray, composeLocalizedRoute, stripAtPrefix, compareFilenames, folderModePageFiles, folderModeChildren } from '../site/content-collector.js'
66
67
  import { parseFrontmatter } from '../utils/frontmatter.js'
67
68
 
68
69
  // The pull-side identity index: a per-clone, GITIGNORED `uuid → relative path`
@@ -183,7 +184,9 @@ const SETTINGS_TO_SITE_YML = {
183
184
  base: 'base',
184
185
  fetcher: 'fetcher',
185
186
  build: 'build',
186
- paths: 'paths',
187
+ // ⛔ Not `paths`: where this project keeps its files is its own `site.yml`'s to say, never a
188
+ // document's. Mapped until 2026-11-04, a clone took another copy's `paths.pages`, wrote its pages
189
+ // there — outside itself — and pruned what it found.
187
190
  seo: 'seo',
188
191
  layout: 'layout',
189
192
  // ⛔ `search` / `submit` / `assistant` / `tracking` are not here: each service rides
@@ -399,7 +402,7 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
399
402
  * site (`siteDefaultSectionType`), which a file leaves out
400
403
  * @returns {'updated'|'unchanged'}
401
404
  */
402
- export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath, freeformCandidates = null, writeId = true, context = null, dataModel = null, impliedType = DEFAULT_SECTION_TYPE, media = null }) {
405
+ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath, freeformCandidates = null, writeId = true, context = null, dataModel = null, impliedType = DEFAULT_SECTION_TYPE, media = null, fileLinks = null }) {
403
406
  // ⛔ A stored `preset` or `input` is not written back: neither has an effect, and the build
404
407
  // would only warn about it (2026-09-27).
405
408
  // ⛔ No `background` / `theme_override` / `insets` / `fetch`: the site-content Model dropped all
@@ -445,6 +448,8 @@ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED
445
448
  params: frontmatter,
446
449
  declaration: paramFetch ?? null,
447
450
  implied: { type: impliedType },
451
+ // The links the file writes as files, as the push reads them (`pageFileTargets`).
452
+ fileLinks,
448
453
  })
449
454
  }
450
455
 
@@ -592,6 +597,7 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
592
597
  writeId: fileSectionName(filePath) !== stableId,
593
598
  context: pageContext ? translationContext({ stableId }, pageContext.route) : null,
594
599
  media: ctx?.media ?? null,
600
+ fileLinks: ctx?.fileLinks ?? null,
595
601
  })
596
602
  written.push(filePath)
597
603
  if (!top) childFiles.push(basename(filePath))
@@ -681,6 +687,76 @@ const PAGE_YML_MANAGED_KEYS = new Set([
681
687
  // backend stays in the file.
682
688
  const PAGE_YML_KEPT_KEYS = new Set(['slug'])
683
689
 
690
+ // ⭐ A WRITABLE MOUNT'S OWN ROUTE IS SAID IN TWO FILES, layered as the push reads them
691
+ // (`layerMountedFolder`): the mounted folder's config says what its content is, the site's stub how
692
+ // this site presents it, and the stub's wins where both say one. A pull writes each setting the app
693
+ // changed in the file that says it — the stub's, where both do — and one neither says by what it is:
694
+ // one of these in the mounted folder, any other in the stub. A setting the app removed goes from each
695
+ // file that says it, and the title a route takes from its segment when no file gives one is not a
696
+ // setting, so it is never written.
697
+ const MOUNT_CONTENT_KEYS = new Set(['title', 'description', 'pages', 'sections', 'nest'])
698
+
699
+ /**
700
+ * A writable mount's own route config (`mount`, `page-files.js`), read as the push layers it and
701
+ * written key by key in the file that says each one.
702
+ *
703
+ * ⛔ A file is made only where making it moves nothing: in the mode the route is read in, and never a
704
+ * stub for a route in page mode that has none — its sections are in the mounted folder, and a stub
705
+ * would be where the build reads them from. There the mounted folder's config, the route's only one,
706
+ * takes every setting.
707
+ *
708
+ * @param {object} mount
709
+ * @returns {{ read: () => object, write: (patch: object) => string[] }} `write` takes each key to set,
710
+ * or `undefined` to remove it, and returns the files it changed
711
+ */
712
+ function mountRouteConfig(mount) {
713
+ const fileIn = (dir, read, mode) => join(dir, read && read.source !== 'inherited' ? read.source : mode === 'pages' ? 'folder.yml' : 'page.yml')
714
+ const stubFile = fileIn(mount.stubDir, mount.stub, mount.mode)
715
+ const mountedFile = fileIn(mount.dir, mount.mounted, mount.mounted.mode)
716
+ const stubMayBe = Boolean(mount.stub) || mount.mode === 'pages'
717
+ const said = () => ({ stub: (mount.stub || stubMayBe ? readAuthoredYaml(stubFile) : null) || {}, mounted: readAuthoredYaml(mountedFile) || {} })
718
+ return {
719
+ read() {
720
+ const { stub, mounted } = said()
721
+ return { title: mounted.title || mount.segment, ...mounted, ...stub }
722
+ },
723
+ write(patch) {
724
+ const { stub, mounted } = said()
725
+ const to = { stub: {}, mounted: {} }
726
+ const off = { stub: [], mounted: [] }
727
+ for (const [key, value] of Object.entries(patch)) {
728
+ if (value === undefined) {
729
+ if (key in stub) off.stub.push(key)
730
+ if (key in mounted) off.mounted.push(key)
731
+ continue
732
+ }
733
+ const where = key in stub ? 'stub' : key in mounted || MOUNT_CONTENT_KEYS.has(key) || !stubMayBe ? 'mounted' : 'stub'
734
+ to[where][key] = value
735
+ }
736
+ const wrote = []
737
+ for (const [where, file] of [['stub', stubFile], ['mounted', mountedFile]]) {
738
+ const keys = [...Object.keys(to[where]), ...off[where]]
739
+ if (keys.length && writeMergedYaml(file, to[where], keys) === 'updated') wrote.push(file)
740
+ }
741
+ return wrote
742
+ },
743
+ }
744
+ }
745
+
746
+ // What of a page's config the app changed, against what the files say (`existing`): each managed or
747
+ // kept key whose value differs, and each managed key the record no longer carries, as `undefined`.
748
+ function changedSettings(existing, next) {
749
+ const patch = {}
750
+ for (const key of new Set([...PAGE_YML_MANAGED_KEYS, ...PAGE_YML_KEPT_KEYS, ...Object.keys(next)])) {
751
+ const was = existing?.[key]
752
+ const now = next[key]
753
+ if (now === undefined) {
754
+ if (was !== undefined && PAGE_YML_MANAGED_KEYS.has(key)) patch[key] = undefined
755
+ } else if (stableJson(was) !== stableJson(now)) patch[key] = now
756
+ }
757
+ return patch
758
+ }
759
+
684
760
  // Inverse of site.js buildPageData → the `page.yml` / `folder.yml` object.
685
761
  // `mode`/`is_dynamic`/`param_name` are NOT keys here — they shape the directory
686
762
  // (name, page.yml vs folder.yml, `[param]/`), not the config body. `slug`'s source
@@ -820,13 +896,36 @@ function pruneOrphanSectionFiles(pageDir, keep, report) {
820
896
  }
821
897
  }
822
898
 
823
- // Delete the page directories in `pagesDir` whose name isn't an incoming page dir.
824
- function pruneOrphanPageDirs(pagesDir, keepDirs, report) {
899
+ // Delete a folder-mode level's `.md` pages that no incoming page is — each its own file — and only one
900
+ // this copy has seen the backend hold (`ctx.seen`, its unit in `sync.json`'s `items`). ⛔ A push before
901
+ // 2026-10-23 sent no folder-mode page, so a backend can lack one the files have always held: read as
902
+ // the app's deletion, it would go. A page folder, and a file the build reads as no page, are not this.
903
+ function pruneOrphanPageFiles(levelDir, keep, report, routePrefix, ctx) {
904
+ let entries
905
+ try {
906
+ entries = readdirSync(levelDir)
907
+ } catch {
908
+ return
909
+ }
910
+ for (const { file, name } of folderModePageFiles(entries).files) {
911
+ if (keep.has(file)) continue
912
+ const route = routePrefix ? `${routePrefix}/${name}` : name
913
+ if (!ctx?.seen?.has(route)) continue
914
+ const p = join(levelDir, file)
915
+ if (!statSync(p).isFile()) continue
916
+ unlinkSync(p)
917
+ report.deleted.push(p)
918
+ }
919
+ }
920
+
921
+ // Delete the page directories in `pagesDir` whose name isn't an incoming page dir — never one that
922
+ // holds a page a prune must not take (`holds`, `page-files.js`), which would go with it.
923
+ function pruneOrphanPageDirs(pagesDir, keepDirs, report, holds = () => false) {
825
924
  if (!existsSync(pagesDir)) return
826
925
  for (const entry of readdirSync(pagesDir)) {
827
926
  if (isIgnoredFolder(entry) || keepDirs.has(entry)) continue
828
927
  const p = join(pagesDir, entry)
829
- if (!statSync(p).isDirectory()) continue
928
+ if (!statSync(p).isDirectory() || holds(p)) continue
830
929
  rmSync(p, { recursive: true, force: true })
831
930
  report.deleted.push(p)
832
931
  }
@@ -845,8 +944,63 @@ function pruneOrphanPageDirs(pagesDir, keepDirs, report) {
845
944
  // incoming level never nukes an existing one (a malformed/partial payload can't
846
945
  // wipe it).
847
946
  function projectPages(pages, pagesDir, sourceLocale, report, prune, ctx) {
848
- writePagesTree(pages, pagesDir, sourceLocale, report, ctx, '', rootOrderList(ctx.siteRoot, pagesDir))
849
- if (prune) prunePagesTree(pages, pagesDir, sourceLocale, report, ctx)
947
+ // The mode the build reads the pages directory in: `pages/folder.yml` puts the whole site in folder mode.
948
+ const rootMode = ctx.files?.levelMode(pagesDir) ?? folderModeOf(pagesDir, 'sections')
949
+ writePagesTree(pages, pagesDir, sourceLocale, report, ctx, '', rootOrderList(ctx.siteRoot, pagesDir), '/', rootMode)
950
+ if (prune) prunePagesTree(pages, pagesDir, sourceLocale, report, ctx, '', rootMode)
951
+ }
952
+
953
+ // ⭐ WHERE A PAGE GOES: where the files keep it (`page-files.js`) — a numbered folder, a folder-mode
954
+ // `.md` file — else where the project's rules place a new one beside its siblings: in a folder-mode
955
+ // level an `.md` file when it can be one, else a page folder named by its slug. ⛔ A page a folder-mode
956
+ // level cannot hold as a file is not written there (`cannot`): a page folder below it, with nothing in
957
+ // its `page.yml`, is read in folder mode, its sections as pages. A folder-mode folder is a folder.
958
+ // ⛔ Until 2026-11-04 every page went to its slug's folder: `pages/2-about/` came back as `about/`.
959
+ function placeOf(ctx, record, route, levelDir, levelMode, sourceLocale) {
960
+ const found = ctx.files?.page(route)
961
+ 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 }
966
+ }
967
+ return { kind: 'folder', dir: join(levelDir, pageDirName(record, sourceLocale)) }
968
+ }
969
+
970
+ // ⭐ A FOLDER-MODE `.md` PAGE, WRITTEN BACK IN PLACE: the file is the page and its one section, so the
971
+ // section is written into it as any section file is (`sectionRecordToFile`) — its text, its params —
972
+ // and its frontmatter's `hidden:` says the page's. One the file cannot hold (`mdPageCannotHold`) is
973
+ // left as written, and said. ⛔ Until 2026-11-04 a pull left every such page alone, so an edit made to
974
+ // one in the app was undone by the next push. Returns whether it was written.
975
+ function writeMdPage({ record, place, route, ctx, report, pageContext, sourceLocale }) {
976
+ const own = parse(place.file).name
977
+ const name = parseNumericPrefix(own).name || own
978
+ const what = mdPageCannotHold(record, { name, sourceLocale })
979
+ if (what.length) {
980
+ report.leftAlone?.push(route)
981
+ report.held?.push({ route, uuids: subtreeUuids(record), what })
982
+ return false
983
+ }
984
+ const section = record.page_sections[0]
985
+ const stableId = recordStableId(section) || name
986
+ // A page renamed in the app moves its file, as a page folder moves (`placeByUuid`).
987
+ placeByUuid(ctx, record.$uuid, place.file)
988
+ sectionRecordToFile({
989
+ filePath: place.file,
990
+ record: { ...section, hidden: record.hidden === true },
991
+ sourceLocale: ctx?.sourceLocale,
992
+ collector: ctx?.collector,
993
+ dataModel: ctx?.dataModel,
994
+ impliedType: ctx?.sectionType,
995
+ freeformRelPath: buildFreeformPath({ stableId }, pageContext),
996
+ freeformCandidates: freeformPathsFor({ stableId }, pageContext),
997
+ writeId: stableId !== name,
998
+ context: translationContext({ stableId }, pageContext.route),
999
+ media: ctx?.media ?? null,
1000
+ fileLinks: ctx?.fileLinks ?? null,
1001
+ })
1002
+ report.sections.push(place.file)
1003
+ return true
850
1004
  }
851
1005
 
852
1006
  // The directory name for a page record (slug, or `[param]/` for a dynamic page).
@@ -867,24 +1021,34 @@ export function pageDirName(record, sourceLocale) {
867
1021
  // section files, recursing into children. No deletes happen here. `routePrefix`
868
1022
  // accumulates the slug-path route (for the free-form translation path; matches the
869
1023
  // producer's slugPath, normalizeRouteForPath strips any leading slash on both).
870
- function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix = '', list = null, canonParent = '/') {
1024
+ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix = '', list = null, canonParent = '/', levelMode = 'sections') {
871
1025
  let leftAlone = false
872
1026
  for (const record of pages || []) {
873
1027
  const slug = unwrapLocalized(record.slug, sourceLocale) // localized {lang:value} → canonical
874
1028
  const route = routePrefix ? `${routePrefix}/${slug}` : slug
875
- // ⭐ A PAGE AUTHORED IN A FILE THE PULL CANNOT WRITE BACK IS LEFT ALONE — a mount's, or a
876
- // folder-mode `.md` page (`git-authored.js`). Its children too: a mount's are the mount's.
877
- if (ctx.leave?.has(route)) {
1029
+ 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
+ }
1035
+ ctx.places?.set(record, place)
1036
+ // ⭐ A PAGE THE PULL MAY NOT OR CANNOT WRITE IS LEFT ALONE — a mount's, a route the files give two
1037
+ // pages for (`page-files.js`), a page its folder-mode level cannot hold as a file. Its children too:
1038
+ // a mount's are the mount's.
1039
+ if (place.kind === 'mounted' || place.kind === 'twice' || place.kind === 'cannot') {
878
1040
  report.leftAlone?.push(...subtreeRoutes(record, route, sourceLocale))
1041
+ // ⭐ Each with its items, for the pull to bank by its outcome: a mount's page lets the folder win, and
1042
+ // one the files cannot hold is held at the version this copy last agreed on.
1043
+ // A mount's are named page by page, each with its own items, so a pull can say which the app changed.
1044
+ if (place.kind === 'mounted') report.mountedPages?.push(...subtreePages(record, route, sourceLocale))
1045
+ else report.held?.push({ route, uuids: subtreeUuids(record), what: place.kind === 'twice' ? ['two pages on one route'] : place.what })
879
1046
  leftAlone = true
880
1047
  continue
881
1048
  }
882
1049
  // The route the build gives the page (`buildRouteOf`, the push's rule): an index page takes its
883
1050
  // parent's, a parametric one is `:<param>`.
884
1051
  const canon = buildRouteOf(record, canonParent, sourceLocale)
885
- const pageDir = join(pagesDir, pageDirName(record, sourceLocale))
886
- // Relocate the whole page dir if this uuid moved to a new slug, then record it.
887
- placeByUuid(ctx, record.$uuid, pageDir)
888
1052
 
889
1053
  // Capture target-locale translations of the page's localized scalars; the
890
1054
  // source value goes inline into page.yml below (pageRecordToYml unwraps it). In the page's
@@ -906,6 +1070,17 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
906
1070
  // homepage the build reads at `/`.
907
1071
  const pageContext = { route: canon, id: record.stable_id }
908
1072
 
1073
+ if (place.kind === 'md') {
1074
+ if (!writeMdPage({ record, place, route, ctx, report, pageContext, sourceLocale })) leftAlone = true
1075
+ continue
1076
+ }
1077
+ const pageDir = place.dir
1078
+ // ⭐ A writable mount's own route is where the site's `paths:` puts it, never where a rename index
1079
+ // last saw it: no move is made, and none recorded.
1080
+ const mount = place.mount ?? null
1081
+ // Relocate the whole page dir if this uuid moved to a new slug, then record it.
1082
+ if (!mount) placeByUuid(ctx, record.$uuid, pageDir)
1083
+
909
1084
  let sectionsArray = []
910
1085
  let filesGiveOrder = false
911
1086
  let filesGiveTopOrder = false
@@ -917,6 +1092,18 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
917
1092
  report.sections.push(...r.written)
918
1093
  }
919
1094
 
1095
+ if (mount) {
1096
+ const config = mountRouteConfig(mount)
1097
+ const existing = config.read()
1098
+ const pageSlug = pageSlugToYml(record, canon, existing, sourceLocale, ctx)
1099
+ const yml = pageRecordToYml(record, sectionsArray, sourceLocale, existing, { isRoot: true, slug: pageSlug, filesGiveOrder, filesGiveTopOrder })
1100
+ report.pages.push(...config.write(changedSettings(existing, yml)))
1101
+ // Its pages are the mounted folder's, read in the mode the route gives them.
1102
+ const list = { pages: config.read().pages, write: (next) => config.write({ pages: next }) }
1103
+ writePagesTree(record.$children || [], mount.dir, sourceLocale, report, ctx, route, list, canon, mount.childMode)
1104
+ continue
1105
+ }
1106
+
920
1107
  const ymlName = record.mode === 'folder' ? 'folder.yml' : 'page.yml'
921
1108
  const ymlPath = join(pageDir, ymlName)
922
1109
  // Merge (not full-dump) so author-added keys survive a pull; the projector
@@ -928,17 +1115,77 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
928
1115
  // (`content-collector.js::readFolderConfig`). ⛔ Until 2026-10-08 a pull wrote `{}` into every page
929
1116
  // whose folder had none. An empty `folder.yml` is written still — its presence is folder mode.
930
1117
  if (ymlName === 'page.yml' && Object.keys(yml).length === 0 && !existsSync(ymlPath)) {
931
- writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon)
1118
+ writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon, folderModeOf(pageDir, levelMode))
932
1119
  continue
933
1120
  }
934
1121
  writeMergedYaml(ymlPath, yml, PAGE_YML_MANAGED_KEYS)
935
1122
  report.pages.push(ymlPath)
936
1123
 
937
- writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon)
1124
+ // Its children are read in the mode the build reads its folder in now, its config just written.
1125
+ writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon, folderModeOf(pageDir, levelMode))
938
1126
  }
939
1127
  // A level holding a page left alone keeps the order its files give: reconciling it would write an
940
1128
  // `order:` into a page folder that does not exist, or rewrite a `pages:` list the author keeps.
941
- if (!leftAlone) reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage: routePrefix ? null : ctx.homepage })
1129
+ if (!leftAlone) reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage: routePrefix ? null : ctx.homepage, ctx, levelMode })
1130
+ }
1131
+
1132
+ // The items of a page and everything below it — its own, its sections', its pages' — by `$uuid`.
1133
+ function subtreeUuids(record) {
1134
+ const out = []
1135
+ const walk = (r) => {
1136
+ if (typeof r?.$uuid === 'string') out.push(r.$uuid)
1137
+ for (const s of r?.page_sections || []) walk(s)
1138
+ for (const c of r?.$children || []) walk(c)
1139
+ }
1140
+ walk(record)
1141
+ return out
1142
+ }
1143
+
1144
+ // ⭐ THE PAGES THE SITE'S FILES ARE, for the links a file writes as files (`site/file-links.js`): each page
1145
+ // of the document at the files the file map keeps it in — an `.md` page's own, a page folder's section
1146
+ // files as the writer finds them — so a pull reads a file's links as the push does, and writes them back
1147
+ // as the file wrote them.
1148
+ function pageFileTargets(ctx, pages, sourceLocale) {
1149
+ const out = []
1150
+ const contentOf = (section) => (isProseMirrorDoc(section?.content) ? section.content : unwrapLocalized(section?.content, sourceLocale))
1151
+ const walk = (records, prefix, parentCanon) => {
1152
+ for (const record of records || []) {
1153
+ const route = prefix ? `${prefix}/${unwrapLocalized(record.slug, sourceLocale)}` : unwrapLocalized(record.slug, sourceLocale)
1154
+ const canon = buildRouteOf(record, parentCanon, sourceLocale)
1155
+ const place = ctx.files?.page(route)
1156
+ const files = []
1157
+ if (place?.kind === 'md' && record.page_sections?.length === 1) {
1158
+ const section = record.page_sections[0]
1159
+ files.push({ file: place.file, id: recordStableId(section), content: contentOf(section) })
1160
+ } else if (place?.kind === 'folder' && record.mode === 'page') {
1161
+ const bases = sectionFileBases(record.page_sections || [])
1162
+ const visit = (list, child) => {
1163
+ for (const section of list || []) {
1164
+ const file = existingSectionFile(place.dir, bases.get(section), recordStableId(section), { child })
1165
+ if (file) files.push({ file, id: recordStableId(section), content: contentOf(section) })
1166
+ visit(section?.$children, true)
1167
+ }
1168
+ }
1169
+ visit(record.page_sections, false)
1170
+ }
1171
+ if (files.length) out.push({ route: canon, files })
1172
+ walk(record.$children, route, canon)
1173
+ }
1174
+ }
1175
+ walk(pages, '', '/')
1176
+ return fileLinkTargets(out)
1177
+ }
1178
+
1179
+ // Each page of a subtree by its route, with its own items: the page's, and its sections' with theirs.
1180
+ function subtreePages(record, route, sourceLocale) {
1181
+ const out = []
1182
+ const sectionUuids = (s) => [s?.$uuid, ...(s?.$children || []).flatMap(sectionUuids)]
1183
+ const walk = (r, at) => {
1184
+ out.push({ route: at, uuids: [r.$uuid, ...(r.page_sections || []).flatMap(sectionUuids)].filter((u) => typeof u === 'string') })
1185
+ for (const child of r.$children || []) walk(child, `${at}/${unwrapLocalized(child.slug, sourceLocale)}`)
1186
+ }
1187
+ walk(record, route)
1188
+ return out
942
1189
  }
943
1190
 
944
1191
  // A page's route and each of its descendants', as `writePagesTree` composes them.
@@ -1022,15 +1269,28 @@ const stableJson = (value) =>
1022
1269
  // the rest after them by filename (`orderFolders`), so the pages at the END that are already in
1023
1270
  // filename order, and carry no `order:`, need none — the way `international` numbers four pages and
1024
1271
  // leaves `404` and `home` to follow. ⛔ The first version of this numbered every page of the level.
1025
- function reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage = null }) {
1272
+ function reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage = null, ctx = null, levelMode = 'sections' }) {
1273
+ // Each page by the entry the files keep it as (`places`): `2-about`, `1-install.md`, a writable
1274
+ // mount's route by its segment — each with how its `order:` is read and written.
1026
1275
  const level = (pages || []).map((r) => {
1027
- const dirName = pageDirName(r, sourceLocale)
1028
- return { dirName, yml: join(pagesDir, dirName, r.mode === 'folder' ? 'folder.yml' : 'page.yml') }
1276
+ const place = ctx?.places?.get(r)
1277
+ if (place?.kind === 'md') {
1278
+ const own = parse(place.file).name
1279
+ return { md: true, dirName: basename(place.file), name: parseNumericPrefix(own).name || own }
1280
+ }
1281
+ if (place?.mount) {
1282
+ const config = mountRouteConfig(place.mount)
1283
+ return { md: false, dirName: place.mount.segment, name: place.mount.segment, readOrder: () => config.read().order, writeOrder: (n) => config.write({ order: n }) }
1284
+ }
1285
+ const dirName = place?.kind === 'folder' ? basename(place.dir) : pageDirName(r, sourceLocale)
1286
+ const yml = join(pagesDir, dirName, r.mode === 'folder' ? 'folder.yml' : 'page.yml')
1287
+ return { md: false, dirName, name: parseNumericPrefix(dirName).name, readOrder: () => readAuthoredYaml(yml)?.order, writeOrder: (n) => writeMergedYaml(yml, { order: n }, ['order']) }
1029
1288
  })
1030
1289
  if (level.length < 2) return
1031
- const folders = level.map(({ dirName, yml }) => {
1032
- const order = readAuthoredYaml(yml)?.order
1033
- return { dirName, name: parseNumericPrefix(dirName).name, order: typeof order === 'number' ? order : undefined }
1290
+ if (levelMode === 'pages') return reconcileFolderModeOrder({ level, pagesDir, list, homepage })
1291
+ const folders = level.map(({ dirName, name, readOrder }) => {
1292
+ const order = readOrder()
1293
+ return { dirName, name, order: typeof order === 'number' ? order : undefined }
1034
1294
  })
1035
1295
  const ordered = orderFolders(folders, list?.pages).map((f) => f.dirName)
1036
1296
  if (ordered.join('\n') === level.map((l) => l.dirName).join('\n')) return
@@ -1053,7 +1313,37 @@ function reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage = n
1053
1313
  if (byName.join('\n') !== candidate.map((f) => f.dirName).join('\n')) break
1054
1314
  tail--
1055
1315
  }
1056
- level.slice(0, tail).forEach(({ yml }, i) => writeMergedYaml(yml, { order: i + 1 }, ['order']))
1316
+ level.slice(0, tail).forEach(({ writeOrder }, i) => writeOrder(i + 1))
1317
+ }
1318
+
1319
+ // ⭐ A FOLDER-MODE LEVEL'S ORDER IS ONE LIST over its `.md` pages and its folders, as the build orders
1320
+ // them (`folderModeChildren`): when the files no longer give the backend's order, the level's `pages:`
1321
+ // says it, in its own config. A page's `order:` cannot — an `.md` page has no config to hold one — and
1322
+ // renaming numbered files would move every page's file for one change.
1323
+ function reconcileFolderModeOrder({ level, pagesDir, list, homepage }) {
1324
+ let entries = []
1325
+ try {
1326
+ entries = readdirSync(pagesDir)
1327
+ } catch {
1328
+ return
1329
+ }
1330
+ const config = { pages: list?.pages }
1331
+ const mine = new Set(level.filter((l) => l.md).map((l) => l.dirName))
1332
+ const files = folderModePageFiles(entries, config).files.filter((f) => mine.has(f.file)).map((f) => ({ name: f.name, entry: f.file }))
1333
+ const folders = orderFolders(
1334
+ level.filter((l) => !l.md).map(({ dirName, name, readOrder }) => {
1335
+ const order = readOrder()
1336
+ return { dirName, name, order: typeof order === 'number' ? order : undefined, entry: dirName }
1337
+ }),
1338
+ list?.pages
1339
+ )
1340
+ const given = folderModeChildren(files, folders, config).map((c) => c.entry)
1341
+ if (given.join('\n') === level.map((l) => l.dirName).join('\n')) return
1342
+ const names = level.map((l) => l.name)
1343
+ const parsed = Array.isArray(list?.pages) ? parseWildcardArray(list.pages) : null
1344
+ // A root list's first entry is the homepage (`reconcileLevelOrder`), so one that does not open with it opens with `...`.
1345
+ if (homepage && names[0] !== homepage) list?.write(['...', ...names])
1346
+ else list?.write(parsed?.mode === 'strict' ? names : [...names, '...'])
1057
1347
  }
1058
1348
 
1059
1349
  // The `pages:` list a level is ordered by, and how to rewrite it. The root's is the site config's,
@@ -1083,27 +1373,39 @@ function collectSectionFileBases(pageSections) {
1083
1373
 
1084
1374
  // Pass 2 — prune orphan section files (per page dir) and orphan page dirs (per
1085
1375
  // level), AFTER every relocation in pass 1. Guarded against wiping an empty level.
1086
- function prunePagesTree(pages, pagesDir, sourceLocale, report, ctx = null, routePrefix = '') {
1376
+ function prunePagesTree(pages, pagesDir, sourceLocale, report, ctx = null, routePrefix = '', levelMode = 'sections') {
1377
+ // Each incoming page by the entry the files keep it as (`places`): a folder's name, an `.md` page's file.
1087
1378
  const incomingDirs = new Set()
1379
+ const incomingFiles = new Set()
1088
1380
  for (const record of pages || []) {
1089
- incomingDirs.add(pageDirName(record, sourceLocale))
1090
1381
  const slug = unwrapLocalized(record.slug, sourceLocale)
1091
1382
  const route = routePrefix ? `${routePrefix}/${slug}` : slug
1092
- // Left alone by pass 1, so nothing of it is pruned either (`git-authored.js`).
1093
- if (ctx?.leave?.has(route)) continue
1094
- const pageDir = join(pagesDir, pageDirName(record, sourceLocale))
1383
+ const place = ctx?.places?.get(record) ?? { kind: 'folder', dir: join(pagesDir, pageDirName(record, sourceLocale)) }
1384
+ if (place.kind === 'md') incomingFiles.add(basename(place.file))
1385
+ else if (place.kind === 'twice') {
1386
+ incomingDirs.add(basename(place.dir))
1387
+ incomingFiles.add(basename(place.file))
1388
+ } else incomingDirs.add(place.mount ? place.mount.segment : place.kind === 'folder' ? basename(place.dir) : pageDirName(record, sourceLocale))
1389
+ // Left alone by pass 1 — and an `.md` page has nothing below it — so nothing of it is pruned.
1390
+ if (place.kind !== 'folder') continue
1391
+ const pageDir = place.dir
1095
1392
  if (record.mode === 'page') {
1096
1393
  // The files pass 1 wrote into — the author's own names among them — else the names it would give.
1097
1394
  const keep = ctx?.sectionFiles?.get(pageDir) || collectSectionFileBases(record.page_sections)
1098
1395
  if (keep.size > 0) pruneOrphanSectionFiles(pageDir, keep, report)
1099
1396
  }
1100
- prunePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route)
1397
+ // A writable mount's pages are in the mounted folder (`page-files.js`).
1398
+ if (place.mount) prunePagesTree(record.$children || [], place.mount.dir, sourceLocale, report, ctx, route, place.mount.childMode)
1399
+ else prunePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, folderModeOf(pageDir, levelMode))
1101
1400
  }
1102
- if (incomingDirs.size === 0) return
1401
+ if (incomingDirs.size === 0 && incomingFiles.size === 0) return
1402
+ if (levelMode === 'pages') pruneOrphanPageFiles(pagesDir, incomingFiles, report, routePrefix, ctx)
1103
1403
  // A mounted route's local folder is never an orphan, whatever the document holds: what it
1104
- // presents is another repository's (`git-authored.js`).
1105
- if (!routePrefix) for (const segment of ctx?.leave?.mounted ?? []) incomingDirs.add(segment)
1106
- pruneOrphanPageDirs(pagesDir, incomingDirs, report)
1404
+ // presents is another repository's (`page-files.js`).
1405
+ if (!routePrefix) for (const segment of ctx?.files?.mounted ?? []) incomingDirs.add(segment)
1406
+ // ⛔ Nor is a folder that holds a folder-mode page, whatever the document holds: until 2026-11-04 a
1407
+ // 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)))
1107
1409
  }
1108
1410
 
1109
1411
  /**
@@ -1345,6 +1647,18 @@ function refuseContentFilesCannotHold(document, sourceLocale) {
1345
1647
  )
1346
1648
  }
1347
1649
 
1650
+ // The routes of the pages a copy's `sync.json` names for a backend — each page unit, `pages/<route>/page.yml`
1651
+ // or `folder.yml`, a parametric folder's segment by its parameter (`[slug]` → `slug`), as `page-files.js`
1652
+ // names routes.
1653
+ function seenPageRoutes(items) {
1654
+ const out = new Set()
1655
+ for (const key of Object.keys(items || {})) {
1656
+ const m = key.match(/^pages\/(.+)\/(?:page|folder)\.yml$/)
1657
+ if (m) out.add(m[1].split('/').map((seg) => seg.match(/^\[(.+)\]$/)?.[1] ?? seg).join('/'))
1658
+ }
1659
+ return out
1660
+ }
1661
+
1348
1662
  /**
1349
1663
  * Project a whole `@uniweb/site-content` document to a site's files: `info` →
1350
1664
  * config (siteInfoToConfig), `collections[]` declarations →
@@ -1371,13 +1685,16 @@ function refuseContentFilesCannotHold(document, sourceLocale) {
1371
1685
  * @param {string} [params.sectionType] - the type a section that names none renders with on this
1372
1686
  * site, which the push filled in and a section's file leaves out — `siteDefaultSectionType`,
1373
1687
  * 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
1374
1691
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
1375
1692
  */
1376
- export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), prune = false, keepAuthoredFoundation = false, scope, dataModel = null, sectionType = DEFAULT_SECTION_TYPE }) {
1693
+ export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), prune = false, keepAuthoredFoundation = false, scope, dataModel = null, sectionType = DEFAULT_SECTION_TYPE, writableMounts = [] }) {
1377
1694
  // Before anything is written: a pull that would leave content out of the files stops here.
1378
1695
  refuseContentFilesCannotHold(document, sourceLocale)
1379
1696
 
1380
- const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [], leftAlone: [] }
1697
+ const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [], leftAlone: [], held: [], mountedPages: [] }
1381
1698
 
1382
1699
  // Collects target-locale translations of localized scalars as they're projected;
1383
1700
  // flushed to locales/{locale}.json at the end (the manifest stays derivable).
@@ -1415,17 +1732,22 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1415
1732
  const siteMap = readAuthoredYaml(join(siteRoot, 'site.yml'))?.i18n?.routeTranslations
1416
1733
  ctx.routes = { siteMap: isPlainRecord(siteMap) && Object.keys(siteMap).length ? siteMap : null, slugs: new Map() }
1417
1734
 
1418
- // Where the tree goes is what `site.yml` says NOW — `siteInfoToConfig` above has
1419
- // written the document's `settings.paths` into it — because that is the file the
1420
- // next push and the build read. See `siteContentDirs`.
1735
+ // Where the tree goes is what this project's own `site.yml` says — the file the next push and the
1736
+ // build read, and one a document never writes `paths` into. See `siteContentDirs`.
1421
1737
  const siteYml = readAuthoredYaml(join(siteRoot, 'site.yml'))
1422
1738
  const { pagesDir, layoutDir: layoutBaseDir } = siteContentDirs(siteRoot, siteYml)
1423
- // The tree a key names its file by: pages and layout wherever `paths:` puts them. (A mount's pages
1424
- // are never written, so the mounts need not join it.)
1425
- if (ctx.media) ctx.media.tree = siteTree(siteRoot, { pagesDir, layoutDir: layoutBaseDir })
1426
- // ⭐ The pages authored in files a pull cannot write back — a mount's, a folder-mode folder's
1427
- // `.md` pages — are neither written nor pruned (`git-authored.js`).
1428
- ctx.leave = gitAuthoredPages(siteYml, pagesDir)
1739
+ // ⭐ WHERE EACH PAGE IS KEPT — found in the files by the build's rules (`page-files.js`), so a page
1740
+ // is written where it lives: a numbered folder, a folder-mode `.md` file, a writable mount's folder.
1741
+ // A read-only mount's pages, and a route the files give two pages for, are neither written nor
1742
+ // pruned. Each record's place, once decided, is the one every pass below reads (`places`).
1743
+ // 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 })
1746
+ ctx.places = new Map()
1747
+ ctx.fileLinks = pageFileTargets(ctx, document?.pages, sourceLocale)
1748
+ // The tree a key names its file by: pages and layout wherever `paths:` puts them, and each mount
1749
+ // the pull writes into. (A read-only mount's pages are never written.)
1750
+ if (ctx.media) ctx.media.tree = siteTree(siteRoot, { pagesDir, layoutDir: layoutBaseDir, mounts: ctx.files.writable })
1429
1751
  // The root page the backend marks as the homepage, by the directory it is written to.
1430
1752
  const home = (document?.pages || []).find((p) => p?.is_index)
1431
1753
  ctx.homepage = home ? pageDirName(home, sourceLocale) : null
@@ -1438,7 +1760,9 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1438
1760
  const root = rootOrderList(siteRoot, pagesDir)
1439
1761
  // A homepage marked `index: true` in its own config — where the push read it (`buildPageData`) —
1440
1762
  // is left marked there alone: a site.yml that names none is not given an `index:` it never had.
1441
- const marksItself = readAuthoredYaml(join(pagesDir, ctx.homepage, home.mode === 'folder' ? 'folder.yml' : 'page.yml'))?.index === true
1763
+ 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
1765
+ const marksItself = homeConfig?.index === true
1442
1766
  if (root.homepage !== ctx.homepage && !(marksItself && root.homepage === undefined)) {
1443
1767
  const listed = Array.isArray(root.pages) ? parseWildcardArray(root.pages) : null
1444
1768
  // A list that names the homepage first beats `index:`, so it opens with `...` instead.
package/src/uwx/site.js CHANGED
@@ -42,7 +42,8 @@
42
42
  //
43
43
  // v0 scope (stated, not silent): media/asset bytes (favicon/assets — carried out of band). Folder-mode `.md`-as-pages and
44
44
  // `paths: { pages/<segment> }` mounts are carried since 2026-10-23, read by the
45
- // build's own rules; a pull leaves those pages alone (`git-authored.js`).
45
+ // build's own rules; a pull writes a folder-mode page back in place, and leaves a mount's alone
46
+ // (`page-files.js`).
46
47
 
47
48
  import { readdir, readFile } from 'node:fs/promises'
48
49
  import { dataBlockModels } from '../i18n/data-models.js'
@@ -1363,7 +1364,9 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
1363
1364
  setIf(settings, 'head_html', headHtml)
1364
1365
  setIf(settings, 'fetcher', siteYml.fetcher)
1365
1366
  setIf(settings, 'build', siteYml.build)
1366
- setIf(settings, 'paths', siteYml.paths)
1367
+ // ⛔ Not `paths`: where a project keeps its files is the project's, and a pull reads it from the
1368
+ // project's own `site.yml`. Sent until 2026-11-04, it reached a clone, which wrote its pages where
1369
+ // another copy kept them — outside itself, pruning what was there.
1367
1370
  setIf(settings, 'base', siteYml.base)
1368
1371
 
1369
1372
  // Locale configuration.