uniweb 1.26.6 → 1.26.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.26.6",
3
+ "version": "1.26.7",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -47,9 +47,9 @@
47
47
  "@uniweb/content-writer": "~1.3.1"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/semantic-parser": "~1.13.2",
50
+ "@uniweb/build": "~1.15.5",
51
51
  "@uniweb/content-reader": "~1.5.8",
52
- "@uniweb/build": "~1.15.4"
52
+ "@uniweb/semantic-parser": "~1.13.2"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -239,7 +239,7 @@ extensions: ['@acme/fx@0.3.1']
239
239
 
240
240
  **Routes:** folders map 1:1 to routes; `pages:` controls order only. The site root is the exception: the first of `pages:` sets `/`, else `index:`, declared in `site.yml` or in the pages directory's own `folder.yml`/`page.yml`, with `site.yml` winning. A folder with `page.yml` but no markdown is a structural group (`hasContent: false`); visiting it redirects to the first descendant with content.
241
241
 
242
- **Mounted folders:** a local folder for a mounted route says how *this site* presents it. Keep `layout:`, `title:` and SEO in a `folder.yml` there; the mounted repo's own `folder.yml` supplies ordering and title where the stub is silent. A `page.yml` with markdown of its own makes a real page above the mounted pages — a landing page for the branch. A mount is one level under `pages/`, and a subfolder in the local folder isn't read, since the branch's pages come from the mount; the build says so. What a site can't do from outside a repo it mounts: leave a file out, title or order a nested folder, or use a `README.md` as a page — those are the mounted repo's to do. A relative link to a markdown file (`./deploying.md#setup`), which is how docs in a repo link to each other, leads to the page that file became; the build names one that leads nowhere.
242
+ **Mounted folders:** a local folder for a mounted route says how *this site* presents it. Keep `layout:`, `title:` and SEO in a `folder.yml` there; the mounted repo's own `folder.yml` supplies ordering and title where the stub is silent. A `page.yml` with markdown of its own makes a real page above the mounted pages — a landing page for the branch. A mount is one level under `pages/`, and a subfolder in the local folder isn't read, since the branch's pages come from the mount; the build says so. What a site can't do from outside a repo it mounts: leave a file out, title or order a nested folder, or use a `README.md` as a page — those are the mounted repo's to do. A relative link to a markdown file (`./deploying.md#setup`), which is how docs in a repo link to each other, leads to the page that file became; the build names one that leads nowhere. A mount that is its own repository (a submodule, or a clone beside the site) takes its edits as commits there, and `uniweb refresh` takes its latest; a push or publish stops on one that is behind its remote or holds uncommitted changes, and `--mounts-as-is` sends it as it is.
243
243
 
244
244
  **Visibility flags:** `hidden: true` is a draft (not published; `uniweb dev` previews it; on a page it takes the pages below with it; on a section it's also kept from the component's params and takes its children with it); `hideIn: ['*']` or `[header]` controls nav placement only; `knowledge: true` is a different audience (below). An authored `pages/404/` needs no flag — `hidden: true` there makes it a draft and the site falls back to the generic 404.
245
245
 
@@ -0,0 +1,160 @@
1
+ /**
2
+ * The stop before a push or publish sends pages mounted from a repository of their own that are
3
+ * not current (`utils/mounted-repositories.js`).
4
+ *
5
+ * ⭐ THIS IS THE BACKEND'S GATE, FOR A MOUNT. For the site's own files, a push refused because a
6
+ * teammate pushed first (`untakenBase`) is settled by a pull, which brings their work into the
7
+ * files. A pull never writes into a mount, so after a teammate pushes newer docs a pull here takes
8
+ * nothing, and a push would put the older ones back. So a push or publish stops when:
9
+ * - a submodule is not checked out, or its checkout is not the commit the site's repository
10
+ * records. Behind it: a `git pull` moved the pin and left the checkout. Ahead of it: a commit
11
+ * made in it, which `--commit` records here as it commits the site's content;
12
+ * - the folder has uncommitted changes, which no commit holds;
13
+ * - the branch it follows has commits that change the folder.
14
+ *
15
+ * Interactive, it offers to take the latest first, and `--yes` takes it without asking.
16
+ * Unattended, it stops and names both ways on: `npx uniweb refresh`, or `--mounts-as-is`, which
17
+ * sends every mounted folder as it is [Diego, 2026-11-04: "we can also have a flag to publish in
18
+ * spite of not being up-to-date, so an explicit option for that case"]. A remote that does not
19
+ * answer is said, and the folder goes as it is.
20
+ *
21
+ * Its own module so the flags it reads stay out of the verbs that only read where mounts stand
22
+ * (`status`, `refresh`, `pull`; `test/flag-guard-coverage.test.js`).
23
+ */
24
+
25
+ import { isNonInteractive, confirm } from '../utils/interactive.js'
26
+ import {
27
+ mountedRepositories,
28
+ askRemote,
29
+ standing,
30
+ fetchTip,
31
+ takeLatest,
32
+ commitPin,
33
+ describeTaken,
34
+ mountName,
35
+ short
36
+ } from '../utils/mounted-repositories.js'
37
+
38
+ const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
39
+
40
+ /**
41
+ * What stands between each mount and being sent: `{ m, line, take, commit }`, where `take` says
42
+ * that taking the latest settles it, and `commit` that committing its pin does.
43
+ */
44
+ async function problemsOf(mounts, { say }) {
45
+ const problems = []
46
+ for (const m of mounts) {
47
+ const name = mountName(m)
48
+ if (m.pin === 'missing') {
49
+ problems.push({ m, take: true, line: `${name}: a submodule that is not checked out.` })
50
+ continue
51
+ }
52
+ if (m.edits.length) {
53
+ problems.push({
54
+ m,
55
+ take: false,
56
+ line: `${name}: ${plural(m.edits.length, 'uncommitted change')}, which no commit holds. Commit or discard ${m.edits.length === 1 ? 'it' : 'them'} there.`
57
+ })
58
+ }
59
+ const recorded = short(m.submodule?.recorded)
60
+ if (m.pin === 'behind') {
61
+ problems.push({ m, take: true, line: `${name}: checked out at ${short(m.head)}, behind the ${recorded} this repository records — \`git pull\` moved it, and the checkout stayed.` })
62
+ } else if (m.pin === 'ahead') {
63
+ problems.push({ m, take: false, commit: true, line: `${name}: checked out at ${short(m.head)}, ahead of the ${recorded} this repository records. Commit it here, or re-run with --commit.` })
64
+ } else if (m.pin === 'diverged') {
65
+ problems.push({ m, take: false, line: `${name}: checked out at ${short(m.head)}, which is not on the line of the ${recorded} this repository records.` })
66
+ }
67
+ // The remote is asked of a checkout that could move: not over changes, nor off its pin's line.
68
+ if (m.edits.length || m.pin === 'behind' || m.pin === 'diverged' || !m.follows) continue
69
+ const answer = await askRemote(m)
70
+ if (!answer) {
71
+ say.note(`${name}: ${m.follows.label} did not answer, so whether it has newer commits is unknown. It goes as it is.`)
72
+ continue
73
+ }
74
+ let s = standing(m, answer.tip)
75
+ // Only the commits can say whether they change the folder, so they are fetched.
76
+ if (s === 'unheld') s = (await fetchTip(m, answer.branch)) ? standing(m, answer.tip) : 'newer'
77
+ const on = answer.branch ? ` on ${answer.branch}` : ''
78
+ if (s === 'newer') problems.push({ m, take: true, line: `${name}: ${m.follows.label} has newer commits for it${on}.` })
79
+ if (s === 'diverged') {
80
+ const pinned = m.submodule ? `, or name the branch it follows: \`git config -f .gitmodules submodule.${m.submodule.name ?? m.submodule.path}.branch <branch>\`` : ''
81
+ problems.push({ m, take: false, line: `${name}: it and ${m.follows.label}${on} have each moved. Bring them together there${pinned}.` })
82
+ }
83
+ }
84
+ return problems
85
+ }
86
+
87
+ /**
88
+ * The stop before a push or publish sends anything, where a mounted folder is not as it should
89
+ * be — or, interactive or with `--yes`, the latest taken first. Returns `{ exitCode }` to stop, or
90
+ * null to go on.
91
+ *
92
+ * @param {string} siteDir
93
+ * @param {string[]} args
94
+ * @param {{ verb: 'push'|'publish', dryRun: boolean, say: { success: Function, info: Function, error: Function, note: Function } }} opts
95
+ */
96
+ export async function mountsBeforeSending(siteDir, args, { verb, dryRun, say }) {
97
+ const mounts = await mountedRepositories(siteDir)
98
+ if (!mounts.length) return null
99
+ if (args.includes('--mounts-as-is')) {
100
+ say.note(`${mounts.map(mountName).join(', ')}: sent as ${mounts.length === 1 ? 'it is' : 'they are'} (--mounts-as-is).`)
101
+ return null
102
+ }
103
+ let problems = await problemsOf(mounts, { say })
104
+ if (!problems.length) return null
105
+
106
+ // A checkout ahead of its pin is the site's own change: `--commit` commits it, as it does the rest.
107
+ if (args.includes('--commit') && problems.some((p) => p.commit)) {
108
+ for (const p of problems.filter((p) => p.commit)) {
109
+ if (dryRun) {
110
+ say.info(`Dry run — would commit ${p.m.submodule.path} at ${short(p.m.head)} first.`)
111
+ continue
112
+ }
113
+ const made = commitPin(siteDir, p.m)
114
+ if (made.error) {
115
+ say.error(`Could not commit ${p.m.submodule.path}'s new pin:`)
116
+ for (const line of String(made.error).split('\n').slice(0, 6)) say.note(` ${line}`)
117
+ return { exitCode: 1 }
118
+ }
119
+ say.success(`Committed ${p.m.submodule.path} at ${short(p.m.head)} — ${short(made.commit)}`)
120
+ }
121
+ problems = problems.filter((p) => !p.commit)
122
+ if (!problems.length) return null
123
+ }
124
+
125
+ const yes = args.includes('--yes')
126
+ const canAsk = !isNonInteractive(args)
127
+ const manyOf = (list) => new Set(list.map((p) => p.m.segment)).size > 1
128
+ if (problems.every((p) => p.take) && (yes || canAsk)) {
129
+ const list = [...new Set(problems.map((p) => mountName(p.m)))].join(', ')
130
+ if (dryRun) {
131
+ say.info(`Dry run — would ${yes ? 'take' : 'offer to take'} the latest of ${list} first.`)
132
+ return null
133
+ }
134
+ for (const p of problems) say.info(p.line)
135
+ if (yes || (await confirm(`Take the latest of ${manyOf(problems) ? 'them' : 'it'} first?`, true))) {
136
+ for (const m of new Map(problems.map((p) => [p.m.segment, p.m])).values()) {
137
+ const r = await takeLatest(siteDir, m)
138
+ ;(r.error || r.left ? say.note : say.success)(describeTaken(m, r))
139
+ }
140
+ problems = await problemsOf(await mountedRepositories(siteDir), { say })
141
+ if (!problems.length) return null
142
+ }
143
+ }
144
+
145
+ const done = verb === 'publish' ? 'published' : 'pushed'
146
+ const many = manyOf(problems)
147
+ const them = many ? 'them' : 'it'
148
+ const asIs = many ? 'as they are' : 'as it is'
149
+ const takes = problems.filter((p) => p.take).length
150
+ say.error(`Not ${done} — ${many ? 'page folders mounted from other repositories are' : 'a page folder mounted from another repository is'} not ready to send:`)
151
+ for (const p of problems) say.note(` ${p.line}`)
152
+ const settle =
153
+ takes === problems.length
154
+ ? 'Take the latest with `npx uniweb refresh`'
155
+ : takes
156
+ ? 'Settle the rest as above, take the latest with `npx uniweb refresh`'
157
+ : `Settle ${them} as above`
158
+ say.note(`${settle}, then ${verb} again — or ${verb} ${them} ${asIs} with --mounts-as-is.`)
159
+ return { exitCode: 1 }
160
+ }
@@ -118,6 +118,7 @@ import {
118
118
  } from '../backend/site-sync.js'
119
119
  import { repoOf } from '../utils/sync-point.js'
120
120
  import { commitBeforeSending } from '../backend/commit-before-sending.js'
121
+ import { mountsBeforeSending } from '../backend/mounts-before-sending.js'
121
122
  import { resolveWorkspace, describeWorkspace, previewWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
122
123
  import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
123
124
  import { liveAddress } from '../backend/live-address.js'
@@ -356,14 +357,16 @@ export async function publish(args = []) {
356
357
  for (const line of unsettled.lines) say.dim(line)
357
358
  return { exitCode: 1 }
358
359
  }
360
+ // ⛔ Pages mounted from a repository of their own go only as current: a pull never writes
361
+ // into one, so the backend's gate cannot keep older ones from replacing newer
362
+ // (`backend/mounts-before-sending.js`). `--mounts-as-is` sends them as they are.
359
363
  // ⛔ In a repository a publish sends what is committed (`uncommittedContent`), whatever the
360
364
  // flags. `--commit` commits it first; a dry run says it would.
361
365
  {
362
- const stop = commitBeforeSending(siteDir, args, {
363
- verb: 'publish',
364
- dryRun,
365
- say: { success: say.ok, info: say.info, error: say.err, note: say.dim }
366
- })
366
+ const said = { success: say.ok, info: say.info, error: say.err, note: say.dim }
367
+ const mounted = await mountsBeforeSending(siteDir, args, { verb: 'publish', dryRun, say: said })
368
+ if (mounted) return mounted
369
+ const stop = commitBeforeSending(siteDir, args, { verb: 'publish', dryRun, say: said })
367
370
  if (stop) return stop
368
371
  }
369
372
  if (!dryRun && !args.includes('--force')) {
@@ -134,6 +134,7 @@ import {
134
134
  readSyncPoint,
135
135
  writeSyncPoint
136
136
  } from '../utils/sync-point.js'
137
+ import { behindLines } from '../utils/mounted-repositories.js'
137
138
  import { isNonInteractive } from '../utils/interactive.js'
138
139
  import {
139
140
  BackendClient,
@@ -1485,6 +1486,8 @@ export async function pull(args = [], deps = {}) {
1485
1486
  `Left as written: ${leftAlone} page(s) whose files a pull does not write — a mounted folder's, or a folder-mode folder's \`.md\` pages. ` +
1486
1487
  'An edit made to one in the app does not come back here, and the next push sends the file.'
1487
1488
  )
1489
+ // ⭐ A mounted folder's pages are as current as its repository, which no pull moves.
1490
+ for (const line of await behindLines(siteDir)) note(line)
1488
1491
  }
1489
1492
  // ⭐ Said, because the text is not in a translation file: one would make the language the site's,
1490
1493
  // and the next publish would ask to serve it (`uwx/source-locale.js`). It is kept for the push to
@@ -109,6 +109,7 @@ import {
109
109
  readSiteWorkspace
110
110
  } from '../backend/site-sync.js'
111
111
  import { commitBeforeSending } from '../backend/commit-before-sending.js'
112
+ import { mountsBeforeSending } from '../backend/mounts-before-sending.js'
112
113
  import { resolveWorkspace, describeWorkspace, previewWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
113
114
 
114
115
  // Re-exported for downstream importers (pull.js, push.test.js) that read these
@@ -232,10 +233,16 @@ export async function push(args = [], deps = {}) {
232
233
  for (const line of unsettled.lines) note(line)
233
234
  return { exitCode: 1 }
234
235
  }
236
+ // ⛔ Pages mounted from a repository of their own go only as current: a pull never writes
237
+ // into one, so the backend's gate cannot keep older ones from replacing newer
238
+ // (`backend/mounts-before-sending.js`). `--mounts-as-is` sends them as they are.
235
239
  // ⛔ In a repository a push sends what is committed (`uncommittedContent`), whatever the
236
240
  // flags but `-o`, which sends nothing. `--commit` commits it first; a dry run says it would.
237
241
  if (!output) {
238
- const stop = commitBeforeSending(siteDir, args, { verb: 'push', dryRun, say: { success, info, error, note } })
242
+ const said = { success, info, error, note }
243
+ const mounted = await mountsBeforeSending(siteDir, args, { verb: 'push', dryRun, say: said })
244
+ if (mounted) return mounted
245
+ const stop = commitBeforeSending(siteDir, args, { verb: 'push', dryRun, say: said })
239
246
  if (stop) return stop
240
247
  }
241
248
  if (!output && !force) {
@@ -1,10 +1,13 @@
1
1
  /**
2
2
  * uniweb refresh — catch up with everything outside your working copy.
3
3
  *
4
- * A developer on a synced site has TWO independent external sources, and nothing
5
- * in the tool used to connect them:
4
+ * A developer on a synced site has independent external sources, and nothing in the
5
+ * tool used to connect them:
6
6
  *
7
7
  * - the git remote — teammates' commits;
8
+ * - each repository the site mounts a page folder from (`paths:`) — its own commits,
9
+ * which neither of the others brings: a `git pull` leaves a submodule's checkout where
10
+ * it was, and a pull never writes into a mount (`utils/mounted-repositories.js`);
8
11
  * - the backend — content authors' edits, made in the app.
9
12
  *
10
13
  * Someone who runs only `git pull` silently misses every app edit; someone who
@@ -12,12 +15,18 @@
12
15
  * caught out is exactly the one starting their day believing they are current.
13
16
  * This is the one command for that: run it in the morning, or before a milestone.
14
17
  *
18
+ * A mount is taken to the tip of the branch it follows, never backwards, never over
19
+ * uncommitted changes in it, and never from a commit that branch does not contain; a
20
+ * submodule's new pin is committed on its own, so what a push sends from it is what a
21
+ * commit records.
22
+ *
15
23
  * READ-ONLY, and that is the load-bearing decision. It never pushes. Because it
16
24
  * cannot ship anything, it can be run reflexively without weighing consequences —
17
25
  * which is the whole point of a start-of-day command. A version that also pushed
18
26
  * would be one you had to think about first, and so one people would stop running.
19
27
  *
20
- * Order is deliberate: git first, then the backend. Teammates' commits — and the sync
28
+ * Order is deliberate: git first, then the mounts (whose pins that pull may have
29
+ * moved), then the backend. Teammates' commits — and the sync
21
30
  * points their pulls merged — are then in the history when the backend's content
22
31
  * arrives, so the pull merges against the newest state of the site this history shares
23
32
  * with the backend (`utils/sync-point.js`), and a teammate's change is merged like your
@@ -34,8 +43,9 @@
34
43
  * content. If a `sync` verb is ever wanted, it is that chain.
35
44
  *
36
45
  * Usage:
37
- * uniweb refresh git pull, then pull: merge the backend's content
38
- * uniweb refresh --no-git skip the git remote; backend only
46
+ * uniweb refresh git pull, the mounts' latest, then pull: merge the backend's content
47
+ * uniweb refresh --no-git skip every git remote, the mounts' included; backend only
48
+ * uniweb refresh --no-mounts leave the mounted repositories where they are
39
49
  * uniweb refresh --no-backend skip the backend; git only
40
50
  *
41
51
  * The backend is the one you are logged in to, as for every backend verb (no flag picks it).
@@ -53,6 +63,7 @@ import {
53
63
  headProvenance
54
64
  } from '../utils/git.js'
55
65
  import { ignoringRepo } from '../utils/sync-point.js'
66
+ import { mountedRepositories, takeLatest, describeTaken } from '../utils/mounted-repositories.js'
56
67
  import { probeUnpushed } from '../backend/site-sync.js'
57
68
  import { resolveBackendOrigin } from '../backend/client.js'
58
69
  import { readBackendState } from '@uniweb/build/uwx'
@@ -114,6 +125,7 @@ export async function refresh(args = [], deps = {}) {
114
125
  }
115
126
  }
116
127
  const skipGit = args.includes('--no-git')
128
+ const skipMounts = args.includes('--no-mounts')
117
129
  const skipBackend = args.includes('--no-backend')
118
130
  const resolveSite = deps.resolveSiteDir || resolveSiteDir
119
131
  const siteDir = await resolveSite(args, 'refresh')
@@ -158,7 +170,26 @@ export async function refresh(args = [], deps = {}) {
158
170
  consulted.push('git')
159
171
  }
160
172
 
161
- // ── 2. the backend ────────────────────────────────────────────────────────
173
+ // ── 2. the repositories the site mounts page folders from ─────────────────
174
+ // After the git pull, which may have moved a submodule's pin and left its checkout.
175
+ // ⭐ A mount that could not be brought to its latest is said at the end too, since "Up to
176
+ // date" would be wrong. One with no remote, or with commits its remote lacks, is as current
177
+ // as it can be.
178
+ const mountsLeft = []
179
+ const mounts = skipGit || skipMounts ? [] : await mountedRepositories(siteDir)
180
+ if (skipGit || skipMounts) {
181
+ skipped.push(`mounts (${skipGit ? '--no-git' : '--no-mounts'})`)
182
+ } else if (mounts.length) {
183
+ say.info(`Taking the latest of ${mounts.length === 1 ? 'the page folder' : `${mounts.length} page folders`} mounted from ${mounts.length === 1 ? 'another repository' : 'other repositories'}…`)
184
+ for (const m of mounts) {
185
+ const r = await takeLatest(siteDir, m)
186
+ say.dim(describeTaken(m, r))
187
+ if (r.error || ['edits', 'no-answer', 'off-branch'].includes(r.kind)) mountsLeft.push(m)
188
+ }
189
+ consulted.push('mounts')
190
+ }
191
+
192
+ // ── 3. the backend ────────────────────────────────────────────────────────
162
193
  // The backend the delegated pull talks to — the one you are logged in to
163
194
  // (resolveBackendOrigin). Everything below asks about THAT one.
164
195
  const backend = resolveBackendOrigin()
@@ -185,7 +216,7 @@ export async function refresh(args = [], deps = {}) {
185
216
  consulted.push('backend')
186
217
  }
187
218
 
188
- // ── 3. where that leaves you ──────────────────────────────────────────────
219
+ // ── 4. where that leaves you ──────────────────────────────────────────────
189
220
  console.log('')
190
221
  tell()
191
222
 
@@ -218,6 +249,10 @@ export async function refresh(args = [], deps = {}) {
218
249
  )
219
250
  return { exitCode: 1 }
220
251
  }
252
+ if (mountsLeft.length) {
253
+ say.warn(`Up to date, except ${mountsLeft.map((m) => `pages/${m.segment}`).join(', ')}, as said above.`)
254
+ return { exitCode: 0 }
255
+ }
221
256
  say.ok('Up to date.')
222
257
  return { exitCode: 0 }
223
258
  }
@@ -81,6 +81,7 @@ import {
81
81
  unmergedPaths
82
82
  } from '../utils/sync-point.js'
83
83
  import { aheadBehind, remoteMoved, upstreamOf } from '../utils/git.js'
84
+ import { mountedRepositories, askRemote, standing, mountName, short } from '../utils/mounted-repositories.js'
84
85
  import { getLatestVersion, isBehind } from '../utils/update-check.js'
85
86
  import { syncedElsewhere } from '../utils/site-identity.js'
86
87
  import { DEFAULT_BACKEND_ORIGIN } from '../utils/config.js'
@@ -258,7 +259,7 @@ const count = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`
258
259
  *
259
260
  * @returns {string[]|null} null when git could not be asked
260
261
  */
261
- function otherUncommitted(siteDir, repo) {
262
+ function otherUncommitted(siteDir, repo, mountedTops = []) {
262
263
  const root = findWorkspaceRoot(siteDir) || siteDir
263
264
  // Only the repository's part of it: a workspace above the repository's top is read from there.
264
265
  const scope = relative(repo.top, root).startsWith('..') ? repo.top : root
@@ -297,7 +298,9 @@ function otherUncommitted(siteDir, repo) {
297
298
  }
298
299
  return [...new Set(paths)]
299
300
  .map((p) => join(repo.top, p.replace(/\/$/, '')))
300
- .filter((abs) => !isContent(abs) && !inOwnProject(abs))
301
+ // ⭐ A mounted submodule's own state is `git.mounts`' to say: committing a checkout that is
302
+ // behind its pin would undo the commit that moved it.
303
+ .filter((abs) => !isContent(abs) && !inOwnProject(abs) && !mountedTops.some((t) => abs === t || abs.startsWith(t + sep)))
301
304
  .map((abs) => relative(siteDir, abs) || '.')
302
305
  }
303
306
 
@@ -321,7 +324,7 @@ async function mountedRoots(siteDir, repo) {
321
324
  * Git: conflicts, a merge waiting, what is not committed, and the git remote.
322
325
  * @returns {Promise<{ checks: object[], proposals: object[], localFiles: string[]|null }>}
323
326
  */
324
- async function gitChecks(siteDir, { offline, origin }) {
327
+ async function gitChecks(siteDir, { offline, origin, mounts = [] }) {
325
328
  const checks = []
326
329
  const proposals = []
327
330
  const repo = repoOf(siteDir)
@@ -378,7 +381,8 @@ async function gitChecks(siteDir, { offline, origin }) {
378
381
 
379
382
  // What else in the project is not committed — a merge holds it until its commit, and a
380
383
  // repository with no commit yet has said so above.
381
- const others = merging || !repo.head ? null : otherUncommitted(siteDir, repo)
384
+ const mountedTops = mounts.filter((m) => m.submodule).map((m) => join(m.siteTop, m.submodule.path))
385
+ const others = merging || !repo.head ? null : otherUncommitted(siteDir, repo, mountedTops)
382
386
  if (others?.length) {
383
387
  const n = others.length
384
388
  const fnd = resolveLocalFoundation(siteDir, readSiteYml(siteDir))
@@ -448,6 +452,124 @@ async function gitChecks(siteDir, { offline, origin }) {
448
452
  return { checks, proposals, localFiles, uncommitted: Boolean(uncommitted), merging, repo: Boolean(repo.head) }
449
453
  }
450
454
 
455
+ /**
456
+ * The page folders this site mounts from a repository of their own, and where each one stands:
457
+ * a submodule's checkout against the commit this repository records, the changes in it that no
458
+ * commit holds, and, unless `--offline`, the branch it follows on its remote, asked with
459
+ * `git ls-remote`, which fetches nothing (`utils/mounted-repositories.js`). A pull never writes
460
+ * into a mount, so this is where a person hears that one is behind, and a push or publish stops
461
+ * on one that is not current (`backend/mounts-before-sending.js`).
462
+ */
463
+ async function mountChecks(mounts, { offline }) {
464
+ if (!mounts.length) return { checks: [], proposals: [] }
465
+ const proposals = []
466
+ const rows = []
467
+ const lines = []
468
+ let attention = 0
469
+ let unknown = 0
470
+ let blocking = false
471
+ for (const m of mounts) {
472
+ const name = mountName(m)
473
+ const where = m.submodule?.path ?? m.dir
474
+ const label = m.follows?.label ?? null
475
+ const recorded = short(m.submodule?.recorded)
476
+ const said = []
477
+ let stuck = false // a push stops on it
478
+ let takes = false // `refresh` takes it
479
+ let needs = false // anything said but "could not ask"
480
+ let asked = false
481
+ if (m.pin === 'missing') {
482
+ said.push(`${name} is a submodule that is not checked out.`)
483
+ stuck = takes = needs = true
484
+ } else if (m.pin === 'behind') {
485
+ said.push(`${name} is checked out at ${short(m.head)}, behind the ${recorded} this repository records — a \`git pull\` moved it, and the checkout stayed.`)
486
+ stuck = takes = needs = true
487
+ } else if (m.pin === 'ahead') {
488
+ said.push(`${name} is checked out at ${short(m.head)}, ahead of the ${recorded} this repository records.`)
489
+ stuck = needs = true
490
+ proposals.push({ step: 'commit', command: null, why: `commit ${where} at ${short(m.head)} here: \`git commit -m "<what changed>" -- ${where}\`, or push with --commit`, ask: true })
491
+ } else if (m.pin === 'diverged') {
492
+ said.push(`${name} is checked out at ${short(m.head)}, which is not on the line of the ${recorded} this repository records.`)
493
+ stuck = needs = true
494
+ }
495
+ if (m.edits.length) {
496
+ said.push(`${name} has ${count(m.edits.length, 'uncommitted change')}, which a push would send as ${m.edits.length === 1 ? 'it is' : 'they are'}.`)
497
+ stuck = needs = true
498
+ proposals.push({ step: 'commit', command: null, why: `commit or discard the ${count(m.edits.length, 'change')} in ${where}, whose pages a push sends as they are on disk`, ask: true })
499
+ }
500
+ let s = null
501
+ let branch = m.follows?.branch ?? null
502
+ if (!offline && m.top && m.follows) {
503
+ const answer = await askRemote(m)
504
+ if (!answer) {
505
+ said.push(`${name}: could not ask ${label} for newer commits — no network, or it needs a sign-in.`)
506
+ unknown++
507
+ } else {
508
+ asked = true
509
+ branch = answer.branch
510
+ s = standing(m, answer.tip)
511
+ const on = branch ? ` on ${branch}` : ''
512
+ if (s === 'newer' || s === 'unheld') {
513
+ said.push(`${name}: ${label} has newer commits${on}.`)
514
+ takes = needs = true
515
+ // A commit not held here can only be read once fetched; in a whole repository it changes the folder.
516
+ if (s === 'newer' || !m.prefix) stuck = true
517
+ } else if (s === 'ahead') {
518
+ said.push(`${name} has commits ${label} does not — push them there, so the rest of your team can take them.`)
519
+ needs = true
520
+ proposals.push({ step: 'gitpush', command: null, why: `push the commits in ${where} to ${label}`, ask: true })
521
+ } else if (s === 'diverged') {
522
+ const pinned = m.submodule ? `, or name the branch it follows in .gitmodules (\`submodule.${m.submodule.name ?? m.submodule.path}.branch\`)` : ''
523
+ said.push(`${name} and ${label}${on} have each moved — bring them together there${pinned}.`)
524
+ stuck = needs = true
525
+ }
526
+ }
527
+ }
528
+ if (takes) proposals.push({ step: 'refresh', command: 'npx uniweb refresh', why: `take the latest of ${name}` })
529
+ if (!said.length) {
530
+ said.push(
531
+ !m.follows
532
+ ? `${name} has no remote, so there is nothing newer to take.`
533
+ : asked
534
+ ? `${name} is at the latest of ${label}${branch ? ` (${branch})` : ''}.`
535
+ : `${name} is at ${short(m.head)}${m.pin === 'same' ? ', the commit this repository records' : ''}; ${label} was not asked (--offline).`
536
+ )
537
+ }
538
+ if (needs) attention++
539
+ if (stuck) blocking = true
540
+ lines.push(...said)
541
+ rows.push({
542
+ segment: m.segment,
543
+ dir: m.dir,
544
+ submodule: m.submodule?.path ?? null,
545
+ head: m.head,
546
+ recorded: m.submodule?.recorded ?? null,
547
+ pin: m.pin,
548
+ edits: m.edits.length,
549
+ remote: label,
550
+ branch,
551
+ standing: s
552
+ })
553
+ }
554
+ const several = mounts.length > 1
555
+ const state = attention ? 'attention' : unknown ? 'unknown' : 'ok'
556
+ return {
557
+ checks: [
558
+ {
559
+ id: 'git.mounts',
560
+ state,
561
+ summary: several
562
+ ? `${count(mounts.length, 'page folder')} come from repositories of their own${attention ? `: ${attention} ${attention === 1 ? 'needs' : 'need'} attention.` : '.'}`
563
+ : lines[0],
564
+ lines: several ? lines : lines.slice(1),
565
+ ...(blocking ? { blocks: ['push', 'publish'] } : {}),
566
+ detail: { mounts: rows }
567
+ }
568
+ ],
569
+ proposals
570
+ }
571
+ }
572
+
451
573
  /**
452
574
  * The session for `origin`, read and never asked for: UNIWEB_TOKEN, else the stored one.
453
575
  * @returns {Promise<{ token: string, handle: string|null } | { expired: true } | null>}
@@ -1667,9 +1789,14 @@ export async function status(args = []) {
1667
1789
  // helpers say on the way goes to stderr.
1668
1790
  const saved = { log: console.log, info: console.info, warn: console.warn }
1669
1791
  if (json) console.log = console.info = console.warn = (...a) => console.error(...a)
1670
- let project, git, app, version, health, dev, deploys, services
1792
+ let project, git, mounted, app, version, health, dev, deploys, services
1671
1793
  try {
1672
- ;[project, git] = await Promise.all([projectChecks(siteDir, siteYml), gitChecks(siteDir, { offline, origin })])
1794
+ const mounts = await mountedRepositories(siteDir)
1795
+ ;[project, git, mounted] = await Promise.all([
1796
+ projectChecks(siteDir, siteYml),
1797
+ gitChecks(siteDir, { offline, origin, mounts }),
1798
+ mountChecks(mounts, { offline })
1799
+ ])
1673
1800
  ;[app, version, health, dev, deploys] = await Promise.all([
1674
1801
  appChecks(siteDir, siteYml, { offline, args, git }),
1675
1802
  versionCheck(siteDir, { offline }),
@@ -1685,6 +1812,7 @@ export async function status(args = []) {
1685
1812
  const checks = [
1686
1813
  ...project.checks,
1687
1814
  ...git.checks,
1815
+ ...mounted.checks,
1688
1816
  ...app.checks,
1689
1817
  ...deploys.checks,
1690
1818
  ...(workflows ? [workflows] : []),
@@ -1693,7 +1821,7 @@ export async function status(args = []) {
1693
1821
  ...health.checks,
1694
1822
  dev
1695
1823
  ]
1696
- const next = planNext([...git.proposals, ...app.proposals, ...deploys.proposals, ...services.proposals, ...version.proposals, ...health.proposals])
1824
+ const next = planNext([...git.proposals, ...mounted.proposals, ...app.proposals, ...deploys.proposals, ...services.proposals, ...version.proposals, ...health.proposals])
1697
1825
 
1698
1826
  const root = findWorkspaceRoot(siteDir) || siteDir
1699
1827
  const site = relative(root, siteDir) || '.'
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-04T15:46:14.453Z",
3
+ "generatedAt": "2026-11-04T16:56:34.431Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.6.9"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.15.4"
9
+ "version": "1.15.5"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.8"
package/src/index.js CHANGED
@@ -1553,6 +1553,10 @@ ${colors.bright}Options:${colors.reset}
1553
1553
  than yours, release yours above it instead of stopping
1554
1554
  --commit In a git repository, commit the site's content first
1555
1555
  (-m <message>) — a publish there sends only what is committed
1556
+ --mounts-as-is Send the page folders mounted from other repositories as they
1557
+ are. Without it, a publish stops on one that is not current —
1558
+ behind its remote, or not committed — and \`uniweb refresh\`
1559
+ takes its latest (interactive, it offers to)
1556
1560
  --no-save Do not record this deploy in deploy.yml
1557
1561
  --no-validate Skip the content-conformance check, which stops a publish
1558
1562
  whose content does not conform to its data schemas
@@ -2041,6 +2045,8 @@ merge those changes with yours, then push again.
2041
2045
 
2042
2046
  ${colors.bright}Options:${colors.reset}
2043
2047
  --commit In a git repository, commit the site's content first (-m <message>)
2048
+ --mounts-as-is Send page folders mounted from other repositories as they are,
2049
+ even when one is behind its remote or not committed
2044
2050
  --dry-run Report what would be sent; send nothing
2045
2051
  -o <file> Write what would be sent to a file; send nothing
2046
2052
  --all Send everything, not only what changed
@@ -2171,17 +2177,21 @@ ${colors.cyan}${colors.bright}uniweb refresh${colors.reset} ${colors.dim}— Cat
2171
2177
  ${colors.bright}Usage:${colors.reset}
2172
2178
  uniweb refresh [options]
2173
2179
 
2174
- A developer on a synced site has TWO external sources: the git remote (teammates'
2175
- commits) and the backend (content authors' edits in the app). Run only \`git pull\`
2176
- and you miss every app edit; run only \`uniweb pull\` and you miss your teammates.
2177
- This does both — git first (merging, never rebasing), then \`uniweb pull\`, which in
2178
- a repository merges the backend's content with yours.
2180
+ A developer on a synced site has separate external sources: the git remote
2181
+ (teammates' commits), the backend (content authors' edits in the app), and any
2182
+ repository the site mounts a page folder from. Run only \`git pull\` and you miss
2183
+ every app edit; run only \`uniweb pull\` and you miss your teammates. This does all
2184
+ of them — git first (merging, never rebasing), then each mounted repository, taken
2185
+ to the latest of the branch it follows (a submodule's new pin committed on its
2186
+ own), then \`uniweb pull\`, which in a repository merges the backend's content with
2187
+ yours.
2179
2188
 
2180
2189
  ${colors.bright}READ-ONLY.${colors.reset} It never pushes and cannot ship anything, so it is safe to run
2181
2190
  reflexively. Exits non-zero if a merge leaves conflicts.
2182
2191
 
2183
2192
  ${colors.bright}Options:${colors.reset}
2184
- --no-git Skip the git remote; backend only
2193
+ --no-git Skip every git remote, the mounted repositories' too; backend only
2194
+ --no-mounts Leave the mounted repositories where they are
2185
2195
  --no-backend Skip the backend; git only
2186
2196
 
2187
2197
  \`--force\` is NOT accepted here: this verb builds the delegated pull's arguments
@@ -2444,6 +2454,7 @@ ${colors.bright}Push Options:${colors.reset}
2444
2454
  --force Overwrite upstream changes (drop the staleness gate)
2445
2455
  --commit In a git repository, commit the site's content first (-m <message>);
2446
2456
  a push there sends only what is committed
2457
+ --mounts-as-is Send page folders mounted from other repositories as they are
2447
2458
  --all Send every record (bypass the changed-only cache)
2448
2459
  --org @org Work in @org for this push, not your login's workspace
2449
2460
  --personal Work in your personal workspace for this push
@@ -69,7 +69,9 @@ const VERBS = {
69
69
  // release above a newer registered version instead of stopping (both bring-along)
70
70
  '--no-release', '--bump',
71
71
  // commit the site's content first, with this message (backend/site-sync.js)
72
- '--commit', '-m', '--message', ...VIA_DEPLOY
72
+ '--commit', '-m', '--message',
73
+ // send the folders mounted from other repositories as they are (backend/mounts-before-sending.js)
74
+ '--mounts-as-is', ...VIA_DEPLOY
73
75
  ],
74
76
  publish: [
75
77
  '--org', '--dry-run', '--force', '--foundation',
@@ -77,7 +79,7 @@ const VERBS = {
77
79
  // read in utils/conformance.js, backend/site-sync.js, and
78
80
  // backend/foundation-bring-along.js — none appear in publish.js
79
81
  '--no-validate', '--yes', '--no-verify', '--no-release', '--bump',
80
- '--commit', '-m', '--message', ...VIA_DEPLOY
82
+ '--commit', '-m', '--message', '--mounts-as-is', ...VIA_DEPLOY
81
83
  ],
82
84
  pull: [
83
85
  '--content-only', '--dry-run', '--force',
@@ -132,7 +134,7 @@ const VERBS = {
132
134
  * the VIA_DEPLOY note above, and required by `flag-guard-coverage.test.js`.
133
135
  */
134
136
  refresh: [
135
- '--no-backend', '--no-git',
137
+ '--no-backend', '--no-git', '--no-mounts',
136
138
  '--org', '--personal', '--dry-run', '--no-validate', '--yes', ...VIA_DEPLOY
137
139
  ],
138
140
  /**
package/src/utils/git.js CHANGED
@@ -233,35 +233,42 @@ export function aheadBehind(dir) {
233
233
  }
234
234
 
235
235
  /**
236
- * Does the git remote hold commits HEAD does not — teammates' work since the last fetch?
237
- * Asked with `git ls-remote`, which fetches nothing and writes nothing, so a read-only
238
- * command can ask it.
236
+ * The environment for a git call that asks a remote and must never wait on a person.
239
237
  *
240
238
  * ⛔ IT NEVER PROMPTS. A credential prompt would hang a command run by an agent, so: no
241
239
  * terminal prompt (`GIT_TERMINAL_PROMPT=0`), no credential manager window
242
240
  * (`GCM_INTERACTIVE=never`), ssh in batch mode with a connect timeout — added to the ssh
243
- * command the person configured, never instead of it — and the whole call bounded.
244
- *
245
- * @param {string} dir
246
- * @param {{ timeoutMs?: number }} [opts]
247
- * @returns {Promise<{ moved: boolean, upstream: object } | null>} null when there is no
248
- * upstream, or the remote did not answer in time
241
+ * command the person configured, never instead of it. The caller bounds the call itself.
249
242
  */
250
- export async function remoteMoved(dir, { timeoutMs = 5000 } = {}) {
251
- const upstream = upstreamOf(dir)
252
- if (!upstream) return null
243
+ export function quietGitEnv(dir, timeoutMs = 5000) {
253
244
  let ssh = process.env.GIT_SSH_COMMAND || ''
254
245
  try {
255
246
  ssh ||= git(['config', '--get', 'core.sshCommand'], dir).trim()
256
247
  } catch {
257
248
  // not configured
258
249
  }
259
- const env = {
250
+ return {
260
251
  ...process.env,
261
252
  GIT_TERMINAL_PROMPT: '0',
262
253
  GCM_INTERACTIVE: 'never',
263
254
  GIT_SSH_COMMAND: `${ssh || 'ssh'} -o BatchMode=yes -o ConnectTimeout=${Math.ceil(timeoutMs / 1000)}`
264
255
  }
256
+ }
257
+
258
+ /**
259
+ * Does the git remote hold commits HEAD does not — teammates' work since the last fetch?
260
+ * Asked with `git ls-remote`, which fetches nothing and writes nothing, so a read-only
261
+ * command can ask it — without a prompt, and bounded (`quietGitEnv`).
262
+ *
263
+ * @param {string} dir
264
+ * @param {{ timeoutMs?: number }} [opts]
265
+ * @returns {Promise<{ moved: boolean, upstream: object } | null>} null when there is no
266
+ * upstream, or the remote did not answer in time
267
+ */
268
+ export async function remoteMoved(dir, { timeoutMs = 5000 } = {}) {
269
+ const upstream = upstreamOf(dir)
270
+ if (!upstream) return null
271
+ const env = quietGitEnv(dir, timeoutMs)
265
272
  let out
266
273
  try {
267
274
  out = await new Promise((resolve, reject) => {
@@ -0,0 +1,403 @@
1
+ /**
2
+ * The page folders a site mounts from a repository of their own, and where each one stands.
3
+ *
4
+ * A site takes a folder of pages from elsewhere with `paths: { pages/<segment>: <dir> }`, and a
5
+ * build or a push reads that folder as it is on disk. When the folder is its own git repository
6
+ * (a submodule of the site's, or a clone beside it), nothing else keeps it current. A `git pull`
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
9
+ * newer docs, a pull here takes nothing and the next push puts the older ones back. So `status`
10
+ * says where each one stands, `refresh` takes its latest, and a push or publish stops before
11
+ * sending one that is not current (`backend/mounts-before-sending.js`).
12
+ *
13
+ * ⭐ ITS LATEST IS THE TIP OF THE BRANCH IT FOLLOWS: for a submodule, the branch `.gitmodules`
14
+ * names for it (git's own `submodule.<name>.branch`), else its remote's default branch
15
+ * [Diego, 2026-11-04: "I imagine that it means the remote's default branch"]; for a clone on a
16
+ * branch, that branch's upstream.
17
+ *
18
+ * ⭐ WHAT IS COMPARED IS THE MOUNTED FOLDER. A mount can be one folder of a larger repository
19
+ * (`external/tool/docs`), so a commit that leaves the folder as it was is nothing to take.
20
+ *
21
+ * ⛔ NOTHING HERE WAITS ON A PERSON. A remote is asked under `quietGitEnv` and a time limit, as
22
+ * `remoteMoved` asks the site's own; one that does not answer is said, never waited on.
23
+ */
24
+
25
+ import { execFile, execFileSync } from 'node:child_process'
26
+ import { existsSync, readFileSync } from 'node:fs'
27
+ import { join, relative, resolve, sep } from 'node:path'
28
+ import yaml from 'js-yaml'
29
+ import { repoOf } from './sync-point.js'
30
+ import { quietGitEnv, upstreamOf } from './git.js'
31
+
32
+ const run = (cwd, args, opts = {}) =>
33
+ execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts })
34
+
35
+ function text(cwd, args, opts) {
36
+ try {
37
+ return run(cwd, args, opts).trim()
38
+ } catch {
39
+ return null
40
+ }
41
+ }
42
+
43
+ /** The same call, bounded and asking nothing of a person: for a remote. */
44
+ function remoteCall(cwd, args, timeoutMs) {
45
+ return new Promise((done, fail) =>
46
+ execFile('git', args, { cwd, env: quietGitEnv(cwd, timeoutMs), timeout: timeoutMs, encoding: 'utf8' }, (err, stdout) =>
47
+ err ? fail(err) : done(String(stdout))
48
+ )
49
+ )
50
+ }
51
+
52
+ /** true, false, or null when git cannot say (a commit it does not hold). */
53
+ function ancestor(cwd, a, b) {
54
+ try {
55
+ run(cwd, ['merge-base', '--is-ancestor', a, b])
56
+ return true
57
+ } catch (err) {
58
+ return err?.status === 1 ? false : null
59
+ }
60
+ }
61
+
62
+ const holds = (cwd, sha) => text(cwd, ['cat-file', '-e', `${sha}^{commit}`]) !== null
63
+
64
+ /** Does the mounted folder read the same at both commits? null when git cannot say. */
65
+ function sameFolder(cwd, a, b, prefix) {
66
+ try {
67
+ run(cwd, ['diff', '--quiet', a, b, '--', prefix || '.'])
68
+ return true
69
+ } catch (err) {
70
+ return err?.status === 1 ? false : null
71
+ }
72
+ }
73
+
74
+ const slash = (p) => p.split(sep).join('/')
75
+ export const short = (sha) => (sha ? sha.slice(0, 7) : '')
76
+ const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
77
+
78
+ /** What git said when it failed, or the fallback. */
79
+ function gitError(err, fallback) {
80
+ const said = [err?.stderr, err?.stdout].map((b) => (b ? String(b).trim() : '')).filter(Boolean).join('\n')
81
+ return said || err?.message || fallback
82
+ }
83
+
84
+ /** `github.com/uniweb/docs`, for the ways a remote's address is written; anything else as it is. */
85
+ export function remoteLabel(url) {
86
+ if (!url) return null
87
+ const s = String(url).trim()
88
+ const scp = s.match(/^[\w.-]+@([^:/]+):(.+?)(?:\.git)?\/?$/)
89
+ if (scp) return `${scp[1]}/${scp[2]}`
90
+ try {
91
+ const u = new URL(s)
92
+ if (!/^(https?|ssh|git):$/.test(u.protocol)) return s
93
+ return `${u.host}${u.pathname.replace(/\.git\/?$/, '').replace(/\/$/, '')}`
94
+ } catch {
95
+ return s
96
+ }
97
+ }
98
+
99
+ /** The submodule of the site's repository holding `abs` — `{ path, recorded }` — or null. */
100
+ function submoduleHolding(siteTop, abs) {
101
+ const rel = slash(relative(siteTop, abs))
102
+ if (!rel || rel === '..' || rel.startsWith('../')) return null
103
+ const candidates = []
104
+ for (let p = rel; p; p = p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '') candidates.push(p)
105
+ const out = text(siteTop, ['ls-tree', '-z', 'HEAD', '--', ...candidates])
106
+ if (!out) return null
107
+ for (const entry of out.split('\0')) {
108
+ const m = entry.match(/^160000 commit ([0-9a-f]+)\t(.+)$/)
109
+ if (m && candidates.includes(m[2])) return { path: m[2], recorded: m[1] }
110
+ }
111
+ return null
112
+ }
113
+
114
+ /** The submodule's name in `.gitmodules`, and the branch it is told to follow there. */
115
+ function gitmodulesEntry(siteTop, path) {
116
+ const out = text(siteTop, ['config', '-f', '.gitmodules', '--get-regexp', '^submodule\\..*\\.path$'])
117
+ for (const line of (out || '').split('\n')) {
118
+ const at = line.indexOf(' ')
119
+ if (at === -1 || line.slice(at + 1) !== path) continue
120
+ const name = line.slice('submodule.'.length, at - '.path'.length)
121
+ let branch = text(siteTop, ['config', '-f', '.gitmodules', '--get', `submodule.${name}.branch`]) || null
122
+ // `.` is git's "the branch the superproject is on".
123
+ if (branch === '.') branch = text(siteTop, ['symbolic-ref', '--short', '-q', 'HEAD']) || null
124
+ return { name, branch }
125
+ }
126
+ return { name: null, branch: null }
127
+ }
128
+
129
+ /** The remote a checkout takes from: its branch's upstream, else `origin`, else its only one. */
130
+ function remoteOf(top) {
131
+ const up = upstreamOf(top)
132
+ if (up) return { name: up.remote, branch: up.merge.replace(/^refs\/heads\//, ''), upstream: true }
133
+ const names = (text(top, ['remote']) || '').split('\n').filter(Boolean)
134
+ const name = names.includes('origin') ? 'origin' : names[0]
135
+ return name ? { name, branch: null, upstream: false } : null
136
+ }
137
+
138
+ /**
139
+ * Each page folder the site mounts that is a repository of its own, with what this machine
140
+ * knows of it: nothing is asked of a remote (`askRemote` does that).
141
+ *
142
+ * @returns {Promise<Array<{
143
+ * segment: string, dir: string, abs: string, siteTop: string|null, top: string|null,
144
+ * prefix: string, head: string|null, edits: string[],
145
+ * submodule: { path: string, recorded: string, name: string|null } | null,
146
+ * pin: 'same'|'behind'|'ahead'|'diverged'|'missing'|null,
147
+ * follows: { remote: string, branch: string|null, upstream: boolean, label: string|null } | null
148
+ * }>>} `pin` compares a submodule's checkout with the commit the site's repository records,
149
+ * and is null for a clone the site's repository does not record.
150
+ */
151
+ export async function mountedRepositories(siteDir) {
152
+ let paths = null
153
+ try {
154
+ paths = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))?.paths ?? null
155
+ } catch {
156
+ return []
157
+ }
158
+ const { mountEntriesOf } = await import('@uniweb/build/site')
159
+ const entries = mountEntriesOf(paths)
160
+ if (!entries.length) return []
161
+ const site = repoOf(siteDir)
162
+ const out = []
163
+ for (const [segment, dir] of entries) {
164
+ const abs = resolve(siteDir, String(dir))
165
+ const sub = site?.head ? submoduleHolding(site.top, abs) : null
166
+ const own = existsSync(abs) ? repoOf(abs) : null
167
+ // A submodule never checked out is an empty folder of the site's own repository.
168
+ const top = own && own.top !== site?.top ? own.top : null
169
+ // In the site's own repository, or in none: the site's own git says all there is.
170
+ if (!sub && !top) continue
171
+ const prefix = slash(relative(top ?? join(site.top, sub.path), abs))
172
+ const head = top ? text(top, ['rev-parse', 'HEAD']) : null
173
+ let edits = []
174
+ if (top) {
175
+ try {
176
+ edits = run(top, ['status', '--porcelain', '--', prefix || '.']).split('\n').filter(Boolean)
177
+ } catch {
178
+ edits = []
179
+ }
180
+ }
181
+ const entry = sub ? gitmodulesEntry(site.top, sub.path) : null
182
+ let pin = null
183
+ if (sub) {
184
+ if (!top || !head) pin = 'missing'
185
+ else if (head === sub.recorded) pin = 'same'
186
+ else if (!holds(top, sub.recorded)) pin = 'behind'
187
+ else if (sameFolder(top, head, sub.recorded, prefix)) pin = 'same'
188
+ else if (ancestor(top, head, sub.recorded)) pin = 'behind'
189
+ else if (ancestor(top, sub.recorded, head)) pin = 'ahead'
190
+ else pin = 'diverged'
191
+ }
192
+ const remote = top ? remoteOf(top) : null
193
+ const follows = remote
194
+ ? {
195
+ remote: remote.name,
196
+ // A submodule follows what `.gitmodules` says, whatever branch its checkout is on.
197
+ branch: sub ? entry.branch : remote.upstream ? remote.branch : null,
198
+ upstream: !sub && remote.upstream,
199
+ label: remoteLabel(text(top, ['remote', 'get-url', remote.name])) ?? remote.name
200
+ }
201
+ : null
202
+ out.push({
203
+ segment,
204
+ dir: String(dir),
205
+ abs,
206
+ siteTop: site?.top ?? null,
207
+ top,
208
+ prefix,
209
+ head,
210
+ edits,
211
+ submodule: sub ? { path: sub.path, recorded: sub.recorded, name: entry.name } : null,
212
+ pin,
213
+ follows
214
+ })
215
+ }
216
+ return out
217
+ }
218
+
219
+ /**
220
+ * The tip of the branch a mount follows, asked of its remote with `git ls-remote`, which fetches
221
+ * nothing and writes nothing: `{ branch, tip }`, or null when it has no remote or no answer came.
222
+ */
223
+ export async function askRemote(m, { timeoutMs = 5000 } = {}) {
224
+ if (!m.top || !m.follows) return null
225
+ const { remote, branch } = m.follows
226
+ let out
227
+ try {
228
+ out = await remoteCall(
229
+ m.top,
230
+ branch ? ['ls-remote', '--', remote, `refs/heads/${branch}`] : ['ls-remote', '--symref', '--', remote, 'HEAD'],
231
+ timeoutMs
232
+ )
233
+ } catch {
234
+ return null
235
+ }
236
+ const lines = out.split('\n').map((line) => line.split('\t'))
237
+ if (branch) {
238
+ const tip = lines.find(([, ref]) => ref === `refs/heads/${branch}`)?.[0]
239
+ return tip ? { branch, tip } : null
240
+ }
241
+ const symref = lines.find(([a, ref]) => a.startsWith('ref: ') && ref === 'HEAD')
242
+ const tip = lines.find(([a, ref]) => a && !a.startsWith('ref: ') && ref === 'HEAD')?.[0]
243
+ return tip ? { branch: symref ? symref[0].replace(/^ref: refs\/heads\//, '') : null, tip } : null
244
+ }
245
+
246
+ /**
247
+ * Where a mount's checkout stands against the tip its remote answered:
248
+ * - `current`: at it, or the mounted folder reads the same there;
249
+ * - `newer`: the remote has commits that change the folder, and the checkout is on their line;
250
+ * - `ahead`: the checkout has commits the remote lacks;
251
+ * - `diverged`: each has commits the other lacks;
252
+ * - `unheld`: the tip is not here yet, so only a fetch can say whether it changes the folder.
253
+ */
254
+ export function standing(m, tip) {
255
+ if (!m.head || !tip) return null
256
+ if (tip === m.head) return 'current'
257
+ if (!holds(m.top, tip)) return 'unheld'
258
+ if (ancestor(m.top, tip, m.head)) return 'ahead'
259
+ if (sameFolder(m.top, m.head, tip, m.prefix)) return 'current'
260
+ if (ancestor(m.top, m.head, tip)) return 'newer'
261
+ return 'diverged'
262
+ }
263
+
264
+ /** Fetch a branch's tip into the mount's repository: objects and a remote-tracking ref, never its checkout. */
265
+ export async function fetchTip(m, branch, { timeoutMs = 60_000 } = {}) {
266
+ if (!m.top || !m.follows || !branch) return false
267
+ try {
268
+ await remoteCall(m.top, ['fetch', '--quiet', m.follows.remote, `refs/heads/${branch}`], timeoutMs)
269
+ return true
270
+ } catch {
271
+ return false
272
+ }
273
+ }
274
+
275
+ /** The site's folder as its repository names it, for a commit message: `uniweb-io/site`, or `.`. */
276
+ function siteName(siteDir) {
277
+ const repo = repoOf(siteDir)
278
+ return repo?.path ?? '.'
279
+ }
280
+
281
+ /**
282
+ * Bring one mount to its latest. A submodule goes first to the commit the site's repository
283
+ * records (checked out if it never was), then to the tip of the branch it follows, with that pin
284
+ * committed on its own; a clone on a branch is fast-forwarded to its upstream. Never over
285
+ * uncommitted changes in it, never backwards, and never from a commit the branch does not
286
+ * contain, which is a pin put somewhere else on purpose.
287
+ *
288
+ * @param {string} siteDir
289
+ * @param {object} m - from `mountedRepositories`
290
+ * @returns {Promise<{ from: string|null, to: string|null, branch: string|null, commits: number|null,
291
+ * committed: string|null, left: string|null, kind: 'edits'|'no-remote'|'no-answer'|'ahead'|'off-branch'|null,
292
+ * error: string|null }>} `left` says why it stayed where it was, and `kind` names that reason;
293
+ * `error`, what failed
294
+ */
295
+ export async function takeLatest(siteDir, m) {
296
+ const r = { from: m.head, to: m.head, branch: null, commits: null, committed: null, left: null, kind: null, error: null }
297
+ if (m.edits.length) return { ...r, left: `it has ${plural(m.edits.length, 'uncommitted change')}`, kind: 'edits' }
298
+ let cur = m
299
+ if (m.submodule && (m.pin === 'missing' || m.pin === 'behind')) {
300
+ try {
301
+ run(m.siteTop, ['submodule', 'update', '--init', '--', m.submodule.path], {
302
+ env: quietGitEnv(m.siteTop, 120_000),
303
+ timeout: 120_000
304
+ })
305
+ } catch (err) {
306
+ return { ...r, error: gitError(err, 'git submodule update failed') }
307
+ }
308
+ cur = (await mountedRepositories(siteDir)).find((x) => x.segment === m.segment) ?? m
309
+ r.to = cur.head
310
+ }
311
+ if (!cur.top || !cur.follows) return { ...r, left: 'it has no remote to take from', kind: 'no-remote' }
312
+ const answer = await askRemote(cur)
313
+ const label = cur.follows.label
314
+ if (!answer) return { ...r, left: `${label} did not answer`, kind: 'no-answer' }
315
+ r.branch = answer.branch
316
+ if (answer.tip === cur.head) return r
317
+ if (!holds(cur.top, answer.tip) && !(await fetchTip(cur, answer.branch))) {
318
+ return { ...r, error: `could not fetch ${answer.branch ?? 'its branch'} from ${label}` }
319
+ }
320
+ if (ancestor(cur.top, answer.tip, cur.head)) return { ...r, left: `it has commits ${label} does not`, kind: 'ahead' }
321
+ let contained = ancestor(cur.top, cur.head, answer.tip)
322
+ // ⭐ A shallow clone holds the branch's recent commits cut off from their past, so the branch
323
+ // can look as if it does not contain the checkout. Only that past can say.
324
+ if (contained !== true && text(cur.top, ['rev-parse', '--is-shallow-repository']) === 'true') {
325
+ try {
326
+ await remoteCall(cur.top, ['fetch', '--quiet', '--unshallow', cur.follows.remote], 300_000)
327
+ } catch (err) {
328
+ return { ...r, error: gitError(err, `could not fetch the history of ${label}`) }
329
+ }
330
+ contained = ancestor(cur.top, cur.head, answer.tip)
331
+ }
332
+ if (contained !== true) return { ...r, left: `${short(cur.head)} is not on ${answer.branch ?? 'its branch'}`, kind: 'off-branch' }
333
+ try {
334
+ if (cur.follows.upstream) run(cur.top, ['merge', '--ff-only', '--quiet', answer.tip])
335
+ else run(cur.top, ['checkout', '--quiet', '--detach', answer.tip])
336
+ } catch (err) {
337
+ return { ...r, error: gitError(err, 'git could not move it') }
338
+ }
339
+ r.to = answer.tip
340
+ const n = Number(text(cur.top, ['rev-list', '--count', `${cur.head}..${answer.tip}`]))
341
+ r.commits = Number.isInteger(n) ? n : null
342
+ if (cur.submodule) {
343
+ const message = `${siteName(siteDir)}: pages/${cur.segment} from ${cur.submodule.path} at ${short(answer.tip)}, the latest of ${label}`
344
+ try {
345
+ run(cur.siteTop, ['commit', '-q', '-m', message, '--', cur.submodule.path])
346
+ r.committed = text(cur.siteTop, ['rev-parse', 'HEAD'])
347
+ } catch (err) {
348
+ r.error = `it moved, and its new pin is not committed: ${gitError(err, 'git commit failed')}`
349
+ }
350
+ }
351
+ return r
352
+ }
353
+
354
+ /**
355
+ * Commit a submodule's checkout as its pin, on its own: what a push sends from the folder is then
356
+ * what the site's commit records. `{ commit }`, or `{ error }`.
357
+ */
358
+ export function commitPin(siteDir, m) {
359
+ const message = `${siteName(siteDir)}: pages/${m.segment} from ${m.submodule.path} at ${short(m.head)}`
360
+ try {
361
+ run(m.siteTop, ['commit', '-q', '-m', message, '--', m.submodule.path])
362
+ return { commit: text(m.siteTop, ['rev-parse', 'HEAD']) }
363
+ } catch (err) {
364
+ return { error: gitError(err, 'git commit failed') }
365
+ }
366
+ }
367
+
368
+ /**
369
+ * A line for each mount `refresh` would bring forward: not checked out, behind the commit the
370
+ * site's repository records, or behind the branch it follows. For a verb that has just left
371
+ * mounted pages as their files hold them (`pull`), where the person would otherwise read that
372
+ * as current.
373
+ */
374
+ export async function behindLines(siteDir) {
375
+ const out = []
376
+ for (const m of await mountedRepositories(siteDir)) {
377
+ const name = mountName(m)
378
+ if (m.pin === 'missing' || m.pin === 'behind') {
379
+ out.push(`${name} is behind the commit this repository records: \`npx uniweb refresh\` takes it.`)
380
+ continue
381
+ }
382
+ if (!m.follows || m.edits.length) continue
383
+ const answer = await askRemote(m)
384
+ const s = answer ? standing(m, answer.tip) : null
385
+ if (s === 'newer' || s === 'unheld') out.push(`${name}: ${m.follows.label} has newer commits, which \`npx uniweb refresh\` takes.`)
386
+ }
387
+ return out
388
+ }
389
+
390
+ /** `pages/docs ← external/docs`: the mount, by the path its repository goes by. */
391
+ export function mountName(m) {
392
+ return `pages/${m.segment} ← ${m.submodule?.path ?? m.dir}`
393
+ }
394
+
395
+ /** One line for what `takeLatest` did. */
396
+ export function describeTaken(m, r) {
397
+ const name = mountName(m)
398
+ if (r.error) return `${name}: ${r.error}`
399
+ if (r.left) return `${name}: left at ${short(r.to)}, since ${r.left}.`
400
+ if (r.from === r.to) return `${name}: at the latest of ${m.follows?.label ?? 'its remote'}${r.branch ? ` (${r.branch})` : ''}.`
401
+ const moved = `${short(r.from) || 'not checked out'} → ${short(r.to)}${r.commits != null ? ` (${plural(r.commits, 'commit')})` : ''}`
402
+ return `${name}: ${moved}${r.committed ? `, committed as ${short(r.committed)}` : ''}.`
403
+ }
@@ -27,6 +27,12 @@ const ORDER = ['login', 'conflicts', 'merge', 'refresh', 'pull', 'commit', 'push
27
27
  */
28
28
  export function planNext(proposals) {
29
29
  const steps = [...proposals]
30
+ // One `refresh` takes the teammates' commits and every mount's latest: one step, its reasons joined.
31
+ const refreshes = steps.filter((p) => p.step === 'refresh')
32
+ if (refreshes.length > 1) {
33
+ refreshes[0].why = refreshes.map((p) => p.why).join(', and ')
34
+ for (const p of refreshes.slice(1)) steps.splice(steps.indexOf(p), 1)
35
+ }
30
36
  // `refresh` is `git pull`, then the same pull: it takes the app's changes too.
31
37
  const refresh = steps.find((p) => p.step === 'refresh')
32
38
  const pull = steps.find((p) => p.step === 'pull')