uniweb 1.34.9 → 1.34.11

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.34.9",
3
+ "version": "1.34.11",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -41,9 +41,9 @@
41
41
  "js-yaml": "^4.3.2",
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
- "@uniweb/schemas": "~1.7.4",
45
44
  "@uniweb/content-writer": "~1.3.2",
46
45
  "@uniweb/core": "~1.6.13",
46
+ "@uniweb/schemas": "~1.7.4",
47
47
  "@uniweb/semantic-parser": "~1.13.5"
48
48
  },
49
49
  "peerDependencies": {
@@ -99,7 +99,7 @@ npx uniweb@latest update --yes # align @uniweb/* deps AND refresh AGENTS.
99
99
 
100
100
  When `status` names a newer release, take it: update, restart any running dev server, build, look at the pages, commit what changed. A foundation is a federated ES module that links to the runtime at load time, like a shared library: the contract between them is stable across releases, and the runtime version a foundation was built against is a floor, not a pin. A hosted site moves forward when it is republished, to a runtime at or above its foundation's floor. The docs describe the latest release; a project that is behind should move, not be documented as it is. A **patch** brings fixes and features; a **minor** is where breaking changes go (`update` lists each package crossing one — build and check before shipping); a **major** is for something big. Dependencies are tilde ranges (`~1.0.1`), so `pnpm install` never crosses a minor on its own.
101
101
 
102
- **Write `@latest`.** In a project, `uniweb` resolves to the copy in your own `node_modules`, pinned by your own `package.json`; it reconciles against the matrix it already has and correctly reports nothing to do. `pnpm uniweb update` and a stale global install are the same. `@latest` makes it a question about the newest release and bumps the pin. Don't `npm update` / `pnpm update` the `@uniweb/*` packages — a matched set, and it won't refresh AGENTS.md, so the guide silently drifts from the code. `update` won't refresh AGENTS.md while declared deps lag the CLI or edited deps aren't installed. Updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`).
102
+ **Write `@latest`.** In a project, `uniweb` resolves to the copy in your own `node_modules`, pinned by your own `package.json`; it reconciles against the matrix it already has and correctly reports nothing to do. `pnpm uniweb update` and a stale global install are the same. `@latest` makes it a question about the newest release and bumps the pin. Don't `npm update` / `pnpm update` the `@uniweb/*` packages — a matched set, and it won't refresh AGENTS.md, so the guide silently drifts from the code. `update` won't refresh AGENTS.md while declared deps lag the CLI or edited deps aren't installed. After a `git pull` that brings a teammate's update, run it too: the files name the new versions while `node_modules` still holds the old ones, and `update` installs what the lockfile holds. Updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`).
103
103
 
104
104
  `uniweb update` rewrites AGENTS.md each version and keeps only blocks between a `<!-- project-notes:start -->` line and a `<!-- project-notes:end -->` line, which it moves to the end (markers that don't pair leave the file as it is) — keep project conventions in a file of your own (`NOTES.md`) and point to it from that block.
105
105
 
@@ -1422,6 +1422,18 @@ export function writeQueryUuids(siteDir, backend, map) {
1422
1422
  if (!map || !Object.keys(map).length) return
1423
1423
  updateBackendMap(siteDir, backend, 'queries', map)
1424
1424
  }
1425
+ /**
1426
+ * The query declarations' identity, by name, from a document the backend handed back (a pull's site
1427
+ * content, or the one a push stored): written WHOLE, so a query removed in the app leaves with its
1428
+ * `$uuid`. A document that carries no `queries` at all leaves the map as it is.
1429
+ *
1430
+ * ⛔ Until 2026-11-13 it was merged, so a query removed in the app kept its `$uuid`, and a new one of the
1431
+ * same name took it on the next push: the failure `writeFolderPlacements` describes for a folder entry.
1432
+ */
1433
+ export function writeQueryUuidsFrom(siteDir, backend, doc) {
1434
+ if (!Array.isArray(doc?.queries)) return
1435
+ setBackendMap(siteDir, backend, 'queries', collectQueryUuids(doc))
1436
+ }
1425
1437
  // Placements a recovery found missing, beside the ones this copy holds (`recoverRecordsIdentity`).
1426
1438
  export function writeFolderItemUuids(siteDir, backend, map) {
1427
1439
  if (!map || !Object.keys(map).length) return
@@ -1497,6 +1509,24 @@ export function writeItemUuids(siteDir, backend, map) {
1497
1509
  if (!map || !Object.keys(map).length) return
1498
1510
  updateBackendMap(siteDir, backend, 'items', map)
1499
1511
  }
1512
+ /**
1513
+ * The units' identity from a document the backend handed back (a pull's site content, or the one a push
1514
+ * stored), with the paths banked before for a unit it still holds: a page the app moved keeps, beside
1515
+ * its new path, the one its files have, which a push of that page needs while a pull holds it. A unit the
1516
+ * document no longer holds leaves with its `$uuid`.
1517
+ *
1518
+ * ⛔ Until 2026-11-13 each document was merged into the map, so a page or section removed in the app kept
1519
+ * its `$uuid` under its path, and a new one made at that path took it on the next push: the failure
1520
+ * `writeFolderPlacements` describes for a folder entry, where the backend re-created the removed row
1521
+ * under the old id. A document with no units leaves the map as it is.
1522
+ */
1523
+ export function writeItemUuidsFrom(siteDir, backend, doc) {
1524
+ const now = collectUnitUuids(doc)
1525
+ if (!Object.keys(now).length) return
1526
+ const held = new Set(Object.values(now))
1527
+ const kept = Object.entries(readItemUuids(siteDir, backend)).filter(([, uuid]) => held.has(uuid))
1528
+ setBackendMap(siteDir, backend, 'items', { ...Object.fromEntries(kept), ...now })
1529
+ }
1500
1530
 
1501
1531
  /**
1502
1532
  * The identity of each record's list items:
@@ -2897,8 +2927,7 @@ export async function pushSyncPackages({
2897
2927
  // unique. Without it every push after the first re-sends the whole `collections`
2898
2928
  // section uuid-less and is refused.
2899
2929
  if (siteFinalizedDoc) {
2900
- const recordIds = collectQueryUuids(siteFinalizedDoc)
2901
- if (Object.keys(recordIds).length) writeQueryUuids(siteDir, client.origin, recordIds)
2930
+ writeQueryUuidsFrom(siteDir, client.origin, siteFinalizedDoc)
2902
2931
  // ⭐ THE SERVICES THIS COPY NOW HOLDS, `{ name: $uuid }`: those the push stated and
2903
2932
  // those held before, as the site returned them (`heldServices`). A service added on
2904
2933
  // the site since this copy's last pull is left out — held, the next push would state
@@ -2941,9 +2970,10 @@ export async function pushSyncPackages({
2941
2970
  if (Object.keys(patch).length) writeUnitBases(siteDir, client.origin, patch)
2942
2971
  // The backend's post-write document carries `$uuid` per item at every nesting
2943
2972
  // level, so the push that just landed also re-arms identity for the next one.
2944
- // Replaced wholesale: an item that no longer exists must not keep a uuid that
2945
- // would re-target something else.
2946
- if (theirs) writeItemUuids(siteDir, client.origin, collectUnitUuids(theirs))
2973
+ // An item that no longer exists must not keep a uuid that would re-target something
2974
+ // else, so a unit the document no longer holds leaves the map (`writeItemUuidsFrom`).
2975
+ // ⛔ This said "replaced wholesale" while the write merged, and those uuids stayed.
2976
+ if (theirs) writeItemUuidsFrom(siteDir, client.origin, theirs)
2947
2977
  else {
2948
2978
  // ⛔ BANKING IS BEST-EFFORT AND ITS FAILURE USED TO BE SILENT — say it here,
2949
2979
  // because the cost lands two commands away and names something else.
@@ -86,7 +86,6 @@ import {
86
86
  readZip,
87
87
  computeUnitHashes,
88
88
  collectUnitUuids,
89
- collectQueryUuids,
90
89
  documentSchema
91
90
  } from '@uniweb/build/uwx'
92
91
  import {
@@ -100,7 +99,7 @@ import {
100
99
  deploymentFields,
101
100
  entityHashes,
102
101
  rebankSyncHashes,
103
- writeQueryUuids,
102
+ writeQueryUuidsFrom,
104
103
  mergeBaseVersions,
105
104
  writeItemBaseVersions,
106
105
  pulledItemVersions,
@@ -110,7 +109,7 @@ import {
110
109
  writeUnitBases,
111
110
  commitWriteBacks,
112
111
  reportWriteBacks,
113
- writeItemUuids,
112
+ writeItemUuidsFrom,
114
113
  writeFolderPlacements,
115
114
  writeHeldTypes,
116
115
  readItemBaseVersions
@@ -1268,11 +1267,12 @@ export async function pull(args = [], deps = {}) {
1268
1267
  pulledVersions = pulledItemVersions(siteDoc, content.itemVersions)
1269
1268
  // Per-item identity for the next push. Without it the backend reads our
1270
1269
  // records as new and re-mints every page and section row.
1271
- writeItemUuids(projDir, client.origin, collectUnitUuids(siteDoc))
1270
+ // A unit the document no longer holds, removed in the app, leaves with its uuid.
1271
+ writeItemUuidsFrom(projDir, client.origin, siteDoc)
1272
1272
  // The collections section's identity has no file to live in either — same
1273
1273
  // reason, same remedy, keyed by name. A pull is the other route by which a
1274
1274
  // copy can recover it (see readQueryUuids).
1275
- writeQueryUuids(projDir, client.origin, collectQueryUuids(siteDoc))
1275
+ writeQueryUuidsFrom(projDir, client.origin, siteDoc)
1276
1276
  // Bring the media down BEFORE projecting: a newly-landed asset gains a map
1277
1277
  // entry, and the projection reads that map to put authored paths back. Run
1278
1278
  // after, and this pull's new assets would project as URLs and only restore
@@ -1320,7 +1320,7 @@ export async function pull(args = [], deps = {}) {
1320
1320
  // The mounts it may write into, each one the site declares writable (above).
1321
1321
  writableMounts: mounts.writable,
1322
1322
  // Where each page was before this pull, read before its identity merged the pulled document's
1323
- // in (`writeItemUuids`, above): a page the app moved is found where the files keep it.
1323
+ // in (`writeItemUuidsFrom`, above): a page the app moved is found where the files keep it.
1324
1324
  priorItems
1325
1325
  })
1326
1326
  wrote.push(...report.pages, ...report.sections, ...report.layout)
@@ -1530,6 +1530,11 @@ export async function pull(args = [], deps = {}) {
1530
1530
  const syncFile = join(siteDir, 'sync.json')
1531
1531
  const cacheFile = join(siteDir, '.uniweb', 'backend-cache.json')
1532
1532
  const before = { sync: bytesOf(syncFile), cache: bytesOf(cacheFile) }
1533
+ // The files as the person left them, before this pull writes anything back: whether a merge
1534
+ // sets work of theirs aside. ⛔ Until 2026-11-13 it was judged after the write-back below, so a
1535
+ // pull that changed `sync.json` (a page added or removed in the app) said "your uncommitted
1536
+ // changes come back" to someone who had none.
1537
+ const asTheyLeftThem = snapshotFiles(repo)
1533
1538
  // What this copy keeps, taken back from the stand-in: the identity the backend minted
1534
1539
  // (`sync.json`, before the merge, so a merge's stash carries it) and its caches.
1535
1540
  const syncNow = bytesOf(join(projDir, 'sync.json'))
@@ -1641,8 +1646,9 @@ export async function pull(args = [], deps = {}) {
1641
1646
  pin: recorded.pins.find((p) => p.at === n.at)
1642
1647
  }))
1643
1648
  }
1644
- // Whether anything was set aside for the merge: the files as they were, against HEAD.
1645
- merge.setAside = files !== repo.head
1649
+ // Whether work of the person's was set aside for the merge: the files as they left them,
1650
+ // against HEAD. The identity this pull wrote back is its own, and comes back with the rest.
1651
+ merge.setAside = asTheyLeftThem !== repo.head
1646
1652
  merge.noBase = !force && !base
1647
1653
  merge.movedFrom = merge.noBase ? siteMovedFrom : null
1648
1654
  merge.changed = changedInFiles(repo, {
@@ -48,7 +48,7 @@ import { spawn } from 'node:child_process'
48
48
  import prompts from 'prompts'
49
49
 
50
50
  import { findUniwebWorkspace, getWorkspacePackages } from '../utils/workspace.js'
51
- import { lockedUniwebPackages, liftCommand, liftMoves } from '../utils/lockfile-uniweb.js'
51
+ import { lockedUniwebPackages, liftCommand, liftMoves, installBehindLockfile } from '../utils/lockfile-uniweb.js'
52
52
  import {
53
53
  readAgentsVersion,
54
54
  refreshAgentsContent,
@@ -257,6 +257,48 @@ async function liftUniwebPackages(workspaceDir, pm) {
257
257
  log('')
258
258
  }
259
259
 
260
+ /**
261
+ * Bring node_modules to what the lockfile holds, when the declared versions are aligned and the
262
+ * install is not: say which packages differ, then install as the rest of this command does, `--yes`
263
+ * running it, a run with no terminal printing it, and otherwise asking.
264
+ *
265
+ * @returns {Promise<boolean>} whether the install ran and succeeded
266
+ */
267
+ async function installToTheLockfile({ behind, installPm, workspaceDir, hasYes, nonInteractive, dryRun }) {
268
+ const cmd = installCmd(installPm)
269
+ warn("What node_modules holds isn't what the lockfile holds:")
270
+ for (const { name, locked, installed } of behind.slice(0, 8)) {
271
+ log(` ${name} ${installed.join(', ') || 'not installed'} → ${locked.join(', ') || 'not in the lockfile'}`)
272
+ }
273
+ if (behind.length > 8) log(` … and ${behind.length - 8} more`)
274
+ log(`${colors.dim}A pull that brings a teammate's update moves the lockfile and leaves node_modules as it was.${colors.reset}`)
275
+ if (dryRun) {
276
+ log(`${colors.dim}Dry-run: would run${colors.reset} ${colors.cyan}${cmd}${colors.reset}`)
277
+ return false
278
+ }
279
+ let go = hasYes
280
+ if (!go && nonInteractive) {
281
+ info(`${colors.dim}Non-interactive — run the install yourself:${colors.reset} ${colors.cyan}${cmd}${colors.reset}`)
282
+ return false
283
+ }
284
+ if (!go) {
285
+ const answer = await prompts({ type: 'confirm', name: 'go', message: `Run \`${cmd}\` now?`, initial: true })
286
+ go = !!answer.go
287
+ }
288
+ if (!go) {
289
+ log(`${colors.dim}Skipped install; run${colors.reset} ${colors.cyan}${cmd}${colors.reset} ${colors.dim}to bring node_modules to the lockfile.${colors.reset}`)
290
+ return false
291
+ }
292
+ const code = await runCommand(cmd, workspaceDir)
293
+ if (code !== 0) {
294
+ error(`Install failed (exit ${code}).`)
295
+ log(`${colors.dim}To retry:${colors.reset} ${colors.cyan}${cmd}${colors.reset}`)
296
+ process.exit(code)
297
+ }
298
+ success('Install complete: node_modules holds what the lockfile does.')
299
+ return true
300
+ }
301
+
260
302
  /** Run a shell command, inheriting stdio. Resolves with the exit code. */
261
303
  function runCommand(cmd, cwd) {
262
304
  return new Promise((resolve) => {
@@ -549,6 +591,16 @@ export async function update(args = []) {
549
591
  warn(
550
592
  `No ${colors.bright}node_modules${colors.reset} in the workspace — run ${colors.cyan}${installCmd(installPm || pmToInstall(workspaceDir))}${colors.reset} to install.`
551
593
  )
594
+ } else {
595
+ // ⭐ ALIGNED IS WHAT THE PROJECT DECLARES; WHAT IS INSTALLED CAN BE OTHER. A `git pull` that
596
+ // brings a teammate's update moves package.json and the lockfile and leaves node_modules, so
597
+ // the project goes on running the CLI it had (`installBehindLockfile`). ⛔ Until 2026-11-13 this
598
+ // said "aligned" and installed nothing: a teammate told to pull and run `update` kept the old
599
+ // CLI, and its pull and push went on behaving as the old ones did.
600
+ const behind = installPm ? installBehindLockfile(workspaceDir, installPm) : null
601
+ if (behind?.length) {
602
+ installRan = await installToTheLockfile({ behind, installPm, workspaceDir, hasYes, nonInteractive, dryRun })
603
+ }
552
604
  }
553
605
  log('')
554
606
  } else {
@@ -48,41 +48,76 @@ const isUniwebPackage = (name) => typeof name === 'string' && name.startsWith('@
48
48
  export function lockedUniwebPackages(workspaceDir, pm) {
49
49
  const file = LOCKFILES[pm]
50
50
  if (!file) return null
51
- const path = join(workspaceDir, file)
51
+ return readPackages(join(workspaceDir, file), pm, isUniwebPackage)
52
+ }
53
+
54
+ // What a package manager records of its last install, inside node_modules: pnpm a copy of the
55
+ // lockfile it installed from, npm its hidden lockfile. Each reads as the lockfile does.
56
+ const INSTALLED = { pnpm: 'node_modules/.pnpm/lock.yaml', npm: 'node_modules/.package-lock.json' }
57
+
58
+ // The framework's packages: the CLI (`uniweb`) and each `@uniweb/*`.
59
+ const isFrameworkPackage = (name) => name === 'uniweb' || isUniwebPackage(name)
60
+
61
+ /**
62
+ * The framework's packages whose versions in the lockfile are not the ones the last install put in
63
+ * node_modules, as the package manager records that install.
64
+ *
65
+ * ⭐ A `git pull` that brings a teammate's `uniweb update` moves package.json and the lockfile, and
66
+ * leaves node_modules as it was, so the project goes on running the CLI and the packages it had.
67
+ * `update` then finds the declared versions aligned, and it has to install all the same.
68
+ *
69
+ * @param {string} workspaceDir
70
+ * @param {'pnpm'|'npm'|'yarn'|null} pm
71
+ * @returns {Array<{ name: string, locked: string[], installed: string[] }>|null} each package that
72
+ * differs; [] when they agree; null when either side can't be read (nothing installed yet, yarn)
73
+ */
74
+ export function installBehindLockfile(workspaceDir, pm) {
75
+ const file = LOCKFILES[pm]
76
+ if (!file || !INSTALLED[pm]) return null
77
+ const locked = readPackages(join(workspaceDir, file), pm, isFrameworkPackage)
78
+ const installed = readPackages(join(workspaceDir, INSTALLED[pm]), pm, isFrameworkPackage)
79
+ if (!locked || !installed) return null
80
+ return [...new Set([...locked.keys(), ...installed.keys()])]
81
+ .sort()
82
+ .map((name) => ({ name, locked: locked.get(name) || [], installed: installed.get(name) || [] }))
83
+ .filter(({ locked, installed }) => locked.join() !== installed.join())
84
+ }
85
+
86
+ function readPackages(path, pm, keep) {
52
87
  if (!existsSync(path)) return null
53
88
  try {
54
89
  const text = readFileSync(path, 'utf8')
55
- return pm === 'pnpm' ? fromPnpmLock(yaml.load(text)) : fromNpmLock(JSON.parse(text))
90
+ return pm === 'pnpm' ? fromPnpmLock(yaml.load(text), keep) : fromNpmLock(JSON.parse(text), keep)
56
91
  } catch {
57
92
  return null
58
93
  }
59
94
  }
60
95
 
61
96
  /** `packages:` keys: `'@uniweb/core@1.6.12'` (v9), `/@uniweb/core@1.6.12(react@19.0.0)` (v6). */
62
- function fromPnpmLock(lock) {
97
+ function fromPnpmLock(lock, keep) {
63
98
  const found = new Map()
64
99
  for (const key of Object.keys(lock?.packages || {})) {
65
100
  const id = key.replace(/^\//, '').replace(/\(.*$/, '')
66
101
  const at = id.lastIndexOf('@')
67
102
  if (at <= 0) continue
68
- add(found, id.slice(0, at), id.slice(at + 1))
103
+ add(found, id.slice(0, at), id.slice(at + 1), keep)
69
104
  }
70
105
  return sorted(found)
71
106
  }
72
107
 
73
108
  /** `packages:` keys: `node_modules/@uniweb/core`, `node_modules/x/node_modules/@uniweb/core`. */
74
- function fromNpmLock(lock) {
109
+ function fromNpmLock(lock, keep) {
75
110
  const found = new Map()
76
111
  for (const [key, entry] of Object.entries(lock?.packages || {})) {
77
112
  const at = key.lastIndexOf('node_modules/')
78
113
  if (at < 0 || entry?.link || !entry?.version) continue
79
- add(found, key.slice(at + 'node_modules/'.length), entry.version)
114
+ add(found, key.slice(at + 'node_modules/'.length), entry.version, keep)
80
115
  }
81
116
  return sorted(found)
82
117
  }
83
118
 
84
- function add(found, name, version) {
85
- if (!isUniwebPackage(name) || !version) return
119
+ function add(found, name, version, keep) {
120
+ if (!keep(name) || !version) return
86
121
  if (!found.has(name)) found.set(name, new Set())
87
122
  found.get(name).add(version)
88
123
  }