@hozu/cli 0.22.0 → 0.23.0

package/skill/topics/data.md

@@ -97,16 +97,44 @@ export default app({
 ```
 - 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; the service answers 409 to calls from other declarations.
+  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`. Only `runs: 'server'` effects and JSON endpoints can be remote (HZ093).
-- `examples/notes-go` is the reference: the notes app with every resolver in Go.
+  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

package/skill/topics/recipes.md

@@ -96,9 +96,10 @@ One machine per feature: an order list (filters, selection) and an order page (s
 `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; the server runs the machine per request, so without JS a step's form posts every earlier field
-again as hidden inputs (`ui.input({ type: 'hidden', name: 'line1', value: ctx.line1 })`), and the last step's
-mutation receives them all. Prefill from the member with `seed: ({ query }) => ({ email: query(me, {}).email })`.
+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;

package/skill/topics/testing.md

@@ -69,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

@@ -67,9 +67,11 @@ export const Board = ui.view({
 ## 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"` (`"true"` for its section): `aria-[current]:font-bold`.
+- 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`.
+  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])))])`.