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 +4 -4
- package/partials/guides/backend.md +60 -5
- package/partials/guides/ship.md +1 -1
- package/src/backend/site-published.js +142 -0
- package/src/commands/dev.js +42 -3
- package/src/commands/update.js +53 -1
- package/src/framework-index.json +4 -4
- package/src/index.js +6 -0
- package/src/utils/flag-guard.js +1 -1
- package/src/utils/lockfile-uniweb.js +43 -8
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "uniweb",
|
|
3
|
-
"version": "1.34.
|
|
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.
|
|
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
|
|
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
|
|
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.
|
package/partials/guides/ship.md
CHANGED
|
@@ -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
|
+
}
|
package/src/commands/dev.js
CHANGED
|
@@ -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(
|
|
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
|
|
package/src/commands/update.js
CHANGED
|
@@ -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 {
|
package/src/framework-index.json
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
|
-
"generatedAt": "2026-11-
|
|
3
|
+
"generatedAt": "2026-11-16T02:18:19.085Z",
|
|
4
4
|
"packages": {
|
|
5
5
|
"@uniweb/api": {
|
|
6
|
-
"version": "1.7.
|
|
6
|
+
"version": "1.7.1"
|
|
7
7
|
},
|
|
8
8
|
"@uniweb/build": {
|
|
9
|
-
"version": "1.23.
|
|
9
|
+
"version": "1.23.9"
|
|
10
10
|
},
|
|
11
11
|
"@uniweb/content-reader": {
|
|
12
|
-
"version": "1.5.
|
|
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
|
package/src/utils/flag-guard.js
CHANGED
|
@@ -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
|
-
|
|
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 (!
|
|
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
|
}
|