@hozu/cli 0.21.1 → 0.23.0

package/skill/example/features/bookmarks/views.ts

@@ -75,9 +75,8 @@ export const Board = ui.view({
           ui.a(
             {
               href: ui.link(home, null, { show: s.value }),
-              'aria-current': search.show === s.value,
               class:
-                'rounded-full border px-3 py-1 aria-[current=true]:bg-indigo-600 aria-[current=true]:text-white',
+                'rounded-full border px-3 py-1 aria-[current=page]:bg-indigo-600 aria-[current=page]:text-white',
             },
             [s.label],
           ),

package/skill/topics/data.md

@@ -50,6 +50,7 @@ export default app({ resolvers: resolvers(project, (implement) => [
   shows it, also from the browser. `'live'` is for data your own mutations change. A refresh the visitor controls
   (a button, Pause / Resume) is `refresh: () => [tag()]` on a machine transition (`hozu docs machine`).
 - Call a `fn` from views or machines: `ui.each(visible({ items, show: ctx.show }), 'id', …)`.
+- **A database** (pool, migrations, numeric ids): see --more.
 
 <!-- more -->
 
@@ -73,3 +74,79 @@ export default app({ resolvers: resolvers(project, (implement) => [
   defaults and transforms applied.
 - Every mutation also has `Invalid` = `{ message, fields }` (input failing its schema, or
   `fail('Invalid', { message, fields: { title: 'Taken' } })`); never declare `Invalid` or `Unexpected` yourself.
+
+## Resolvers in another language (Go)
+Only when the person asks for it or the service already exists in Go: TypeScript resolvers are the default and need
+no second process. `remote()` sends server effects to a service over HTTP; everything else (access, caching, tags,
+the output schema check) stays in the Hozu server, so a wrong answer is `Unexpected`, never a wrong page.
+```ts
+import { remote, resolvers } from '@hozu/data'
+export default app({
+  resolvers: resolvers(project, (implement) => [
+    implement(me, (_, { session }) => ({ name: session?.user ?? '' })),
+    ...remote(
+      {
+        url: { env: 'NOTES_SERVICE_URL' },
+        secret: { env: 'NOTES_SERVICE_SECRET' },
+        contract: new URL('./service/hozu/contract.go', import.meta.url),
+      },
+      [listNotes, addNote],
+    ),
+  ]),
+})
+```
+- The loop: change the declaration in TypeScript → `npx hozu gen` (writes the contract: types, the `Resolvers`
+  interface, `Handler`) → implement the interface until `go test ./...` passes → restart the service → `hozu check`.
+  A contract older than the declarations is HZ093 naming the changed effects; each effect has its own fingerprint, so
+  the service answers 409 only to calls of an effect that changed.
+- In Go: return a declared error as the error value (`hozu.NotesAddNoteDuplicate{Text: t}`), `hozu.Invalid{…}` for
+  input problems; `ctx.Session` is nil when signed out; `ctx.SetSession(…)` / `ctx.SignOut()` in mutations. Public
+  queries never receive the session. `ctx.File(token)` reads an upload, `ctx.Header` an endpoint's request headers
+  (no cookie), `ctx.Preview` preview mode. The secret is required (16+ characters, the same value on both sides,
+  HZ093): the service trusts the session it is sent, so serve `hozu.Handler(r, hozu.Options{Secret: …})` on a private
+  address (it refuses to start without one).
+- Any other Go error answers 500 with its first line, which reaches `onError` and `Unexpected` as a thrown TypeScript
+  error does, with the call's id (`x-hozu-call`) that the service's log line names
+  (`hozu: notes.listNotes (call 3fa2c1d0): …`). A service that is not running is `no service answers at <url>`.
+- `.meta({ title: 'Note' })` on a schema makes it one Go type wherever it appears; `z.int()` is `int64`, a plain
+  number `float64` (`hozu gen` notes number fields named like ids or counts); a string `z.enum` is a named type with
+  one constant per member (`hozu.OrderStatusPending`, named by its title or its field). Only `runs: 'server'` effects
+  and JSON endpoints can be remote (HZ093).
+- [`examples/notes-go`](https://github.com/olevatorr/Hozu/tree/main/examples/notes-go) is the reference: the notes
+  app with every resolver in Go. Its `service/main.go` is all a service needs besides the resolvers (`go.mod` is
+  yours; the contract's folder is the `hozu` package):
+```go
+func main() {
+	secret := os.Getenv("NOTES_SERVICE_SECRET") // the app's remote() secret, 16+ characters
+	addr := os.Getenv("NOTES_SERVICE_ADDR")     // the app's NOTES_SERVICE_URL is http://<addr>/effect
+	mux := http.NewServeMux()
+	mux.Handle("/effect", hozu.Handler(newResolvers(), hozu.Options{Secret: secret}))
+	server := &http.Server{Addr: addr, Handler: mux}
+	go func() {
+		if err := server.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
+			log.Fatal(err)
+		}
+	}()
+	stop, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer cancel()
+	<-stop.Done() // finish the calls in flight, then exit
+	ctx, done := context.WithTimeout(context.Background(), 5*time.Second)
+	defer done()
+	server.Shutdown(ctx)
+}
+```
+
+## A database
+- One pool per process, made in `app.ts`; close it in `app({ dispose: () => pool.end() })` so `hozu get`, `call` and
+  `browse` exit and `hozu serve` stops cleanly. Transactions belong in one mutation resolver (`BEGIN` … `COMMIT`).
+- Migrations and seed data are scripts in `package.json` (`"db:migrate": "node db/migrate.ts"`), idempotent, run
+  before `npm start`; the URL and password are server env (`project({ env: { server } })`, `hozu docs env`).
+- Route params and form fields are strings: a numeric id is `z.coerce.number()` in the query or mutation input
+  (a query input that fails its schema is a program error, reported to `onError` with the field).
+- Data the whole staff shares but only staff may read is `scope: 'user'` with `access` (it is never cached across
+  requests). Share one rule: `const staffOnly = part(({ session }) => session.role !== 'editor')`, then
+  `access: { allow: staffOnly }` on each effect.
+- A resolver may answer `fail('Forbidden', { message })` (a row deleted meanwhile, a check `access` cannot make);
+  with `access: 'signedIn'` its `session` is never null.
+- Another app writing the same database: give the reading app a signed `endpoint` that `invalidates` the tags, and
+  call it after a write (`hozu docs endpoints`).

package/skill/topics/diagnostics.md

@@ -97,3 +97,4 @@ around the rule. `npx hozu docs HZ083` prints one code: its cause, its fix and t
 | HZ090 (warning) | `access: 'anyone'` on a `scope: 'user'` query: every visitor, signed in or not, may read it | say who may read it (`'signedIn'`, `{ owner: { row, session } }`), or accept the warning with a reason |
 | HZ091 | a query with `owner` access returned rows the visitor does not own (reported at run time) | read only the visitor's rows in the resolver (filter by the session); production drops the extra rows and logs this |
 | HZ092 | a preview in `project({ previews })` no longer fits the app: data off its query output schema, an error the query does not declare, a route without a page, or a component use that does not build | update the preview to the current schema, error, page or component (previews are for people: they never ship) |
+| HZ093 | a `remote()` resolver that cannot answer: its generated contract is missing or stale, or it lists an effect the browser runs or a non-JSON endpoint | run `hozu gen` and rebuild the service; implement browser-run effects in fetch.ts and non-JSON endpoints in TypeScript |

package/skill/topics/http.md

@@ -18,4 +18,5 @@ http: {
 },
 ```
 Server options live in the app module: `app({ resolvers, session?, components?, onError?, csp?, og?, preview? })`.
-A strict CSP, `nosniff` and a cross-site POST check are on by default; `csp: { script: ['https://…'] }` adds sources.
+A strict CSP, `nosniff` and a cross-site POST check are on by default; `csp: { img: ['https://…'] }` adds sources
+(`script style img font connect frame media`).

package/skill/topics/machine.md

@@ -68,8 +68,7 @@ export const m = machine({
   }),
 })
 ```
-- A machine the next page shows too keeps its state across the page change (calm states only; fields the address
-  seeds come from the address).
+- Calm state follows the visitor to a page that shows the same view, and back to the same address.
 - **assign** values are event (`e`), result (`r`) or error fields, context, literals, operators and `fn()` calls.
 - **guard** conditions: a field (`() => ctx.auto`), comparisons, `&&`, `||`, `!`, or a boolean `fn()`.
 - **navigate** sends the browser to `ui.link(route, params, search?)` after the transition. It returns one link: to
@@ -79,9 +78,9 @@ export const m = machine({
 - **Shared transitions:** `machine({ on })` entries are copied into every state that has no `invoke`, is not final,
   and neither handles nor ignores the event itself. Without `target` they stay in the state they fire in; one
   contract covers every copy.
-- **Start from the URL:** a view with a `route` may declare `seed: ({ params, search }) => ({ q: search.q })`; the
-  page's machine then starts with those context fields (server render, hydration and no-JS posts alike). One view
-  per page may seed a machine (HZ048).
+- **Start from the URL or server data:** a view with a `route` may declare
+  `seed: ({ params, search, query }) => ({ q: search.q, email: query(me, {}).email })` (server render, hydration and
+  no-JS posts alike; a failed query leaves `initialContext`). One view per page may seed a machine (HZ048).
 - In an app with `site.locales`, machines never hold
   translated text (HZ041): store a code (`ctx.error = 'duplicate'`) and choose the message in the view. The
   scaffold does this in every app.

package/skill/topics/pages.md

@@ -11,7 +11,7 @@ export const docs = route({ path: '/docs/:path+', params: z.object({ path: z.arr
 - **Pages** go in `project({ routes: { home, itemPage }, pages: [...] })` (the whole config: see --more):
   `ui.page(home, { views: [Board], head: { render: () => ({ title: 'Items' }) } })`.
 - **Head from a query:** `head: { query: getItem, input: (params, locale) => ({ id: params.id }), render: (item) => ({ title:
-  item.title }), failed: { NotFound: 404 } }`. `failed` maps every declared error of the query (HZ051) to a route
+  item.title }), failed: { NotFound: 404 } }`. Both also get `search`. `failed` maps every declared error of the query (HZ051) to a route
   without params (303) or to `403`, `404` or `410`.
 - `head.render` fields: `title`, `description`, `type` (`'website' | 'article'`), `image`, `published`, `noindex`;
   any other is HZ014 (Open Graph, `twitter:card` and the JSON-LD are derived from these).

package/skill/topics/recipes.md

@@ -81,3 +81,26 @@ Run a fresh scaffold into a scratch app with `--with detail`, and copy the parts
 - Following the system needs no code: Tailwind's `dark:` classes (`bg-white dark:bg-slate-900`).
 - A switch the visitor chooses: a client component (`hozu docs components`) puts `dark` on `<html>` and keeps the
   choice in `localStorage`; `app.css` adds `@custom-variant dark (&:where(.dark, .dark *));`.
+
+## A shell shared by many pages (a back office)
+Pages are config, so a helper is the layout:
+```ts
+const staffHead = { query: me, render: (m) => ({ title: `${m.name} · Admin` }), failed: { Forbidden: signIn } }
+const staff = (route, View) => ui.page(route, { views: [Sidebar, View], head: staffHead })
+export default project({ /* … */ pages: [staff(orders, OrderList), staff(orderDetail, OrderPage), …] })
+```
+The sidebar's links mark the page shown with `aria-current` by themselves (`aria-[current]:font-bold`).
+
+## Screens with different state
+One machine per feature: an order list (filters, selection) and an order page (shipping, refund) are two features,
+`orders` and `order`, sharing declarations through `exports`. Each machine stays small and its contracts few.
+
+## A multi-step checkout that also works without JavaScript
+Each step is a state and each step's form posts only its own fields: after a native post the server renders the next
+step, and every form on that page carries the machine's state in a signed hidden field, so the next post continues
+from it (going back to edit a step too). Prefill from the member with
+`seed: ({ query }) => ({ email: query(me, {}).email })`.
+
+## A notice after saving
+A `notice` context field set in `done` and cleared by `after: [{ ms: 4000, target: 'idle' }]` on a `saved` state;
+the view shows `ctx.notice !== null && ui.p({ role: 'status' }, [ctx.notice])`. There is no global toast store.

package/skill/topics/testing.md

@@ -7,8 +7,8 @@
   `hozu call api.who --input '{"room":"a"}' --header 'Authorization: Bearer t'` (a POST needs `--write`).
 - **Drive the app in a real browser, still without a server:**
   `hozu browse / --session '{"user":"ada"}' --do 'fill New note=Milk' --do 'press Enter' --do 'click Pin in "Milk"'`.
-  - Steps: `fill <label>=<value>`, `select <label>=<option>`, `check` / `uncheck <label>`, `click <name>`,
-    `submit "<form>"`, `press <key>`, `wait <ms>`, `goto <path>`, `post <path> a=1&b=2`,
+  - Steps: `fill <label>=<value>` (`\n`, `\t` work), `select <label>=<option>`, `check` / `uncheck <label>`,
+    `click <name>`, `submit "<form>"`, `press <key>`, `wait <ms>`, `goto <path>`, `post <path> a=1&b=2`,
     `remember <name> from url|<selector> [@attr]` (later steps read `$name`); a target may end with `in "<text>"`
     (for fill and select, before or after `=value`).
   - Labels are what `hozu get <page> --forms` lists; a missing one prints `Did you mean "…"?`. One `--do` may hold
@@ -29,8 +29,12 @@
 
 <!-- more -->
 
-- **A calm page:** a step that rebuilds elements unchanged says `N elements rebuilt unchanged (a flash)` (a control
-  hidden while busy: disable it instead), and layout that moves without input says `layout shift X`. Both are
+- **Server errors:** what the app's `onError` receives (a resolver that threw, an invalid input) is listed under the
+  step or the `get` request that caused it, `server error: <message> (<feature.effect>)`; `--json` `serverErrors`.
+- **A calm page:** a step that rebuilds elements unchanged says `N elements rebuilt unchanged (a flash: main > form >
+  button[type=submit])`, naming up to five (`--json` `flashes.elements` has all; a control hidden while busy: disable
+  it instead). Equal means tag, class, text, `name`, `id`, `href`, `src`, `type` and parent path; a node that moved is
+  no flash. Layout that moves without input says `layout shift X`. Both are
   problems to fix; a calm step prints neither. An address changed with `replace` stays `in place`.
 - **`hozu get`** prints the status, redirect, `set-cookie` attributes (`HttpOnly`, `SameSite`), title, alerts and
   visible text.
@@ -65,6 +69,8 @@
   navigation prints `→ <path>` and the new page's lines; a live update on another actor's page prints under the step
   (`bob: + Milk`).
   - `≠ DIFFERS` marks a step where both modes made a request and the resulting text differs: a no-JS/JS parity bug.
+    It names the differing words (`≠ DIFFERS (on vs off): "#1307" vs "#1306"`): the two modes write twice to the same
+    data, so a new row per mode (an order number, a count) differs without a bug.
   - Errors: uncaught exceptions, `console.error`s, CSP violations and failed requests, each with the page, the
     resource type and the mode. A 400 re-render of an invalid native post is not an error, and a page answering
     401, 403, 404 or 410 is the step's status (`→ /notes/n1 (403)`), so an access check exits 0.

package/skill/topics/views.md

@@ -23,10 +23,10 @@ export const Board = ui.view({
 - **Events:** `on: { click: ui.send(Event, payload) }`; payload fields are literals, data, `ui.dom.value`,
   `ui.dom.form('name')` (submit; `hozu docs forms`). A control that only sets a context field:
   `on: { click: ui.set(ctx.open, !ctx.open) }`, `on: { input: ui.set(ctx.q, ui.dom.value) }` (no event to declare).
-- **Links:** `ui.a({ href: ui.link(itemPage, { id: item.id }) }, [...])`; never a string path (HZ032).
+- **Links:** `ui.a({ href: ui.link(itemPage, { id: item.id }) }, [...])`; never a string path (HZ032). Menus,
+  dialogs, plurals: --more.
 - **Data:** `ui.query(listItems, input, { ready: (items) => …, failed: { NotFound: () => …, Unexpected: () => … } })`;
-  `failed` lists every declared error plus `Unexpected`. When the input changes, the rows stay (`aria-busy` on the
-  parent) and update by key; `pending` shows only before the first answer.
+  `failed` lists every declared error plus `Unexpected`.
 - **Shared UI** (buttons, inputs, fields): `ui.use(Button, { variant, props, on }, ['Save'])` of a kit component
   (`hozu docs components`).
 
@@ -63,3 +63,15 @@ export const Board = ui.view({
   (`hozu docs components`; `examples/showcase` has a Chart.js one).
 - **Also:** `ui.html(post.html)` (trusted HTML from query data only, HZ030), `ui.asset(new URL('./x.png',
   import.meta.url))`, `ui.window({ on })` / `ui.document({ on })`, `ui.embed(OtherView)`.
+
+## Menus, dialogs, counting
+- When a query's input changes, the rows stay (`aria-busy` on the parent) and update by key; `pending` shows only
+  before the first answer.
+- A link to the page shown gets `aria-current="page"`, a link to a section above it (`/orders` on `/orders/7`)
+  `"true"`; the same path with another search (a next page) gets nothing. An `aria-current` you set wins.
+- `ui.dialog({ open: is(['editing']), on: { close: ui.send(Cancel, {}) } }, [...])` opens as a modal and closes with
+  the machine; Escape sends `close`. It needs JavaScript: a dialog that must open without it uses the native
+  `commandfor` button (the short form) and closes when the data that shows it changes.
+- `ui.format.plural(n, { one: '# item', other: '# items' })` picks the case for the page's language (`=0` works).
+- `null` and `false` render nothing, also inside a constant list:
+  `ui.ul({}, [...kinds.map((k) => (k === 'draft' ? null : ui.li({}, [k])))])`.