@stacksjs/defaults 0.70.206 → 0.70.208

package/ai/skills/stacks-health/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: stacks-health
+description: Use when implementing health checks in a Stacks application — service monitoring, health endpoints, or diagnostic checks. Covers @stacksjs/health (currently WIP — Oh Dear integration planned).
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Health
+
+## Key Paths
+- Core package: `storage/framework/core/health/src/`
+- Drivers: `storage/framework/core/health/src/drivers/`
+- Notifications: `storage/framework/core/health/src/notifications/`
+- Package: `@stacksjs/health`
+
+## Source Files
+```
+health/src/
+├── index.ts              # Re-exports drivers and notifications
+├── drivers/
+│   ├── index.ts          # Driver exports
+│   └── ohdear.ts         # Oh Dear health check driver (WIP)
+└── notifications/
+    └── index.ts          # Health notifications (WIP)
+```
+
+## Current Status
+
+**This package is WIP.** Current exports are placeholder markers:
+
+```typescript
+export const ohdearWip = 1              // Oh Dear driver placeholder
+export const healthNotificationsWip = 1  // Notifications placeholder
+```
+
+## Built-in Health Endpoint
+
+The health check functionality currently lives in the router, not this package:
+
+```
+GET /health
+```
+
+Returns:
+```json
+{
+  "status": "ok",
+  "uptime": 12345,
+  "memory": { "rss": 1234567, "heapUsed": 987654 },
+  "pid": 1234,
+  "bunVersion": "1.3.0"
+}
+```
+
+This endpoint is registered via `route.health()` in the router.
+
+## CLI Commands
+
+```bash
+buddy doctor              # Comprehensive system diagnostics
+```
+
+## Planned Features
+- Oh Dear integration for external health monitoring
+- Health check notifications (email, Slack, etc.)
+- Custom health check drivers
+- Database connectivity checks
+- External service status verification
+
+## Gotchas
+- **Package is WIP** — only placeholder exports exist
+- **Health endpoint is in the router** — `GET /health` works via `route.health()`, not this package
+- **`buddy doctor`** — system diagnostics are in the buddy CLI, not this health package
+- **Oh Dear driver planned** — integration with ohdear.app for external monitoring

package/ai/skills/stacks-http/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: stacks-http
+description: Use when working with HTTP utilities in a Stacks application — HTTP status codes, making outbound HTTP requests via HttxClient, reactive fetch composables (useFetch/createFetch), or HTTP-related helpers. Covers @stacksjs/http, @stacksjs/httx, and the fetch composables in @stacksjs/composables.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks HTTP
+
+## Key Paths
+- Core package: `storage/framework/core/http/src/`
+- Composables (useFetch/createFetch): `storage/framework/core/composables/src/useFetch.ts`, `storage/framework/core/composables/src/createFetch.ts`
+- Buddy CLI command: `storage/framework/core/buddy/src/commands/http.ts`
+- httx dependency (installed): `node_modules/@stacksjs/httx/`
+- Package: `@stacksjs/http` (status codes), `@stacksjs/httx` (HTTP client), `@stacksjs/composables` (useFetch/createFetch)
+
+## Source Files
+```
+http/src/
+└── index.ts           # Response enum — all HTTP status codes (100-511)
+
+composables/src/
+├── useFetch.ts        # Chainable reactive fetch composable (builder pattern)
+└── createFetch.ts     # Factory for pre-configured useFetch with baseUrl
+
+buddy/src/commands/
+└── http.ts            # `buddy http [domain]` CLI command using HttxClient
+```
+
+## Response Enum — HTTP Status Codes (index.ts)
+
+The `@stacksjs/http` package exports a single `Response` enum with all standard HTTP status codes:
+
+```typescript
+import { Response } from '@stacksjs/http'
+
+Response.HTTP_OK                    // 200
+Response.HTTP_CREATED               // 201
+Response.HTTP_NO_CONTENT            // 204
+Response.HTTP_MOVED_PERMANENTLY     // 301
+Response.HTTP_NOT_MODIFIED          // 304
+Response.HTTP_BAD_REQUEST           // 400
+Response.HTTP_UNAUTHORIZED          // 401
+Response.HTTP_FORBIDDEN             // 403
+Response.HTTP_NOT_FOUND             // 404
+Response.HTTP_UNPROCESSABLE_ENTITY  // 422
+Response.HTTP_TOO_MANY_REQUESTS     // 429
+Response.HTTP_INTERNAL_SERVER_ERROR // 500
+Response.HTTP_SERVICE_UNAVAILABLE   // 503
+```
+
+### Full Status Code Categories
+- **1xx Informational**: `HTTP_CONTINUE` (100), `HTTP_SWITCHING_PROTOCOLS` (101)
+- **2xx Success**: `HTTP_OK` (200), `HTTP_CREATED` (201), `HTTP_ACCEPTED` (202), `HTTP_NON_AUTHORITATIVE_INFORMATION` (203), `HTTP_NO_CONTENT` (204), `HTTP_RESET_CONTENT` (205), `HTTP_PARTIAL_CONTENT` (206)
+- **3xx Redirection**: `HTTP_MULTIPLE_CHOICES` (300), `HTTP_MOVED_PERMANENTLY` (301), `HTTP_FOUND` (302), `HTTP_SEE_OTHER` (303), `HTTP_NOT_MODIFIED` (304), `HTTP_USE_PROXY` (305), `HTTP_UNUSED` (306), `HTTP_TEMPORARY_REDIRECT` (307), `HTTP_PERMANENT_REDIRECT` (308)
+- **4xx Client Error**: `HTTP_BAD_REQUEST` (400) through `HTTP_UNAVAILABLE_FOR_LEGAL_REASONS` (451) — includes `HTTP_I_AM_A_TEAPOT` (418)
+- **5xx Server Error**: `HTTP_INTERNAL_SERVER_ERROR` (500) through `HTTP_NETWORK_AUTHENTICATION_REQUIRED` (511)
+
+## HttxClient — Outbound HTTP Client (@stacksjs/httx)
+
+The `@stacksjs/httx` package provides the `HttxClient` class for making outbound HTTP requests. It wraps Bun's `fetch()` with retry logic, timeouts, timing data, and Result-based error handling via `ts-error-handling`.
+
+```typescript
+import { HttxClient } from '@stacksjs/httx'
+
+const client = new HttxClient(config?: Partial<HttxConfig>)
+const result = await client.request<T>(url: string, options: RequestOptions): Promise<Result<HttxResponse<T>, Error>>
+```
+
+### HttxConfig
+```typescript
+interface HttxConfig {
+  verbose?: boolean | string[]       // Enable debug logging (or filter by category)
+  defaultHeaders?: Record<string, string>
+  baseUrl?: string                   // Prepended to all request URLs
+  timeout?: number                   // Request timeout in ms
+  retry?: RetryOptions               // Default retry configuration
+}
+```
+
+### RequestOptions
+```typescript
+interface RequestOptions {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'
+  query?: Record<string, string>     // URL query parameters
+  form?: boolean                     // Send body as form-encoded
+  multipart?: boolean                // Send body as multipart/form-data
+  json?: boolean                     // Send body as JSON
+  unix?: string                      // Unix socket path
+  proxy?: string                     // Proxy URL
+  downloadProgress?: (progress: number) => void
+  retry?: RetryOptions               // Per-request retry override
+  stream?: boolean                   // Stream response
+  acceptHeader?: string              // Override Accept header
+  verbose?: boolean
+  timeout?: number
+  body?: BodyInit | Record<string, string>
+  headers?: HeadersInit
+}
+```
+
+### RetryOptions
+```typescript
+interface RetryOptions {
+  retries?: number                   // Max retry attempts
+  retryDelay?: number                // Base delay between retries (ms)
+  retryOn?: number[]                 // HTTP status codes that trigger retry
+  shouldRetry?: (error: Error, attempt: number) => boolean  // Custom retry predicate
+}
+```
+
+### HttxResponse
+```typescript
+interface HttxResponse<T = unknown> {
+  status: number
+  statusText: string
+  headers: Headers
+  data: T
+  timings: {
+    start: number
+    end: number
+    duration: number                 // Total request duration in ms
+  }
+}
+```
+
+### Result Pattern (from ts-error-handling)
+`client.request()` returns a `Result<HttxResponse<T>, Error>`. Use `.match()` to handle success/failure:
+
+```typescript
+const result = await client.request('https://api.example.com/users', {
+  method: 'GET',
+})
+
+result.match({
+  ok: (response) => {
+    console.log(response.status)          // 200
+    console.log(response.timings.duration) // e.g. 142 (ms)
+    console.log(response.data)            // parsed response body
+  },
+  err: (error) => {
+    console.error(error.message)
+  },
+})
+```
+
+Or use `result.isOk` / `result.value` / `result.error` directly.
+
+### Error Classes
+```typescript
+class HttxError extends Error {
+  readonly context?: Record<string, unknown>
+}
+
+class HttxRequestError extends HttxError {
+  readonly method: string
+  readonly url: string
+  readonly statusCode?: number
+}
+
+class HttxTimeoutError extends HttxError {
+  readonly method: string
+  readonly url: string
+  readonly timeout: number
+}
+
+class HttxNetworkError extends HttxError {
+  readonly method: string
+  readonly url: string
+  readonly originalError?: Error
+}
+
+class HttxResponseError extends HttxRequestError {
+  readonly statusText: string
+  readonly responseBody?: unknown
+}
+```
+
+### Utility Exports
+```typescript
+import { debugLog, sleep } from '@stacksjs/httx'
+
+debugLog(category: string, message: string | (() => string), verbose?: boolean | string[]): void
+sleep(ms: number): Promise<void>
+```
+
+### Config Exports
+```typescript
+import { config, defaultConfig, getConfig } from '@stacksjs/httx'
+
+const config: HttxConfig               // Synchronous access with default fallback
+const defaultConfig: HttxConfig         // Default configuration object
+function getConfig(): Promise<HttxConfig>  // Async config loader
+```
+
+## useFetch — Reactive Fetch Composable (@stacksjs/composables)
+
+A chainable, reactive fetch composable using the builder pattern. Uses native `fetch()` under the hood (not HttxClient). Returns reactive `Ref` values from `@stacksjs/stx`.
+
+```typescript
+import { useFetch } from '@stacksjs/composables'
+
+// Builder pattern: method -> format -> result
+const { data, error, isFetching } = await useFetch('/api/posts').get().json()
+```
+
+### FetchBuilder Interface
+```typescript
+interface FetchBuilder {
+  get: () => FetchBuilder
+  post: (body?: string) => FetchBuilder
+  patch: (body?: string) => FetchBuilder
+  put: (body?: string) => FetchBuilder
+  delete: () => FetchBuilder
+  json: () => UseFetchResult
+}
+```
+
+### UseFetchResult Interface
+```typescript
+interface UseFetchResult {
+  data: Ref<any>          // Reactive ref — populated with parsed JSON on success
+  error: Ref<any>         // Reactive ref — populated with error JSON or Error object
+  isFetching: Ref<boolean>  // Starts as true, becomes false when request completes
+  then: (resolve: (value: { data: Ref<any>, error: Ref<any> }) => void) => Promise<void>
+}
+```
+
+### Usage Examples
+
+```typescript
+import { useFetch } from '@stacksjs/composables'
+
+// GET request
+const { data, error } = await useFetch('/api/users').get().json()
+
+// POST with JSON body
+const { data, error } = await useFetch('/api/users')
+  .post(JSON.stringify({ name: 'Alice', email: 'alice@example.com' }))
+  .json()
+
+// PATCH with body
+const { data, error } = await useFetch('/api/users/1')
+  .patch(JSON.stringify({ name: 'Updated' }))
+  .json()
+
+// DELETE
+const { data, error } = await useFetch('/api/users/1').delete().json()
+
+// Synchronous access (reactive — updates when request completes)
+const result = useFetch('/api/items').get().json()
+result.isFetching.value  // true (synchronously, before microtask resolves)
+// ... later ...
+result.data.value        // parsed JSON response
+result.isFetching.value  // false
+```
+
+### How json() Works Internally
+1. Builds a `RequestInit` with the configured method and `Accept: application/json` header
+2. For POST/PATCH/PUT with a body, also sets `Content-Type: application/json`
+3. Calls native `fetch(url, init)`
+4. On success (`response.ok`), parses JSON into `data.value`
+5. On HTTP error, parses JSON into `error.value`
+6. On network error, sets `error.value` to the caught Error
+7. Always sets `isFetching.value = false` in `finally`
+
+## createFetch — Pre-configured Fetch Factory (@stacksjs/composables)
+
+Creates a reusable `useFetch` instance with a pre-configured base URL.
+
+```typescript
+import { createFetch } from '@stacksjs/composables'
+
+interface CreateFetchOptions {
+  baseUrl?: string          // Base URL prepended to all requests
+  options?: RequestInit     // Default options (currently unused in implementation)
+}
+
+const useApi = createFetch({ baseUrl: 'https://api.example.com' })
+
+// URL becomes: https://api.example.com/users
+const { data, error } = await useApi('/users').get().json()
+```
+
+### URL Resolution
+`createFetch` joins the base URL and path by stripping trailing/leading slashes:
+- `baseUrl: 'https://api.example.com/'` + `'/users'` → `'https://api.example.com/users'`
+- `baseUrl: 'https://api.example.com'` + `'users'` → `'https://api.example.com/users'`
+
+## CLI Command — buddy http
+
+```bash
+buddy http [domain]          # Send a GET request (defaults to config.app.url)
+buddy http example.com       # GET https://example.com
+buddy http -v example.com    # Verbose output
+```
+
+The CLI command uses `HttxClient` from `@stacksjs/httx`:
+- Prepends `https://` if the URL does not start with `http`
+- Logs status code, status text, and duration
+- Prints response body (string or pretty-printed JSON)
+
+## Gotchas
+- **`@stacksjs/http` is status codes only** — it exports a single `Response` enum with HTTP status code constants. It does NOT contain an HTTP client, request helpers, or fetch utilities
+- **The actual HTTP client is `@stacksjs/httx`** — a separate package (not part of `@stacksjs/http`). It is used by `buddy http` and available for general use
+- **`useFetch` uses native `fetch()`, not HttxClient** — despite `@stacksjs/httx` being available, the `useFetch` composable calls the global `fetch()` directly
+- **`useFetch` only supports `.json()` format** — there is no `.text()`, `.blob()`, or `.arrayBuffer()` method. The only terminal method is `.json()`
+- **Method chaining overrides previous method** — calling `.post('body').get()` will send a GET request (last method wins, body is cleared for GET/DELETE)
+- **`createFetch` ignores the `options` parameter** — the `CreateFetchOptions.options` field is declared in the interface but not used in the implementation
+- **`useFetch` body is only sent for POST/PATCH/PUT** — GET and DELETE requests strip the body even if one was set
+- **The `Response` enum name conflicts with the global `Response`** — importing `Response` from `@stacksjs/http` shadows the native Fetch API `Response` type. Use a named import alias if both are needed: `import { Response as HttpStatus } from '@stacksjs/http'`
+- **HttxClient uses Result pattern** — `request()` returns `Result<HttxResponse, Error>` from `ts-error-handling`, not a plain Promise. Use `.match()`, `.isOk`, or `.value`/`.error` to unwrap
+- **`useFetch` returns reactive Refs** — `data`, `error`, and `isFetching` are `Ref<T>` from `@stacksjs/stx`. Access values via `.value` property
+- **No request interceptors or middleware** — neither `useFetch` nor `HttxClient` support request/response interceptors
+- **For API route handling, use `@stacksjs/router`** — `@stacksjs/http` and `@stacksjs/httx` are for outbound requests only, not for defining API endpoints

package/ai/skills/stacks-i18n/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: stacks-i18n
+description: Use when working with internationalization in a Stacks application — translations, locale management, pluralization, date/number/currency formatting, or loading translation files. Covers @stacksjs/i18n with translator, formatter, loader, and pluralization modules.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks i18n
+
+## Key Paths
+- Core package: `storage/framework/core/i18n/src/`
+- Locale files: `locales/` (en.yml, de.yml)
+- Package: `@stacksjs/i18n`
+
+## Source Files
+```
+i18n/src/
+├── index.ts              # Main entry point and exports
+├── types.ts              # All type definitions
+├── translator.ts         # I18n class, global API (t, tc, te, tm)
+├── formatter.ts          # Locale-aware formatting (dates, numbers, currency, lists)
+├── loader.ts             # File-based translation loader (JSON, YAML, JS/TS)
+└── pluralization.ts      # CLDR plural rules for 25+ languages
+```
+
+## Core Types
+
+```typescript
+type TranslationMessages = { [key: string]: string | TranslationMessages }
+type Translations = { [locale: string]: TranslationMessages }
+type InterpolationValues = Record<string, string | number | boolean | null | undefined>
+
+interface I18nConfig {
+  locale: string                    // default: 'en'
+  fallbackLocale: string            // default: 'en'
+  availableLocales?: string[]
+  messages?: Translations
+  missingHandler?: (locale: string, key: string) => string | undefined
+  warnMissing?: boolean             // default: true
+  escapeValues?: boolean            // default: false
+  keySeparator?: string             // default: '.'
+  pluralSeparator?: string          // default: '|'
+  dateTimeFormats?: DateTimeFormats
+  numberFormats?: NumberFormats
+}
+```
+
+## Translation API
+
+### Instance-Based
+```typescript
+import { createI18n, useI18n } from '@stacksjs/i18n'
+
+const i18n = createI18n({
+  locale: 'en',
+  fallbackLocale: 'en',
+  messages: {
+    en: { greeting: 'Hello, {name}!' },
+    de: { greeting: 'Hallo, {name}!' },
+  },
+})
+
+i18n.t('greeting', { name: 'World' })  // 'Hello, World!'
+i18n.setLocale('de')
+i18n.t('greeting', { name: 'Welt' })   // 'Hallo, Welt!'
+```
+
+### Global API
+```typescript
+import { t, tc, te, tm, trans, setLocale, getLocale, addTranslations, configure } from '@stacksjs/i18n'
+
+t('greeting', { name: 'World' })         // Translate with interpolation
+tc('items', 5, { count: 5 })             // Plural translation
+te('greeting')                            // Key exists? → boolean
+tm('section')                             // Raw message object
+trans('greeting')                         // Alias for t()
+
+setLocale('fr')
+getLocale()                               // 'fr'
+addTranslations('fr', { greeting: 'Bonjour, {name}!' })
+```
+
+### Lookup Flow
+```
+1. Look up key in target locale
+2. If not found → try fallback locale
+3. If still not found → call missingHandler → warn → return key string
+```
+
+## Pluralization
+
+CLDR plural rules, pipe-separated forms:
+
+```typescript
+addTranslations('en', { items: 'no items | one item | {count} items' })
+tc('items', 0)    // 'no items'
+tc('items', 1)    // 'one item'
+tc('items', 5)    // '5 items'
+```
+
+### Supported Languages
+
+| Rule | Languages |
+|------|-----------|
+| One/Other | en, de, nl, es, it, pt, sv, da, no, fi, el, he, hu, tr |
+| French (0-1=one) | fr |
+| No plural | zh, ja, ko, vi, th, id, ms |
+| One/Few/Many/Other | ru, uk, pl |
+| One/Few/Other | cs, sk |
+| Full (zero/one/two/few/many/other) | ar, cy |
+
+```typescript
+import { getPluralCategory, addPluralRule, hasPluralRule } from '@stacksjs/i18n'
+getPluralCategory(1, 'en')     // 'one'
+getPluralCategory(5, 'en')     // 'other'
+```
+
+## Formatting
+
+### Date/Time
+```typescript
+import { formatDate, formatTime, formatDateTime, formatRelativeTime } from '@stacksjs/i18n'
+
+formatDate(new Date(), 'long')                    // 'March 23, 2026'
+formatDate(new Date(), 'short')                   // '3/23/26'
+formatTime(new Date(), 'short')                   // '2:30 PM'
+formatDateTime(new Date(), 'medium', 'short')     // 'Mar 23, 2026, 2:30 PM'
+formatRelativeTime(pastDate)                      // '3 hours ago'
+```
+
+### Numbers & Currency
+```typescript
+import { formatNumber, formatCurrency, formatPercent, formatUnit, formatBytes } from '@stacksjs/i18n'
+
+formatNumber(1234567)                              // '1,234,567'
+formatNumber(1234567, { compact: true })           // '1.2M'
+formatCurrency(29.99)                              // '$29.99'
+formatCurrency(29.99, 'EUR', {}, 'de')             // '29,99 €'
+formatPercent(0.85)                                // '85%'
+formatUnit(60, 'kilometer-per-hour', 'short')      // '60 km/h'
+formatBytes(1536)                                  // '1.50 KB'
+```
+
+### Lists & Display Names
+```typescript
+import { formatList, getLanguageName, getRegionName, isRTL } from '@stacksjs/i18n'
+
+formatList(['Alice', 'Bob', 'Charlie'])            // 'Alice, Bob, and Charlie'
+formatList(['A', 'B'], 'disjunction')              // 'A or B'
+getLanguageName('de')                               // 'German'
+getRegionName('JP')                                 // 'Japan'
+isRTL('ar')                                         // true
+```
+
+### String Collation
+```typescript
+import { sortStrings, compareStrings } from '@stacksjs/i18n'
+sortStrings(['ö', 'a', 'ü'], {}, 'de')            // Locale-aware sort
+```
+
+## Translation File Loader
+
+```typescript
+import { loadFromDirectory, loadFile, createLoader } from '@stacksjs/i18n'
+
+const translations = await loadFromDirectory({
+  directory: './locales',
+  extensions: ['.json', '.yaml', '.yml', '.ts', '.js'],
+  recursive: false,
+})
+
+const loader = createLoader('./locales')
+const all = await loader.load()
+const fr = await loader.loadLocale('fr', 'messages.yml')
+```
+
+## Locale Files
+
+```yaml
+# locales/en.yml
+default:
+  button:
+    about: About
+    back: Back
+  intro:
+    desc: Rapid Application Development
+    hi: 'Hi, {name}!'
+```
+
+## Gotchas
+- **Dual API** — instance-based (`createI18n()`) and global (`t()`) both exist. Global uses a singleton
+- **YAML parsed with Bun.YAML** — not a third-party parser
+- **Missing keys return the key itself** — not an error, not empty string
+- **Pluralization uses `|` separator** — not ICU MessageFormat
+- **CLDR rules are built-in** — no external data needed, 25+ languages hardcoded
+- **HTML escaping is opt-in** — `escapeValues: true` in config
+- **Formatting uses Intl APIs** — delegates to `Intl.DateTimeFormat`, `Intl.NumberFormat`, etc.