@maestro-js/agent-skills 1.0.0-alpha.0

package/dist/maestro-packages/exceptions.md

@@ -0,0 +1,231 @@
+---
+name: exceptions
+description: "Centralized exception reporting with automatic severity mapping and structured context, backed by @maestro-js/log. Use when working with @maestro-js/exceptions — reporting errors, silencing expected exceptions, attaching tags/extra metadata to error reports, or integrating exception handling into application services. Key capabilities: report exceptions with auto-detected severity (Error maps to 'error', non-Error maps to 'warn'), override log level via context, ignore/unignore specific exception instances, attach structured tags and extra data to reports. Follows the Provider pattern from @maestro-js/service-registry."
+---
+
+# @maestro-js/exceptions
+
+Centralized exception reporting that forwards exceptions as structured log entries through `@maestro-js/log`. Severity is auto-detected (`Error` instances log at `'error'`, everything else at `'warn'`) but can be overridden per report.
+
+## Quick Setup
+
+```ts
+import { Log } from '@maestro-js/log'
+import { Exceptions } from '@maestro-js/exceptions'
+
+// 1. Create a logger
+const logger = Log.create<[Exceptions.LogMessage]>({
+  transports: [{ write(message) { console.log(message) } }]
+})
+
+// 2. Create and register the exceptions service
+const service = Exceptions.Provider.create({ logger })
+Exceptions.Provider.register('default', service)
+
+// 3. Use the facade directly
+Exceptions.report(new Error('disk full'))
+```
+
+## Provider Pattern
+
+Follows the standard Maestro service-registry pattern.
+
+| Export | Purpose |
+|---|---|
+| `Exceptions.Provider.create(config)` | Factory — accepts `{ logger }` and returns an `ExceptionsService` |
+| `Exceptions.Provider.register(name, service)` | Register a named instance in the registry |
+| `Exceptions.provider(key)` | Resolve a named instance |
+| `Exceptions.report(...)` / `Exceptions.ignore(...)` / etc. | Facade — delegates to the `'default'` provider |
+
+### Config
+
+```ts
+interface ExceptionsServiceConfig {
+  logger: Log.LogFunctions<[Exceptions.LogMessage]>
+}
+```
+
+The `logger` must be a typed `Log` instance parameterized with `[Exceptions.LogMessage]`. Typically created via `Log.create<[Exceptions.LogMessage]>({ transports: [...] })` or by calling `.channel()` on an existing logger.
+
+## API Reference
+
+### `report(exception: unknown, context?: Exceptions.Context): void`
+
+Log an exception through the configured logger. Skips exceptions marked by `ignore()`.
+
+- `Error` instances default to `'error'` level.
+- Non-Error values (strings, objects, etc.) default to `'warn'` level.
+- Override level, attach `tags`, or add `extra` metadata via the context parameter.
+
+```ts
+// Basic error report
+Exceptions.report(new Error('disk full'))
+
+// Non-Error value — logged at 'warn'
+Exceptions.report('something broke')
+
+// Override level and attach metadata
+Exceptions.report(err, {
+  level: 'emergency',
+  tags: { userId: '42', region: 'us-east' },
+  extra: { requestBody: body }
+})
+```
+
+### `ignore<E>(exception: E): E`
+
+Mark an exception so future `report()` calls silently skip it. Returns the same reference.
+
+Only object-type values (Error instances, plain objects, arrays) are tracked via an internal `WeakMap`. Primitives (string, number, null, undefined) are returned unchanged but not tracked.
+
+```ts
+const err = new Error('expected')
+Exceptions.ignore(err)
+Exceptions.report(err) // no-op — silently skipped
+```
+
+### `unignore<E>(exception: E): E`
+
+Reverse a previous `ignore()` call, allowing the exception to be reported again. Returns the same reference. No-op if the exception was never ignored or is a primitive.
+
+```ts
+Exceptions.unignore(err)
+Exceptions.report(err) // now logged again
+```
+
+### `isIgnored(exception: unknown): boolean`
+
+Check whether an exception has been previously marked by `ignore()`. Returns `false` for primitives.
+
+```ts
+Exceptions.isIgnored(err) // true if ignore() was called on this reference
+```
+
+## Types
+
+### `Exceptions.LogMessage`
+
+Structured payload written to the logger on each `report()` call.
+
+```ts
+interface LogMessage {
+  exception: any
+  tags?: { [key: string]: Primitive }
+  extra?: Record<string, unknown>
+}
+```
+
+`Primitive` is `number | string | boolean | bigint | symbol | null | undefined`.
+
+### `Exceptions.Context`
+
+Optional metadata passed to `report()`.
+
+```ts
+type Context = {
+  tags?: { [key: string]: Primitive }
+  extra?: Record<string, unknown>
+  level?: Log.Level
+}
+```
+
+When `level` is omitted, severity is auto-detected from the exception type.
+
+## Common Patterns
+
+### Error Reporting with Context
+
+Attach structured tags for filtering and extra data for debugging.
+
+```ts
+try {
+  await processOrder(orderId)
+} catch (err) {
+  Exceptions.report(err, {
+    tags: { orderId, userId: ctx.userId },
+    extra: { payload: ctx.body }
+  })
+}
+```
+
+### Silencing Expected Exceptions
+
+Mark known/expected exceptions to prevent noise in logs.
+
+```ts
+const err = new Error('expected timeout')
+const ignored = Exceptions.ignore(err)
+// ... pass ignored around; any report() call with this reference is a no-op
+Exceptions.report(ignored) // silent
+
+// Later, re-enable reporting
+Exceptions.unignore(ignored)
+Exceptions.report(ignored) // now logged
+```
+
+### Multiple Named Providers
+
+Register separate exception services for different subsystems.
+
+```ts
+const apiService = Exceptions.Provider.create({ logger: apiLogger })
+Exceptions.Provider.register('api', apiService)
+
+const workerService = Exceptions.Provider.create({ logger: workerLogger })
+Exceptions.Provider.register('worker', workerService)
+
+// Use a specific provider
+Exceptions.provider('api').report(err)
+Exceptions.provider('worker').report(err)
+```
+
+### Isolation Between Services
+
+Each service instance maintains its own ignore state. Ignoring an exception in one service does not affect other services.
+
+```ts
+const a = Exceptions.Provider.create({ logger: loggerA })
+const b = Exceptions.Provider.create({ logger: loggerB })
+
+a.ignore(err)
+a.isIgnored(err)  // true
+b.isIgnored(err)  // false — independent state
+```
+
+## Cross-Package Integration
+
+### Dependencies
+
+- **`@maestro-js/service-registry`** — provides the Provider registry pattern
+- **`@maestro-js/log`** — the logger that receives exception reports; the `logger` config must be a `Log.LogFunctions<[Exceptions.LogMessage]>` instance
+
+### Works With
+
+- **`@maestro-js/log`** — create typed loggers with transports (console, file, external services) that receive structured `LogMessage` entries
+- **`@maestro-js/context`** — use `AsyncLocalStorage`-based context to pull request-scoped data (user ID, request ID) into exception report tags/extra
+
+## Testing
+
+Tests are at `packages/exceptions/tests/exceptions.test.ts`.
+
+```bash
+pnpm --filter @maestro-js/exceptions test
+```
+
+Test setup creates an in-memory logger that captures messages for assertion:
+
+```ts
+function setup() {
+  const messages: Log.Message<[Exceptions.LogMessage]>[] = []
+  const logger = Log.create<[Exceptions.LogMessage]>({
+    transports: [{ write(message) { messages.push(message) } }]
+  })
+  const service = Exceptions.Provider.create({ logger })
+  return { service, messages }
+}
+```
+
+## Source Files
+
+- `packages/exceptions/src/index.ts` — single source file containing types, factory, registry, and facade
+- `packages/exceptions/package.json` — package manifest

package/dist/maestro-packages/form.md

@@ -0,0 +1,391 @@
+---
+name: form
+description: "Headless React form primitives with client and server validation, hidden inputs for custom components, controlled/uncontrolled state management, and Standard Schema (Zod) FormData parsing with automatic type coercion. Use when building custom form components that need native constraint validation, server error integration, file upload handling, or type-safe FormData parsing. Provides HeadlessForm root component, useValidation/useWarningState/useControlledState/useReset hooks, HiddenInput/HiddenFileInput/HiddenSelect components, parseFormData/parseFormDataClientSide utilities, and composeValidators."
+---
+
+# @maestro-js/form
+
+Headless React form primitives with client and server validation, hidden inputs for custom components, controlled/uncontrolled state management, and Standard Schema (Zod) FormData parsing with automatic type coercion.
+
+## Quick Setup
+
+```tsx
+import { HeadlessForm } from '@maestro-js/form'
+
+// 1. Wrap your app with GlobalProvider to enable server error integration
+function App() {
+  return (
+    <HeadlessForm.GlobalProvider useServerErrors={useMyServerErrors}>
+      <MyPage />
+    </HeadlessForm.GlobalProvider>
+  )
+}
+
+// 2. Use HeadlessForm as your form element
+function LoginForm() {
+  return (
+    <HeadlessForm as="form" method="post" action="/login">
+      <input name="email" type="email" required />
+      <button type="submit">Log in</button>
+    </HeadlessForm>
+  )
+}
+```
+
+## Core Concepts
+
+### Validation Flow
+
+Custom validation via `validate` functions runs in realtime, setting `setCustomValidity()` on the referenced native element. Errors are committed (shown to the user) on input `change` or form `submit`. Server errors from `GlobalProvider` are shown immediately and cleared when the user edits the field. The first invalid input auto-focuses on submit.
+
+### Hidden Inputs for Custom Components
+
+Custom UI components (dropdowns, file pickers, date pickers) can't natively participate in HTML forms. `HiddenInput`, `HiddenFileInput`, and `HiddenSelect` bridge this gap with visually-hidden native elements that carry the value and participate in constraint validation.
+
+### FormData Parsing
+
+`parseFormData` and `parseFormDataClientSide` convert native FormData into typed objects using a Standard Schema (Zod). They handle type coercion (strings to numbers/booleans), nested objects via dot notation (`address.city`), arrays, and file uploads.
+
+## API Reference
+
+### HeadlessForm (Component)
+
+```tsx
+<HeadlessForm as="form" method="post" id="profile-form">
+  {children}
+</HeadlessForm>
+```
+
+Root form component. Wraps a native `<form>` with validation and server error support.
+
+- `as` -- Component to render (must resolve to `HTMLFormElement`)
+- `method` -- `'get'` | `'post'` | `'put'` | `'patch'` | `'delete'`
+- `id` -- Optional (auto-generated via `useId()` if omitted)
+- Plus all standard form element props
+
+GET forms validate on submit and prevent submission if invalid. Non-GET forms inject a hidden `__formId` input for server-side form identification.
+
+### GlobalProvider
+
+```tsx
+<HeadlessForm.GlobalProvider useServerErrors={useMyServerErrors}>
+  {children}
+</HeadlessForm.GlobalProvider>
+```
+
+Wraps your app to provide server error resolution to all forms. The `useServerErrors` prop is a hook with signature:
+
+```ts
+(formId: string) => { path: string; message: string }[] | null
+```
+
+### useValidation
+
+```ts
+HeadlessForm.useValidation<T>(
+  props: {
+    name: string | string[]
+    value: T
+    form: string
+    validate?: ValidationFunction<T>
+    isInvalid?: boolean
+    isRequired?: boolean
+    focus?: () => void
+  },
+  ref: RefObject<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>
+): {
+  isInvalid: boolean
+  validationErrors: string[]
+  validationDetails: ValidityState
+  validationMessage: string
+  commitValidation(): void
+}
+```
+
+Connects custom validation to the native Constraint Validation API. Use inside custom input components.
+
+- Runs `validate(value)` in realtime, sets `setCustomValidity()` on the referenced element
+- Commits errors on `change` event or form submit (`invalid` event)
+- Auto-focuses the first invalid input on submission
+- Integrates server errors from `GlobalProvider` -- clears when user edits
+- Resets on form `reset` event
+
+### useWarningState
+
+```ts
+HeadlessForm.useWarningState<T>(
+  props: { value: T; validate?: ValidationFunction<T>; isInvalid?: boolean }
+): {
+  realtimeValidation: ValidationResult
+  displayValidation: ValidationResult
+  warningMessage: string
+  commitValidation(): void
+  resetValidation(): void
+  updateValidation(result: ValidationResult): void
+}
+```
+
+Like `useValidation` but for non-blocking warnings. Does not integrate with native constraint validation or server errors. Use for soft validation hints that don't prevent submission.
+
+### useControlledState
+
+```ts
+HeadlessForm.useControlledState<T>(
+  value: T | undefined,
+  defaultValue: T,
+  onChange?: (v: T) => void
+): [T, (value: T) => void]
+```
+
+Manages controlled/uncontrolled state for custom form components. When `value` is defined, the component is controlled; when `undefined`, it uses `defaultValue` and manages its own state.
+
+### useReset
+
+```ts
+HeadlessForm.useReset(
+  ref: RefObject<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>,
+  initialValue: T,
+  onReset: (value: T) => void
+)
+```
+
+Calls `onReset` with the initial value when the parent form fires a `reset` event.
+
+### useServerErrors
+
+```ts
+HeadlessForm.useServerErrors(formId?: string): { path: string; message: string }[]
+```
+
+Returns server errors for the given form ID (or the current form's ID from context if omitted). Requires `GlobalProvider` in the tree.
+
+### useTopLevelFormValidation
+
+```ts
+HeadlessForm.useTopLevelFormValidation(
+  formElement: HTMLFormElement | string
+): { revalidate(field: string | null): void }
+```
+
+Programmatically re-triggers validation on form fields. Pass `null` to revalidate all fields, or a field name prefix to revalidate only matching fields.
+
+### composeValidators
+
+```ts
+HeadlessForm.composeValidators<T>(
+  ...fns: (ValidationFunction<T> | undefined | null)[]
+): ValidationFunction<T>
+```
+
+Combines multiple validation functions. Each is called with the value; all returned errors are collected into a single array.
+
+```ts
+const required = (v: string) => (!v ? 'Required' : null)
+const minLen = (min: number) => (v: string) => (v.length < min ? `At least ${min} chars` : null)
+
+const validate = HeadlessForm.composeValidators(required, minLen(5))
+validate('')  // ['Required', 'At least 5 chars']
+```
+
+### Hidden Input Components
+
+#### HiddenInput
+
+Visually hidden `<input>` that participates in form submission. Use inside custom components.
+
+```tsx
+<HeadlessForm.HiddenInput ref={inputRef} name="country" value={selectedCountry} form={formId} isRequired />
+```
+
+Props: `value`, `name`, `form`, `isRequired`, `type`, `min`, `max`
+
+#### HiddenFileInput
+
+Visually hidden `<input type="file">` with programmatic file assignment via `DataTransfer`.
+
+```tsx
+<HeadlessForm.HiddenFileInput ref={fileRef} name="avatar" value={selectedFile} form={formId} isRequired />
+```
+
+Props: `value` (`File | File[] | null`), `name`, `form`, `isRequired`
+
+#### HiddenSelect
+
+Visually hidden `<select>` for custom dropdown components.
+
+```tsx
+<HeadlessForm.HiddenSelect ref={selectRef} name="role" value={selectedRole} form={formId} isRequired>
+  <option value="admin">Admin</option>
+  <option value="viewer">Viewer</option>
+</HeadlessForm.HiddenSelect>
+```
+
+Props: `value`, `name`, `form`, `isRequired`, `children`, `autoComplete`, `onChange`, `label`
+
+### FormData Parsing
+
+#### parseFormData
+
+```ts
+HeadlessForm.parseFormData<T>(
+  schema: StandardSchema<T>,
+  formData: FormData | Promise<FormData>,
+  options?: {
+    handleFile?(file: File, path: string, data: T): Promise<string>
+    libraryOptions?: Record<string, unknown>
+  }
+): Promise<ParseFormDataResult<T>>
+```
+
+Server-side FormData parser. Converts raw FormData into a typed object validated against a Standard Schema (Zod).
+
+```ts
+const schema = z.object({ name: z.string(), age: z.number(), avatar: z.string() })
+
+const result = await HeadlessForm.parseFormData(schema, request.formData(), {
+  handleFile: async (file) => await uploadToS3(file)
+})
+
+if (result.success) {
+  result.data // { name: 'Alice', age: 30, avatar: 'https://cdn.example.com/avatar.png' }
+}
+```
+
+#### parseFormDataClientSide
+
+```ts
+HeadlessForm.parseFormDataClientSide<T>(
+  schema: StandardSchema<T>,
+  formData: FormData,
+  options?: ParseFormDataOptions<T>
+): ParseFormDataResult<T> & { fileEntries: FoundFile[] }
+```
+
+Synchronous client-side variant. Files are replaced with placeholder URLs for validation; actual file entries are returned separately in `fileEntries`.
+
+### Coercion Rules
+
+The parser uses the schema's JSON Schema representation to coerce FormData string values:
+
+| Schema Type | FormData Value | Result |
+| --- | --- | --- |
+| `string` | `'Alice'` | `'Alice'` |
+| `string` (nullable) | `''` | `null` |
+| `number` / `integer` | `'42'` | `42` |
+| `number` (empty) | `''` | `null` |
+| `boolean` | `'true'` / `'false'` | `true` / `false` |
+| `boolean` (absent) | *(missing)* | `false` |
+| `array` | multiple values | `['a', 'b']` |
+| `array` | JSON string `'[1,2]'` | `[1, 2]` |
+| `array` (empty) | `''` | `[]` |
+| nested object | `'addr.city'` key | `{ addr: { city: ... } }` |
+| array of objects | `'items.0.name'` key | `[{ name: ... }]` |
+
+### Types
+
+```ts
+type ValidationFunction<T> = (value: T) => string | string[] | null | undefined
+
+interface ValidationResult {
+  isInvalid: boolean
+  validationDetails: ValidityState
+  validationErrors: string[]
+}
+
+type ParseFormDataResult<T> =
+  | { success: true; data: T; formData: FormData; formId: string | null; issues: undefined }
+  | { success: false; data: any; formData: FormData; formId: string | null; issues: readonly StandardSchemaV1.Issue[] }
+```
+
+## Common Patterns
+
+### Custom Input with Validation
+
+```tsx
+function PhoneInput({ name, form }: { name: string; form: string }) {
+  const inputRef = useRef<HTMLInputElement>(null)
+  const [value, setValue] = HeadlessForm.useControlledState<string>(undefined, '')
+
+  const validation = HeadlessForm.useValidation(
+    {
+      name,
+      form,
+      value,
+      validate: (v) => (v && !/^\d{10}$/.test(v) ? 'Enter a 10-digit phone number' : null)
+    },
+    inputRef
+  )
+
+  HeadlessForm.useReset(inputRef, '', setValue)
+
+  return (
+    <div>
+      <input value={value} onChange={(e) => setValue(e.target.value)} />
+      <HeadlessForm.HiddenInput ref={inputRef} name={name} value={value} form={form} />
+      {validation.isInvalid && <span>{validation.validationMessage}</span>}
+    </div>
+  )
+}
+```
+
+### Server-Side Form Processing
+
+```ts
+async function handleProfileUpdate(formData: FormData) {
+  const schema = z.object({
+    name: z.string().min(1),
+    bio: z.string().nullable(),
+    age: z.number().min(13),
+    avatar: z.string(),
+    tags: z.array(z.string())
+  })
+
+  const result = await HeadlessForm.parseFormData(schema, formData, {
+    handleFile: async (file) => uploadToStorage(file)
+  })
+
+  if (!result.success) {
+    return { errors: result.issues.map((i) => ({ path: i.path?.join('.') ?? '', message: i.message })) }
+  }
+
+  await db.updateUser(result.data)
+}
+```
+
+### Custom Select with Hidden Native Element
+
+```tsx
+function RoleSelect({ name, form }: { name: string; form: string }) {
+  const selectRef = useRef<HTMLSelectElement>(null)
+  const [value, setValue] = HeadlessForm.useControlledState<string>(undefined, '')
+
+  const validation = HeadlessForm.useValidation({ name, form, value, isRequired: true }, selectRef)
+  HeadlessForm.useReset(selectRef, '', setValue)
+
+  return (
+    <div>
+      <CustomDropdown value={value} onChange={setValue} options={['admin', 'editor', 'viewer']} />
+      <HeadlessForm.HiddenSelect ref={selectRef} name={name} value={value} form={form} isRequired>
+        <option value="admin">Admin</option>
+        <option value="editor">Editor</option>
+        <option value="viewer">Viewer</option>
+      </HeadlessForm.HiddenSelect>
+      {validation.isInvalid && <span>{validation.validationMessage}</span>}
+    </div>
+  )
+}
+```
+
+## Warnings and Gotchas
+
+> **Warning:** `GlobalProvider` must wrap your app before any `HeadlessForm` is rendered. Without it, `useServerErrors` throws: `'GlobalContext not found. Please wrap your site with GlobalProvider'`.
+
+> **Warning:** Do not use async validation with `parseFormData` / `parseFormDataClientSide` -- they throw `'Async validation not supported'`. All schema validation must be synchronous.
+
+> **Note:** Non-GET forms inject a hidden `__formId` field. `parseFormData` strips this automatically. If you parse FormData manually, filter out `__formId`.
+
+> **Note:** `parseFormData` requires a `handleFile` option when the form contains file uploads. Without it, it throws. The client-side variant replaces files with placeholder URLs instead.
+
+> **Warning:** Unchecked boolean checkboxes are absent from FormData. The parser defaults these to `false` based on the schema. If the boolean field isn't declared in the schema, the absent value won't be coerced.
+
+> **Note:** `useControlledState` warns in the console if a component switches between controlled and uncontrolled mode. Always consistently pass either a value or `undefined`.