uniweb 1.26.8 → 1.27.0

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.
@@ -44,7 +44,7 @@
44
44
 
45
45
  import { execFileSync } from 'node:child_process'
46
46
  import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
47
- import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path'
47
+ import { basename, dirname, join, posix, relative, resolve, sep } from 'node:path'
48
48
  import yaml from 'js-yaml'
49
49
 
50
50
  import {
@@ -80,6 +80,7 @@ import {
80
80
  siteTreeIn,
81
81
  unmergedPaths
82
82
  } from '../utils/sync-point.js'
83
+ import { submoduleMountRoots, writableMounts, refusedMountLines, heldMountLines } from '../utils/site-roots.js'
83
84
  import { aheadBehind, remoteMoved, upstreamOf } from '../utils/git.js'
84
85
  import { mountedRepositories, askRemote, standing, mountName, short } from '../utils/mounted-repositories.js'
85
86
  import { getLatestVersion, isBehind } from '../utils/update-check.js'
@@ -304,21 +305,12 @@ function otherUncommitted(siteDir, repo, mountedTops = []) {
304
305
  .map((abs) => relative(siteDir, abs) || '.')
305
306
  }
306
307
 
307
- /**
308
- * The folders this site mounts from elsewhere in its repository, relative to the site: a push
309
- * sends their pages as they are on disk, so they wait to be pushed like the site's own.
310
- *
311
- * ⛔ Until 2026-10-31 `status` read the site's own folder alone: it said "nothing waiting" over
312
- * four commits of mounted docs, and the push that followed sent them. A mount in a repository of
313
- * its own is a submodule's pin here, and reads as changed when the pin moves; one outside this
314
- * repository has no commit to compare with, and is left out.
315
- */
316
- async function mountedRoots(siteDir, repo) {
317
- const { mountEntriesOf } = await import('@uniweb/build/site')
318
- return mountEntriesOf(readSiteYml(siteDir)?.paths)
319
- .map(([, dir]) => dir)
320
- .filter((dir) => !isAbsolute(dir) && !posix.normalize(`${repo.prefix}${dir}`).startsWith('..'))
321
- }
308
+ // ⭐ What waits to be pushed is read under the roots a push sends from — a mounted folder the site's
309
+ // repository holds among them (`sentRoots`) — and the submodules that hold a mounted folder, whose
310
+ // pin reads as changed when it moves (`submoduleMountRoots`, `utils/site-roots.js`). A mount outside
311
+ // this repository has no commit to compare with, and is left out. ⛔ Until 2026-10-31 `status` read
312
+ // the site's own folder alone: it said "nothing waiting" over four commits of mounted docs, and the
313
+ // push that followed sent them.
322
314
 
323
315
  /**
324
316
  * Git: conflicts, a merge waiting, what is not committed, and the git remote.
@@ -408,7 +400,7 @@ async function gitChecks(siteDir, { offline, origin, mounts = [] }) {
408
400
  let localFiles = null
409
401
  const point = readSyncPoint(siteDir, origin)
410
402
  if (repo.head && point && isAncestor(repo, point) && siteTreeIn(repo, point)) {
411
- localFiles = filesDifferFrom(repo, point, [...sentRoots(siteDir), ...(await mountedRoots(siteDir, repo))])
403
+ localFiles = filesDifferFrom(repo, point, [...sentRoots(siteDir), ...submoduleMountRoots(siteDir)])
412
404
  }
413
405
 
414
406
  const upstream = upstreamOf(siteDir)
@@ -912,7 +904,7 @@ function changeChecks(siteDir, changes, unpushedFiles, proposals, { elsewhere =
912
904
  * `app.changes` from the pull's own answer (`probePull`): the files it would change, each
913
905
  * as the pull would write it.
914
906
  */
915
- function probedChanges({ files: list, recordsNotPlaced, noBase, movedFrom, itemsBehind = 0 }, unpushedFiles, proposals) {
907
+ function probedChanges({ files: list, recordsNotPlaced, noBase, movedFrom, itemsBehind = 0, mountedMoved = [], held = [] }, unpushedFiles, proposals) {
916
908
  if (noBase && movedFrom) {
917
909
  if (!proposals.some((p) => p.step === 'pull')) {
918
910
  proposals.push({ step: 'pull', command: 'npx uniweb pull', why: 'record where the site is now' })
@@ -922,15 +914,22 @@ function probedChanges({ files: list, recordsNotPlaced, noBase, movedFrom, items
922
914
  if (noBase) return noBaseChanges(list, recordsNotPlaced)
923
915
  // ⛔ Until 2026-10-31 this said nothing changed, and the push that followed was refused: the
924
916
  // backend held newer versions of a mounted folder's pages, which a pull does not write.
925
- if (!list.length && itemsBehind) {
917
+ if (!list.length && (itemsBehind || mountedMoved.length || held.length)) {
926
918
  proposals.push({ step: 'pull', command: 'npx uniweb pull', why: 'record what moved on the backend' })
919
+ // ⭐ Named, page by page, where the pull can say which (`mountedMoved`, `held`): a mounted page the
920
+ // app changed, which the next push puts back, and a page whose file cannot say what the app made of it.
921
+ const named = [
922
+ mountedMoved.length && `${count(mountedMoved.length, 'mounted page')} changed in the app, which the next push puts back: ${mountedMoved.map((r) => `/${r}`).join(', ')}`,
923
+ held.length && `${count(held.length, 'page')} whose files cannot say what the app made of them, kept on the site as the app has them: ${held.map((h) => `/${h.route}`).join(', ')}`,
924
+ ].filter(Boolean)
927
925
  return [
928
926
  {
929
927
  id: 'app.changes',
930
928
  state: 'attention',
931
- summary:
932
- 'The backend moved with no file here to show it: a push from another copy, or pages from a mounted folder. A pull changes no file and records that, and a push before it may be refused.',
933
- detail: { source: 'pull', files: [], itemsBehind }
929
+ summary: named.length
930
+ ? `The backend moved with no file here to show it — ${named.join('; ')}. A pull changes no file and records that.`
931
+ : 'The backend moved with no file here to show it: a push from another copy, or pages from a mounted folder. A pull changes no file and records that, and a push before it may be refused.',
932
+ detail: { source: 'pull', files: [], itemsBehind, mountedMoved, held }
934
933
  }
935
934
  ]
936
935
  }
@@ -1282,33 +1281,34 @@ async function projectChecks(siteDir, siteYml) {
1282
1281
  }
1283
1282
  })
1284
1283
 
1285
- // ⭐ Pages from outside the site's folder (`paths:` mounts, by the build's own rule): a pull
1286
- // never writes them (`uwx/git-authored.js`), and one in its own repository is edited there.
1284
+ // ⭐ Pages from outside the site's folder (`paths:` mounts, by the build's own rule): a pull writes the
1285
+ // app's edits into each one this copy can merge, and holds them for any other (`writableMounts`,
1286
+ // `uwx/page-files.js`); one in its own repository is edited there.
1287
1287
  const { mountEntriesOf } = await import('@uniweb/build/site')
1288
1288
  const siteRepo = repoOf(siteDir)?.top ?? null
1289
+ const { writable, held, refused } = writableMounts(siteDir)
1289
1290
  const mounts = mountEntriesOf(siteYml?.paths).map(([segment, dir]) => {
1290
1291
  const abs = resolve(siteDir, String(dir))
1291
1292
  const exists = existsSync(abs)
1292
1293
  const top = exists ? repoOf(abs)?.top ?? null : null
1293
1294
  const repository = !exists ? null : !top ? 'none' : top === siteRepo ? 'same' : 'other'
1294
- return { segment, dir: String(dir), exists, repository }
1295
+ return { segment, dir: String(dir), exists, repository, writable: writable.includes(segment), held: held.some((h) => h.segment === segment) }
1295
1296
  })
1296
1297
  const mountLine = (m) =>
1297
1298
  !m.exists
1298
1299
  ? `pages/${m.segment} names ${m.dir}, which does not exist.`
1299
- : m.repository === 'other'
1300
- ? `pages/${m.segment} comes from ${m.dir}, its own git repository — edits there are commits in it.`
1301
- : `pages/${m.segment} comes from ${m.dir}, outside the site's folder.`
1300
+ : m.held
1301
+ ? `pages/${m.segment} comes from ${m.dir}, which a pull cannot merge into — it holds the app's edits to those pages.`
1302
+ : m.repository === 'other'
1303
+ ? `pages/${m.segment} comes from ${m.dir}, its own git repository — a pull writes the app's edits there as commits, which you push there before this repository.`
1304
+ : `pages/${m.segment} comes from ${m.dir}, outside pages/ — a pull writes the app's edits into it.`
1302
1305
  checks.push(
1303
1306
  mounts.length
1304
1307
  ? {
1305
1308
  id: 'project.mounts',
1306
- state: mounts.some((m) => !m.exists) ? 'attention' : 'ok',
1307
- summary: mounts.length === 1 ? mountLine(mounts[0]) : `${count(mounts.length, 'page folder')} come from outside the site's folder.`,
1308
- lines: [
1309
- ...(mounts.length === 1 ? [] : mounts.map(mountLine)),
1310
- 'An edit made in the app to those pages does not come back on a pull, and the next push replaces it with the files.'
1311
- ],
1309
+ state: mounts.some((m) => !m.exists) || refused.length ? 'attention' : 'ok',
1310
+ summary: mounts.length === 1 ? mountLine(mounts[0]) : `${count(mounts.length, 'page folder')} come from outside pages/.`,
1311
+ lines: [...(mounts.length === 1 ? [] : mounts.map(mountLine)), ...refused.flatMap(refusedMountLines), ...held.flatMap(heldMountLines)],
1312
1312
  detail: { mounts }
1313
1313
  }
1314
1314
  : { id: 'project.mounts', state: 'skipped', summary: "All the site's pages are in its own folder.", quiet: true, detail: { mounts: [] } }
@@ -1375,7 +1375,7 @@ function ciWorkflow(repo, host) {
1375
1375
  function siteCommitsSince(repo, sha, siteDir) {
1376
1376
  try {
1377
1377
  if (!isAncestor(repo, sha)) return null
1378
- const roots = sentRoots(siteDir).map((r) => `${repo.prefix}${r}`)
1378
+ const roots = sentRoots(siteDir).map((r) => posix.normalize(`${repo.prefix}${r}`))
1379
1379
  const out = execFileSync('git', ['rev-list', '--count', `${sha}..HEAD`, '--', ...roots], {
1380
1380
  cwd: repo.top,
1381
1381
  encoding: 'utf8',
@@ -1,15 +1,15 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-04T16:56:34.431Z",
3
+ "generatedAt": "2026-11-05T01:35:06.410Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.6.9"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.15.5"
9
+ "version": "1.16.0"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
- "version": "1.5.8"
12
+ "version": "1.5.9"
13
13
  },
14
14
  "@uniweb/content-writer": {
15
15
  "version": "1.3.1"
@@ -42,7 +42,7 @@
42
42
  "version": "1.0.1"
43
43
  },
44
44
  "@uniweb/schemas": {
45
- "version": "1.6.7"
45
+ "version": "1.6.8"
46
46
  },
47
47
  "@uniweb/scholar": {
48
48
  "version": "1.1.0"
@@ -54,13 +54,13 @@
54
54
  "version": "1.1.2"
55
55
  },
56
56
  "@uniweb/templates": {
57
- "version": "1.2.5"
57
+ "version": "1.2.6"
58
58
  },
59
59
  "@uniweb/theming": {
60
60
  "version": "1.2.1"
61
61
  },
62
62
  "@uniweb/unipress": {
63
- "version": "1.1.32"
63
+ "version": "1.1.33"
64
64
  }
65
65
  },
66
66
  "templates": {
package/src/utils/git.js CHANGED
@@ -22,68 +22,11 @@
22
22
  */
23
23
 
24
24
  import { execFile, execFileSync } from 'node:child_process'
25
- import { readFileSync } from 'node:fs'
26
- import { join } from 'node:path'
27
- import yaml from 'js-yaml'
28
25
  import { repoOf } from './sync-point.js'
29
26
 
30
- /**
31
- * The files and directories `uniweb pull` writes into.
32
- *
33
- * ONE definition, shared by the guard that stops a pull outside git and the merge a
34
- * pull makes in a repository, whose sync points hold exactly these (and `public/`, where
35
- * the media land) — a second copy would drift, and a stale list here means a guard that
36
- * misses or a merge that drops a file. `paths:` can relocate the content roots, so the
37
- * local site.yml is consulted rather than assuming the defaults.
38
- */
39
- export function siteContentRoots(siteDir) {
40
- // ⚠️ `queries.yml` IS AT THE SITE ROOT, and that is why it must be named here.
41
- // Its predecessor lived at `collections/collections.yml`, so the `collections`
42
- // root added below already covered it and the bare `'collections.yml'` entry
43
- // that used to sit in this list resolved to a path no site ever had. A
44
- // root-level file has no directory entry standing in for it.
45
- //
46
- // The records folder's `folder.yml` is the reverse case: it lives in the records
47
- // directory, which is a root below, so it needs no entry. (It was `records.yml` at
48
- // the site root until 2026-09-21, and was listed here then.)
49
- const roots = new Set([
50
- 'site.yml',
51
- 'theme.yml',
52
- 'head.html',
53
- 'queries.yml',
54
- 'locales'
55
- ])
56
- let paths = {}
57
- try {
58
- paths =
59
- yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))?.paths || {}
60
- } catch {
61
- /* no or unreadable site.yml — the defaults are right */
62
- }
63
- roots.add(paths.pages || 'pages')
64
- roots.add(paths.layout || 'layout')
65
- roots.add(paths.records || 'records')
66
- return [...roots]
67
- }
68
-
69
- /**
70
- * What each lane of a push carries, as roots: the folder lane the records — their files,
71
- * and their translations — and the content lane everything else a pull writes, media
72
- * (`public/`) included. ⚠️ `locales` stays whole on the content side, record translations
73
- * with it: a root too many there costs a less precise base, never a wrong one.
74
- */
75
- export function siteLaneRoots(siteDir) {
76
- let records = 'records'
77
- try {
78
- records = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))?.paths?.records || 'records'
79
- } catch {
80
- /* no or unreadable site.yml — the default is right */
81
- }
82
- return {
83
- content: [...siteContentRoots(siteDir), 'public'].filter((r) => r !== records),
84
- records: [records, 'locales/records']
85
- }
86
- }
27
+ // The roots a pull writes into and a push sends from are the build's to say, mounts included: they
28
+ // moved to `utils/site-roots.js` on 2026-11-04, which may import `@uniweb/build` — this module may not,
29
+ // since the CLI's entry loads it.
87
30
 
88
31
  function git(args, cwd) {
89
32
  return execFileSync('git', args, {
@@ -5,7 +5,7 @@
5
5
  * build or a push reads that folder as it is on disk. When the folder is its own git repository
6
6
  * (a submodule of the site's, or a clone beside it), nothing else keeps it current. A `git pull`
7
7
  * of the site moves a submodule's recorded commit and leaves its checkout where it was. A
8
- * `uniweb pull` never writes into a mount (`uwx/git-authored.js`), so after a teammate pushes
8
+ * `uniweb pull` never writes into a mount (`uwx/page-files.js`), so after a teammate pushes
9
9
  * newer docs, a pull here takes nothing and the next push puts the older ones back. So `status`
10
10
  * says where each one stands, `refresh` takes its latest, and a push or publish stops before
11
11
  * sending one that is not current (`backend/mounts-before-sending.js`).
@@ -23,7 +23,7 @@
23
23
  */
24
24
 
25
25
  import { execFile, execFileSync } from 'node:child_process'
26
- import { existsSync, readFileSync } from 'node:fs'
26
+ import { existsSync, readFileSync, realpathSync } from 'node:fs'
27
27
  import { join, relative, resolve, sep } from 'node:path'
28
28
  import yaml from 'js-yaml'
29
29
  import { repoOf } from './sync-point.js'
@@ -50,6 +50,11 @@ function remoteCall(cwd, args, timeoutMs) {
50
50
  }
51
51
 
52
52
  /** true, false, or null when git cannot say (a commit it does not hold). */
53
+ // Does a remote branch hold this commit? Then it came from someone's line of work, not this checkout's.
54
+ function onARemoteBranch(cwd, sha) {
55
+ return Boolean(text(cwd, ['branch', '-r', '--contains', sha]))
56
+ }
57
+
53
58
  function ancestor(cwd, a, b) {
54
59
  try {
55
60
  run(cwd, ['merge-base', '--is-ancestor', a, b])
@@ -120,6 +125,37 @@ function submoduleHolding(siteTop, abs) {
120
125
  return null
121
126
  }
122
127
 
128
+ /**
129
+ * Which repository holds a mounted folder, as `mountedRepositories` tells them apart:
130
+ * - `site`: the site's own repository holds its files — they are the site's roots (`utils/site-roots.js`);
131
+ * - `submodule`: a submodule of the site's repository holds it, `submodule` naming which;
132
+ * - `own`: a repository the site's does not record — a clone beside the site;
133
+ * - `none`: no repository holds it, or the site is in none.
134
+ *
135
+ * @param {string} siteDir
136
+ * @param {string} abs - the mounted folder
137
+ * @returns {{ kind: 'site'|'submodule'|'own'|'none', submodule?: { path: string, recorded: string } }}
138
+ */
139
+ export function mountHolding(siteDir, abs) {
140
+ const site = repoOf(siteDir)
141
+ if (!site) return { kind: 'none' }
142
+ const sub = site.head ? submoduleHolding(site.top, realOf(abs)) : null
143
+ if (sub) return { kind: 'submodule', submodule: sub }
144
+ const own = existsSync(abs) ? repoOf(abs) : null
145
+ if (!own) return { kind: 'none' }
146
+ return { kind: own.top === site.top ? 'site' : 'own' }
147
+ }
148
+
149
+ // git names a repository's top by its real path, and a mount may be reached through a link (a
150
+ // temporary folder on macOS is): compared as written, it would read as outside the repository.
151
+ function realOf(abs) {
152
+ try {
153
+ return realpathSync(abs)
154
+ } catch {
155
+ return abs // not there: compared as written
156
+ }
157
+ }
158
+
123
159
  /** The submodule's name in `.gitmodules`, and the branch it is told to follow there. */
124
160
  function gitmodulesEntry(siteTop, path) {
125
161
  const out = text(siteTop, ['config', '-f', '.gitmodules', '--get-regexp', '^submodule\\..*\\.path$'])
@@ -171,13 +207,14 @@ export async function mountedRepositories(siteDir) {
171
207
  const out = []
172
208
  for (const [segment, dir] of entries) {
173
209
  const abs = resolve(siteDir, String(dir))
174
- const sub = site?.head ? submoduleHolding(site.top, abs) : null
210
+ // ⭐ The one classification `mountHolding` gives — a submodule's mount among them.
211
+ const sub = site?.head ? submoduleHolding(site.top, realOf(abs)) : null
175
212
  const own = existsSync(abs) ? repoOf(abs) : null
176
213
  // A submodule never checked out is an empty folder of the site's own repository.
177
214
  const top = own && own.top !== site?.top ? own.top : null
178
215
  // In the site's own repository, or in none: the site's own git says all there is.
179
216
  if (!sub && !top) continue
180
- const prefix = slash(relative(top ?? join(site.top, sub.path), abs))
217
+ const prefix = slash(relative(top ?? join(site.top, sub.path), realOf(abs)))
181
218
  const head = top ? text(top, ['rev-parse', 'HEAD']) : null
182
219
  let edits = []
183
220
  if (top) {
@@ -294,14 +331,22 @@ function siteName(siteDir) {
294
331
  * uncommitted changes in it, never backwards, and never from a commit the branch does not
295
332
  * contain, which is a pin put somewhere else on purpose.
296
333
  *
334
+ * ⭐ `merge`: a mount a pull writes into (a submodule's, `writableMounts`) takes its latest as the site takes its own,
335
+ * by merging, where its checkout holds work of its own — commits no remote branch has, a pull's among
336
+ * them: that checkout and a branch that moved on have each moved, and the merge of the two is its
337
+ * latest. Never a rebase, which would replay a pull's commit onto another one while the site's sync
338
+ * point still names it. A checkout another remote branch holds is a pin put there on purpose, and is
339
+ * left where it is, merge or not.
340
+ *
297
341
  * @param {string} siteDir
298
342
  * @param {object} m - from `mountedRepositories`
343
+ * @param {{ merge?: boolean }} [opts]
299
344
  * @returns {Promise<{ from: string|null, to: string|null, branch: string|null, commits: number|null,
300
- * committed: string|null, left: string|null, kind: 'edits'|'no-remote'|'no-answer'|'ahead'|'off-branch'|null,
345
+ * committed: string|null, left: string|null, kind: 'edits'|'no-remote'|'no-answer'|'ahead'|'off-branch'|'conflict'|null,
301
346
  * error: string|null }>} `left` says why it stayed where it was, and `kind` names that reason;
302
347
  * `error`, what failed
303
348
  */
304
- export async function takeLatest(siteDir, m) {
349
+ export async function takeLatest(siteDir, m, { merge = false } = {}) {
305
350
  const r = { from: m.head, to: m.head, branch: null, commits: null, committed: null, left: null, kind: null, error: null }
306
351
  if (m.edits.length) return { ...r, left: `it has ${plural(m.edits.length, 'uncommitted change')}`, kind: 'edits' }
307
352
  let cur = m
@@ -338,18 +383,28 @@ export async function takeLatest(siteDir, m) {
338
383
  }
339
384
  contained = ancestor(cur.top, cur.head, answer.tip)
340
385
  }
341
- if (contained !== true) return { ...r, left: `${short(cur.head)} is not on ${answer.branch ?? 'its branch'}`, kind: 'off-branch' }
386
+ if (contained !== true && (!merge || onARemoteBranch(cur.top, cur.head))) {
387
+ return { ...r, left: `${short(cur.head)} is not on ${answer.branch ?? 'its branch'}`, kind: 'off-branch' }
388
+ }
342
389
  try {
343
- if (cur.follows.upstream) run(cur.top, ['merge', '--ff-only', '--quiet', answer.tip])
390
+ if (contained !== true) {
391
+ // Each has moved: the checkout's commits — a pull's among them — merged with the branch's.
392
+ try {
393
+ run(cur.top, ['merge', '--no-edit', '--no-verify', '--quiet', '-m', `Merge ${answer.branch ?? 'the latest'} of ${label}`, answer.tip])
394
+ } catch {
395
+ return { ...r, left: `its merge with ${answer.branch ?? 'its branch'} of ${label} has conflicts: settle them there and commit, then record it here`, kind: 'conflict' }
396
+ }
397
+ } else if (cur.follows.upstream) run(cur.top, ['merge', '--ff-only', '--quiet', answer.tip])
344
398
  else run(cur.top, ['checkout', '--quiet', '--detach', answer.tip])
345
399
  } catch (err) {
346
400
  return { ...r, error: gitError(err, 'git could not move it') }
347
401
  }
348
- r.to = answer.tip
402
+ const tip = contained === true ? answer.tip : text(cur.top, ['rev-parse', 'HEAD'])
403
+ r.to = tip
349
404
  const n = Number(text(cur.top, ['rev-list', '--count', `${cur.head}..${answer.tip}`]))
350
405
  r.commits = Number.isInteger(n) ? n : null
351
406
  if (cur.submodule) {
352
- const message = `${siteName(siteDir)}: pages/${cur.segment} from ${cur.submodule.path} at ${short(answer.tip)}, the latest of ${label}`
407
+ const message = `${siteName(siteDir)}: pages/${cur.segment} from ${cur.submodule.path} at ${short(tip)}, ${contained === true ? 'the latest' : 'merged with the latest'} of ${label}`
353
408
  try {
354
409
  run(cur.siteTop, ['commit', '-q', '-m', message, '--', cur.submodule.path])
355
410
  r.committed = text(cur.siteTop, ['rev-parse', 'HEAD'])
@@ -0,0 +1,175 @@
1
+ /**
2
+ * The places a push sends a site's content from and a pull merges it into, each relative to the site.
3
+ *
4
+ * ⭐ ONE ANSWER, the build's (`siteContentRoots`, `@uniweb/build/uwx`): the site's config, its
5
+ * translations, its pages, layout and records where `paths:` puts them, its media, and each mounted
6
+ * page folder. A mount the site's own repository holds is one of the site's roots like any other —
7
+ * committed with it, sent from it, merged into it. A mount that is a repository of its own is held to
8
+ * its commits by `backend/mounts-before-sending.js`, and one in no repository has none to be held to
9
+ * (`mountHolding`, `utils/mounted-repositories.js`).
10
+ *
11
+ * ⛔ Until 2026-11-04 the CLI kept a list of its own (`siteContentRoots` in `utils/git.js`) that named
12
+ * no mount: a push sent a same-repository mount's uncommitted edits and named HEAD as what it sent,
13
+ * while `uniweb status` counted that folder among what waits to be pushed.
14
+ *
15
+ * Project-local: it imports `@uniweb/build`, which a global `uniweb` may lack, so nothing the CLI's
16
+ * entry loads statically imports this.
17
+ */
18
+ import { readFileSync, realpathSync } from 'node:fs'
19
+ import { isAbsolute, join, posix, relative, resolve, sep } from 'node:path'
20
+ import yaml from 'js-yaml'
21
+ import { siteContentRoots } from '@uniweb/build/uwx'
22
+ import { mountEntriesOf } from '@uniweb/build/site'
23
+ import { mountHolding } from './mounted-repositories.js'
24
+ import { repoOf } from './sync-point.js'
25
+
26
+ function readSiteYml(siteDir) {
27
+ try {
28
+ return yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8')) || {}
29
+ } catch {
30
+ return {} // no or unreadable site.yml — the defaults are right
31
+ }
32
+ }
33
+
34
+ const rootsOf = (siteDir) => siteContentRoots(siteDir, readSiteYml(siteDir))
35
+
36
+ /**
37
+ * The site's roots: its own, and each mount its repository holds. `media: false` leaves out
38
+ * `public/`, for what a pull writes over outside git.
39
+ *
40
+ * @param {string} siteDir
41
+ * @param {{ media?: boolean }} [opts]
42
+ * @returns {string[]}
43
+ */
44
+ export function siteRoots(siteDir, { media = true } = {}) {
45
+ return rootsOf(siteDir)
46
+ .filter((r) => (r.kind === 'media' ? media : r.kind !== 'mount' || mountHolding(siteDir, r.abs).kind === 'site'))
47
+ .map((r) => r.path)
48
+ }
49
+
50
+ /** What a push sends from the files: the site's roots, its media among them. */
51
+ export const sentRoots = (siteDir) => siteRoots(siteDir)
52
+
53
+ /**
54
+ * What each lane of a push carries, as roots: the folder lane the records — their files, and their
55
+ * translations — and the content lane everything else a pull writes, media (`public/`) and the
56
+ * mounts the site's repository holds included. ⚠️ `locales` stays whole on the content side, record
57
+ * translations with it: a root too many there costs a less precise base, never a wrong one.
58
+ */
59
+ export function laneRoots(siteDir) {
60
+ const records = rootsOf(siteDir).find((r) => r.kind === 'records').path
61
+ return {
62
+ content: siteRoots(siteDir).filter((r) => r !== records),
63
+ records: [records, 'locales/records'],
64
+ }
65
+ }
66
+
67
+ /**
68
+ * The submodules that hold a mounted folder, each by its path relative to the site: the commit the
69
+ * site's repository records for one is the site's to commit, and `uniweb status` reads a pin that
70
+ * moved as a change waiting. ⭐ The submodule's own path, not the mounted folder's — a folder inside
71
+ * one is no path of the site's repository (`unipress/docs` is in the `unipress` submodule).
72
+ */
73
+ export function submoduleMountRoots(siteDir) {
74
+ const repo = repoOf(siteDir)
75
+ if (!repo) return []
76
+ const out = new Set()
77
+ for (const r of rootsOf(siteDir)) {
78
+ if (r.kind !== 'mount') continue
79
+ const held = mountHolding(siteDir, r.abs)
80
+ if (held.kind !== 'submodule') continue
81
+ out.add(posix.relative(repo.prefix.replace(/\/$/, '') || '.', held.submodule.path) || '.')
82
+ }
83
+ return [...out]
84
+ }
85
+
86
+ /**
87
+ * ⭐ WHETHER A PULL WRITES THE APP'S EDITS INTO EACH MOUNT — no setting, but where its folder is
88
+ * [Diego, 2026-11-04: "I don't think it should default to false and I don't even know if it should
89
+ * exist. Ignoring incoming changes and then submitting the unmodified version may be wrong"]:
90
+ * - `writable`: a folder the site's own repository holds, whose files are among the site's roots; or a
91
+ * folder in a submodule of it (`submodules`), merged in the submodule's own history, git's own pairing
92
+ * of the two; or, for a site in no repository, a folder inside the site's own. Written like the
93
+ * site's own pages.
94
+ * - `held`: one a pull cannot merge into, with why — `own`, a repository the site's does not record, a
95
+ * clone beside it; `none`, a folder no repository holds, or one ignores, or outside the folder of a
96
+ * site in none; `unchecked`, a submodule not checked out. Its app edits are neither written nor
97
+ * undone: the copy holds the version it last agreed on (`agreedVersions`, `commands/pull.js`).
98
+ * - `refused`: a mount written as an object, the form `writable` was set in, which the build refuses
99
+ * too. The pull stops on it.
100
+ * ⛔ Until 2026-11-04 a mount was written only where the site marked it `writable: true`, and the next
101
+ * push undid every app edit to any other.
102
+ *
103
+ * @param {string} siteDir
104
+ * @returns {{ writable: string[], held: Array<{ segment: string, path: string, why: 'own'|'none'|'unchecked' }>,
105
+ * refused: Array<{ segment: string, path: string|null }>,
106
+ * submodules: Array<{ segment: string, at: string, root: string, repo: object }> }} `submodules`: each
107
+ * mount in one, with the submodule's path from the site repository's top, the mounted folder's path
108
+ * in it, and its `repoOf`
109
+ */
110
+ export function writableMounts(siteDir) {
111
+ const repo = repoOf(siteDir)
112
+ const writable = []
113
+ const held = []
114
+ const refused = []
115
+ const submodules = []
116
+ for (const [segment, folder] of mountEntriesOf(readSiteYml(siteDir).paths)) {
117
+ if (typeof folder !== 'string' || !folder) {
118
+ refused.push({ segment, path: typeof folder?.path === 'string' ? folder.path : null })
119
+ continue
120
+ }
121
+ const abs = resolve(siteDir, folder)
122
+ let why = null
123
+ if (repo) {
124
+ const holding = mountHolding(siteDir, abs)
125
+ if (holding.kind === 'submodule') {
126
+ const top = join(repo.top, holding.submodule.path)
127
+ const sub = repoOf(top)
128
+ if (!sub?.head) why = 'unchecked'
129
+ else submodules.push({ segment, at: holding.submodule.path, root: relative(realOf(top), realOf(abs)).split(sep).join('/') || '.', repo: sub })
130
+ } else if (holding.kind !== 'site') why = holding.kind
131
+ } else {
132
+ const rel = relative(siteDir, abs)
133
+ if (!rel || isAbsolute(rel) || rel === '..' || rel.startsWith(`..${posix.sep}`) || rel.startsWith('..\\')) why = 'none'
134
+ }
135
+ if (why) held.push({ segment, path: folder, why })
136
+ else writable.push(segment)
137
+ }
138
+ return { writable, held, refused, submodules }
139
+ }
140
+
141
+ const realOf = (p) => {
142
+ try {
143
+ return realpathSync(p)
144
+ } catch {
145
+ return p
146
+ }
147
+ }
148
+
149
+ /** What stops a pull on a mount written as an object, and what replaced it. */
150
+ export function refusedMountLines({ segment, path }) {
151
+ return [
152
+ `pages/${segment} in site.yml's paths: is an object. A mount is its folder: \`pages/${segment}: ${path ?? '../docs'}\`.`,
153
+ " `writable` is retired: a pull writes the app's edits into a mounted folder wherever it can merge them, a folder of the site's repository or of a submodule, and holds them where it cannot."
154
+ ]
155
+ }
156
+
157
+ /** What to tell a person about a mount whose app edits a pull holds, and what lets a pull write them. */
158
+ export function heldMountLines({ segment, path, why }) {
159
+ const what =
160
+ why === 'unchecked'
161
+ ? 'a submodule that is not checked out'
162
+ : why === 'own'
163
+ ? "a repository of its own, which the site's repository does not record"
164
+ : "a folder no history of the site's holds"
165
+ const settle =
166
+ why === 'unchecked'
167
+ ? 'Check it out (`git submodule update --init`), then pull to take them.'
168
+ : why === 'own'
169
+ ? "To have a pull write them, make it a submodule of the site's repository."
170
+ : "To have a pull write them, make it part of the site's repository, or a submodule of it."
171
+ return [
172
+ `pages/${segment} comes from ${path}, ${what}, so a pull cannot merge into it: the app's edits to its pages are held — kept on the backend, not written here, and not undone by a push while their files are unchanged.`,
173
+ ` ${settle}`
174
+ ]
175
+ }