@stacksjs/defaults 0.70.207 → 0.70.208

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

@@ -0,0 +1,120 @@
+---
+name: stacks-mail
+description: Use when creating mail classes in app/Mail/ — defining email content and templates, using the template() function with STX or HTML templates, variable interpolation, email layouts, or the app-level mail sending pattern. For the email framework itself (drivers, Mail singleton, EmailSDK, inbox management), see stacks-email.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Mail Classes
+
+Application-level email definitions in `app/Mail/`.
+
+## Key Paths
+- Application mail: `app/Mail/`
+- Email templates: `resources/emails/` (or `storage/framework/defaults/resources/emails/`)
+- Email layouts: `storage/framework/defaults/resources/emails/layouts/`
+
+## Creating a Mail Class
+
+```typescript
+// app/Mail/WelcomeEmail.ts
+import { mail, template } from '@stacksjs/email'
+import { config } from '@stacksjs/config'
+
+interface WelcomeEmailOptions {
+  to: string
+  name: string
+}
+
+export async function sendWelcomeEmail({ to, name }: WelcomeEmailOptions) {
+  const { html, text } = await template('welcome', {
+    variables: { name, appName: config.app.name },
+    layout: 'default'
+  })
+
+  await mail.send({
+    from: { name: config.app.name, address: config.email.from.address },
+    to,
+    subject: `Welcome to ${config.app.name}!`,
+    html,
+    text
+  })
+}
+```
+
+## Template Rendering
+
+```typescript
+import { template, renderHtml, templateExists, listTemplates } from '@stacksjs/email'
+
+// From template file (welcome.stx or welcome.html)
+const { html, text } = await template('welcome', {
+  variables: { name: 'John', url: 'https://app.com/verify' },
+  layout: 'default',     // wrap in layout (or false to skip)
+  subject: 'Welcome'
+})
+
+// From raw HTML
+const { html, text } = renderHtml('<h1>Hello {{ name }}</h1>', { name: 'John' })
+
+// Check templates
+templateExists('welcome')   // boolean
+listTemplates()              // string[]
+```
+
+Variable syntax: `{{ variableName }}` (double braces with spaces).
+
+## Example: Subscription Confirmation
+
+```typescript
+// app/Mail/SubscriptionConfirmation.ts
+import { mail, template } from '@stacksjs/email'
+import { url } from '@stacksjs/router'
+import { config } from '@stacksjs/config'
+
+export async function sendSubscriptionConfirmation({ to, subscriberUuid }: Options) {
+  const { html, text } = await template('subscription-confirmation', {
+    variables: {
+      unsubscribeUrl: url('email.unsubscribe', { token: subscriberUuid }),
+      appName: config.app.name
+    }
+  })
+
+  await mail.send({
+    from: { name: config.app.name, address: config.email.from.address },
+    to,
+    subject: 'Confirm your subscription',
+    html,
+    text
+  })
+}
+```
+
+## Using Mail in Actions/Events
+
+```typescript
+// In an action
+import { sendWelcomeEmail } from '../../app/Mail/WelcomeEmail'
+
+export default {
+  name: 'SendWelcomeEmail',
+  async handle(event: { email: string, name: string }) {
+    await sendWelcomeEmail({ to: event.email, name: event.name })
+    return { success: true }
+  }
+}
+```
+
+## Template Locations
+- STX templates: `.stx` files processed by STX engine
+- HTML templates: `.html` files with `{{ }}` variable interpolation
+- Layouts: base HTML wrapping templates (header, footer, styles)
+
+## Gotchas
+- Mail classes are plain functions, not classes — no inheritance needed
+- Templates support both `.stx` (reactive) and `.html` (static) formats
+- Variable interpolation uses `{{ }}` — not `${}`
+- `text` output is auto-generated from HTML via `htmlToText()`
+- Layouts wrap the template content with shared structure (header/footer)
+- For the email driver system (SES, SendGrid, etc.), see the `stacks-email` skill

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

@@ -0,0 +1,249 @@
+---
+name: stacks-middleware
+description: Use when working with middleware in a Stacks application — defining middleware, applying to routes, middleware aliases, parameterized middleware, groups, or the middleware execution pipeline. Covers the Middleware class, app/Middleware.ts alias registry, and all 22 default middleware files.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Middleware
+
+Built into `@stacksjs/router`. Middleware intercepts requests before they reach route handlers.
+
+## Key Paths
+- Middleware class: `storage/framework/core/router/src/middleware.ts`
+- Execution engine: `storage/framework/core/router/src/stacks-router.ts`
+- Alias registry: `app/Middleware.ts`
+- Default middleware: `storage/framework/defaults/app/Middleware/` (22 files)
+- Auth middleware (standalone): `storage/framework/core/auth/src/middleware.ts`
+- Tests: `storage/framework/core/router/tests/middleware.test.ts`
+
+## Middleware Class
+
+```typescript
+import { Middleware } from '@stacksjs/router'
+
+export interface MiddlewareConfig {
+  name: string
+  priority?: number  // Lower = runs first, default: 10
+  handle: (request: EnhancedRequest) => void | Promise<void>
+}
+
+export class Middleware {
+  readonly name: string
+  readonly priority: number
+  readonly handle: (request: EnhancedRequest) => void | Promise<void>
+
+  constructor(config: MiddlewareConfig)
+}
+```
+
+## Creating Custom Middleware
+
+Create a file in `app/Middleware/`:
+
+```typescript
+// app/Middleware/RateLimit.ts
+import { Middleware } from '@stacksjs/router'
+
+export default new Middleware({
+  name: 'RateLimit',
+  priority: 2,
+  async handle(request) {
+    // Throw to short-circuit the request
+    // throw new HttpError(429, 'Too many requests')
+
+    // Return void to continue to next middleware
+  },
+})
+```
+
+### Short-Circuiting
+
+Middleware can stop request processing by:
+1. **Throwing an Error with `statusCode`** — converted to HTTP error response
+2. **Throwing a Response** — returned directly to client
+3. **Returning void** — continues to next middleware
+
+```typescript
+// Error with status code
+const error = new Error('Unauthorized') as Error & { statusCode: number }
+error.statusCode = 401
+throw error
+
+// Direct Response (full control)
+throw new Response(JSON.stringify({ error: 'Rate limited' }), {
+  status: 429,
+  headers: { 'Retry-After': '60' },
+})
+```
+
+## Alias Registry (app/Middleware.ts)
+
+Maps short names to middleware class filenames:
+
+```typescript
+export default {
+  'maintenance': 'Maintenance',
+  'auth': 'Auth',
+  'guest': 'Guest',
+  'api': 'Api',
+  'team': 'Team',
+  'logger': 'Logger',
+  'abilities': 'Abilities',
+  'can': 'Can',
+  'throttle': 'Throttle',
+  'env': 'Env',
+  'env:local': 'EnvLocal',
+  'env:development': 'EnvDevelopment',
+  'env:dev': 'EnvDevelopment',
+  'env:staging': 'EnvStaging',
+  'env:production': 'EnvProduction',
+  'env:prod': 'EnvProduction',
+  'role': 'Role',
+  'permission': 'Permission',
+  'verified': 'EnsureEmailIsVerified',
+} satisfies Middleware
+```
+
+## Applying Middleware
+
+### Per-Route (Chainable)
+```typescript
+route.get('/dashboard', 'DashboardAction')
+  .middleware('auth')
+  .middleware('verified')
+  .name('dashboard.show')
+```
+
+### Route Groups
+```typescript
+route.group({ prefix: '/api/v1', middleware: ['auth', 'throttle'] }, () => {
+  route.get('/users', listUsers)
+  route.post('/users', createUser)
+})
+```
+
+Group middleware is prepended to all routes inside the callback. Groups can be nested — middleware accumulates.
+
+### Parameterized Middleware
+
+Pass parameters using colon syntax:
+
+```typescript
+route.get('/admin', handler).middleware('throttle:60,1')     // 60 requests per 1 minute
+route.get('/posts', handler).middleware('abilities:read,write')
+route.get('/settings', handler).middleware('role:admin,editor')
+route.get('/posts/{id}', handler).middleware('can:update,post')
+```
+
+Parameters are stored on `request._middlewareParams[middlewareName]` and parsed by the middleware's `handle` function.
+
+## Default Middleware Reference
+
+| Alias | Class | Priority | Description |
+|-------|-------|----------|-------------|
+| `maintenance` | Maintenance | 0 | Checks maintenance mode, supports secret bypass URL and IP allowlist |
+| `auth` | Auth | 1 | Validates bearer token, sets authenticated user on request |
+| `api` | Api | 1 | Validates request accepts JSON |
+| `guest` | Guest | 1 | Ensures user is NOT authenticated (for login/register pages) |
+| `env` | Env | 1 | Checks current environment |
+| `logger` | Logger | 2 | Logs request method and URL |
+| `abilities` | Abilities | 2 | Checks token abilities/scopes (parameterized: `abilities:read,write`) |
+| `can` | Can | 3 | Authorization gate (parameterized: `can:update,post`) |
+| `role` | Role | 3 | Checks user roles (parameterized: `role:admin`) |
+| `permission` | Permission | 3 | Checks user permissions (parameterized: `permission:edit-posts`) |
+| `team` | Team | 3 | Ensures user belongs to a team (parameterized: `team:teamId`) |
+| `verified` | EnsureEmailIsVerified | 4 | Verifies email is confirmed |
+| `throttle` | Throttle | — | Rate limiting (parameterized: `throttle:60,1` or `throttle:100,5m`) |
+| `env:local` | EnvLocal | — | Only allows local environment |
+| `env:development` / `env:dev` | EnvDevelopment | — | Only allows development |
+| `env:staging` | EnvStaging | — | Only allows staging |
+| `env:production` / `env:prod` | EnvProduction | — | Only allows production |
+
+### Environment Negation Variants
+
+Files exist for `EnvNotLocal`, `EnvNotDevelopment`, `EnvNotStaging`, `EnvNotProduction` — but they have **no aliases registered** in `app/Middleware.ts`.
+
+## Middleware Loading Flow
+
+```
+1. Parse middleware name: 'throttle:60,1' → { name: 'throttle', params: '60,1' }
+2. Check middleware cache (loaded once, cached for performance)
+3. Resolve alias: 'throttle' → 'Throttle' (via app/Middleware.ts)
+4. Try loading from app/Middleware/Throttle.ts (user overrides)
+5. Fall back to storage/framework/defaults/app/Middleware/Throttle.ts
+6. Store params on request: request._middlewareParams.throttle = '60,1'
+7. Execute: await middleware.handle(enhancedRequest)
+```
+
+User middleware in `app/Middleware/` always takes precedence over framework defaults.
+
+## Representative Implementations
+
+### Auth Middleware
+```typescript
+export default new Middleware({
+  name: 'Auth',
+  priority: 1,
+  async handle(request) {
+    const bearerToken = request.bearerToken()
+    if (!bearerToken)
+      throw new HttpError(401, 'Unauthorized. No token provided.')
+    const isValid = await Auth.validateToken(bearerToken)
+    if (!isValid)
+      throw new HttpError(401, 'Unauthorized. Invalid token.')
+  },
+})
+```
+
+### Maintenance Middleware
+```typescript
+export default new Middleware({
+  name: 'Maintenance',
+  priority: 0,
+  async handle(request) {
+    if (!(await isDownForMaintenance())) return
+    const payload = await maintenancePayload()
+    // Check secret bypass URL → set cookie and redirect
+    // Check bypass cookie or allowed IP → continue
+    // Otherwise → throw maintenance response
+  },
+})
+```
+
+### Throttle Middleware (Parameterized)
+```typescript
+// '60,1' = 60 requests per 1 minute
+// '100,5m' = 100 requests per 5 minutes
+// '1000,1h' = 1000 requests per hour
+async handle(request) {
+  const params = request._middlewareParams?.throttle || '60,1'
+  const config = parseThrottleString(params)
+  const limiter = createRateLimitMiddleware(config)
+  // Returns 429 if rate limit exceeded
+}
+```
+
+## Standalone Auth Middleware (@stacksjs/auth)
+
+A separate, more complete auth middleware exists:
+
+```typescript
+import { authMiddleware, authMiddlewareHandler } from '@stacksjs/auth'
+
+// Checks both request.bearerToken() and raw Authorization header
+// Calls Auth.getUserFromToken() to validate
+// Sets Auth.setUser(user) and request._authenticatedUser
+// Loads current access token onto request._currentAccessToken
+```
+
+## Gotchas
+- **Priority exists but isn't used for ordering** — the router executes middleware in registration order, not priority order
+- **`terminate()` doesn't exist** — some docs reference it, but it's not in the actual `MiddlewareConfig` interface
+- **Two auth middleware implementations** — defaults version (basic token check) and `@stacksjs/auth` version (full user loading)
+- **EnvNot* files have no aliases** — `EnvNotLocal.ts`, etc. exist but aren't registered in `app/Middleware.ts`
+- **Middleware is cached after first load** — changes require server restart
+- **User overrides take precedence** — `app/Middleware/Auth.ts` replaces the framework default completely
+- **Group middleware accumulates** — nested groups combine all parent middleware
+- **Request body parsed before middleware** — Laravel-style methods (`.input()`, `.query`, `.file()`) are available in middleware

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

@@ -0,0 +1,105 @@
+---
+name: stacks-migrations
+description: Use when working with database migrations in a Stacks application — creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 96+ built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Database Migrations
+
+Schema change management via migration files.
+
+## Key Paths
+- Migration files: `database/migrations/` (96+ files)
+- Database config: `config/database.ts`
+
+## CLI Commands
+
+```bash
+buddy migrate                       # run pending migrations
+buddy migrate --diff                # show SQL without running
+buddy migrate --auth                # include auth tables
+buddy migrate:fresh                 # drop ALL tables and re-migrate
+buddy migrate:fresh --seed          # drop, migrate, then seed
+buddy migrate:dns                   # DNS-specific migration
+buddy make:migration <name>         # create new migration file
+buddy seed                          # seed database
+buddy generate:migrations           # generate migrations from model diffs
+```
+
+## Creating a Migration
+
+```bash
+buddy make:migration create_orders_table
+```
+
+Creates a timestamped migration file in `database/migrations/`.
+
+## Migration Generation from Models
+
+When you define or modify a model, generate migrations automatically:
+
+```bash
+buddy generate:migrations
+```
+
+This diffs model definitions against the current schema and generates the necessary SQL.
+
+## Built-in Migrations (96+)
+
+The framework includes migrations for all built-in models:
+
+### Core Tables
+- `users` — id, name, email (unique), password, timestamps
+- `personal_access_tokens` — auth tokens
+- `passkeys` — WebAuthn credentials
+- `password_resets` — password reset tokens
+
+### Content
+- `posts` — title, content, excerpt, views, status, published_at, author_id
+- `pages`, `categories`, `tags`, `comments`
+- `authors` — linked to users
+
+### Commerce (20+ tables)
+- `products`, `product_variants`, `product_units`
+- `orders`, `order_items`
+- `carts`, `cart_items`
+- `coupons`, `gift_cards`, `reviews`
+- `customers`, `manufacturers`
+
+### Payments
+- `payments`, `payment_methods`, `payment_products`, `payment_transactions`
+- `subscriptions`, `transactions`
+
+### Shipping
+- `shipping_methods`, `shipping_rates`, `shipping_zones`
+- `delivery_routes`, `drivers`
+
+### System
+- `jobs`, `failed_jobs` — queue tables
+- `errors`, `logs`, `notifications`
+- `activities`, `requests`, `websockets`
+
+### Indexes
+- `users.email` (unique), `users(email, name)` (composite)
+- `subscribers.email` (unique)
+- `coupons.code` (unique), `gift_cards.code` (unique)
+- `payments.transaction_id` (unique)
+- `subscriptions.provider_id` (unique)
+
+## Workflow
+
+1. Define/modify model in `storage/framework/defaults/app/Models/` or `app/Models/`
+2. Run `buddy generate:migrations` to generate SQL diffs
+3. Review generated migration files
+4. Run `buddy migrate` to apply
+
+## Gotchas
+- `migrate:fresh` drops ALL tables — only use in development
+- Migrations run in filename order (timestamps ensure correct sequence)
+- Never edit a migration that's been run in production — create a new one
+- `--seed` flag after `migrate:fresh` seeds the database with factory data
+- 96+ migration files exist by default for all framework models
+- SQLite >= 3.47.2 is required (system requirement)
+- For the database API (queries, connections), see the `stacks-database` skill