uniweb 1.26.8 → 1.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.26.8",
3
+ "version": "1.27.0",
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/schemas": "~1.6.7",
45
44
  "@uniweb/content-writer": "~1.3.1",
46
45
  "@uniweb/core": "~1.6.4",
47
- "@uniweb/semantic-parser": "~1.13.2"
46
+ "@uniweb/semantic-parser": "~1.13.2",
47
+ "@uniweb/schemas": "~1.6.8"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/semantic-parser": "~1.13.2",
51
- "@uniweb/content-reader": "~1.5.8",
52
- "@uniweb/build": "~1.15.5"
50
+ "@uniweb/build": "~1.16.0",
51
+ "@uniweb/content-reader": "~1.5.9",
52
+ "@uniweb/semantic-parser": "~1.13.2"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -249,7 +249,7 @@ content = { title, pretitle, subtitle, paragraphs, links, images, icons, videos,
249
249
 
250
250
  **Backgrounds and theme are frontmatter.** `background:` takes an image, video, gradient, quoted color or palette token, or an object (`image`, `video`, `overlay`); `theme: light | medium | dark`, or a map with token overrides (`section: neutral-100`).
251
251
 
252
- **Pages.** `pages/<name>/` → `/<name>`; a name or `slug:` holding `?`, `#` or `%` stops the build. `page.yml`: `title`, `description`, `id`, `order`, `sections: [a, b, ...]`, `pages: [...]`, `nest`, `redirect`, `slug: { fr: … }`, `hidden` (draft; takes the pages below it), `hideIn` (nav only), `knowledge` (agent-only, never rendered — not a security control), `query` / `fetch`, `seo`, `layout`. `folder.yml` for a folder *of pages*. Numeric prefixes order sections; `2.5-x.md` slots between. Config cascades `page.yml → folder.yml → site.yml → foundation`. `layout/header.md`, `footer.md` render on every page — a markdown list is the nav, a standalone link the CTA, `yaml:nav` for richer menus. Child sections: `@child.md` + `nest: { parent: [child] }`.
252
+ **Pages.** `pages/<name>/` → `/<name>`; a name or `slug:` holding `?`, `#` or `%` stops the build. `page.yml`: `title`, `description`, `id`, `order`, `sections: [a, b, ...]`, `pages: [...]`, `nest`, `redirect`, `slug: { fr: … }`, `hidden` (draft; takes the pages below it), `hideIn` (nav only), `knowledge` (agent-only, never rendered — not a security control), `query` / `fetch`, `seo`, `layout`. `folder.yml` for a folder *of pages*. Numeric prefixes (a number then a dash) order sections, pages and page folders and never reach a URL: `2-about/` is `/about`, and `pages:`/`index:` name it `about`; `2.5-x.md` slots between; `3d-printing` has no number. Config cascades `page.yml → folder.yml → site.yml → foundation`. `layout/header.md`, `footer.md` render on every page — a markdown list is the nav, a standalone link the CTA, `yaml:nav` for richer menus. Child sections: `@child.md` + `nest: { parent: [child] }`.
253
253
 
254
254
  **`site.yml`.** `index`, `pages`, `foundation`, `extensions`, `paths`, `placeholders`, `languages`, `services`, `agents`, `seo` (`origin`: scheme + host, `image`: 1200×630), `favicon`, `touchIcon`. Everything in `site.yml` and `queries.yml` ships to the browser — **never a secret**.
255
255
 
@@ -73,9 +73,13 @@ fields:
73
73
  # schemas/course.yml
74
74
  fields:
75
75
  lessons: { ref: '@/lesson', many: true, sold_with: true } # a buyer of the course reads its lessons (up to three steps)
76
+
77
+ # schemas/inquiry.yml
78
+ fields:
79
+ email: { type: email, required: true, visitor_fills: true } # a site's visitor may fill it, with no account
76
80
  ```
77
81
 
78
- `readable_with` (`read` | `edit` | `admin`, only on a reference) is one step; a backend refuses adding it to a field entries already fill. `grantable: false` keeps entries from being shared with a person or team. `sold_with` only on a reference; an unmarked one carries nothing.
82
+ `readable_with` (`read` | `edit` | `admin`, only on a reference) is one step; a backend refuses adding it to a field entries already fill. `grantable: false` keeps entries from being shared with a person or team. `sold_with` only on a reference; an unmarked one carries nothing. `visitor_fills: true` marks a field a site's visitor may fill, and a type with one takes visitors' submissions, confirmed by email. Mark it per field, on a top-level section's fields only. The build refuses it on files, on a reference with `readable_with`/`sold_with`, and in a section that leaves a `required` field unmarked.
79
83
 
80
84
  ## Acting as an administrator
81
85
 
@@ -209,7 +209,7 @@ site/pages/home/
209
209
  └── 2-features.md
210
210
  ```
211
211
 
212
- Decimals insert between (`2.5-x.md`). Ignored: `README.md`, `_*.md`, `_*/`.
212
+ Decimals insert between (`2.5-x.md`). A page folder's number works the same way: `pages/2-about/` orders second and is `/about`, named `about` in `pages:` and `index:`. A number counts only with a dash after it, or as the whole name (`404`): `3d-printing.md` keeps its name. Ignored: `README.md`, `_*.md`, `_*/`.
213
213
 
214
214
  ```yaml
215
215
  # page.yml
@@ -237,9 +237,11 @@ extensions: ['@acme/fx@0.3.1']
237
237
 
238
238
  **Cascade:** `page.yml → folder.yml → site.yml → foundation defaults`. Put `layout: marketing` in a `folder.yml` and every page inherits it; one page can still override.
239
239
 
240
+ **A folder of pages holds pages of one section.** Under a `folder.yml`, each page is one `.md` file of one section, and each subfolder is a folder of pages too. The build stops on a subfolder with a `page.yml` of its own, a parametric `[slug]/` included. A page of several sections goes outside the folder. In the app, such a page takes no second section, and a pull holds one made there.
241
+
240
242
  **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
243
 
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.
244
+ **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. A pull writes an author's app edits into a mounted folder where the site's own repository holds it, or a submodule of it does (a commit there, to push before the site's repository). A folder it cannot merge into — a clone beside the site — keeps its text and the app keeps the author's: the pull and `status` name each such page as held, and a push leaves it alone while its file is unchanged. A mount is its folder, `pages/docs: ../docs`; the object form is refused.
243
245
 
244
246
  **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
247
 
@@ -27,7 +27,7 @@ import {
27
27
  unmergedPaths,
28
28
  mergeInProgress
29
29
  } from '../utils/sync-point.js'
30
- import { siteContentRoots } from '../utils/git.js'
30
+ import { sentRoots } from '../utils/site-roots.js'
31
31
  import { humanBytes } from '../utils/bytes.js'
32
32
  import {
33
33
  describeRequestError,
@@ -47,6 +47,7 @@ import {
47
47
  computeUnitHashes,
48
48
  collectSiteUnits,
49
49
  collectUnitUuids,
50
+ heldUnitsOf,
50
51
  collectFolderItemUuids,
51
52
  collectFolderRecordTypes,
52
53
  collectQueryUuids,
@@ -976,6 +977,69 @@ export function writeItemBaseVersions(siteDir, backend, versions) {
976
977
  if (!versions || typeof versions !== 'object') return
977
978
  updateSyncCache(siteDir, backend, { itemBaseVersions: { ...versions } })
978
979
  }
980
+ /**
981
+ * ⭐ WHAT A PULL HELD — `{ <unit path>: <hash> }`: each page or section the app changed in a way its
982
+ * files cannot say, where the files keep it, with what they said there at the pull
983
+ * (`@uniweb/build`'s `held-units.js`). A push leaves out each whose files still say it, so the backend
984
+ * keeps the app's version — it deletes only an item a push holds a version for, and a pull banks none
985
+ * for these (`agreedVersions`) — and stops on one whose files changed since. REPLACED by every pull that
986
+ * takes the site's content, and empty when it held nothing. Per copy, like every map here: a copy
987
+ * without it has no base either, and a push refuses it until a pull records both (`untakenBase`).
988
+ */
989
+ export function readHeldUnits(siteDir, backend) {
990
+ return readMap(siteDir, backend, 'heldUnits')
991
+ }
992
+ export function writeHeldUnits(siteDir, backend, held) {
993
+ updateSyncCache(siteDir, backend, { heldUnits: { ...(held || {}) } })
994
+ }
995
+
996
+ /**
997
+ * What a pull held, as the files it wrote into keep it (`heldUnitsOf`): each held item's unit, and
998
+ * every unit below a held page, by path, with the hash the files give it — the files' document before
999
+ * any media is rewritten, as a push compares it. Found by the identity this copy held BEFORE the pull
1000
+ * (`itemUuids`), so a page the app moved is found where the files still keep it. Offline.
1001
+ *
1002
+ * @param {string} siteDir - the files the pull wrote into: the stand-in, in a repository
1003
+ * @param {string} backend
1004
+ * @param {{ held: Iterable<string>, itemUuids?: object, declarations?: Map, fields?: object }} opts
1005
+ * @returns {Promise<Object<string,string>>}
1006
+ */
1007
+ export async function heldUnitBaseline(siteDir, backend, { held = [], itemUuids = {}, declarations = null, fields = null } = {}) {
1008
+ const uuids = [...held]
1009
+ if (!uuids.length) return {}
1010
+ const pkg = await comparisonEmit(siteDir, { backend, sendAll: true, declarations, fields, heldUnits: {}, extra: { unitHashes: true, itemUuids } })
1011
+ return heldUnitsOf({ hashes: pkg.unitHashes || {}, uuids: pkg.unitUuids || {}, held: uuids })
1012
+ }
1013
+
1014
+ // A held unit's page, by its route: `pages/guide/install/page.yml` and `pages/guide/install/install.md`
1015
+ // are both `/guide/install`.
1016
+ function heldRoute(path) {
1017
+ const dir = /\/(page|folder)\.yml$/.test(path) ? path.replace(/\/(page|folder)\.yml$/, '') : path.slice(0, path.lastIndexOf('/'))
1018
+ return `/${dir.replace(/^pages\/?/, '')}`
1019
+ }
1020
+
1021
+ /**
1022
+ * ⭐ A PAGE A PULL HELD WHOSE FILES CHANGED SINCE STOPS A PUSH: the app's version and the file's would
1023
+ * both claim it, and the push cannot keep the one without dropping the other (`heldChanged`,
1024
+ * `@uniweb/build`'s `held-units.js`). Shared by push and publish. Returns whether it stopped.
1025
+ */
1026
+ export function refuseChangedHeld(pkg, { error, note }) {
1027
+ const routes = [...new Set((pkg?.heldChanged || []).map(heldRoute))]
1028
+ if (!routes.length) return false
1029
+ error(`${routes.length} page(s) changed in the app in a way their files cannot say, and changed in their files since the pull:`)
1030
+ for (const route of routes) note(` ${route}`)
1031
+ note('Undo one of the two: the app\'s change, then pull, or the file\'s. `--force` sends the files\' version over the app\'s.')
1032
+ return true
1033
+ }
1034
+
1035
+ /** The pages a push left out because a pull held them, said — they stay as the app has them. */
1036
+ export function noteHeldLeftOut(pkg, { note }) {
1037
+ const routes = [...new Set((pkg?.heldLeftOut || []).map(heldRoute))]
1038
+ if (!routes.length) return
1039
+ note(`Left out: ${routes.length} page(s) a pull held, which stay as the app has them — their files cannot say its change (\`uniweb pull\` names why):`)
1040
+ for (const route of routes) note(` ${route}`)
1041
+ }
1042
+
979
1043
  export function mergeItemBaseVersions(siteDir, backend, versions) {
980
1044
  if (!versions || !Object.keys(versions).length) return
981
1045
  // ⛔ The read names the backend. Without it the read keyed nothing, came back `{}`,
@@ -1095,8 +1159,9 @@ export function holdUnchangedPush(siteDir, backend) {
1095
1159
  return repo.head
1096
1160
  }
1097
1161
 
1098
- /** What a push sends from the files: the site's content, and its media (`public/`). */
1099
- export const sentRoots = (siteDir) => [...siteContentRoots(siteDir), 'public']
1162
+ // What a push sends from the files — the site's content, its media (`public/`) and the mounted folders
1163
+ // its repository holds — is `utils/site-roots.js`'s to say; re-exported for the readers that ask here.
1164
+ export { sentRoots }
1100
1165
 
1101
1166
  /**
1102
1167
  * ⛔ IN A REPOSITORY, A PUSH SENDS WHAT IS COMMITTED. The commit a push is made from is where
@@ -1104,6 +1169,11 @@ export const sentRoots = (siteDir) => [...siteContentRoots(siteDir), 'public']
1104
1169
  * the push sends must be what that commit holds. Returns the refusal, or null: outside a
1105
1170
  * repository nothing is kept to merge from.
1106
1171
  *
1172
+ * ⭐ A page folder mounted from elsewhere in the same repository (`paths: { pages/<segment> }`) is
1173
+ * one of `sentRoots`, so it is held to its commits like the site's pages. ⛔ Until 2026-11-04 no
1174
+ * mount was: its uncommitted edits went out with the push, which named HEAD (measured that day).
1175
+ * A mount that is a repository of its own is held to its commits by `mounts-before-sending.js`.
1176
+ *
1107
1177
  * ⛔ Until 2026-10-18 a push sent uncommitted edits on top of HEAD and recorded HEAD. Measured
1108
1178
  * against a real backend: an edit pushed that way and undone before the next pull came back
1109
1179
  * with it — exit 0, no conflict, reported as the backend's change. Every such push also had
@@ -2108,7 +2178,7 @@ export async function probeUnpushed(siteDir, { backend = null, sendAll = false }
2108
2178
  */
2109
2179
  async function comparisonEmit(
2110
2180
  siteDir,
2111
- { backend = null, priorHashes = {}, sendAll = false, declarations = null, fields = null } = {}
2181
+ { backend = null, priorHashes = {}, sendAll = false, declarations = null, fields = null, heldUnits = undefined, extra = {} } = {}
2112
2182
  ) {
2113
2183
  const applied = readAppliedInjections(siteDir, backend)
2114
2184
  // ⛔ Per backend: an asset id is minted by one and means nothing to another, so a
@@ -2132,7 +2202,11 @@ async function comparisonEmit(
2132
2202
  // the last push banked.
2133
2203
  ...(fields || {}),
2134
2204
  ...(Object.keys(queryUuids).length ? { queryUuids } : {}),
2135
- ...(Object.keys(assetIds).length ? { assetIds } : {})
2205
+ ...(Object.keys(assetIds).length ? { assetIds } : {}),
2206
+ // What a pull held stays out of the comparison as it stays out of a push (`readHeldUnits`), so a
2207
+ // hash banked over it compares with the push's.
2208
+ heldUnits: heldUnits === undefined ? readHeldUnits(siteDir, backend) : heldUnits,
2209
+ ...extra
2136
2210
  // ⛔ No `org`: a site's `@/x` refs resolve into its FOUNDATION's scope, which the
2137
2211
  // emit reads itself — the same read a push makes, so the hashes compare alike.
2138
2212
  })
@@ -2183,12 +2257,12 @@ export async function entityHashes(siteDir, backend = null, { declarations, fiel
2183
2257
  * @param {Map<string,object>} [opts.declarations] - the Models the pull read, by name — so a
2184
2258
  * site whose foundation is not in the project (a clone's) can be re-banked offline
2185
2259
  */
2186
- export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, declarations, fields = null, contentTaken = false } = {}) {
2260
+ export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, declarations, fields = null, contentTaken = false, contentAgreed = true } = {}) {
2187
2261
  // ⛔ With the keys this deployment's Sections take, when the caller has them (`deploymentFields`):
2188
2262
  // they shape the document the next push sends (`typed_by_data_key`, `og_title`), so a hash banked
2189
2263
  // without them marks a clone's first push as changed. Until 2026-09-26 a pull banked none.
2190
2264
  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true, declarations, fields })
2191
- writeSyncCache(siteDir, backend, onlyWhatThePullTook(siteDir, backend, pkg, recordDocs), pkg.applied || {})
2265
+ writeSyncCache(siteDir, backend, onlyWhatThePullTook(siteDir, backend, pkg, recordDocs, { contentAgreed }), pkg.applied || {})
2192
2266
  // ⭐ And the local unit base, from what this copy would send for the content the pull took, so a
2193
2267
  // refusal after a pull can tell this copy's edits from the backend's. ⛔ Until 2026-10-30 a pull
2194
2268
  // left it empty, and the next refusal said "No record of your last sync" just after one.
@@ -2227,8 +2301,12 @@ export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, de
2227
2301
  *
2228
2302
  * @param {object[]|undefined} recordDocs - the record documents the pull took
2229
2303
  */
2230
- function onlyWhatThePullTook(siteDir, backend, pkg, recordDocs) {
2304
+ function onlyWhatThePullTook(siteDir, backend, pkg, recordDocs, { contentAgreed = true } = {}) {
2231
2305
  const hashes = { ...(pkg.hashes || {}) }
2306
+ // ⭐ A site whose files do not hold some page as the backend does — a mounted page the app changed,
2307
+ // one held because its file cannot say the change — is not agreed: its hash is not banked, so the next
2308
+ // push sends it, the folder winning where it is read-only and the gate keeping a held page's.
2309
+ if (!contentAgreed) for (const key of Object.keys(hashes)) if (key.startsWith('@uniweb/site-content ')) delete hashes[key]
2232
2310
  const prior = readSyncCache(siteDir, backend)
2233
2311
  const keep = (key) => {
2234
2312
  if (Object.hasOwn(prior, key)) hashes[key] = prior[key]
@@ -98,6 +98,9 @@ import {
98
98
  readSyncCache,
99
99
  readBaseVersions,
100
100
  readItemBaseVersions,
101
+ readHeldUnits,
102
+ refuseChangedHeld,
103
+ noteHeldLeftOut,
101
104
  ensureItemUuids,
102
105
  readFolderItemUuids,
103
106
  readRecordItemUuids,
@@ -665,7 +668,9 @@ export async function publish(args = []) {
665
668
  // Placement identity for the folder — see writeFolderItemUuids.
666
669
  folderItemUuids: readFolderItemUuids(siteDir, client.origin),
667
670
  ...(foundationDir ? { foundationDir } : {}),
668
- resolveModel
671
+ resolveModel,
672
+ // What a pull held, for a page that changed since to stop the publish before anything goes up.
673
+ ...(args.includes('--force') ? {} : { heldUnits: readHeldUnits(siteDir, client.origin) })
669
674
  })
670
675
  } catch (err) {
671
676
  say.err(`Could not build the sync package: ${err.message}`)
@@ -676,6 +681,8 @@ export async function publish(args = []) {
676
681
  if (refuseUnsendableRecords(probe.refusals, { error: say.err, note: say.dim })) {
677
682
  return { exitCode: 1 }
678
683
  }
684
+ // …and so does a page a pull held whose files changed since (`refuseChangedHeld`).
685
+ if (refuseChangedHeld(probe, { error: say.err, note: say.dim })) return { exitCode: 1 }
679
686
  const schemalessNames = (probe.schemaless || []).map((col) => col.name)
680
687
  // A product decision the author is usually making unknowingly — say it at warn
681
688
  // level, not dim among everything else. See the helper for what the old
@@ -969,7 +976,9 @@ export async function publish(args = []) {
969
976
  ? {}
970
977
  : {
971
978
  baseVersions: readBaseVersions(siteDir, client.origin),
972
- itemBaseVersions: readItemBaseVersions(siteDir, client.origin)
979
+ itemBaseVersions: readItemBaseVersions(siteDir, client.origin),
980
+ // What a pull held is left out while its files still say it — see `uniweb push`.
981
+ heldUnits: readHeldUnits(siteDir, client.origin)
973
982
  }),
974
983
  ...(Object.keys(injectInfo).length ? { injectInfo } : {}),
975
984
  ...(Object.keys(ext.pins).length ? { injectExtensions: ext.pins } : {}),
@@ -996,6 +1005,8 @@ export async function publish(args = []) {
996
1005
  if (refuseUnsendableRecords(pkg.refusals, { error: say.err, note: say.dim })) {
997
1006
  return { exitCode: 1 }
998
1007
  }
1008
+ if (refuseChangedHeld(pkg, { error: say.err, note: say.dim })) return { exitCode: 1 }
1009
+ noteHeldLeftOut(pkg, { note: (m) => say.dim(m) })
999
1010
  // ⭐ `records` is what delivers the records the pages show on the published site — said
1000
1011
  // here, at publish, and never at push: syncing records does not depend on it.
1001
1012
  const notAsked = recordsNotAsked({ siteYml, shown: pkg.recordsShown })