uniweb 1.34.10 → 1.34.12

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.10",
3
+ "version": "1.34.12",
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/semantic-parser": "~1.13.5",
45
44
  "@uniweb/core": "~1.6.13",
45
+ "@uniweb/semantic-parser": "~1.13.5",
46
46
  "@uniweb/schemas": "~1.7.4",
47
47
  "@uniweb/content-writer": "~1.3.2"
48
48
  },
49
49
  "peerDependencies": {
50
+ "@uniweb/build": "~1.23.9",
50
51
  "@uniweb/semantic-parser": "~1.13.5",
51
- "@uniweb/content-reader": "~1.5.10",
52
- "@uniweb/build": "~1.23.8"
52
+ "@uniweb/content-reader": "~1.5.11"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -43,6 +43,16 @@ await writer.remove(itemId)
43
43
  - Ordering is the server's; never compute an order number.
44
44
  - `writer.conflict` is reported, not retried — a retry would overwrite a change nobody looked at. Tell the person.
45
45
 
46
+ ## Rich text a member writes
47
+
48
+ ```jsx
49
+ import { useRichTextEditor, RichTextContent } from '@uniweb/api/rich-text' // TipTap 3.x, an optional peer: install it, load the editor lazily
50
+ const editor = useRichTextEditor({ value, onChange }) // onChange(doc): each change as a backend stores it
51
+ <RichTextContent editor={editor} /> // your toolbar: editor.chain().focus().toggleBold().run()
52
+ ```
53
+
54
+ Its document model is the stored vocabulary: it edits what TipTap's kit does, with a divider for the rule and no underline, and keeps everything else a stored text holds. Don't configure TipTap yourself for a rich-text field: what it makes beyond the vocabulary is left out when saved, which the mock prints.
55
+
46
56
  ## Translated fields
47
57
 
48
58
  A `localized` field holds `{ en: '…', fr: '…' }` or one plain value for every language; a read answers in the page's language. Never write that one value back as the whole field — it becomes every language's value.
@@ -56,7 +66,7 @@ await writer.update(item.id, { ...item.data, bio: 'Bonjour' }, { language: 'fr'
56
66
 
57
67
  ## Permissions are the server's; your UI is a courtesy
58
68
 
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.
69
+ Gate controls on what the viewer may do — `mayDo(entry, 'edit' | 'delete' | 'share')` on a record or a list row, `useMayCreate({ schemas })` for a type, each `'now'`, `'once-elevated'` (confirm it is them first, then act), `'no'` or `null` (not told: offer it) — 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
70
 
61
71
  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
72
 
@@ -107,6 +117,44 @@ integrations: # by a mapping the foundation declares in src/mappi
107
117
  - 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.
108
118
  - A static build carries none of it. A pull writes it back here, never into `site.yml`.
109
119
 
120
+ ## Your admin area, and the admin app
121
+
122
+ A site with a backend is a solution: public pages, a members' area for each role, and an **admin area** for the people who run it — its staff, its instructors. You build the admin area: section types of your foundation, branded, in the solution's own words, with what follows. The **admin app** is the backend's own administration, the same for every site: the payment account, the teams and who is in them, roles, an integration's address and keys, the store's offerings and coupons. Never rebuild those; link to it (`adminHref`, below). The docs' Building a Solution page walks the whole path.
123
+
124
+ ## Selling
125
+
126
+ ```jsx
127
+ import { useStore, offeringState, useEntitlements, useHolders } from '@uniweb/api'
128
+ const { status, store, offerings, checkout, checking } = useStore({ entity: course.uuid }) // 'none': the site sells nothing
129
+ offeringState(offering, store) // 'owned' · 'take' (a free one-off) · 'not-ready' (payments not connected) · 'buy'
130
+ await checkout(offering) // sends the buyer to pay; a free one-off is held at once: { url: null, held: true }
131
+ ```
132
+
133
+ - The owner sets the offerings, and connects their own Stripe account, in the admin app. `price` is in the currency's smallest unit. Nobody signed in → `absent`: the store is a signed-in member's to read.
134
+ - After paying, the buyer lands on `successUrl` (this page by default). The purchase is written when the payment's notice arrives, so the page there calls `refresh()` until the offering reads `owned`.
135
+ - A purchase lets the buyer read the record, and through it what its `sold_with` references point to: `useEntity({ schema: '@/lesson', uuid, via: course.uuid })`.
136
+ - `useEntitlements()` — what the viewer holds, for "My courses". `useHolders({ schema, uuid })` — who holds a record, for a roster: its owner's or an `admin`'s to read, `forbidden` for anyone else, so draw nothing.
137
+ - Why a checkout was refused: `error.extensions.reason` — `payments_not_ready`, `coupon_not_applicable` (with `cause`), `not_for_sale`.
138
+
139
+ ## The inbox
140
+
141
+ ```jsx
142
+ const { unread } = useNotifications({ every: 60_000, list: false }) // a badge, polled lightly
143
+ const { notifications, markRead, dismiss, markAllRead } = useNotifications() // the rows, when opened
144
+ ```
145
+
146
+ Each row is as the backend sends it (`kind`, `payload`, `read_at`, …). For `kind: 'entity_shared'`, `payload` is `{ entity_uuid, entity_model, permission, actor_handle }`. The kinds grow: draw those you know, pass over the rest. There is no push: poll the count, and read the list when it is opened.
147
+
148
+ ## Signing in and up
149
+
150
+ ```jsx
151
+ const { options } = useSignInOptions() // providers, signup, email_sign_in; password: { min_length } and email_code: { length, lifetime_minutes }, each present only while offered
152
+ const { signIn, completeChallenge, resendVerification } = useSignIn() // username, @handle or address
153
+ const code = useEmailSignIn() // where options.email_code: request({ email }) → confirm(code); one door for new and returning members
154
+ ```
155
+
156
+ Draw each way only where `options` states it. After a provider, `useSignIn().returned` says what came back (`signed-in`, `link`, `error` with its `reason`); after signing in, go to `signInReturnPath()` — the `?next=` path, never another site — or your default. `useFeedback().send({ message, kind, rating })` sends a member's feedback to the site's administrators. The backend answers an emailed code's request alike for every address, and the confirming code makes the account of an address that has none. Every refusal names `error.extensions.reason` with the values a message needs (`password_too_short` and `min_length`, `email_code_wrong` and `tries_left`, `email_code_throttled` and `retry_after_seconds`, …): `ACCOUNT_REASON` in `@uniweb/api/wire` lists them. The words are the foundation's, from content.
157
+
110
158
  ## Acting as an administrator
111
159
 
112
160
  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.
@@ -116,6 +164,7 @@ const { available, elevated, until, elevate, lower, error } = useElevation()
116
164
  // available: the account holds a role that does more than read — offer it only then
117
165
  // elevate({ password, code }) — code when the account has a second factor; refusal: error.kind === 'auth'
118
166
  // elevated turns false at `until`; lower() ends early; elevateWithProvider(provider) for a passwordless account
167
+ // ways: { password, emailCode } — an account made by an emailed code: requestCode(), then elevateWithCode({ code })
119
168
  ```
120
169
 
121
170
  While elevated, `viewer.roles` names the role and every record read before is read again. Nothing says whether the account has a second factor — offer the code field. It does not open the backend's administration — the Admin link does:
@@ -129,14 +178,14 @@ const { adminHref } = useSession()
129
178
 
130
179
  ## Mailed links, invitations, access, units
131
180
 
132
- **Mailed links** (sign-up confirmation `?verify=`, password reset `?reset=`, invitation `?offer=`) arrive at the site's root; the landing page finishes the step:
181
+ **Mailed links** (sign-up confirmation `?verify=`, password reset `?reset=`, invitation `?offer=`, an emailed code's sign-in `?signin=`) arrive at the site's root; the landing page finishes the step:
133
182
 
134
183
  ```jsx
135
184
  const { step, status, result, error, confirm } = useMailedLink()
136
- // step: null | 'verify' | 'reset' | 'offer' status: 'idle' | 'working' | 'done' | 'error'
185
+ // step: null | 'verify' | 'reset' | 'offer' | 'signin' status: 'idle' | 'working' | 'done' | 'error'
137
186
  ```
138
187
 
139
- `verify` finishes by itself. `reset` waits for `confirm({ new_password })` (`error.extensions.reason === 'password_too_short'`; the link works again). `offer` waits for a sign-in then claims; `result` is counts `{ invitations, grants }`; `error.kind === 'absent'` means unknown, revoked or used, alike — one sentence, no cause. Render it where the root renders (a header or layout). Never copy the token anywhere.
188
+ `verify` finishes by itself. `reset` waits for `confirm({ new_password })` (`error.extensions.reason === 'password_too_short'`; the link works again). `offer` waits for a sign-in then claims; `result` is counts `{ invitations, grants }`; `error.kind === 'absent'` means unknown, revoked or used, alike — one sentence, no cause. `signin` waits for a click: `confirm()` signs in — never on load, which a mail scanner's prefetch would spend. Render it where the root renders (a header or layout). Never copy the token anywhere.
140
189
 
141
190
  **Invitations** wait for the member's answer, mailed link or not:
142
191
 
@@ -165,6 +214,8 @@ const { units } = useUnits() // [{ unit, id, handle?, name?, parent?, depth, p
165
214
  await createEntity({ schema: '@/submission', unit: course.unit, items: [...] })
166
215
  ```
167
216
 
217
+ **A unit's staff**, for its administrator on an elevated session (`absent` before): `useUnitStaff({ unit })` lists the roles and `give({ account, role })` / `take(…)` them (`content_reader`, `content_editor`, `unit_admin` — the last only to someone placed in the unit, with a second factor), and `archive()` / `restore()` the unit, whose content then reads and changes for no one (`unit_archived`). `useUnitEntryGrants({ unit, schema })` gives a type's entries there to `{ account }`, `{ team }` or `{ members: true }`.
218
+
168
219
  Nested items in one create: give an item `uuid: uuidv7()` and a later item names it as `parent` (`{ section: 'degrees/thesis', parent: degree, data }`); those uuids serve the write alone.
169
220
 
170
221
  ## A backend on your machine
@@ -185,4 +236,8 @@ const blueprint = readBlueprint(fileURLToPath(new URL('..', import.meta.url)))
185
236
  export default createMockBackend({ seed, blueprint }).fetch
186
237
  ```
187
238
 
188
- `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.
239
+ `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`, and lets a buyer read through what they hold to what its `sold_with` references point to. It gives the backend's refusal reasons, holds passwords to 8 characters, signs in by emailed code, keeps rich text to the stored vocabulary, and staffs and archives units; it doesn't model public queries, `readable_with` or second factors (a seeded `twoFactor: true` stands for one). 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. `store: { info, offerings: [{ entry: <a seeded uuid>, price }] }`, `coupons`, `entitlements: [{ username, entity }]` and `notifications: [{ to, from?, payload }]` try selling and the inbox: a priced checkout opens a payment page of the mock's own, which takes no payment, and giving someone access adds a row to their inbox. The seed names your own types `@/track`. State is in memory; restart to reset, or `getClient().request('POST', '/_mock/reset')` for a demo's "start over" (the mock's own route). `uniweb create my-event --template conference` is a worked example.
240
+
241
+ ## Against the site as published
242
+
243
+ The mock is for working with no backend at hand; where it and the backend differ, the backend is right. Once the site is published to the backend you are logged in to, a local one included, `uniweb dev --published` serves this copy (its foundation and pages, with live reload) against the published site's services. Members sign in to its real backend and may do what it enforces, and pages show the records its visitors see, the entries its public queries open included. The dev server reads the service addresses from the published page and forwards each request, so the page talks to one origin and sign-in cookies behave as on the published site; `$devBackend` is not mounted. Under `--published` the copy sends its own types in full (`@acme/track`), as a build does, so the backend answers for the types it holds: one you add reaches it when you publish again. Record files reach the page through `uniweb push`, which a published site serves at once. It is the published site's real data, members' entries included, and the output says so.
@@ -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
 
@@ -0,0 +1,142 @@
1
+ /**
2
+ * What `uniweb dev --published` reads before serving a working copy against the site as published.
3
+ *
4
+ * A published site's services — its own `backend`, its `records`, its forms — are answered by its
5
+ * host, at addresses the host chooses and states in the page it serves. So this asks the backend you
6
+ * are logged in to where the site is published (its status, the address `uniweb status` shows),
7
+ * reads the published page, and takes the host's services block from the data the page boots from
8
+ * (`__DATA__`, `content.config.services`). The dev server is handed it in `UNIWEB_PUBLISHED`
9
+ * (`@uniweb/build/site`'s `published.js` has the contract) and answers each service by forwarding
10
+ * to it.
11
+ *
12
+ * ⭐ Read, never composed: the addresses are the ones the published page carries, so whatever
13
+ * serves the site — on this machine or not — is what the working copy talks to.
14
+ *
15
+ * ⛔ Nothing here is kept. The answer lives as long as the dev server, and no file a push, pull or
16
+ * build reads gets an address from it.
17
+ */
18
+ import { gunzipSync } from 'node:zlib'
19
+ import { readBackendState } from '@uniweb/build/uwx'
20
+ import { BackendClient } from './client.js'
21
+ import { resolveWorkspace } from './workspace.js'
22
+ import { liveAddress } from './live-address.js'
23
+ import { syncedBackends } from '../utils/site-identity.js'
24
+
25
+ /**
26
+ * What the dev server of `siteDir` is handed under `--published`.
27
+ *
28
+ * @param {object} p
29
+ * @param {string} p.siteDir
30
+ * @param {string[]} [p.args]
31
+ * @param {BackendClient} [p.client] - injected in tests
32
+ * @param {typeof fetch} [p.fetchPage] - injected in tests
33
+ * @returns {Promise<{ published: { site: string, backend: string, base: string|null, services: object } }
34
+ * | { refused: string[] }>}
35
+ */
36
+ export async function readSitePublished({ siteDir, args = [], client = null, fetchPage = globalThis.fetch }) {
37
+ client = client || new BackendClient({ args, command: 'Testing against' })
38
+ const uuid = readBackendState(siteDir, client.origin).site?.uuid
39
+ if (!uuid) {
40
+ const known = syncedBackends(siteDir)
41
+ return {
42
+ refused: [
43
+ '`--published` serves this copy against the site as published from the backend you are logged in to, and the site is not on it.',
44
+ known.length
45
+ ? `The site is on ${known.join(', ')}, not on ${client.origin}. To use it: uniweb login --server <url>`
46
+ : `Publish it there first: uniweb publish`
47
+ ]
48
+ }
49
+ }
50
+
51
+ const ws = await resolveWorkspace({ client, args })
52
+ if (ws.refused) return { refused: ['`--published` reads the site in one workspace, and none is chosen.', ws.reason] }
53
+ client.setWorkspace(ws.workspace, { source: ws.source })
54
+
55
+ let status
56
+ try {
57
+ status = await client.siteStatus(uuid)
58
+ } catch (err) {
59
+ return { refused: [err.message] }
60
+ }
61
+ if (!status) return { refused: [`Could not read this site's status on ${client.origin}, so its published address is unknown.`] }
62
+ const address = liveAddress(status.visitor_url, status.last_published_url)
63
+ if (status.published === false || !address) {
64
+ return { refused: ['This site is not published, so it has no published services to test against.', 'Publish it first: uniweb publish'] }
65
+ }
66
+
67
+ let page
68
+ try {
69
+ page = await readPublishedPage(address, fetchPage)
70
+ } catch (err) {
71
+ return { refused: [`Could not read the site as published at ${address}: ${err.message}`] }
72
+ }
73
+ const config = page.data?.content?.config
74
+ const services = config?.services
75
+ if (!services || typeof services !== 'object' || Array.isArray(services)) {
76
+ return {
77
+ refused: [
78
+ `The site as published at ${page.url} offers no services, so there is nothing to test against.`,
79
+ 'Without --published, uniweb dev answers them itself.'
80
+ ]
81
+ }
82
+ }
83
+ return {
84
+ published: {
85
+ site: page.url,
86
+ backend: client.origin,
87
+ base: typeof config.base === 'string' ? config.base : null,
88
+ services
89
+ }
90
+ }
91
+ }
92
+
93
+ /**
94
+ * The published page at `address`, and the data it boots from.
95
+ *
96
+ * @param {string} address
97
+ * @param {typeof fetch} fetchPage
98
+ * @returns {Promise<{ url: string, data: object }>} `url` is the page's address after redirects,
99
+ * which its own relative addresses are read against
100
+ */
101
+ async function readPublishedPage(address, fetchPage) {
102
+ const res = await fetchPage(address, { headers: { accept: 'text/html' }, redirect: 'follow' })
103
+ if (!res.ok) throw new Error(`HTTP ${res.status}`)
104
+ const data = readDataScript(await res.text())
105
+ if (!data) throw new Error('the page carries no site data (`__DATA__`)')
106
+ return { url: res.url || address, data }
107
+ }
108
+
109
+ /**
110
+ * The boot data a host writes into a page's shell — `<script id="__DATA__">`, as JSON, or as
111
+ * base64 gzip when its type says so (the runtime's `decodeData` reads both).
112
+ *
113
+ * @param {string} html
114
+ * @returns {object|null}
115
+ */
116
+ export function readDataScript(html) {
117
+ for (const [, attributes, text] of html.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/gi)) {
118
+ if (!/\bid\s*=\s*["']__DATA__["']/i.test(attributes)) continue
119
+ const type = /\btype\s*=\s*["']([^"']+)["']/i.exec(attributes)?.[1] ?? 'application/json'
120
+ const body = text.trim()
121
+ return type === 'application/json'
122
+ ? JSON.parse(body)
123
+ : JSON.parse(gunzipSync(Buffer.from(body, 'base64')).toString('utf8'))
124
+ }
125
+ return null
126
+ }
127
+
128
+ /**
129
+ * Whether an address is on this machine — what decides if `uniweb dev --published` warns that
130
+ * the data it works with is real.
131
+ *
132
+ * @param {string} address
133
+ * @returns {boolean}
134
+ */
135
+ export function isOnThisMachine(address) {
136
+ try {
137
+ const { hostname } = new URL(address)
138
+ return hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '127.0.0.1' || hostname === '[::1]'
139
+ } catch {
140
+ return false
141
+ }
142
+ }
@@ -15,6 +15,15 @@
15
15
  * uniweb dev --port <n> On that port, or not at all
16
16
  * uniweb dev --status Print the running dev server's address
17
17
  * uniweb dev --stop Stop the running dev server
18
+ * uniweb dev --published This copy, against the services of the site as published
19
+ *
20
+ * ⭐ `--published` SERVES THE WORKING COPY AGAINST THE SITE AS PUBLISHED. Its foundation and pages
21
+ * are this copy's, with live reload; its services — its own backend, its records, its forms — are
22
+ * the published site's, read from the page the host serves and forwarded by the dev server, so a
23
+ * member signs in to the real site backend and a page shows the records a visitor sees, the
24
+ * entries its public queries open included (`backend/site-published.js`). A flag, not a key in
25
+ * `site.yml`, because it needs a published site, and a committed key would make every copy's
26
+ * `uniweb dev` need one.
18
27
  *
19
28
  * ⭐ THE DEV SERVER SAYS WHERE IT IS; NOTHING GUESSES. It takes a free port (Vite moves past a
20
29
  * busy one), and once it listens, the server `dev` starts — only that one — records the address
@@ -88,7 +97,7 @@ const VALUE_FLAGS = ['--site', '--port', '--org']
88
97
  * whether to report on the running server or stop it rather than start one.
89
98
  *
90
99
  * @param {string[]} args
91
- * @returns {{ site: string|null, port: number|null, status: boolean, stop: boolean, error?: string }}
100
+ * @returns {{ site: string|null, port: number|null, status: boolean, stop: boolean, published: boolean, error?: string }}
92
101
  */
93
102
  export function readDevArgs(args) {
94
103
  let positional = null
@@ -102,7 +111,8 @@ export function readDevArgs(args) {
102
111
  site: typeof siteFlag === 'string' ? siteFlag : positional,
103
112
  port: null,
104
113
  status: args.includes('--status'),
105
- stop: args.includes('--stop')
114
+ stop: args.includes('--stop'),
115
+ published: args.includes('--published')
106
116
  }
107
117
  const port = readFlagValue(args, '--port')
108
118
  if (port !== undefined) {
@@ -115,6 +125,9 @@ export function readDevArgs(args) {
115
125
  if (wanted.status && wanted.stop) {
116
126
  return { ...wanted, error: '`--status` and `--stop` ask for different things; pass one.' }
117
127
  }
128
+ if (wanted.published && (wanted.status || wanted.stop)) {
129
+ return { ...wanted, error: '`--published` starts a dev server, and `--status` and `--stop` ask about the running one; pass one.' }
130
+ }
118
131
  return wanted
119
132
  }
120
133
 
@@ -217,7 +230,11 @@ export async function dev(args = []) {
217
230
  process.exit(1)
218
231
  }
219
232
  console.error(`${GREEN}✓${RESET} ${site.name} is already being served at ${CYAN}${running.url}${RESET} (pid ${running.pid}).`)
220
- console.error(' Stop it with: uniweb dev --stop')
233
+ console.error(
234
+ wanted.published
235
+ ? ' To serve it with --published instead, stop it first: uniweb dev --stop'
236
+ : ' Stop it with: uniweb dev --stop'
237
+ )
221
238
  return
222
239
  }
223
240
 
@@ -253,6 +270,28 @@ export async function dev(args = []) {
253
270
  `${DIM}→ Previewing with ${asked.preview.foundation.ref}, served by ${asked.preview.backend}${RESET}`
254
271
  )
255
272
  }
273
+ // ⭐ `--published`: the services of the site as published, read from the page its host serves,
274
+ // for this dev server alone (`backend/site-published.js`).
275
+ if (wanted.published) {
276
+ const { readSitePublished, isOnThisMachine } = await import('../backend/site-published.js')
277
+ const got = await readSitePublished({ siteDir: sitePath, args })
278
+ if (got.refused) {
279
+ console.error(`${RED}✗${RESET} ${got.refused[0]}`)
280
+ for (const line of got.refused.slice(1)) console.error(` ${line}`)
281
+ process.exit(1)
282
+ }
283
+ const { PUBLISHED_ENV, encodePublished } = await import('@uniweb/build/site')
284
+ env = { ...env, [PUBLISHED_ENV]: encodePublished(got.published) }
285
+ const names = Object.keys(got.published.services)
286
+ console.error(
287
+ `${DIM}→ This copy, against the site as published at ${got.published.site}: ${names.join(', ') || 'no services'}${RESET}`
288
+ )
289
+ if (!isOnThisMachine(got.published.site)) {
290
+ console.error(
291
+ `${YELLOW}⚠${RESET} That site is not on this machine, so what you do here reads and changes its real data.`
292
+ )
293
+ }
294
+ }
256
295
  // That port or none: the dev server refuses to move past it (`dev-server.js`).
257
296
  if (wanted.port !== null) env = { ...env, [DEV_PORT_ENV]: String(wanted.port) }
258
297
 
@@ -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 {
@@ -1,15 +1,15 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-13T06:00:46.139Z",
3
+ "generatedAt": "2026-11-16T02:18:19.085Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
- "version": "1.7.0"
6
+ "version": "1.7.1"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.23.8"
9
+ "version": "1.23.9"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
- "version": "1.5.10"
12
+ "version": "1.5.11"
13
13
  },
14
14
  "@uniweb/content-writer": {
15
15
  "version": "1.3.2"
package/src/index.js CHANGED
@@ -1672,6 +1672,12 @@ ${colors.bright}Usage:${colors.reset}
1672
1672
  uniweb dev --port <n> On that port, or not at all
1673
1673
  uniweb dev --status Print the running dev server's address
1674
1674
  uniweb dev --stop Stop the running dev server
1675
+ uniweb dev --published This copy, against the services of the site as published
1676
+
1677
+ \`--published\` serves your foundation and pages, with live reload, against
1678
+ the services of the site as you published it to the backend you are logged
1679
+ in to: members sign in to its real backend, and pages show the records its
1680
+ visitors see. Without it, \`$devBackend\` and your record files answer.
1675
1681
 
1676
1682
  The dev server takes a free port and says where it is: once it listens,
1677
1683
  \`dev\` prints \`Serving <site> at <url>\`. Don't assume a port: another
@@ -145,7 +145,7 @@ const VERBS = {
145
145
  * `flag-guard-coverage.test.js`'s walk does not see it). ⛔ Until 2026-10-25 `dev` checked
146
146
  * no flags, and read the value of `--port 5199` as the name of a site.
147
147
  */
148
- dev: ['--site', '--port', '--status', '--stop', '--org', '--personal'],
148
+ dev: ['--site', '--port', '--status', '--stop', '--published', '--org', '--personal'],
149
149
  // Prints a file: a flag it doesn't know is a typo, not a backend it might reach.
150
150
  guide: ['--path']
151
151
  }
@@ -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
  }