npm - @voltro/cli - Versions diffs - 0.52.0 → 0.54.0 - Mend

@voltro/cli 0.52.0 → 0.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (244) hide show

package/templates/agent-docs/schema-driven-ui.md CHANGED Viewed

@@ -173,8 +173,10 @@ A combined create-or-edit screen is a three-line wrapper:
 ### The customization ladder
 - **Rung 0 — zero config.** Fields render from the schema: a `Schema.Literal`
-  union → `select`; string → text; boolean → checkbox; `Date` → date; nested
-  object → a `custom` placeholder asking for a render-prop.
+  union → `select`; string → text; boolean → checkbox; `Schema.Date` → date;
+  a nested struct → a real `<fieldset>` SECTION with its legend and dotted
+  fields; widgets receive `onBlur`, so errors reveal on leave-field exactly
+  like the headless binding.
 - **Rung 1 — one custom widget** via a `<Field>` render-prop:
   ```tsx
   import { AutoForm, Field, AsyncSelect } from '@voltro/ui'
@@ -214,6 +216,189 @@ Schema.Struct({
 })
 ```
+### Validation — one schema, translated messages, server field errors
+Client and server validate the SAME input schema, and the messages a user
+sees are structured, not developer text. Every failed check maps to a stable
+message id with params — `validation.required`, `validation.minLength {min}`,
+`validation.minValue {min}` — rendered through a built-in en/de catalog. The
+locale follows `<html lang>` (the framework's locale contract); override it
+per form with `locale:`, or wire your own catalog in one line:
+```tsx
+// ONCE, at the app root — every form under it resolves ids through your catalog
+<ValidationMessagesProvider messages={(id, params) => t(id, params)}>
+  <App />
+</ValidationMessagesProvider>
+```
+A per-form `messages:` option still exists and wins over the provider; a
+resolver returning `undefined` falls through to the built-ins per id, so a
+partial catalog costs nothing.
+A widget kit that resolves ids itself reads the same resolver with
+`useValidationMessages()`. It returns the provider's function, or
+`undefined` when no provider is mounted — so a kit can fall through to the
+built-in catalog instead of shipping its own.
+Errors key the FULL field path (`address.city`, `entries.0.startsAt`), and a
+`message` annotation on a schema may BE an id with params — as may the issues
+a struct-level `filter` returns, which land at THEIR field:
+```ts
+const Input = Schema.Struct({
+  name: Schema.String.pipe(Schema.minLength(2)),
+  startsAt: Schema.Number,
+  endsAt: Schema.Number,
+}).pipe(
+  Schema.filter((v) =>
+    v.startsAt < v.endsAt ? undefined : [{ path: ['endsAt'], message: 'validation.beforeStart' }],
+  ),
+)
+```
+**Server-side rules route to their field too.** An executor raises a typed
+field error through the always-present `ctx.validation` — no declaration
+needed, `ValidationError` is auto-merged into every mutation's and action's
+wire error union exactly like `ScopeError`:
+```ts
+// executor
+if (await emailTaken(input.email)) {
+  return yield* ctx.validation.fail('email', 'validation.emailTaken')
+}
+yield* ctx.validation.require(input.startsAt < input.endsAt, 'endsAt', 'validation.beforeStart')
+// several at once: ctx.validation.failAll([{ field, message }, …])
+```
+The binding routes it: the message lands in `errors.email` (translated
+through the same catalog), the form stays editable, and `submitError` only
+carries what NO field can — a `BusinessRuleViolation` whose rule pinpointed
+a `field` routes the same way. Custom widget kits get the same judgement via
+`fieldIssuesOf(error)` from `@voltro/protocol`.
+**Async checks gate the submit.** Bind a uniqueness probe to its field and
+`submit` waits for it — an `invalid` verdict blocks with the message on that
+field, an unsettled check fails closed after 5s:
+```tsx
+const email = useAsyncValidation('app', 'users.emailAvailable', values.email ?? '', {
+  interpret: (r) => ({ valid: (r as { available: boolean }).available, message: 'Email taken' }),
+})
+const form = useFormBinding('app', 'users.create', { asyncFields: { email } })
+```
+**The binding is typed — `toInput` included.** `createHooks<AppProcedures>('app')`
+returns `useFormBinding` beside the other hooks — tag as a literal type,
+`values`/`defaults` and the submit output inferred from the descriptor. With
+`toInput`, the form gets its OWN `Values` shape and the mapper's return is
+checked against the mutation's input by the compiler — a mapping that stops
+producing the wire shape is a type error, not a runtime refusal.
+### The full binding — nested values, arrays, timing, one state
+`useFormBinding` carries a complete form, not just flat fields. Nested structs
+flatten into SECTIONS (`address.city`, grouped under `section('address')`),
+arrays of structs become field arrays, and every field is reachable as a
+bound handle a widget kit spreads onto its input:
+```tsx
+const form = useFormBinding('app', 'employees.update', {
+  defaults: fromRow(employee),
+  toInput: (values) => ({ id: employee.id, ...employeePatch(values) }),
+  errorPath: { fullName: 'name' },
+})
+const city = form.field('address.city')   // { value, setValue, onBlur, error, required, label, a11y, … }
+form.array('entries').push({ startsAt: '' })
+form.section('address')                    // the section's descriptors
+form.state                                 // { isDirty, canSubmit, isSubmitting, isSubmitSuccessful, submissionAttempts, errorCount, pending, … }
+form.reset(nextDefaults)                   // switch the edited record without a remount
+form.focusFirstInvalid()
+```
+**Error timing has defaults a form can trust:** a form NEVER opens with
+errors — a field reveals its error after ITS blur or after the first submit
+attempt, then live (`validate: { onChange: 'afterTouched' }`; `'always'` and
+`'never'` exist). `isValid`/`canSubmit` always tell the truth underneath, so
+the save button disables correctly while the user is not yet being scolded.
+**Values ≠ mutation input:** `toInput` maps form values to the wire input
+BEFORE validation; input-schema issues route back to form fields via
+`errorPath` (same-name fields map automatically). For composed saves,
+`onSubmit: async ({ input, values, mutate }) => …` owns the write and keeps
+optimistic + error routing.
+**Per-field rendering:** with `subscribe: 'fields'` the binding only
+re-renders on submission-level changes, and each field component subscribes
+narrowly:
+```tsx
+const BoundField = ({ form, path }: { form: FormBinding<Record<string, unknown>, unknown>; path: string }) => {
+  const f = useFormField(form, path)
+  return <input id={f.a11y.id} value={String(f.value ?? '')} onChange={(e) => f.setValue(e.target.value)} onBlur={f.onBlur} aria-invalid={f.a11y['aria-invalid']} />
+}
+```
+Annotate structure on the schema itself: `formField({ section, order, label,
+widget })` rides an annotation, `description` becomes help text, and
+`Schema.Date` / `Schema.DateTimeUtc` map to date/datetime widgets. The engine
+underneath is an implementation detail — no engine type appears in the public
+API, and production builds stub its devtools channel automatically.
+### Reference fields, uploads, and testing the form
+**Reference fields.** Mark a schema field as a table reference and it renders
+as a picker-shaped field whose VALUE stays the id (or id list — which is
+exactly what a target's declared `relations:` consumes):
+```ts
+const EmployeesUpdateInput = Schema.Struct({
+  id: Schema.String,
+  storeId: Schema.String.annotations(formField({ reference: 'stores' })),
+  assignedStores: Schema.Array(Schema.String).annotations(formField({ reference: 'stores' })),
+})
+```
+The descriptor carries `widget: 'reference'` + `reference: 'stores'`; bind
+the shipped `<AsyncSelect>` (or your own picker) to it via a render-prop —
+the default registry deliberately renders the render-prop note, because a
+live picker needs a query binding only the app can name.
+**Uploads as field values.** `useUpload` returns a `fileId`; hold it in a
+field and LINK it in the submit — the composed save is what `onSubmit` is
+for, so the upload that never got attached cannot happen silently:
+```tsx
+const form = useFormBinding('app', 'tasks.create', {
+  onSubmit: async ({ input, values, mutate }) => {
+    const row = await mutate(input)
+    // attachments: [...existing, ...uploaded fileIds] — linked HERE, not forgotten
+    return row
+  },
+})
+```
+**Leaving a dirty form** is guarded by the router: `useBlocker(form.state.isDirty)`
+holds SPA navigations (Back button included) and arms the native
+`beforeunload` prompt — see the routing docs.
+**Testing.** `renderFormBinding` (from `@voltro/testing/client`) drives the
+REAL binding against a fake api — fill, blur, submit, read the visible
+errors; a mutation handler that throws `ValidationError({ field })`
+exercises the same routing path a server refusal takes:
+```ts
+const form = await renderFormBinding('users.create', {
+  binding: { schema: UsersCreateInput },
+  mutation: () => { throw new ValidationError({ field: 'email', message: 'validation.emailTaken' }) },
+})
+await form.submit()
+expect(form.errors()['email']).toBe('validation.emailTaken')
+```
+Runs under jsdom (`// @vitest-environment jsdom`).
 ### Forms without JavaScript
 On a server-rendered page, `<AutoForm>` works with JavaScript disabled — or not
@@ -234,7 +419,18 @@ the SAME input schema the RPC path decodes:
 - unknown keys are dropped
 Validation runs through the same `validateFields` as the client-side
-validation, so the error texts are identical. Then:
+validation, so the error texts are identical — in the request's language, not
+in English. The handler resolves the locale from THIS request through the same
+resolver that decided the surrounding page's language ([`voltro:locale` cookie
+› `Accept-Language` › the app's
+`defaultLocale`](/docs/i18n/overview#locale-resolution-order)); an app that
+configures no `locales` gets `en`. Then:
+Under URL-prefix i18n the referring URL wins over the cookie chain: a form on
+`/de/todos` renders its errors in German even if the `voltro:locale` cookie says
+otherwise, because there the prefix is which page you are on rather than a
+preference. A first segment that is not a declared locale falls through to the
+cookie chain.
 - **Success → `303 See Other`** (POST-redirect-GET): back to the submitting
   page, or to `redirectTo` (same-origin relative paths only; anything else is
@@ -720,7 +916,33 @@ multi-device CRDT (single-user/device, honest about its limits).
 ```tsx
 const outbox = useOutbox({ send })
-// → { queue, enqueue, replay, online, pending, conflicts }
+// → { queue, enqueue, replay, online, pending, conflicts, resolveConflict }
+```
+**Durable across reloads.** Pass `persistence` and the queue survives:
+entries rehydrate on mount, every transition persists (delivered entries are
+compacted away), and a failing backing degrades to the in-memory behaviour
+instead of breaking the outbox. The one real implementation is
+`outboxPersistence()` from `@voltro/local-first`, backed by the same
+`PersistenceAdapter` the sync engine drains — one durable queue per device:
+```tsx
+import { createIndexedDbPersistence, outboxPersistence } from '@voltro/local-first'
+const adapter = await createIndexedDbPersistence()
+const outbox = useOutbox({ send, persistence: outboxPersistence(adapter) })
+```
+**Resolving a conflict.** A conflicted entry blocks everything behind it
+(causality). `resolveConflict(id, input)` replaces its input with the RESOLVED
+value, returns it to pending and replays — typically computed with
+`resolveWithPolicy()` from `@voltro/local-first`, where `crdtText()` columns
+merge and scalars follow the declared `conflictPolicy()`:
+```tsx
+outbox.resolveConflict(entry.id, resolveWithPolicy(policy, local, remote, {
+  crdtColumns: ['body'],
+}))
 ```

package/templates/agent-docs/security.md CHANGED Viewed

@@ -195,7 +195,7 @@ would break every link into your api.
 ### Raw WebSocket gateways are guarded before the upgrade
-A [`defineWebSocket` gateway](/docs/data/subscriptions#raw-websocket-gateways--definewebsocket)
+A [`defineWebSocket` gateway](/docs/data/subscriptions#raw-websocket-gateways-definewebsocket)
 mounts its own upgrade path beside the rpc socket, and the listener treats it
 exactly like the rpc upgrade:
@@ -479,7 +479,7 @@ deferred registry, the shell's bundle tags, and React's own bootstrap/settle
 scripts — while the policy header itself stays the middleware's to set via
 `responseHeaders`, carrying the same nonce. An `isr` page combined with
 `cspNonce` refuses the render: a cached nonce is a lie the browser enforces.
-Mechanics + examples: [Middleware → cspNonce](/docs/routing/middleware#a-per-request-csp-nonce--cspnonce).
+Mechanics + examples: [Middleware → cspNonce](/docs/routing/middleware#a-per-request-csp-nonce-cspnonce).
 ## Incoming webhooks must verify their caller
@@ -582,7 +582,7 @@ dependency, like a rate-limit counter in Redis — catches internally and
 degrades **loudly**. `@voltro/plugin-ratelimit`'s `httpShield` does exactly
 that: a Redis outage means unlimited-with-a-warning, never a self-inflicted API
 outage. The full authoring guidance is in the
-[plugin contract](/docs/plugins/contract#onhttprequest-httprequestinterceptor--pre-auth-http-pipeline-hook).
+[plugin contract](/docs/plugins/contract#onhttprequest-httprequestinterceptor-pre-auth-http-pipeline-hook).
 ## Response compression — and where BREACH sits

package/templates/agent-docs/templates/appshells.md CHANGED Viewed

@@ -13,7 +13,7 @@ _A marketing landing page — hero, features, CTA. Static-rendered with zero JS
 A marketing landing page. The page exports `renderMode = 'static'` + `interactive = 'none'`, so `voltro build` pre-renders it to HTML and `voltro start` serves the file directly — zero framework JS on the wire. Template id: **`frontend-landing`**.
-It ships plain JSX (a hero, a features list, a CTA) you replace with your own copy — no design-system dependency to fight. When you need a contact form or sign-up flow, switch `interactive: 'islands'` on the page and mark the interactive component with a `*.island.tsx` suffix so only that bundle ships.
+It ships plain JSX (a hero, a features list, a CTA) you replace with your own copy, bilingual out of the box (URL-prefix i18n: `/` + `/de`), plus the two asset pipelines a marketing page actually needs: a **local hero image** through `?image` + `<Image>` and a **self-hosted woff2** declared under `fonts:`. When you need a contact form or sign-up flow, switch `interactive: 'islands'` on the page and mark the interactive component with a `*.island.tsx` suffix so only that bundle ships.
 ## Scaffold
@@ -27,14 +27,21 @@ voltro add-app marketing --template=frontend-landing --to acme
 ```text
 apps/acme/web/                          # dir named by the app, not the template
-├── app.config.ts                       # type:web, port:<allocated>
+├── app.config.ts                       # type:web, port:<allocated>, locales, fonts:
 ├── package.json
 ├── tsconfig.json
 └── src/
     ├── globals.css
+    ├── globals.d.ts                    # ambient '*.css' + '*?image'
+    ├── assets/hero.jpg                 # imported with ?image (build-time pipeline)
+    ├── fonts/Geist-Variable.woff2      # self-hosted, declared in app.config.ts
+    ├── fonts/LICENSE-Geist.txt         # the face's licence, shipped beside it
+    ├── lib/locale.ts                   # URL-prefix i18n helpers
+    ├── locales/{en,de}.ts              # the two catalogs
     └── pages/
         ├── layout.tsx                  # imports globals.css, renders {children}
-        └── index.tsx                   # the landing page (hero · features · CTA)
+        ├── page.tsx                    # the landing page (hero · features · CTA)
+        └── [locale]/page.tsx           # the /de mirror
 ```
 ## The page
@@ -88,9 +95,34 @@ import SignupForm from '../components/SignupForm.island'
 The surrounding HTML stays static; only the island hydrates.
+## The hero image — `?image` + `<Image>`
+`src/assets/hero.jpg` is imported with the **`?image` suffix**, the explicit opt-in to the [build-time image pipeline](/docs/routing/assets): the import resolves to an optimized-asset object instead of vite's plain hashed URL, and `<Image>` renders it as a `<picture>` with one `<source>` per modern format.
+```tsx
+import { Image } from '@voltro/web'
+import hero from '../assets/hero.jpg?image'
+<Image src={hero} alt="Abstract gradient artwork" priority sizes="(max-width: 900px) 100vw, 900px" />
+```
+`width`, `height` and the blur placeholder are **not props** — they come off the asset, which is what reserves the box (CLS ≈ 0) without hand-written numbers. `priority` marks it the LCP image (eager + high fetch priority). Nothing here needs JS, so it survives `interactive: 'none'`.
+The `*?image` ambient type is declared once in `src/globals.d.ts`. A **dynamic** `src` (a URL from a loader or CMS frontmatter) cannot be seen at build time — use the loader seam (`<Image src={url} loader={cdn} />`) instead.
+> **Under `voltro test`** the image plugin is not wired (it is a dev/build transform), so a `?image` specifier resolves to a plain URL string. The shipped `page.test.tsx` `vi.mock`s the import with the asset object the pipeline produces — copy that pattern rather than hand-writing `width`/`height` on the page.
+## The font — self-hosted, no CDN
+`app.config.ts` declares one family under [`fonts:`](/docs/routing/fonts), pointing at the woff2 committed in `src/fonts/`. The build content-hashes it and serves it from **your origin**, emits `@font-face`, computes a size-adjusted fallback face from the file's real metrics so the swap moves no text, and puts a `<link rel="preload">` in the shell.
+Reference it from CSS through the `--font-geist` variable the shell defines (`globals.css` points the kit's `--font-sans` at it), or from TSX with `localFont('Geist')`.
+**Swapping in your own face:** drop the `woff2` **and its licence file** into `src/fonts/`, then change `family` + `path`. The framework ships no font downloader on purpose — licence terms differ per family. The bundled Geist is SIL OFL 1.1 (`src/fonts/LICENSE-Geist.txt`).
 ## Styling
-`globals.css` is yours. Add `@import "tailwindcss"` plus the mandatory `@source "./**/*.{tsx,ts,jsx,js}"` glob if you want Tailwind, or `@import "@voltro/ui-shadcn/tokens.css"` (plus the kit `@source`) to pull in the design tokens and compose shadcn-style components on top.
+`globals.css` imports `@voltro/ui-shadcn/tokens.css` (the design tokens) plus the mandatory `@source "./**/*.{tsx,ts,jsx,js}"` glob. Drop the kit import and use `@import "tailwindcss"` directly if you would rather start from nothing — but keep the `@source` line either way, and keep the `--font-sans` mapping if you keep the font declaration.
 ## What it doesn't ship