@hozu/cli 0.18.2 → 0.19.0

package/dist/migrate/steps.js.map

@@ -1 +1 @@
-{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../src/migrate/steps.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../src/migrate/steps.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hozu/cli",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "description": "The hozu command: check, map, why, show, get, browse, call, plan, add, build, dev, serve, docs, migrate and skill (all with --json)",
   "keywords": [
     "hozu",
@@ -37,7 +37,9 @@
   "files": [
     "bin",
     "dist",
-    "schema"
+    "schema",
+    "skill",
+    "templates"
   ],
   "engines": {
     "node": ">=22.18"
@@ -46,12 +48,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@hozu/devtools": "0.18.2",
-    "@hozu/core": "0.18.2",
-    "@hozu/validator": "0.18.2",
-    "@hozu/machine": "0.18.2",
-    "@hozu/compiler": "0.18.2",
-    "@hozu/transform": "0.18.2",
-    "create-hozu": "0.18.2"
+    "@hozu/devtools": "0.19.0",
+    "@hozu/core": "0.19.0",
+    "@hozu/validator": "0.19.0",
+    "@hozu/machine": "0.19.0",
+    "@hozu/compiler": "0.19.0",
+    "@hozu/transform": "0.19.0"
+  },
+  "devDependencies": {
+    "create-hozu": "0.19.0"
   }
 }

package/schema/browse.schema.json

@@ -153,6 +153,19 @@
         "navigated": {
           "type": "boolean"
         },
+        "document": {
+          "type": "string",
+          "enum": [
+            "in place",
+            "reloaded",
+            "navigated"
+          ],
+          "description": "What the step did to the document: kept it, loaded the same URL again, or loaded another one (ADR 0063 C3)."
+        },
+        "replaced": {
+          "type": "number",
+          "description": "With the document kept: how many elements are new after the step (a region drawn again)."
+        },
         "url": {
           "type": "string"
         },

package/schema/inspect.schema.json

@@ -529,6 +529,23 @@
           ],
           "additionalProperties": false
         },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "poll"
+            },
+            "seconds": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "kind",
+            "seconds"
+          ],
+          "additionalProperties": false
+        },
         {
           "type": "object",
           "properties": {
@@ -1925,6 +1942,9 @@
             },
             "context": {
               "$ref": "#/definitions/Json"
+            },
+            "previous": {
+              "type": "string"
             }
           },
           "required": [

package/skill/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: hozu
+description: Build or change an app with the Hozu framework (packages @hozu/*, files like hozu.config.ts, features/*/model.ts, views.ts). Use it before writing any Hozu code. It is the complete authoring reference, so you do not need to read the framework source.
+---
+
+# Hozu
+
+Hozu is not in your training data: this file and `npx hozu docs <topic>` are the whole API (skip
+`node_modules/@hozu`). Diagnostics teach the other rules: apply their fix.
+
+## The change loop
+1. `npx hozu map`: the session, the verify line, each file's role and declaration's `file:line`; open only the
+   lines you change. A new app: `npx hozu add feature <name> --page / --with …`, then
+   `npx hozu docs feature`.
+2. Edit everything the change needs (table below).
+3. `npx hozu check` once. For an intended behaviour change, `npx hozu check --update-lock`, then list the accepted
+   `now:` lines in your summary.
+4. Verify once with the line `hozu map` prints: `npx hozu browse <path> --session '…' --js both --do '…'` (the
+   app with and without JS; no server, no `curl`).
+5. Show the person the change: `npx hozu show <file:line> --note "<in their words>"`.
+
+## What to touch
+| Change | Touch |
+|---|---|
+| UI-only state (a tab) | model: a context field, an event, an `on` whose `assign` sets it → views: the control |
+| Filter / sort in the URL | the route's `search` (with a default) → `ui.link(route, params, { key })` → `search.key`; while typing: `seed` the machine from `search` |
+| A per-item action (pin, archive) | model: the item field, an event, a mutation that `invalidates` the list tag, an `on` into a state with `invoke` → views: the per-item form (`hozu docs patterns`) → store it where the data lives |
+| A control every state handles | `machine({ on: [...] })` |
+| New page | `routes.ts` → a view with `route` → `ui.page(...)` in `hozu.config.ts` |
+| UI (a button, a field) | `ui.use` of a kit component (`npx hozu docs components`) |
+
+## Rules no diagnostic checks
+- **Where data lives is the person's call; ask when the request does not say.** The visitor's own, no sign-in →
+  `'browser'` (`localStorage` in `fetch.ts`); a user's across devices → session + database; everyone's → a
+  database. Arrays in examples are stand-ins, never storage (`npx hozu docs data`).
+- **Every query and mutation states `runs`:** a database, a secret or the session → `'server'` (resolver in
+  `app.ts`); browser storage or credentials → `'browser'`; a public API → `'either'` (`fetch.ts`).
+- **Query resolvers only read.** Writes belong in mutations and endpoints.
+- **Other users, reloads, sign-out:** verify in one `browse` chain with `--js both`, `--as <name>` per user.
+- **Contracts only where a transition decides:** a guard, `navigate` or a computed value; the lock has the rest.
+- **`'live'` only for push**.
+- **`invalidates` drives the client refresh** of the queries with those tags.
+- **`previews.ts` is for people:** read it only if asked or when HZ092 names a line.
+
+## Topics (`npx hozu docs <topic>`; `--more`: options, edge cases)
+| Task | Topic |
+|---|---|
+| a new feature, the files, a complete example | `feature` |
+| elements, attributes, events, lists, links, reuse | `views` |
+| states, events, invoke, timers, guards | `machine` |
+| queries, mutations, tags, `fn()`, resolvers | `data` |
+| where effects run, `fetch.ts`, browser storage, static hosts | `fetch` |
+| contracts and the lock | `contracts` |
+| routes, search, pages, `head`, 403 / 404 | `pages` |
+| forms, checkboxes, bulk forms, no JS | `forms` |
+| sign-in, sessions, per-user data | `auth` |
+| filters, modes, per-item actions, load more | `patterns` |
+| worked changes | `recipes` |
+| webhooks, JSON APIs, redirects | `endpoints` |
+| components, kits, browser APIs, DOM libraries, `previews.ts` | `components` |
+| languages, env, HTTP, Markdown, tests, deploying, upgrading Hozu | `i18n` `env` `http` `content` `testing` `deploy` |
+| a diagnostic code | `diagnostics` |
+| requests from Hozu DevTools; showing a change (`hozu show`) | `requests` |

package/skill/example/app.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/skill/example/app.ts

@@ -0,0 +1,35 @@
+import { resolvers } from '@hozu/data'
+import { app } from '@hozu/runtime-server'
+import { addBookmark, getBookmark, listBookmarks, toggleRead } from './features/bookmarks/model.ts'
+import project from './hozu.config.ts'
+
+type Kind = 'article' | 'video' | 'podcast'
+
+const demoBookmarks = [
+  { id: 'b1', title: 'Closed-world UI', kind: 'article' as Kind, read: false },
+  { id: 'b2', title: 'Islands explained', kind: 'video' as Kind, read: true },
+]
+let demoSeq = demoBookmarks.length
+export default app({
+  resolvers: resolvers(project, (implement) => [
+    implement(listBookmarks, () => demoBookmarks.map((b) => ({ ...b }))),
+    implement(getBookmark, ({ id }, { fail }) => {
+      const b = demoBookmarks.find((x) => x.id === id)
+      return b ? { ...b } : fail('NotFound', { id })
+    }),
+    implement(addBookmark, ({ title, kind }, { fail }) => {
+      const clean = title.trim()
+      if (demoBookmarks.some((b) => b.title.toLowerCase() === clean.toLowerCase()))
+        return fail('Duplicate', { title: clean })
+      const b = { id: `b${++demoSeq}`, title: clean, kind, read: false }
+      demoBookmarks.unshift(b)
+      return { ...b }
+    }),
+    implement(toggleRead, ({ id }, { fail }) => {
+      const b = demoBookmarks.find((x) => x.id === id)
+      if (!b) return fail('NotFound', { id })
+      b.read = !b.read
+      return { ...b }
+    }),
+  ]),
+})

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

@@ -0,0 +1,13 @@
+import { feature } from '@hozu/core'
+import * as model from './model.ts'
+import * as views from './views.ts'
+
+export const bookmarks = feature({
+  id: 'bookmarks',
+  intent: {
+    summary:
+      'A shared reading list: add bookmarks with a kind, mark them read, filter unread, one page each.',
+    invariants: ['Titles are unique, case-insensitive', 'New bookmarks are listed first'],
+  },
+  declarations: [model, views],
+})

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

@@ -0,0 +1,163 @@
+import { event, fn, invoke, machine, mutation, on, query, tag, ui } from '@hozu/core'
+import { z } from 'zod'
+import { bookmarkPage, Show } from '../../routes.ts'
+
+export const Kind = z.enum(['article', 'video', 'podcast'])
+export const Bookmark = z.object({ id: z.string(), title: z.string(), kind: Kind, read: z.boolean() })
+const Bookmarks = z.array(Bookmark)
+const BookmarkKey = z.object({ id: z.string() })
+const NewBookmark = z.object({
+  title: z.string().min(2, 'Use at least 2 characters').max(80, 'Use at most 80 characters'),
+  kind: Kind,
+})
+
+export const Draft = event({ payload: z.object({ text: z.string() }) })
+export const Add = event({ payload: z.object({ title: z.string(), kind: Kind }) })
+export const ToggleRead = event({ payload: BookmarkKey })
+
+export const bookmarksTag = tag({ param: null })
+
+export const listBookmarks = query({
+  input: z.object({}),
+  output: Bookmarks,
+  scope: 'public',
+  freshness: 'static',
+  tags: () => [bookmarksTag()],
+  runs: 'server',
+})
+
+export const getBookmark = query({
+  input: BookmarkKey,
+  output: Bookmark,
+  errors: { NotFound: BookmarkKey },
+  scope: 'public',
+  freshness: 'static',
+  tags: () => [bookmarksTag()],
+  runs: 'server',
+})
+
+export const addBookmark = mutation({
+  input: NewBookmark,
+  output: Bookmark,
+  errors: { Duplicate: z.object({ title: z.string() }) },
+  invalidates: () => [bookmarksTag()],
+  runs: 'server',
+  access: 'anyone',
+})
+
+export const toggleRead = mutation({
+  input: BookmarkKey,
+  output: Bookmark,
+  errors: { NotFound: BookmarkKey },
+  invalidates: () => [bookmarksTag()],
+  runs: 'server',
+  access: 'anyone',
+})
+
+const Visible = z.object({ items: Bookmarks, show: Show })
+
+export const visible = fn({
+  input: Visible,
+  output: Bookmarks,
+  impl: ({ items, show }) => items.filter((b) => show === 'all' || !b.read),
+})
+
+export const isEmpty = fn({
+  input: Visible,
+  output: z.boolean(),
+  impl: ({ items, show }) => !items.some((b) => show === 'all' || !b.read),
+})
+
+export const DUPLICATE = 'This bookmark already exists'
+
+export const bookmarksMachine = machine({
+  context: z.object({
+    draft: z.string(),
+    kind: Kind,
+    target: z.string(),
+    error: z.string().nullable(),
+    fields: z.object({ title: z.string().nullable(), kind: z.string().nullable() }),
+  }),
+  initialContext: {
+    draft: '',
+    kind: 'article',
+    target: '',
+    error: null,
+    fields: { title: null, kind: null },
+  },
+  initial: 'idle',
+  states: ({ ctx }) => ({
+    idle: {
+      on: [
+        on(Draft, {
+          target: 'idle',
+          assign: (e) => {
+            ctx.draft = e.text
+          },
+        }),
+        on(Add, {
+          target: 'adding',
+          assign: (e) => {
+            ctx.draft = e.title
+            ctx.kind = e.kind
+            ctx.error = null
+            ctx.fields = { title: null, kind: null }
+          },
+        }),
+        on(ToggleRead, {
+          target: 'toggling',
+          assign: (e) => {
+            ctx.target = e.id
+          },
+        }),
+      ],
+    },
+    adding: {
+      invoke: invoke(addBookmark, {
+        input: { title: ctx.draft, kind: ctx.kind },
+        done: {
+          target: 'idle',
+          assign: () => {
+            ctx.draft = ''
+          },
+          navigate: (b) => ui.link(bookmarkPage, { id: b.id }),
+        },
+        failed: {
+          Duplicate: {
+            target: 'idle',
+            assign: () => {
+              ctx.error = DUPLICATE
+            },
+          },
+          Invalid: {
+            target: 'idle',
+            assign: (e) => {
+              ctx.fields = e.fields
+            },
+          },
+          Unexpected: {
+            target: 'idle',
+            assign: (e) => {
+              ctx.error = e.message
+            },
+          },
+        },
+      }),
+    },
+    toggling: {
+      invoke: invoke(toggleRead, {
+        input: { id: ctx.target },
+        done: 'idle',
+        failed: {
+          NotFound: 'idle',
+          Unexpected: {
+            target: 'idle',
+            assign: (e) => {
+              ctx.error = e.message
+            },
+          },
+        },
+      }),
+    },
+  }),
+})

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

@@ -0,0 +1,156 @@
+import { contract, ui } from '@hozu/core'
+import { bookmarkPage, home } from '../../routes.ts'
+import { Badge } from '../../ui/badge.ts'
+import { Button } from '../../ui/button.ts'
+import { Field } from '../../ui/field.ts'
+import { Input } from '../../ui/input.ts'
+import {
+  Add,
+  addBookmark,
+  bookmarksMachine,
+  Draft,
+  getBookmark,
+  isEmpty,
+  listBookmarks,
+  ToggleRead,
+  visible,
+} from './model.ts'
+
+const kinds = ['article', 'video', 'podcast'] as const
+const shows = [
+  { value: 'all', label: 'All' },
+  { value: 'unread', label: 'Unread' },
+] as const
+
+export const Board = ui.view({
+  machine: bookmarksMachine,
+  route: home,
+  render: ({ ctx, search, when }) =>
+    ui.main({ class: 'mx-auto max-w-xl space-y-6 px-4 py-12' }, [
+      ui.h1({ class: 'text-3xl font-bold' }, ['Bookmarks']),
+      ui.form(
+        {
+          class: 'flex items-start gap-2',
+          on: { submit: ui.send(Add, { title: ui.dom.form('title'), kind: ui.dom.form('kind') }) },
+        },
+        [
+          ui.use(Field, {
+            props: { for: 'title', label: 'Title', error: ctx.fields.title, errorId: 'title-error' },
+            slots: {
+              control: ui.use(Input, {
+                props: {
+                  id: 'title',
+                  name: 'title',
+                  value: ctx.draft,
+                  required: true,
+                  minlength: 2,
+                  maxlength: 80,
+                  invalid: ctx.fields.title !== null,
+                  describedby: 'title-error',
+                },
+                on: { input: ui.send(Draft, { text: ui.dom.value }) },
+              }),
+            },
+          }),
+          ui.select(
+            { name: 'kind', 'aria-label': 'Kind', class: 'rounded border px-2 py-2' },
+            kinds.map((k) => ui.option({ value: k, selected: ctx.kind === k }, [k])),
+          ),
+          ui.use(Button, { props: { type: 'submit' } }, ['Add']),
+        ],
+      ),
+      ctx.error !== null && ui.p({ role: 'alert', class: 'text-rose-600' }, [ctx.error]),
+      when(
+        ['adding'],
+        [
+          ui.p({ class: 'rounded border px-4 py-3 opacity-50', 'aria-busy': 'true' }, [
+            'Adding ',
+            ctx.draft,
+            '…',
+          ]),
+        ],
+      ),
+      ui.nav(
+        { class: 'flex gap-2', 'aria-label': 'Show' },
+        shows.map((s) =>
+          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',
+            },
+            [s.label],
+          ),
+        ),
+      ),
+      ui.query(
+        listBookmarks,
+        {},
+        {
+          ready: (items) =>
+            isEmpty({ items, show: search.show })
+              ? ui.p({ class: 'text-slate-500' }, ['No bookmarks'])
+              : ui.ul({ class: 'divide-y rounded border' }, [
+                  ui.each(visible({ items, show: search.show }), 'id', (b) =>
+                    ui.li({ class: 'flex items-center gap-3 px-4 py-3' }, [
+                      ui.a({ href: ui.link(bookmarkPage, { id: b.id }), class: 'flex-1 underline' }, [
+                        b.title,
+                      ]),
+                      ui.use(Badge, {}, [b.kind]),
+                      ui.use(
+                        Button,
+                        { variant: { tone: 'quiet' }, on: { press: ui.send(ToggleRead, { id: b.id }) } },
+                        [b.read ? 'Mark unread' : 'Mark read'],
+                      ),
+                    ]),
+                  ),
+                ]),
+          pending: ui.p({}, ['Loading…']),
+          failed: { Unexpected: () => ui.p({ role: 'alert' }, ['Bookmarks are unavailable']) },
+        },
+      ),
+    ]),
+})
+
+export const Detail = ui.view({
+  route: bookmarkPage,
+  render: ({ params }) =>
+    ui.main({ class: 'mx-auto max-w-xl space-y-4 px-4 py-12' }, [
+      ui.query(
+        getBookmark,
+        { id: params.id },
+        {
+          ready: (b) =>
+            ui.article({}, [
+              ui.h1({ class: 'text-3xl font-bold' }, [b.title]),
+              ui.p({}, ['Kind: ', b.kind]),
+              ui.use(Badge, {}, [b.read ? 'Read' : 'Unread']),
+            ]),
+          pending: null,
+          failed: {
+            NotFound: () => ui.p({ role: 'alert' }, ['Bookmark not found']),
+            Unexpected: () => ui.p({ role: 'alert' }, ['Bookmark unavailable']),
+          },
+        },
+      ),
+      ui.a({ href: ui.link(home, null), class: 'underline' }, ['Back']),
+    ]),
+})
+
+export const addsBookmark = contract(bookmarksMachine, {
+  given: { state: 'idle' },
+  when: [
+    { send: Add, payload: { title: 'Hozu talk', kind: 'podcast' } },
+    { send: Draft, payload: { text: 'ignored while adding' } },
+    { done: addBookmark, result: { id: 'b3', title: 'Hozu talk', kind: 'podcast', read: false } },
+  ],
+  expect: {
+    state: 'idle',
+    changes: { kind: 'podcast' },
+    effects: [
+      { effect: addBookmark, input: { title: 'Hozu talk', kind: 'podcast' } },
+      { navigate: '/bookmarks/b3' },
+    ],
+  },
+})

package/skill/example/hozu.config.ts

@@ -0,0 +1,34 @@
+import { project, ui } from '@hozu/core'
+import { zodAdapter } from '@hozu/schema-zod'
+import { bookmarks } from './features/bookmarks/feature.ts'
+import { getBookmark, listBookmarks } from './features/bookmarks/model.ts'
+import { Board, Detail } from './features/bookmarks/views.ts'
+import { bookmarkPage, home } from './routes.ts'
+import { kit as uiKit } from './ui/kit.ts'
+
+export default project({
+  schema: zodAdapter,
+  app: new URL('./app.ts', import.meta.url),
+  previews: new URL('./previews.ts', import.meta.url),
+  styles: new URL('./app.css', import.meta.url),
+  site: { url: 'http://localhost:3000', name: 'Bookmarks', lang: 'en' },
+  routes: { home, bookmarkPage },
+  pages: [
+    ui.page(home, {
+      views: [Board],
+      head: { render: () => ({ title: 'Bookmarks', description: 'A shared reading list.' }) },
+    }),
+    ui.page(bookmarkPage, {
+      views: [Detail],
+      head: {
+        query: getBookmark,
+        input: (params) => ({ id: params.id }),
+        failed: { NotFound: 404 },
+        render: (b) => ({ title: b.title, description: b.title, type: 'article' }),
+      },
+      entries: { query: listBookmarks, input: {}, params: (b) => ({ id: b.id }) },
+    }),
+  ],
+  kits: [uiKit],
+  features: [bookmarks],
+})

package/skill/example/previews.ts

@@ -0,0 +1,13 @@
+import { previews } from '@hozu/core/preview'
+import { listBookmarks } from './features/bookmarks/model.ts'
+import { home } from './routes.ts'
+import { Button } from './ui/button.ts'
+
+export default previews((p) => [
+  p.component(Button, 'Long label', {
+    variant: { tone: 'primary' },
+    children: 'Add it to the shared reading list',
+  }),
+  p.page(home, 'Empty list', [p.data(listBookmarks, [])]),
+  p.page(home, 'List failed', [p.fail(listBookmarks, 'Unexpected')]),
+])

package/skill/example/routes.ts

@@ -0,0 +1,11 @@
+import { route } from '@hozu/core'
+import { z } from 'zod'
+
+export const Show = z.enum(['all', 'unread'])
+
+export const home = route({ path: '/', params: null, search: z.object({ show: Show.default('all') }) })
+export const bookmarkPage = route({
+  path: '/bookmarks/:id',
+  params: z.object({ id: z.string() }),
+  search: null,
+})

package/skill/example/ui/badge.ts

@@ -0,0 +1,11 @@
+import { ui } from '@hozu/core'
+import { tv } from './tv.ts'
+
+const styles = tv({ base: 'rounded-full bg-slate-100 px-2 py-0.5 text-xs text-slate-600' })
+
+export const Badge = ui.component({
+  tag: 'span',
+  styles,
+  children: true,
+  render: ({ children }) => ui.span({}, children),
+})

package/skill/example/ui/button.ts

@@ -0,0 +1,23 @@
+import { ui } from '@hozu/core'
+import { z } from 'zod'
+import { tv } from './tv.ts'
+
+const styles = tv({
+  base: 'inline-flex items-center justify-center gap-2 rounded px-4 py-2 font-medium',
+  variants: {
+    tone: {
+      primary: 'bg-indigo-600 text-white hover:bg-indigo-700',
+      quiet: 'px-2 py-1 text-sm text-slate-600 hover:text-slate-900',
+    },
+  },
+  defaultVariants: { tone: 'primary' },
+})
+
+export const Button = ui.component({
+  tag: 'button',
+  styles,
+  props: z.object({ type: z.enum(['button', 'submit']).default('button') }),
+  children: true,
+  events: ['press'],
+  render: ({ props, children, on }) => ui.button({ type: props.type, on: { click: on.press } }, children),
+})

package/skill/example/ui/field.ts

@@ -0,0 +1,20 @@
+import { ui } from '@hozu/core'
+import { z } from 'zod'
+import { tv } from './tv.ts'
+
+const styles = tv({
+  slots: { base: 'flex-1 space-y-1', label: 'sr-only', error: 'text-sm text-rose-600' },
+})
+
+export const Field = ui.component({
+  tag: 'div',
+  styles,
+  props: z.object({ for: z.string(), label: z.string(), error: z.string().nullable(), errorId: z.string() }),
+  slots: ['control'],
+  render: ({ props, slots, classes }) =>
+    ui.div({}, [
+      ui.label({ for: props.for, class: classes.label }, [props.label]),
+      slots.control,
+      ui.p({ id: props.errorId, class: classes.error }, [props.error]),
+    ]),
+})