uniweb 1.31.1 → 1.31.3

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.31.1",
3
+ "version": "1.31.3",
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/content-writer": "~1.3.1",
44
+ "@uniweb/core": "~1.6.9",
45
45
  "@uniweb/semantic-parser": "~1.13.2",
46
46
  "@uniweb/schemas": "~1.7.0",
47
- "@uniweb/core": "~1.6.9"
47
+ "@uniweb/content-writer": "~1.3.1"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.20.1",
50
+ "@uniweb/semantic-parser": "~1.13.2",
51
51
  "@uniweb/content-reader": "~1.5.9",
52
- "@uniweb/semantic-parser": "~1.13.2"
52
+ "@uniweb/build": "~1.20.3"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -326,7 +326,7 @@ Every guide ships with the CLI this project pins, so it describes the version in
326
326
  | start a project, grow the workspace, learn from a template | `uniweb guide start` |
327
327
  | work with records, queries, `[slug]` pages, external APIs, schemas, Loom | `uniweb guide data` |
328
328
  | add search, forms, tracking, Google Analytics or Tag Manager, an assistant | `uniweb guide services` |
329
- | the site has accounts or member data (`services.backend`, `@uniweb/api`) | `uniweb guide backend` |
329
+ | the site has accounts or member data (`services.backend`, `blueprint.yml`, `@uniweb/api`) | `uniweb guide backend` |
330
330
  | add a language | `uniweb guide i18n` |
331
331
  | publish, deploy, push/pull, register, CI, workspaces, updates | `uniweb guide ship` |
332
332
  | port a React / Next / generated design | `uniweb guide migrate` |
@@ -58,7 +58,7 @@ await writer.update(item.id, { ...item.data, bio: 'Bonjour' }, { language: 'fr'
58
58
 
59
59
  Gate controls on what the viewer may do — a record's `can_edit` from a single-entity read — but never rely on that for safety: a foundation runs with the viewer's authority, so hiding a button hides a button. Not on `viewer.roles` alone: a session holds its roles as a reader's until elevated, so a gate on `system_admin` shows the operator nothing until then. Draw a role-acting control from `useElevation().rolesInFull` and let the record answer.
60
60
 
61
- What protects content is the **entry**: a member writes their own entries and not another's, enforced by the store. **Models are open** — anyone signed in may create entries of any Model. A schema protects how an item changes and who reads an entry:
61
+ What protects content is the **entry**: a member writes their own entries and not another's, enforced by the store. **Every type starts closed**: the operator adds its entries, and anyone else only where the site's `blueprint.yml` opens it (below). A schema protects how an item changes and who reads an entry:
62
62
 
63
63
  ```yaml
64
64
  # schemas/attendance.yml
@@ -81,6 +81,29 @@ fields:
81
81
 
82
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.
83
83
 
84
+ ## Who adds and reads each type: `blueprint.yml`
85
+
86
+ Beside `site.yml`, in a site whose `services` names `backend`: how a backend started from the site begins.
87
+
88
+ ```yaml
89
+ signup: invite_only # or open, the default: who may create an account
90
+ teams: # founded empty; people join them in the backend's administration
91
+ sales: { label: Sales }
92
+ access:
93
+ '@/vehicle':
94
+ add: [sales] # who adds entries: open (every signed-in account) · [teams] · [] (the operator alone)
95
+ all: { sales: edit } # every entry of the type, not only one's own: <team> or members → read | edit
96
+ '@/request': { add: open } # each member keeps their own
97
+ publicQueries: # what visitors who aren't signed in may read
98
+ '@/vehicle': { whole: true, where: { status: { in: [available, pending] } } } # whole is required; false = briefs
99
+ ```
100
+
101
+ - **Applied once**, when a backend is started from the site: its own, a clone's of a template, or one started again after it was destroyed. Then the operator changes these in the backend's administration. An edited file is pushed and pulled with the site, and reaches no backend already running.
102
+ - A type not listed stays closed. Name types as `queries.yml` does: `@/vehicle` for the foundation's own, sent in its scope.
103
+ - A build, a push and `uniweb doctor` refuse a malformed file, naming the key; a push refuses whole. A type none of the site's foundations declares only warns: a backend started from the site leaves that line out, and the publish says so. `where`, `sort` and `limit` are the backend's to judge, and one it refuses is left out the same way.
104
+ - A team's `all: edit` reaches the entries once the member confirms it is them (below); a team's `add` and `members: edit` need no confirming. Who is in a team, and roles, are never the file's.
105
+ - A static build carries none of it. A pull writes it back here, never into `site.yml`.
106
+
84
107
  ## Acting as an administrator
85
108
 
86
109
  An administrator's session reads what their role reaches and changes nothing through the role until they confirm it is them; their own records they edit as always.
@@ -152,8 +175,11 @@ $devBackend: ./mock/api.js # what answers in `uniweb dev`; `$` keys are never
152
175
 
153
176
  ```js
154
177
  // site/mock/api.js
178
+ import { fileURLToPath } from 'node:url'
155
179
  import { createMockBackend } from '@uniweb/api/mock'
156
- export default createMockBackend({ seed }).fetch
180
+ import { readBlueprint } from '@uniweb/build/blueprint'
181
+ const blueprint = readBlueprint(fileURLToPath(new URL('..', import.meta.url))) // the site's blueprint.yml
182
+ export default createMockBackend({ seed, blueprint }).fetch
157
183
  ```
158
184
 
159
- `uniweb dev` answers the `backend` service with it at an address on its own origin (cookies behave as in production). Write no address of your own: under `services:` an address means a backend you run. The mock **enforces** entry ownership and `append_only`; it doesn't model `readable_with`, `sold_with`, second factors or password rules. Mail it would send prints in the terminal with its link on the site's root. Seed `offers: [{ email, invitations: 1 }]` to try an invitation; a seeded entity takes `grants: { member: 'read' }`; `units: [{ handle, parent?, members, floor? }]` gives a create somewhere to land. The seed names your own types `@/track`. State is in memory; restart to reset. `uniweb create my-event --template conference` is a worked example.
185
+ `uniweb dev` answers the `backend` service with it at an address on its own origin (cookies behave as in production). Write no address of your own: under `services:` an address means a backend you run. The mock begins as a backend started from the site does: every type closed until the blueprint opens it, its `signup`, its teams (a seeded account names its own, `teams: ['sales']`). It **enforces** those, entry ownership and `append_only`; it doesn't model public queries, `readable_with`, `sold_with`, second factors or password rules. Mail it would send prints in the terminal with its link on the site's root. Seed `offers: [{ email, invitations: 1 }]` to try an invitation; a seeded entity takes `grants: { member: 'read' }`; `units: [{ handle, parent?, members, floor? }]` gives a create somewhere to land. The seed names your own types `@/track`. State is in memory; restart to reset. `uniweb create my-event --template conference` is a worked example.
@@ -108,7 +108,7 @@ When `status` names a newer release, take it: update, restart any running dev se
108
108
  | `[dir]` / `[path]` as parametric folder names; a folder inside `[...path]/` | `[slug]`, `[uuid]`, `[<field>]`, `[...path]` |
109
109
  | `fonts.mono` | `fonts.code` |
110
110
  | `seo.baseUrl`; `seo.defaultImage`; `seo.locales`; `url:`, `trailingSlash:` in `site.yml` | `seo.origin` (scheme + host, no path); `seo.image`; `languages:`; `seo.origin` again |
111
- | `creatable_by` in a schema | models are open; protect with `append_only`, `readable_with`, `grantable` |
111
+ | `creatable_by` in a schema | who adds a type's entries is `blueprint.yml`'s `access.<type>.add`; a schema protects them with `append_only`, `readable_with`, `grantable` |
112
112
  | `uniweb.id`, `uniweb.scope` in a foundation's `package.json` | `name: '@scope/name'` in `main.js` |
113
113
  | `main.jsx`, `foundation.js`; JSX in a `.js` component | `main.js` (plain JS); `.jsx` |
114
114
  | `visuals:` in `meta.js`; `data` as a `content:` element | a `media:` element in `content:`; declare the tag in `data:` |
@@ -32,7 +32,7 @@ import {
32
32
  findPublicFavicon
33
33
  } from '@uniweb/build/site'
34
34
  import { listAdapters } from '@uniweb/build/hosts'
35
- import { RUNTIME_KEYS, writeSiteConfig } from '@uniweb/build/uwx'
35
+ import { RUNTIME_KEYS, writeSiteConfig, readBlueprint, refuseUnreadableBlueprint, blueprintWarnings, siteDeclaredTypes, siteSelfScope, BLUEPRINT_FILE } from '@uniweb/build/uwx'
36
36
  import { getCliVersion } from '../versions.js'
37
37
  import { readAgentsVersion } from '../utils/agents-stamp.js'
38
38
  import { writeJsonPreservingStyle } from '../utils/json-file.js'
@@ -1257,6 +1257,41 @@ export async function checkSiteAddress({ sitePath, siteName, siteYml, workspaceD
1257
1257
  log(` ${colors.dim}${without}${colors.reset}`)
1258
1258
  }
1259
1259
 
1260
+ /**
1261
+ * `blueprint.yml` — how a backend started from the site begins. What a build and a push would refuse
1262
+ * is an error; a line a backend would leave out — a type none of the site's foundations declares — a
1263
+ * warning, as the push says it; and a blueprint whose types could not be checked here, a note saying
1264
+ * why, since a clean report would otherwise read as checked.
1265
+ */
1266
+ export async function checkBlueprint({ sitePath, siteName, siteYml, issues }) {
1267
+ let blueprint
1268
+ try {
1269
+ blueprint = readBlueprint(sitePath)
1270
+ refuseUnreadableBlueprint(blueprint, { siteYml })
1271
+ } catch (err) {
1272
+ const id = 'blueprint-unreadable'
1273
+ const message = err.message.replace(/^\[uniweb\] /, '')
1274
+ issues.push({ id, type: 'error', site: siteName, message })
1275
+ error(`[${id}] ${message}`)
1276
+ return
1277
+ }
1278
+ if (!blueprint) return
1279
+ const scope = await siteSelfScope(sitePath)
1280
+ const declared = await siteDeclaredTypes(sitePath, siteYml, { scope })
1281
+ for (const line of blueprintWarnings(blueprint, { scope, declared })) {
1282
+ const id = 'blueprint-leaves-out'
1283
+ issues.push({ id, type: 'warn', site: siteName, message: line })
1284
+ warn(`[${id}] ${line}`)
1285
+ }
1286
+ const namesTypes = ['access', 'publicQueries'].some((key) => blueprint[key] && Object.keys(blueprint[key]).length)
1287
+ if (namesTypes && !declared.types) {
1288
+ const id = 'blueprint-types-unchecked'
1289
+ const message = `${BLUEPRINT_FILE}: its types were not checked against the site's foundations — ${declared.unread.join('; ')}`
1290
+ issues.push({ id, type: 'info', site: siteName, message })
1291
+ info(`[${id}] ${message}`)
1292
+ }
1293
+ }
1294
+
1260
1295
  // What a link preview draws, from the platforms' own pages, read 2026-10-27. Facebook
1261
1296
  // (developers.facebook.com/docs/sharing/webmasters/images): 1.91:1 shows the whole image, at least
1262
1297
  // 1200×630 for high-resolution screens and 600×315 for a large card, 8 MB at most. LinkedIn
@@ -2268,6 +2303,8 @@ async function runDoctor(args = []) {
2268
2303
  await checkFormSubmitTarget({ sitePath, siteName, siteYml, issues })
2269
2304
  checkAgentsBlock({ siteName, siteYml, issues })
2270
2305
  checkTrackingBlock({ siteName, siteYml, issues })
2306
+ // How a backend started from the site begins: what a push would refuse, and what a backend would leave out.
2307
+ await checkBlueprint({ sitePath, siteName, siteYml, issues })
2271
2308
 
2272
2309
  // `public/<DATA_DIR>/` is the build's output directory and nothing else —
2273
2310
  // `records/` is the only supported way to provide structured data. That makes the mapping a bijection: every entry there should be backed
@@ -1218,6 +1218,8 @@ export async function pull(args = [], deps = {}) {
1218
1218
  let notTaken = false
1219
1219
  // The languages the backend holds text in that the site does not list: not written (`documentLanguages`).
1220
1220
  let outsideLanguages = []
1221
+ // A `blueprint.yml` the pull left as it was, and why (`@uniweb/build/uwx`, `writePulledBlueprint`).
1222
+ let blueprintKept = null
1221
1223
  try {
1222
1224
  if (siteDoc) {
1223
1225
  // Re-base the page attribution. The pulled document IS the backend's own
@@ -1294,6 +1296,7 @@ export async function pull(args = [], deps = {}) {
1294
1296
  mountRoutes = report.mountRoutes || []
1295
1297
  mountedMoved = mountedPagesMoved(mountedPages, pulledVersions, priorVersions)
1296
1298
  outsideLanguages = report.outsideLanguages || []
1299
+ blueprintKept = report.config?.blueprint?.file === 'kept' ? report.config.blueprint.note : null
1297
1300
  // ⭐ WHAT IT HELD, AS THE FILES KEEP IT — where each held page is in the files it wrote into, the
1298
1301
  // stand-in in a repository, and what they say there — for a push to leave out while they still
1299
1302
  // say it (`readHeldUnits`). Replaced by each pull that takes the site's content. In the stand-in's
@@ -1703,6 +1706,8 @@ export async function pull(args = [], deps = {}) {
1703
1706
  // ⭐ A mounted folder's pages are as current as its repository, which no pull moves.
1704
1707
  for (const line of await behindLines(siteDir)) note(line)
1705
1708
  }
1709
+ // ⭐ Said, since the file and the site now differ: the file is the author's, and the next push sends it.
1710
+ if (blueprintKept) note(blueprintKept)
1706
1711
  // ⭐ Said, because the text is not in a translation file: one would make the language the site's,
1707
1712
  // and the next publish would ask to serve it (`uwx/source-locale.js`). It is kept for the push to
1708
1713
  // send back (`locales/_kept.json`), since a language removed in the app keeps its translations.
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-09T20:11:18.154Z",
3
+ "generatedAt": "2026-11-09T23:18:54.820Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
- "version": "1.6.10"
6
+ "version": "1.7.0"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.20.1"
9
+ "version": "1.20.3"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.9"
@@ -54,7 +54,7 @@
54
54
  "version": "1.1.2"
55
55
  },
56
56
  "@uniweb/templates": {
57
- "version": "1.2.10"
57
+ "version": "1.2.11"
58
58
  },
59
59
  "@uniweb/theming": {
60
60
  "version": "1.3.2"