create-hozu 0.2.0 → 0.4.0

package/README.md

@@ -1,3 +1,5 @@
+<img src="https://raw.githubusercontent.com/olevatorr/Hozu/main/docs/assets/logo.png" alt="Hozu logo" width="72">
+
 # create-hozu
 
 Create a Hozu app, set up for Claude Code or for agents that read AGENTS.md.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-hozu",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Create a Hozu app, set up for Claude Code or for agents that read AGENTS.md",
   "keywords": [
     "hozu",

package/skill/SKILL.md

@@ -5,10 +5,10 @@ description: Build or change an app with the Hozu framework (packages @hozu/*, f
 
 # Hozu authoring guide
 
-Hozu is not in your training data. These files are the whole API; do not read `node_modules/@hozu`.
+Hozu is not in your training data. These files are the whole API; skip `node_modules/@hozu`.
 - **Changing an app:** read `changing.md` first, then only the app's own files.
-- **Building an app:** read this file, run `hozu add feature <name> --page /` (a working feature) and edit it;
-  `patterns.md` says which part of `example/` shows each pattern.
+- **Building an app:** read this file, run `hozu add feature <name> --page / --with auth,detail,toggle,filter,remove`
+  (auth = sign-in, per-user data) and edit the texts it lists; don't print the generated files.
 - **`reference.md`** when the task needs it: routes, DOM fields, no-JS forms, `head`, 404/500, field errors,
   sessions, languages, env, HTTP, Markdown, images, preview, PWA, page tests, deployment.
 - **A diagnostic you do not understand:** `diagnostics.md`.
@@ -36,18 +36,18 @@ features/<name>/
   model.ts  schemas, events, query / mutation / tag / fn, the machine
   views.ts  views, contracts, feature()
 ```
-Relative imports end in `.ts`.
 
 ## Commands (from the app directory)
 ```
-pnpm exec hozu check  # after every edit: types, every rule, every contract
+pnpm exec hozu check  # after every edit: types, rules, contracts
 pnpm exec hozu check --update-lock  # accept an intended behaviour change
-pnpm exec hozu add feature items --page /items  # scaffold a working feature and wire it in
-pnpm exec hozu get / /items  # try pages without a server: status, title, alerts, text
+pnpm exec hozu add feature items --page / --with detail,toggle  # a working feature, wired in
+pnpm exec hozu map  # outline of the app with file:line
+pnpm exec hozu get / --select button --forms  # pages without a server: text, attributes, forms
 pnpm exec hozu post / --field title=A --next 'POST / title=a' --next /  # submit a form like a browser
 ```
-Each diagnostic has a `file:line`, a cause and a fix: apply the fix, do not work around the rule. Every `get` /
-`post` starts from fresh in-memory data, so chain steps with `--next`. Run `node serve.ts` only to use the app.
+Diagnostics give `file:line`, cause and fix: apply the fix. `get` / `post` start from fresh in-memory data;
+chain steps with `--next`. Run `node serve.ts` only to use the app. Relative imports end in `.ts`.
 
 ## model.ts
 ```ts
@@ -128,12 +128,11 @@ export const Board = ui.view({
     ]),
 })
 ```
-- `ui.<tag>(attrs, children)`; attribute values are literals, references or guards.
+- `ui.<tag>(attrs, children)`; values are literals, references or guards. `ui.each(list, 'id', (item) => node)`.
 - `class` is a static string of Tailwind classes that must exist (HZ026). Conditional classes:
   `toggle: { 'bg-indigo-600 text-white': op.eq(ctx.tab, t) }`. CSS variables: `vars: { '--hue': item.hue }`.
 - Events: `on: { click: ui.send(Event, payload) }`. Payload fields: literals, references, `ui.dom.value`,
   `ui.dom.form('name')`, `ui.dom.checked`, `ui.dom.valueAsNumber`, `ui.dom.key`.
-- `ui.each(list, 'id', (item) => node)` (key `null` for primitives).
 - Links: `ui.link(route, params, search)`, never a string path (HZ032). The third argument exists only when the
   route declares `search` (`null` = all defaults). Filters that belong in the URL are `search` links, not context.
 - A form whose submit reads only `ui.dom.form(...)`, literals, context, params and search also works without JS.

package/skill/changing.md

@@ -1,28 +1,78 @@
 # Changing a Hozu app
 
-Keep the loop short: read once, edit everything, check once, verify once.
+Keep the loop short: map once, edit everything, check once, verify once.
 
 ## 1. Read
 - The change request.
-- The app: `features/<name>/*.ts`, `server.ts`, `routes.ts`, `hozu.config.ts`. Below, *model* is where the
-  app keeps schemas, events, effects and the machine (`model.ts` in the recommended layout), and *views* is
-  where it keeps views, contracts and `feature()`.
-- Nothing else. The API is in `SKILL.md`; open `patterns.md` only for a pattern you have not seen in the app,
-  and `reference.md` only for a topic it lists.
-
-## 2. Where each kind of change goes
-| Change | Touch, in this order |
+- `pnpm exec hozu map`: every route, query, mutation, event, state, view and contract, each with its `file:line`.
+  Open only the lines the change touches. Below, *model* is where the app keeps schemas, events, effects and
+  the machine (`model.ts`), and *views* where it keeps views, contracts and `feature()`.
+- The API is in `SKILL.md`. Use a recipe below when one fits; open `patterns.md` / `reference.md` only for
+  something else.
+
+## 2. Recipes
+Names follow `hozu add feature items`: `Item`, `NewItem`, `Add`, `addItem`, `itemsMachine`, `ItemsBoard`.
+
+### A field chosen in the add form (an enum)
+- **model:**
+  - `export const Priority = z.enum(['low', 'normal', 'high'])`;
+  - add `priority: Priority` to `Item`, `NewItem` and the `Add` payload;
+  - context: `priority: Priority`, with `priority: 'normal'` in `initialContext`;
+  - `fields` gets `priority: z.string().nullable()`, with `priority: null` in `initialContext` and in the `Add`
+    assign that resets it;
+  - the `Add` assign also gets `op.set(ctx.priority, e.priority)`, and the add `invoke` input becomes
+    `{ title: ctx.draft, priority: ctx.priority }`.
+- **views:**
+  - the form's submit sends `{ title: ui.dom.form('title'), priority: ui.dom.form('priority') }`;
+  - inside the form add
+    `ui.select({ name: 'priority', 'aria-label': 'Priority', class: 'rounded border px-2' }, ['low', 'normal', 'high'].map((p) => ui.option({ value: p, selected: p === 'normal' }, [p])))`;
+  - in the item: `ui.span({ class: 'text-xs' }, [item.priority])`.
+- **Contracts:**
+  - add `priority: 'normal'` to every `Add` payload, to the add effect's input, and to the `done` result;
+  - `rejectsInvalid`'s `data.fields` and `changes.fields` get `priority: null`.
+- **server:** store `priority` (seed items included) and return it.
+
+### An action button that works on many items (e.g. "Clear done")
+- **model:**
+  - `export const ClearDone = event({ payload: z.object({}) })`;
+  - `export const clearDone = mutation({ input: z.object({}), output: z.object({ removed: z.number() }), invalidates: () => [itemsTag()] })`;
+  - in `idle`: `on(ClearDone, { target: 'clearing', assign: () => [op.set(ctx.error, null)] })`;
+  - a state
+    `clearing: { ignore: [...], invoke: invoke(clearDone, { input: {}, done: [{ target: 'idle' }], failed: { Unexpected: [{ target: 'idle', assign: (e) => [op.set(ctx.error, e.message)] }] } }) }`;
+  - add `ClearDone` to every busy state's `ignore`, and give `clearing` the same list.
+- **views:** the control
+  `ui.form({ on: { submit: ui.send(ClearDone, {}) } }, [ui.button({ type: 'submit', class: 'text-sm underline' }, ['Clear done'])])`.
+- **Contracts:**
+  - `given: { state: 'idle' }`, when `[{ send: ClearDone, payload: {} }, { done: clearDone, result: { removed: 1 } }]`,
+    expect `{ state: 'idle', effects: [{ effect: clearDone, input: {} }] }`;
+  - a second one for `failed … 'Unexpected'` from `clearing`;
+  - add `ClearDone`, `clearDone` and both contracts to `declarations`.
+- **server:**
+  `implement(clearDone, () => { const before = items.length; items.splice(0, items.length, ...items.filter((i) => !i.done)); return { removed: before - items.length } })`.
+- **Try it:** `hozu post / --button 'Clear done' --next /`.
+
+### A field shown on the detail page
+In the detail view's `ready`: `ui.p({}, ['Priority: ', item.priority])`. The detail query already returns the whole
+item.
+
+### A detail page, when the feature has none
+Run a fresh scaffold into a scratch app with `--with detail`, and copy the parts it prints:
+- the route with params;
+- the `get` query and its resolver;
+- the detail view;
+- the link in the list;
+- `ui.page(...)` with `head` and `entries`.
+
+### Other changes
+| Change | Touch |
 |---|---|
-| New data field (e.g. `priority`) | model: the domain and input schemas → `server.ts` (seed data, store it) → views: show it, also in the detail view if there is one. If the user picks it in a form: a `<select name="…">` inside the form, sent with the submit as `ui.dom.form('…')` (HZ033 checks the options), plus the matching field in the event payload and the mutation input. |
-| New server action (e.g. "clear done") | model: a `mutation` with `invalidates`, an event, and `on(Event)` into a new busy state that `invoke`s the mutation, with `done` and every `failed` handled and the same `ignore` list as the other busy states → views: the control, the contracts, and both new declarations in `feature({ declarations })` → `server.ts`: `implement(...)` it. |
-| New UI-only state (a filter, a tab) | model: the context field, its initial value, an event and an `on` that `op.set`s it (add the event to every busy state's `ignore`) → views: the control, a contract, the event in `declarations`. |
-| New page | `routes.ts` (`params`, `search`) → a view with `route`, added to `declarations` → `ui.page(...)` in `hozu.config.ts` (with `head`, and `entries` when the route has params). |
-| New filter / sort / page number that should be in the URL | the route's `search` schema (with a default) → links with `ui.link(route, params, { key: value })` → read `search.key` in the view. No machine change. |
+| New UI-only state (a tab) | model: the context field and its initial value, an event, an `on` that `op.set`s it (add the event to every busy state's `ignore`) → views: the control, a contract, the event in `declarations`. |
+| Filter / sort / page in the URL | the route's `search` schema (with a default) → links with `ui.link(route, params, { key: value })` → read `search.key` in the view. No machine change. |
+| New page | `routes.ts` → a view with `route`, in `declarations` → `ui.page(...)` in `hozu.config.ts` (`head`, and `entries` when the route has params). |
 
 Whenever the machine changes:
-- Add one contract per new transition; HZ016 prints each missing one ready to paste. A new context field needs
-  no change to existing contracts: `given` defaults to the initial context and `changes` lists only what changes.
-- Every busy state `ignore`s every event its visible controls can send. HZ005 prints the missing `ignore` entries.
+- Add one contract per new transition; HZ016 prints each missing one ready to paste.
+- Every busy state `ignore`s every event its visible controls can send; HZ005 prints the missing entries.
 
 ## 3. Check (once, after all edits)
 ```
@@ -32,9 +82,13 @@ Fix what it reports. When the behaviour change is intended and everything is cle
 `pnpm exec hozu check --update-lock`. HZ018 asks for this.
 
 ## 4. Verify (once, no server needed)
-- Pages: `pnpm exec hozu get / /items/i1` prints status, title, alerts and the visible text.
-- Forms: `pnpm exec hozu post / --field title=A --field kind=video --next /items` fills the form like a browser (other
-  fields keep their defaults), follows the redirect, then requests the next steps in the same process.
-- Chain what must share data: `--next 'POST / title=a'` (fields as `a=1&b=2`), `--next /items/i3`.
-- A form with only a button (an action such as "Clear done"): `--button 'Clear done'`, or `--next 'POST / @Clear done'`.
-  One form per item: `--field id=t2` picks the item's form.
+- **Pages:** `pnpm exec hozu get / /items/i1` prints the status, title, alerts and visible text.
+- **Attributes and forms:** `--select button` (or `'[role=alert]'`, `a[href]`, `#id`) prints elements with their
+  attributes, e.g. `aria-pressed`; `--forms` lists each form's fields and buttons. Never start a server for this.
+- **Forms:** `pnpm exec hozu post / --field title=A --field priority=high --next /items` fills the form like a
+  browser (other fields keep their defaults). It follows the redirect, then runs the next steps in the same
+  process.
+- **Chaining:** chain what must share data, e.g. `--next 'POST / title=a'` (fields as `a=1&b=2`) or
+  `--next /items/i3`.
+- **A form with only a button:** `--button 'Clear done'`, or `--next 'POST / @Clear done'`. With one form per item,
+  `--field id=t2` picks the item's form.

package/skill/reference.md

@@ -51,6 +51,10 @@ Every mutation also has the framework error `Invalid` = `{ message, fields }`: o
   (see `patterns.md`).
 
 ## Sessions
+- **Start from the scaffold:** `hozu add feature notes --page / --with auth` writes `features/account`
+  (sign-in page, sign-out, `me`), the session cookie in `serve.ts`, per-user resolvers, and a redirect to `/login`
+  when signed out. Replace the name-only sign-in with real credentials before production; set `SESSION_SECRET`
+  (and `SESSION_SECURE=true` behind HTTPS).
 - `project({ session: z.object({ user: z.string() }) })` declares the identity. Queries with `scope: 'user'` and
   mutations receive `session`; public resolvers never do.
 - `createServer({ session: (request) => value })`, or `sessionCookie({ name, secret })` from
@@ -108,8 +112,12 @@ There are no rewrites: one URL has one owner.
   dimensions). With `@hozu/image` installed, pass `images: await optimizeImages(build)` to `createServer` (and
   `hozu build` does it itself): raster assets get WebP `srcset` widths and `sizes`.
 - **Share images:** `head.render` → `image: ui.og({ title, subtitle })` renders a 1200×630 card; pass
-  `og: ogImage` (from `@hozu/image`) to `createServer`.
+  `og: ogImage` (from `@hozu/image`) to `createServer`. On a static host, use a file instead:
+  `image: ui.asset(new URL('./share.png', import.meta.url))` (made absolute with `site.url`).
 - **Fonts:** a local `@font-face` gets a size-matched `"<Family> Fallback"` automatically.
+- **Page transitions:** the stylesheet turns on cross-document view transitions, so links between pages cross-fade
+  instead of flashing (no JS). Turn them off with `@view-transition { navigation: none; }` in `app.css`; style them
+  with `::view-transition-*`.
 
 ## Preview (drafts)
 `createServer({ preview: { secret } })`; `GET /_hozu/preview?secret=…&path=/posts/a` turns preview on (a signed
@@ -132,6 +140,9 @@ Cloudflare Workers or Vercel the server is `createHandler({ build, manifest, res
 `@hozu/runtime-server` with `export default { fetch: handler.fetch }`, where
 `import * as render from './dist/server/render.js'` is the page code `hozu build` generates (edge runtimes cannot
 generate it at startup). Page cache and tag revalidation are per instance.
+A fully static site (GitHub Pages, any file host): `exportStatic({ build, styles, resolvers, outDir })` from
+`@hozu/adapter-static` writes every page without per-request data, plus the files they link to, and lists skipped
+routes.
 ```ts
 import manifest from './dist/manifest.json' with { type: 'json' }
 import * as render from './dist/server/render.js'

package/templates/guide.md

@@ -9,14 +9,17 @@ A web app built with Hozu (`@hozu/*`). Hozu is not in your training data.
 
 ## The loop
 ```
-__RUN__ hozu add feature tasks --page /   # start a feature from working code, then edit it
+__RUN__ hozu add feature tasks --page / --with detail,toggle,filter,remove   # then edit the texts it lists
+                                          # add auth to the list for sign-in and per-user data
+__RUN__ hozu map                           # outline of the app with file:line, before a change
 __RUN__ hozu check                         # after every change: types, rules, contracts
 __RUN__ hozu check --update-lock           # only to accept a clean, intended behaviour change
-__RUN__ hozu get / /tasks/t1               # try pages without a server
+__RUN__ hozu get / --select button --forms  # try pages without a server: text, attributes, forms
 __RUN__ hozu post / --field title=Ship --next /   # submit a form like a browser
 ```
 __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.
 - Every behaviour change comes with a contract change.
 - Do not edit `__SKILL__/`: `__RUN__ hozu skill` rewrites it for the installed Hozu version.