uniweb 1.24.22 → 1.25.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.24.22",
3
+ "version": "1.25.1",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -41,15 +41,15 @@
41
41
  "js-yaml": "^4.3.2",
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
- "@uniweb/core": "~1.5.2",
44
+ "@uniweb/core": "~1.6.0",
45
45
  "@uniweb/semantic-parser": "~1.13.2",
46
- "@uniweb/content-writer": "~1.3.1",
47
- "@uniweb/schemas": "~1.6.7"
46
+ "@uniweb/schemas": "~1.6.7",
47
+ "@uniweb/content-writer": "~1.3.1"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.13.11",
51
- "@uniweb/content-reader": "~1.5.8",
52
- "@uniweb/semantic-parser": "~1.13.2"
50
+ "@uniweb/build": "~1.14.0",
51
+ "@uniweb/semantic-parser": "~1.13.2",
52
+ "@uniweb/content-reader": "~1.5.8"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -807,6 +807,10 @@ Measured on exactly that shape: **the agent corpus holds every page; the public
807
807
 
808
808
  ⇒ **The way to know is to ask, at render:** `isAssistantEnabled()` from `@uniweb/kit` is true only where an agent endpoint is declared. On a site that is *only* knowledge there is no component to ask — so confirm with your host that the agent is enabled for that site before you build an integration against it. If you meant to build an agent endpoint and got silence, this is where to look.
809
809
 
810
+ ### Older versions of docs
811
+
812
+ Most docs need one version. When a release is about to stop being the latest and its readers need its docs kept, run `uniweb add version v2` (`--in <folder>`, `--label "2.x"`). It copies the docs to a folder named `v2` beside them, at `/docs/v2/…`, with the copy's links leading to the copy, no page ids in it, and search engines told to leave it out. Keep writing where you were: the pages beside version folders are the latest, and their URLs never change. Don't copy a version folder by hand. A foundation draws versions with kit's `useVersion`: `versions` for a switcher (`version.href` is where each leads from this page, for `<Link>`), `isOlderVersion` and `latestVersion` for a notice, and `hierarchy({ for: 'left' })` for a menu of one version, which is the whole tree on a site with none. See [versioning](https://github.com/uniweb/docs/blob/main/reference/versioning.md).
813
+
810
814
  ### Your site is readable by agents, automatically
811
815
 
812
816
  Every build emits two things an AI agent can use directly, alongside the HTML. **Free, on by default, nothing to install.**
@@ -1913,9 +1917,9 @@ const page = website.activePage
1913
1917
 
1914
1918
  ```jsx
1915
1919
  // getPageHierarchy(options) →
1916
- // [{ id, route, navigableRoute, translatedRoute, title, label, description, hasContent, version, children }]
1920
+ // [{ id, route, navigableRoute, translatedRoute, title, label, description, hasContent, children }]
1917
1921
  // Options: for: 'header'|'footer'|<area> (respects hideIn) · nested: true (default)
1918
- // includeHidden: false · filter: (page) => bool · sort: (a, b) => number
1922
+ // includeHidden: false · under: route · filter: (page) => bool · sort: (a, b) => number
1919
1923
  website.getPageHierarchy({ for: 'header' }) // = website.getHeaderPages()
1920
1924
  website.getPageHierarchy({ nested: false }) // = website.getAllPages()
1921
1925
 
@@ -45,6 +45,7 @@ import {
45
45
  diffSiteUnits,
46
46
  describeSiteDiff,
47
47
  computeUnitHashes,
48
+ collectSiteUnits,
48
49
  collectUnitUuids,
49
50
  collectFolderItemUuids,
50
51
  collectQueryUuids,
@@ -390,29 +391,72 @@ export function filesOfUnits(siteDir, units) {
390
391
 
391
392
  // How many files a push names before it says how many more.
392
393
  const MOVED_SHOWN = 12
394
+ // How many changed media files one of those lines names.
395
+ const MEDIA_SHOWN = 3
396
+
397
+ /** Which of the moved media (ref → address) a part of the document holds, as a phrase, or null. */
398
+ function mediaNamedIn(part, moved) {
399
+ const text = JSON.stringify(part)
400
+ const names = Object.entries(moved)
401
+ .filter(([, address]) => text.includes(address))
402
+ .map(([ref]) => basename(ref))
403
+ .sort()
404
+ if (!names.length) return null
405
+ if (names.length === 1) return `${names[0]} changed`
406
+ if (names.length > MEDIA_SHOWN) {
407
+ return `${names.slice(0, MEDIA_SHOWN - 1).join(', ')} and ${names.length - MEDIA_SHOWN + 1} more changed`
408
+ }
409
+ return `${names.slice(0, -1).join(', ')} and ${names.at(-1)} changed`
410
+ }
393
411
 
394
412
  /**
395
413
  * What a site-content push moved, file by file. The lane sends one entity, the site's whole
396
414
  * document, so the backend's `changed` flag counts to 1 however much moved. ⛔ Until 2026-11-01
397
415
  * that was all it said, and a publish of the hero and ten pages read `site-content: 1 changed`.
398
416
  *
417
+ * ⭐ A file can be listed with nothing changed in it, because a push sends the DELIVERED document
418
+ * (`readAppliedInjections`). A media file's serve address changes with the file, so a replaced
419
+ * picture moves every unit that shows it, and a released foundation moves `site.yml`, through the
420
+ * version it pins. Those lines say so, or someone checking git finds no change and no reason.
421
+ *
399
422
  * @param {string} siteDir
400
423
  * @param {object} sent - the document this push sent
401
424
  * @param {Record<string,string>} base - each unit's hash at the last sync (`readUnitBases().local`)
425
+ * @param {{ before?: object, now?: object }} [opts] - what the last push and this one applied to
426
+ * the document (`readAppliedInjections`, `pkg.applied`)
402
427
  * @returns {string[]} the lines to print
403
428
  */
404
- export function describeContentMoved(siteDir, sent, base) {
429
+ export function describeContentMoved(siteDir, sent, base, { before = {}, now = {} } = {}) {
405
430
  // Nothing to compare with, so the backend's word is all there is.
406
431
  if (!Object.keys(base).length) return ['site-content: changed']
407
432
  const hashes = computeUnitHashes(sent)
408
433
  const units = Object.keys(hashes)
434
+ const records = collectSiteUnits(sent)
435
+ const moved = units.filter((u) => u in base && base[u] !== hashes[u])
436
+
437
+ const addressWas = before.assetRewrite || {}
438
+ const media = Object.fromEntries(
439
+ Object.entries(now.assetRewrite || {}).filter(([ref, address]) => addressWas[ref] && addressWas[ref] !== address)
440
+ )
441
+ const pinWas = before.injectInfo?.foundation
442
+ const pin = now.injectInfo?.foundation
443
+ const aboutTheSite = [
444
+ pinWas && pin && pin !== pinWas ? `foundation now ${pin}` : null,
445
+ // `settings` is no unit, and what it names is written in site.yml, as `seo.image`.
446
+ mediaNamedIn([sent.info, sent.settings], media)
447
+ ].filter(Boolean)
448
+ if (aboutTheSite.length && !moved.includes('site.yml')) moved.push('site.yml')
449
+
409
450
  const files = [
410
- ...filesOfUnits(siteDir, units.filter((u) => u in base && base[u] !== hashes[u])),
451
+ ...filesOfUnits(siteDir, moved).map((f, i) => {
452
+ const why = moved[i] === 'site.yml' ? aboutTheSite : [mediaNamedIn(records.get(moved[i]), media)].filter(Boolean)
453
+ return why.length ? `${f} (${why.join(', ')})` : f
454
+ }),
411
455
  ...filesOfUnits(siteDir, units.filter((u) => !(u in base))).map((f) => `${f} (new)`),
412
456
  ...filesOfUnits(siteDir, Object.keys(base).filter((u) => !(u in hashes))).map((f) => `${f} (removed)`)
413
457
  ].sort()
414
458
  // The document moved and no unit did: what moved is outside the pages (`contentChanges`).
415
- if (!files.length) return ["site-content: the site's settings changed — its services, languages or queries"]
459
+ if (!files.length) return ["site-content: the site's settings changed, in a file such as site.yml, theme.yml or queries.yml"]
416
460
  return [
417
461
  `site-content: ${files.length} file${files.length === 1 ? '' : 's'} changed`,
418
462
  ...files.slice(0, MOVED_SHOWN).map((f) => ` ${f}`),
@@ -2752,7 +2796,12 @@ export async function pushSyncPackages({
2752
2796
  sent: siteContent.buffer,
2753
2797
  // Read before `settleSiteContent` moves the bases on to this push.
2754
2798
  describeMoved: sentSiteDoc
2755
- ? () => describeContentMoved(siteDir, sentSiteDoc, readUnitBases(siteDir, client.origin).local)
2799
+ ? () =>
2800
+ describeContentMoved(siteDir, sentSiteDoc, readUnitBases(siteDir, client.origin).local, {
2801
+ // Still the last push's: this one banks its own when it ends.
2802
+ before: readAppliedInjections(siteDir, client.origin),
2803
+ now: applied
2804
+ })
2756
2805
  : null
2757
2806
  }
2758
2807
  )
@@ -9,11 +9,12 @@
9
9
  * uniweb add site [name] [--from <template>] [--foundation <name>] [--path <dir>] [--project <name>]
10
10
  * uniweb add extension [name] [--from <template>] [--site <name>] [--path <dir>]
11
11
  * uniweb add section <name> [--foundation <name>]
12
+ * uniweb add version <name> [--in <folder>] [--label <text>] [--keep-in-search] [--dry-run] [--site <name>]
12
13
  */
13
14
 
14
15
  import { existsSync, realpathSync } from 'node:fs'
15
16
  import { readFile, writeFile, mkdir } from 'node:fs/promises'
16
- import { join, relative, basename } from 'node:path'
17
+ import { join, relative, basename, isAbsolute } from 'node:path'
17
18
  import prompts from 'prompts'
18
19
  import yaml from 'js-yaml'
19
20
  import {
@@ -135,12 +136,17 @@ function parseArgs(args) {
135
136
  starter: false,
136
137
  preset: null,
137
138
  write: null,
138
- json: false
139
+ json: false,
140
+ // `add version` only.
141
+ in: null,
142
+ label: null,
143
+ keepInSearch: false,
144
+ dryRun: false
139
145
  }
140
146
 
141
147
  // Booleans (no value) consumed up-front so the value-flag loop below
142
148
  // doesn't accidentally swallow the next positional.
143
- const BOOLEAN_FLAGS = new Set(['--force', '--no-previews', '--starter', '--json'])
149
+ const BOOLEAN_FLAGS = new Set(['--force', '--no-previews', '--starter', '--json', '--keep-in-search', '--dry-run'])
144
150
 
145
151
  // Value flags, mapped to their result key. Both spellings are accepted:
146
152
  // `--host github-pages` and `--host=github-pages`.
@@ -162,7 +168,9 @@ function parseArgs(args) {
162
168
  '--target': 'target',
163
169
  '--project-name': 'projectName',
164
170
  '--preset': 'preset',
165
- '--write': 'write'
171
+ '--write': 'write',
172
+ '--in': 'in',
173
+ '--label': 'label'
166
174
  }
167
175
 
168
176
  /** Split `--flag=value` into [flag, value]; `--flag` into [flag, null]. */
@@ -204,6 +212,10 @@ function parseArgs(args) {
204
212
  result.starter = true
205
213
  } else if (flag === '--json') {
206
214
  result.json = true
215
+ } else if (flag === '--keep-in-search') {
216
+ result.keepInSearch = true
217
+ } else if (flag === '--dry-run') {
218
+ result.dryRun = true
207
219
  }
208
220
  }
209
221
 
@@ -247,6 +259,7 @@ export async function add(rawArgs) {
247
259
  { label: 'site', description: 'Content site' },
248
260
  { label: 'extension', description: 'Additional component package' },
249
261
  { label: 'section', description: 'Section type in a foundation' },
262
+ { label: 'version', description: 'Freeze a site\'s docs as an older version' },
250
263
  {
251
264
  label: 'ci',
252
265
  description: 'CI deploy workflow for a host (e.g., GitHub Pages)'
@@ -291,6 +304,11 @@ export async function add(rawArgs) {
291
304
  title: 'CI workflow',
292
305
  value: 'ci',
293
306
  description: 'Deploy workflow for a host (e.g., GitHub Pages)'
307
+ },
308
+ {
309
+ title: 'Version',
310
+ value: 'version',
311
+ description: 'Freeze a site\'s docs as an older version'
294
312
  }
295
313
  ]
296
314
  },
@@ -351,10 +369,13 @@ export async function add(rawArgs) {
351
369
  case 'ci':
352
370
  await addCi(rootDir, parsed, pm)
353
371
  break
372
+ case 'version':
373
+ await addVersionOfDocs(rootDir, parsed)
374
+ break
354
375
  default:
355
376
  error(`Unknown subcommand: ${parsed.subcommand}`)
356
377
  log(
357
- `Valid subcommands: project, foundation, site, extension, section, ci`
378
+ `Valid subcommands: project, foundation, site, extension, section, ci, version`
358
379
  )
359
380
  process.exit(1)
360
381
  }
@@ -1761,6 +1782,73 @@ async function addCi(rootDir, opts, pm = 'pnpm') {
1761
1782
  }
1762
1783
  }
1763
1784
 
1785
+ /**
1786
+ * `uniweb add version v2`: freeze a site's docs as a version beside them. What it does to the copy
1787
+ * is `@uniweb/build`'s (`site/add-version.js`); here it's only which site, and saying what happened.
1788
+ */
1789
+ async function addVersionOfDocs(rootDir, opts) {
1790
+ setAddJsonMode(opts.json)
1791
+ const prefix = getCliPrefix()
1792
+
1793
+ if (!opts.name) {
1794
+ error('Missing the version\'s name.\n')
1795
+ log(`Usage: ${prefix} add version v2 [--in <folder>] [--label "2.x"]`)
1796
+ process.exit(1)
1797
+ }
1798
+
1799
+ const sites = await discoverSites(rootDir)
1800
+ const here = sites.find((site) => {
1801
+ const inSite = relative(join(rootDir, site.path), process.cwd())
1802
+ return !inSite.startsWith('..') && !isAbsolute(inSite)
1803
+ })
1804
+ const site = opts.site ? sites.find((s) => s.name === opts.site) : (here ?? (sites.length === 1 ? sites[0] : null))
1805
+ if (!site) {
1806
+ error(opts.site ? `Could not find site '${opts.site}'.` : 'Multiple sites in this workspace. Say which one.\n')
1807
+ log(formatOptions(sites.map((s) => ({ label: s.name, description: s.path }))))
1808
+ log('')
1809
+ log(`Usage: ${prefix} add version ${opts.name} --site <name>`)
1810
+ process.exit(1)
1811
+ }
1812
+
1813
+ const { addVersion } = await import('@uniweb/build/site')
1814
+ let report
1815
+ try {
1816
+ report = await addVersion(join(rootDir, site.path), {
1817
+ name: opts.name,
1818
+ folder: opts.in ?? undefined,
1819
+ label: opts.label ?? undefined,
1820
+ keepInSearch: opts.keepInSearch,
1821
+ dryRun: opts.dryRun
1822
+ })
1823
+ } catch (err) {
1824
+ error(err.message)
1825
+ process.exit(1)
1826
+ }
1827
+
1828
+ if (opts.json) {
1829
+ console.log(JSON.stringify(report, null, 2))
1830
+ return
1831
+ }
1832
+
1833
+ const pageWord = report.pages === 1 ? 'page' : 'pages'
1834
+ const where = `pages/${report.folder}`
1835
+ success(
1836
+ `${opts.dryRun ? 'Would freeze' : 'Froze'} ${report.pages} ${pageWord} of ${colors.cyan}${where}${colors.reset} as ${colors.cyan}${report.path}${colors.reset}, at ${colors.cyan}${report.route}${colors.reset}`
1837
+ )
1838
+ log(` ${report.links} ${report.links === 1 ? 'link leads' : 'links lead'} to the copy now. Links in code samples are as written.`)
1839
+ if (report.ids) log(` ${report.ids} page ${report.ids === 1 ? 'id' : 'ids'} left out of the copy: ids stay with the latest pages.`)
1840
+ log(
1841
+ report.keptOutOfSearch
1842
+ ? ` Kept out of search engines, and in the site's own search. To open it to them, remove \`noindex\` from its page.yml.`
1843
+ : ` Open to search engines, like the rest of the site.`
1844
+ )
1845
+ for (const note of report.notes) log(` ${note}`)
1846
+ if (!opts.dryRun) {
1847
+ log('')
1848
+ log(`${colors.bright}Next:${colors.reset} keep writing in ${where}, which is still the latest. A foundation shows versions with useVersion.`)
1849
+ }
1850
+ }
1851
+
1764
1852
  /**
1765
1853
  * The name to register this site under on the host (Cloudflare Pages
1766
1854
  * project, etc.).
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-01T19:28:59.853Z",
3
+ "generatedAt": "2026-11-02T00:19:04.917Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
- "version": "1.6.7"
6
+ "version": "1.6.8"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.13.11"
9
+ "version": "1.14.0"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.8"
@@ -15,28 +15,28 @@
15
15
  "version": "1.3.1"
16
16
  },
17
17
  "@uniweb/core": {
18
- "version": "1.5.2"
18
+ "version": "1.6.0"
19
19
  },
20
20
  "@uniweb/frame-bridge": {
21
21
  "version": "1.0.3"
22
22
  },
23
23
  "@uniweb/icons": {
24
- "version": "1.0.7"
24
+ "version": "1.0.8"
25
25
  },
26
26
  "@uniweb/kit": {
27
- "version": "1.6.16"
27
+ "version": "1.7.0"
28
28
  },
29
29
  "@uniweb/loom": {
30
30
  "version": "1.1.2"
31
31
  },
32
32
  "@uniweb/press": {
33
- "version": "1.2.0"
33
+ "version": "1.2.1"
34
34
  },
35
35
  "@uniweb/projections": {
36
- "version": "1.2.9"
36
+ "version": "1.2.10"
37
37
  },
38
38
  "@uniweb/runtime": {
39
- "version": "1.3.8"
39
+ "version": "1.3.9"
40
40
  },
41
41
  "@uniweb/scene": {
42
42
  "version": "1.0.1"
@@ -54,13 +54,13 @@
54
54
  "version": "1.1.2"
55
55
  },
56
56
  "@uniweb/templates": {
57
- "version": "1.1.15"
57
+ "version": "1.2.1"
58
58
  },
59
59
  "@uniweb/theming": {
60
60
  "version": "1.2.1"
61
61
  },
62
62
  "@uniweb/unipress": {
63
- "version": "1.1.27"
63
+ "version": "1.1.29"
64
64
  }
65
65
  },
66
66
  "templates": {
@@ -198,7 +198,7 @@
198
198
  },
199
199
  "business-docs": {
200
200
  "name": "Business Documents",
201
- "description": "A complete business-document site: invoice and SOW records, pages listing them, and a filtered engagement report with XLSX export. Built on @unipress/business-docs and demonstrates the same foundation that ships the unipress invoice template.",
201
+ "description": "A complete business-document site: invoice and SOW records, pages listing them, and an engagement report, each page downloadable as Word, Excel or a print page. Built on @unipress/business-docs and demonstrates the same foundation that ships the unipress invoice template.",
202
202
  "tags": [
203
203
  "business-docs",
204
204
  "invoice",
package/src/index.js CHANGED
@@ -1705,6 +1705,7 @@ ${colors.bright}Usage:${colors.reset}
1705
1705
  uniweb add extension <name> [options]
1706
1706
  uniweb add section <name> [options]
1707
1707
  uniweb add ci [options]
1708
+ uniweb add version <name> [options]
1708
1709
 
1709
1710
  ${colors.bright}Common Options:${colors.reset}
1710
1711
  --from <template> Apply content from a template after scaffolding
@@ -1723,6 +1724,10 @@ ${colors.bright}Extension Options:${colors.reset}
1723
1724
 
1724
1725
  ${colors.bright}Section Options:${colors.reset}
1725
1726
  --foundation <n> Foundation to add section to (prompted if multiple exist)
1727
+ --in <folder> add version: the folder under pages/ holding the docs (. for all of pages/)
1728
+ --label <text> add version: what a version switcher calls it
1729
+ --keep-in-search add version: leave it open to search engines
1730
+ --dry-run add version: say what would happen, and write nothing
1726
1731
  --starter Generate starter content from the section's \`content:\`
1727
1732
  declaration — what an author would begin editing. Works on
1728
1733
  a section that already exists (nothing is written), and on
@@ -1763,6 +1768,8 @@ ${colors.bright}Examples:${colors.reset}
1763
1768
  uniweb add section Hero --starter # Starter content for an existing Hero
1764
1769
  uniweb add section Pricing --starter # Scaffold Pricing + content that fills it
1765
1770
  uniweb add section Hero --starter --preset split # Frontmatter it with the 'split' preset
1771
+ uniweb add version v2 # Freeze the docs as pages/docs/v2
1772
+ uniweb add version v2 --in manual --label "2.x" # Another folder, and what a switcher calls it
1766
1773
  uniweb add section Hero --starter --json # The structure + ProseMirror, for a script
1767
1774
  uniweb add foundation --project docs # Create ./docs/src/ (co-located)
1768
1775
  uniweb add site --project docs # Create ./docs/site/ (co-located)
@@ -2378,6 +2385,7 @@ ${colors.bright}Add Subcommands:${colors.reset}
2378
2385
  add extension <name> Add an extension (--from, --site, --path)
2379
2386
  add section <name> Add a section type to a foundation (--foundation, --starter)
2380
2387
  add ci Add a CI workflow so every push deploys (--host, --target)
2388
+ add version Freeze a site's docs as a version beside them (--in, --label)
2381
2389
 
2382
2390
  ${colors.bright}Global Options:${colors.reset}
2383
2391
  --version, -v Show version