@hozu/cli 0.18.2 → 0.19.0

package/skill/topics/testing.md

@@ -0,0 +1,84 @@
+# Testing
+
+- **Read a page without a server:** `hozu get /path --select 'button[aria-pressed=true]' --forms` (status, title,
+  visible text; `--forms` lists each form's fields and submit buttons). Endpoints: `hozu get '/api/items?x=1'`.
+- **Try one query or mutation without a page:** `hozu call notes.listNotes --input '{}' --session '{"user":"ada"}'`;
+  a mutation writes real data, so it needs `--write`. An endpoint too:
+  `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"'`.
+  - `--js both` (the default) runs every step with JS and with JS switched off; submit with `press Enter` or
+    `submit "<form>"` so one step list drives both.
+  - 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`,
+    `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
+    several steps: `--do 'fill Title=Milk; press Enter'`.
+- **Other users, other pages, after a reload, after sign-out:** verify any such statement once, in one `browse`
+  chain with `--js both`. `--as <name>` starts an actor with its own browser; all actors share one app.
+  - A stale form (sent after the data changed elsewhere): `--do 'remember save from form:has([name=title]) @action'`,
+    change the data as another `--as`, then `--do 'post $save title=x'`. No server and no curl needed.
+- **The output** is per step only the lines added (`+`) or removed (`−`). A passing six-step run stays under 1.5 KB.
+  Exit code 1 when a step failed, the modes differ or an error was printed.
+- **A step that reloads the page** with JS on says `the page reloaded` (a form that should update in place);
+  `--full` adds `N elements replaced` (a region drawn again), `--json` has both as `document` / `replaced`.
+- **A pending state:** `--do 'hold notes.addNote'` keeps that effect's answer back; the next steps (and
+  `--screenshot`) see the busy UI; `--do 'release'` answers it.
+- `browse` runs the `npm start` app: what only `hozu dev` does (reload on edits, DevTools) is not in it.
+- In code: `const page = await testApp(app).get('/')` from `@hozu/testing` → `{ status, headers, html, text, payload }`.
+- A build with errors renders nothing: run `hozu check`.
+
+<!-- more -->
+
+- **`hozu get`** prints the status, redirect, `set-cookie` attributes (`HttpOnly`, `SameSite`), title, alerts and
+  visible text.
+  - `--forms` lists each form: fields with their defaults, checkbox / radio groups with every value (checked ones
+    marked ✓), controls that join through `form=` (marked `(form=)`), and submit buttons with their name and value.
+  - It needs no browser.
+- **`hozu call`** runs the effect through the app's own handler and prints the value or the declared error. With
+  `--write`, a mutation also prints the tags it invalidated and the queries they refresh. `runs: 'browser'` effects
+  need `hozu browse`.
+- **`hozu browse`:**
+  - It uses the installed Chrome / Chromium / Edge (`HOZU_CHROME=/path` to choose); without one it is a config
+    error. The app runs in-process, exactly as `npm start` serves it.
+  - `--js both` runs both modes in the same Chrome, side by side. Use `--js on` or `--js off` for one mode.
+  - Steps in detail: a second fill of a repeated name fills the next field; `check` / `uncheck` set the state;
+    `click <name>` on a submit button posts with its name and value; `submit "<form>"` takes a form's `aria-label` or
+    its submit button text. Labels and names are what a user reads (aria-label, `<label>`, placeholder, button text,
+    `title`), or a field's `name`.
+  - `in "<text>"` picks the smallest list item, table row or form containing that text
+    (`click Delete in "Buy milk"`).
+  - A step with no native effect prints `js-only (<reason>)` in the off column, e.g. a `type=button` button.
+- **Actors:** the steps after an `--as <name>` are that actor's, and a later `--as <name>` switches back. `--session`
+  right after an `--as` signs that actor in. All actors share one data store and one session store, so what ada
+  writes is what bob reads.
+  - Signing out and in again inside one actor's chain also works (`click Sign out`, `fill Name=bob`, `press Enter`).
+  - `hozu browse /notes --as ada --session '{"user":"ada"}' --as bob --session '{"user":"bob"}' --as ada --do 'click Share in "Milk"' --as bob --do 'goto /inbox'`
+  - `--header 'Name: value'` adds a header to every request: before the first `--as` for every actor, after an
+    `--as` for that actor.
+  - **Another visitor's data:** `--as ada --do 'remember note from li a @href' --as bob --do 'goto $note'` (bob's page
+    should answer 403), or `--as bob --do 'post /notes/n1 text=x'`: a forged native post, as bob, without the page.
+    Each mode keeps its own remembered values.
+- **The output** is small on purpose: lines print once when both modes agree and per mode where they differ; a
+  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.
+  - 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.
+  - To forge a post, take the form's `action` from `hozu get <page> --forms` or `remember … @action` on a page the
+    server rendered (`goto` it first): forms the client renders after a change carry no `action`.
+  - Exit code 1 also when a client component failed. `--json` has every line; `--full` prints them all;
+    `--select <css>`, `--screenshot shot.png` (after the steps), `--viewport 390x844` (a phone; default 1280x800) and
+    `--reduced-motion`.
+  - It also prints the client components on the page (mounted, failed, size, canvases).
+- **`testApp`:** `app` is the default export of `app.ts`; `.post(path, fields)` submits a native form, with fields as
+  a record or as `[name, value]` pairs for repeated names. `testApp(app, { session: store })` may swap only the
+  session store (a test issuer). `testApp` reads no env files: pass `testApp(app, { env: process.env })` (or a record)
+  for the variables your resolvers need; `hozu get`, `call` and `browse` read `env.files` themselves.
+- `hozu get`, `hozu browse` and `testApp` build the app module; a build with errors exits 1 (throws).
+- Vitest: add `hozuTransform()` from `@hozu/transform/vite` to `plugins`.
+- Browser tests: wait for `html[data-hozu-ready]` (set after hydration) before clicking.
+- A person checks the result with `npm run dev` (`hozu dev`: reloads and Hozu DevTools); what they ask for from
+  there arrives as requests (`hozu docs requests`). The tools above stay the way you verify.

package/skill/topics/views.md

@@ -0,0 +1,51 @@
+# Views
+
+```ts
+export const Board = ui.view({
+  machine: m,        // optional: without it, no ctx / when / events, and 0 JS
+  route: home,       // optional: render gets { params, search } typed by the route
+  seed: ({ search }) => ({ q: search.q }),   // optional, with machine + route: context fields from the URL
+  render: ({ ctx, when, params, search, locale }) => ui.main({ class: 'mx-auto max-w-xl' }, [ /* children */ ]),
+})
+```
+- **Elements:** `ui.<tag>(attrs, children)` for every HTML and SVG element; void tags (`input`, `img`) take only attrs.
+  Children are nodes, strings, numbers, data values, and `null` / `false` (render nothing).
+- **Classes:** `class` is a static string of Tailwind classes that must exist (HZ026); conditional classes:
+  `toggle: { 'bg-indigo-600 text-white': ctx.tab === t }`. No `style`.
+- **Conditions:** `ctx.error !== null && ui.p({ role: 'alert' }, [ctx.error])`, `item.done ? 'done' : 'open'`.
+  By machine state: `when(['adding', 'saving'], [ui.p({}, ['Saving…'])])`.
+- **Lists:** `ui.each(items, 'id', (item) => ui.li({}, [item.title]))`. Never `.map` over data.
+- **Numbers and dates:** `ui.format.number(q.price, { style: 'currency', currency: 'USD' })`, `ui.format.date(x,
+  { dateStyle: 'medium' })`, `ui.format.relative(n, 'day')`, `ui.format.list(xs)` (Intl, the page's locale).
+- **Events:** `on: { click: ui.send(Event, payload) }`; payload fields are literals, data, `ui.dom.value`,
+  `ui.dom.form('name')` (submit; `hozu docs forms`).
+- **Links:** `ui.a({ href: ui.link(itemPage, { id: item.id }) }, [...])`; never a string path (HZ032).
+- **Data:** `ui.query(listItems, input, { ready: (items) => …, failed: { NotFound: () => …, Unexpected: () => … } })`;
+  `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`).
+
+<!-- more -->
+
+- **Attributes:** HTML names in lower case (`for`, `minlength`, `aria-pressed`, `data-x`), typed per tag. Values are
+  literals or data: `'aria-pressed': ctx.show === 'all'`, `title: ctx.error ?? 'OK'`.
+- **CSS variables:** `vars: { '--hue': item.hue }`.
+- **More conditions:** `list.length === 0 ? ui.p({}, ['Empty']) : ui.ul({}, [...])`; a `?:` / `&&` branch may be a list:
+  `open ? [a, b] : null`. A query branch or an each item returns one node: wrap several in an element (HZ014).
+  With an enter/leave animation: `ui.if(cond, [then], [else], 'fade')` (the motion name is required).
+- **More lists:** `ui.each(tags, null, (t) => …)` for primitives. `.map` only over constants:
+  `['a', 'b'].map((k) => ui.option({ value: k }, [k]))`.
+- **Text:** template strings work: `` `${n} items` ``.
+- **Reuse:** `export const row = part((item: Item) => ui.li({}, [item.done ? 'Done' : item.title]))`, called as
+  `row(item)`; it is inlined, so the IR equals the inline form. A plain function that receives data is HZ059.
+- **Shared UI:** use the kit component, not a styled `ui.button` per page (`example/` uses a kit).
+- **More events:** any DOM event name plus `visible` (entered the viewport). Payload fields also:
+  `ui.dom.formAll('name')`, `ui.dom.checked`, `ui.dom.valueAsNumber`, `ui.dom.key`. `ui.dom.value` / `ui.dom.form`
+  fill an enum field only from a `<select>`, radios or submit buttons whose literal values are all members (HZ033).
+- **Search in links:** the third argument of `ui.link` is optional and exists only when the route declares `search`:
+  omitted means every default, and a search lists only the fields that differ: `ui.link(home, null, { show: 'done' })`.
+- **More data:** `pending: ui.p({}, ['Loading…'])` is optional; a branch may return `null` to render nothing.
+  Server-fetched data is sent with the page and never fetched again; after a mutation, queries whose tags it
+  invalidates refresh in place.
+- **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)`.

package/templates/guide.md

@@ -0,0 +1,16 @@
+# __NAME__
+
+A web app built with Hozu (`@hozu/*`). Hozu is not in your training data.
+
+## Before writing code
+- __READ__ It has the change loop, the commands and the rules no diagnostic checks.
+- The files in `__SKILL__/` are the whole API. Do not read the framework source in `node_modules/@hozu`.
+__NOTE__
+## Rules
+- After `hozu add feature`, do not print the generated files: edit the texts it lists; `hozu map` shows the rest.
+- Apply the fix each diagnostic gives; do not work around a rule.
+- `__RUN__ hozu get` and `__RUN__ hozu browse` run the same app as `npm start`; do not start a server to check.
+- Asked to do the Hozu requests (from DevTools under `npm run dev`): `__RUN__ hozu requests --full`, then follow
+  `__RUN__ hozu docs requests`.
+- Do not edit `__SKILL__/` or the text between the `hozu` markers: `__RUN__ hozu skill` rewrites both for the
+  installed Hozu version.