@stacksjs/defaults 0.70.207 → 0.70.208

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

@@ -0,0 +1,58 @@
+---
+name: stacks-registry
+description: Use when working with the Stacks extension registry — framework extension metadata, package discovery, or the registry system. Covers @stacksjs/registry.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Registry
+
+## Key Paths
+- Core package: `storage/framework/core/registry/src/`
+- Config: `config/stacks.ts`
+- Package: `@stacksjs/registry`
+
+## Source Files
+```
+registry/src/
+└── index.ts              # Registry definition and exports
+```
+
+## API
+
+```typescript
+import { registry } from '@stacksjs/registry'
+import type { Registry } from '@stacksjs/registry'
+
+type Registry = StackExtensionRegistry
+
+const registry: Registry = [
+  {
+    name: 'stacks',
+    url: 'stacksjs.com',
+    github: 'stacksjs/stacks',
+  },
+]
+
+export default registry
+```
+
+The registry is a simple array of `StackExtensionRegistry` entries containing framework extension metadata — name, URL, and GitHub repository.
+
+## Usage
+
+```typescript
+import { registry } from '@stacksjs/registry'
+
+// Access extension metadata
+registry.forEach(ext => {
+  console.log(ext.name, ext.url, ext.github)
+})
+```
+
+## Gotchas
+- **Minimal package** — currently just a static array with the core Stacks framework entry
+- **Type comes from `@stacksjs/types`** — `StackExtensionRegistry` is defined in the types package
+- **Used for framework metadata** — not a package manager or dependency registry
+- **Config in `config/stacks.ts`** — the `StackExtensionRegistry` config is defined there

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

@@ -0,0 +1,80 @@
+---
+name: stacks-repl
+description: Use when working with the Stacks REPL — interactive TypeScript sessions, tinker sessions, debugging, or exploring the framework interactively. Covers @stacksjs/repl and @stacksjs/tinker.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks REPL / Tinker
+
+## Key Paths
+- REPL package: `storage/framework/core/repl/src/`
+- Tinker package: `storage/framework/core/tinker/src/`
+- Packages: `@stacksjs/repl`, `@stacksjs/tinker`
+
+## API
+
+```typescript
+import { startRepl } from '@stacksjs/repl'
+
+interface ReplConfig extends TinkerConfig {
+  loadFile?: string  // Path to file to preload before starting
+}
+
+async function startRepl(config: ReplConfig): Promise<{ exitCode: number }>
+```
+
+### How It Works
+1. If `config.loadFile` is specified, reads the file content
+2. Merges file content into `config.eval` for evaluation
+3. Starts an interactive Bun REPL session with all framework modules available
+4. Returns the process exit code when the session ends
+
+## Re-exports from @stacksjs/tinker
+
+```typescript
+import {
+  startTinker,      // Start a tinker session
+  tinkerEval,       // Evaluate an expression
+  tinkerPrint,      // Print a result
+  getHistoryPath,   // Get REPL history file path
+  readHistory,      // Read command history
+  appendHistory,    // Append to command history
+  clearHistory,     // Clear command history
+} from '@stacksjs/repl'
+
+import type { TinkerConfig } from '@stacksjs/repl'
+```
+
+## CLI Commands
+
+```bash
+buddy tinker                    # Start interactive REPL session
+buddy tinker --load file.ts     # Preload a file before starting
+```
+
+## Usage
+
+Inside the REPL, all framework modules are available:
+
+```typescript
+// Query the database
+const users = await db.selectFrom('users').get()
+
+// Use models
+const post = await Post.find(1)
+
+// Access config
+console.log(config.app.name)
+
+// Use faker for quick testing
+const email = faker.internet.email()
+```
+
+## Gotchas
+- **Tinker is the user-facing command, REPL is the engine** — `buddy tinker` calls `startRepl()` under the hood
+- **All framework imports available** — models, database, config, faker, etc. are preloaded
+- **History is persisted** — REPL history is saved to disk via `getHistoryPath()`
+- **File preloading** — use `loadFile` to run setup code before entering interactive mode
+- **Bun runtime** — the REPL runs in Bun's JavaScript runtime, not Node.js

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

@@ -0,0 +1,122 @@
+---
+name: stacks-retro
+description: Use for git-based session retrospectives — session detection, commit categorization, focus scores, streak counting, and behavioral observations. Invoke with /stacks-retro.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# /stacks-retro — Session Retrospective
+
+Generate a retrospective analysis of recent development work based on git history.
+
+## Step 1: Session Detection
+
+Detect sessions using a **45-minute gap threshold** between commits.
+
+```bash
+git log --all --format="%H|%ai|%an|%s" --since="7 days ago"
+```
+
+Adjust `--since` if user specifies a range ("today", "this week", etc.).
+
+## Step 2: Commit Categorization
+
+| Category | Indicators | Icon |
+|----------|-----------|------|
+| Feature | `feat:`, new files, new exports | 🟢 |
+| Fix | `fix:`, corrective changes | 🔴 |
+| Refactor | `refactor:`, structural changes | 🔵 |
+| Test | `test:`, test file changes | 🟡 |
+| Docs | `docs:`, README changes | 📝 |
+| Chore | `chore:`, deps, config, CI | ⚙️ |
+| Style | `style:`, formatting, lint | 🎨 |
+
+Parse `gitlint`-style conventional commit prefixes. Stacks uses these scopes: `core`, `auth`, `database`, `router`, `buddy`, `ui`, `build`, etc.
+
+## Step 3: Session Analysis
+
+### Focus Score (0-100)
+```
+focus_score = (commits_in_primary_area / total_commits) × 100
+```
+
+Primary area = most-touched `storage/framework/core/*/` package or top-level directory.
+
+- **80-100**: Deep focus
+- **50-79**: Moderate focus
+- **0-49**: Scattered
+
+```
+### Session [N]: [start] → [end] ([duration])
+**Focus**: [score]/100 — [assessment]
+**Primary area**: [package/directory]
+**Commits**: [count]
+
+| Time | Category | Message | Files |
+|------|----------|---------|-------|
+
+**Observation**: [one behavioral insight]
+```
+
+## Step 4: Streaks
+
+```bash
+git log --all --format="%ad" --date=short | sort -u
+```
+
+```
+## Streaks
+🔥 Current streak: [N] days
+📈 Longest streak: [N] days ([range])
+📅 Active days: [N] / [total]
+```
+
+## Step 5: Per-Contributor Metrics (if multiple)
+
+```
+| Contributor | Commits | Primary Focus | Top Category | Avg Focus |
+|-------------|---------|---------------|--------------|-----------|
+```
+
+## Step 6: Behavioral Observations
+
+2-4 observations backed by data:
+
+- "You wrote 12 fix commits after the auth refactor — consider adding tests before next refactor session."
+- "Focus score drops in afternoon sessions. Morning sessions average 85."
+- "No test commits this week despite 8 feature commits. Test debt accumulating."
+- "3/4 sessions started with chore commits. Consider batching into a maintenance session."
+
+## Output
+
+```
+# Retrospective: [date range]
+
+## Overview
+- **Period**: [range]
+- **Sessions**: [count]
+- **Total commits**: [count]
+
+## Category Breakdown
+[icons and counts]
+
+## Sessions
+[session details]
+
+## Streaks
+[streak data]
+
+## Observations
+[behavioral insights]
+
+## Suggested Focus for Next Session
+[one specific suggestion]
+```
+
+## Rules
+
+- **Data-driven only.** Every observation backed by commits/metrics.
+- **No judgment on work hours.** Don't comment on when someone works.
+- **Default to 7 days** if no range specified.
+- **Handle messy history gracefully.** Squash/merge/rebase can distort sessions.

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

@@ -0,0 +1,135 @@
+---
+name: stacks-review
+description: Use when reviewing code changes in the Stacks project — two-pass code review with critical issue detection, test coverage audit, and auto-fix workflow. Invoke with /stacks-review.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# /stacks-review — Code Review
+
+You are performing a structured two-pass code review for the Stacks framework. Be direct, specific, and opinionated. Every finding must reference a specific file and line number.
+
+## Determine Scope
+
+1. If the user provides a PR number or branch, review the diff against the base branch
+2. If no scope is given, review staged changes (`git diff --cached`). If nothing staged, review unstaged (`git diff`)
+3. If no changes at all, ask what to review
+
+Read changed files in full to understand context around the changes.
+
+## Pass 1: Critical Issues
+
+Scan for issues that **must be fixed before merge**. Only flag with confidence 8/10+:
+
+### Security
+- SQL injection, XSS, command injection, path traversal
+- Hardcoded secrets, API keys, tokens (check `config/services.ts`)
+- Missing auth/authorization checks on API routes
+- Unsafe deserialization or eval usage
+- Improper input validation at system boundaries
+
+### Correctness
+- Race conditions, missing `await` on async calls
+- Off-by-one errors, null/undefined access without guards
+- Resource leaks (unclosed database connections, missing `db.close()`)
+- Incorrect error handling (swallowed errors, wrong error types)
+- Logic errors in ORM model definitions or migration files
+
+### Stacks-Specific
+- Incorrect model attribute definitions (wrong validator types, missing `factory` for seeder)
+- Broken route definitions (missing middleware, wrong action paths)
+- Misconfigured `config/*.ts` files
+- Breaking changes to `@stacksjs/*` package exports
+- Migration files that won't work on SQLite (check preprocessing quirks)
+
+For each critical finding:
+
+```
+🔴 CRITICAL: [title]
+File: [path]:[line]
+Issue: [specific description]
+Impact: [what can go wrong]
+Fix: [concrete fix, not "consider doing X"]
+```
+
+## Pass 2: Informational
+
+Scan for non-blocking issues:
+
+- Run `bunx --bun pickier` compliance (don't flag what pickier catches)
+- TypeScript best practices (avoid `any`, prefer discriminated unions, use `satisfies`)
+- Naming clarity (misleading variable/function names)
+- Missing error context (errors that lose stack traces)
+- Test gaps (changed logic without corresponding test changes)
+- Dead code introduced by the change
+- Performance concerns (N+1 queries in ORM, unnecessary re-renders)
+- Conventional commit compliance for the PR title (`gitlint` standards)
+
+For each:
+
+```
+🟡 INFO: [title]
+File: [path]:[line]
+Note: [observation]
+Suggestion: [improvement]
+```
+
+## Test Coverage Audit
+
+1. Identify all changed functions/methods
+2. Search for existing tests (`bun test` files)
+3. List untested paths
+
+```
+## Test Coverage
+
+| Changed Function | Test File | Covered? |
+|-----------------|-----------|----------|
+| [function] | [test file or "none"] | ✅ / ❌ |
+
+Missing coverage:
+- [untested path or edge case]
+```
+
+## Auto-Fix Workflow
+
+After presenting findings, ask:
+
+> "Want me to fix the mechanical issues? (formatting, imports, simple type fixes)"
+
+If yes, fix ONLY mechanical issues. After fixing, run `bunx --bun pickier . --fix`.
+
+Do NOT auto-fix: architectural decisions, logic changes, anything with multiple valid approaches.
+
+## Output Format
+
+```
+# Code Review: [brief description]
+
+## Pass 1: Critical Issues
+[findings or "No critical issues found."]
+
+## Pass 2: Informational
+[findings]
+
+## Test Coverage
+[table]
+
+## Summary
+- Critical: [count]
+- Informational: [count]
+- Test gaps: [count]
+```
+
+## Rules
+
+- Never say "consider" or "you might want to" — it's a problem or it isn't
+- Every finding must have a concrete fix
+- Don't flag style issues that `pickier` would catch
+- Don't review generated files, lock files, or `storage/framework/types/` auto-generated types
+- For Stacks monorepo changes, check cross-package impacts — a change in `core/` might affect 15+ downstream packages
+
+## Downstream
+
+> **Review complete.** Run `/stacks-browse` to QA in the browser, or `/stacks-retro` to reflect on this session.

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

@@ -0,0 +1,231 @@
+---
+name: stacks-router
+description: Use when working with routing in a Stacks application — defining routes, HTTP methods, route groups, middleware, named routes, URL generation, request enhancement (Laravel-style input/query/file helpers), response helpers, error responses, route model binding, or rate limiting. Covers @stacksjs/router, routes/, and app/Routes.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Router
+
+Built on `@stacksjs/bun-router` with `ts-rate-limiter`.
+
+## Key Paths
+- Core package: `storage/framework/core/router/src/`
+- Route files: `routes/` (api.ts, v1.ts, buddy.ts, users.ts)
+- Route registry: `app/Routes.ts`
+- Generated route manifest: `storage/framework/stx/routes.ts` (written by the dev server)
+- Generated action paths: `storage/framework/types/actions.d.ts`
+
+## Route Definition
+
+```typescript
+import { route } from '@stacksjs/router'
+
+route.get('/users', handler)
+route.post('/users', handler)
+route.put('/users/{id}', handler)
+route.patch('/users/{id}', handler)
+route.delete('/users/{id}', handler)
+route.options('/users', handler)
+route.health()  // GET /health endpoint
+```
+
+### Chainable Methods
+```typescript
+route.get('/admin', handler)
+  .middleware('auth')
+  .name('admin.dashboard')
+```
+
+### Route Groups
+```typescript
+route.group({ prefix: '/api/v1', middleware: ['auth', 'throttle'] }, () => {
+  route.get('/users', listUsers)
+  route.post('/users', createUser)
+})
+```
+
+### Handler Types
+- Function: `(req: EnhancedRequest) => Response | Promise<Response>`
+- Action string: `'Actions/CreateUser'` — auto-loads action
+- Controller: `'Controllers/UserController@index'` — calls controller method
+
+## Route Registry (app/Routes.ts)
+
+```typescript
+export default {
+  'api': 'api',                              // routes/api.ts → /api/* (auto-prefixed; see #1835)
+  'v1': { path: 'v1', prefix: 'v1' },       // routes/v1.ts → /v1/*
+  'admin': { path: 'admin', prefix: 'admin', middleware: ['auth'] }
+} satisfies Record<string, string | RouteDefinition>
+```
+
+## Enhanced Request (Laravel-style)
+
+### Input Methods
+```typescript
+req.get('name', 'default')        // get input value
+req.input('name', 'default')      // alias
+req.all()                          // all input
+req.only(['name', 'email'])       // specific fields
+req.except(['password'])          // all except
+req.has('name')                    // exists?
+req.has(['name', 'email'])        // all exist?
+req.hasAny(['name', 'email'])     // any exist?
+req.filled('name')                // exists and not empty?
+req.missing('name')               // doesn't exist?
+req.query                         // query parameters object
+```
+
+### Type Conversion
+```typescript
+req.string('name', '')
+req.integer('page', 1)
+req.float('price', 0.0)
+req.boolean('active', false)
+req.array('tags')
+```
+
+### File Handling
+```typescript
+const file = req.file('avatar')          // UploadedFile | null
+const files = req.getFiles('images')     // UploadedFile[]
+req.hasFile('avatar')                    // boolean
+const all = req.allFiles()               // Record<string, UploadedFile[]>
+```
+
+### Authentication
+```typescript
+const user = await req.user()
+const token = await req.userToken()
+await req.tokenCan('create-posts')
+await req.tokenCant('delete-users')
+```
+
+## Response Helpers
+
+```typescript
+import { response } from '@stacksjs/router'
+
+response.json(data, { status: 200 })
+response.created(data)         // 201
+response.noContent()           // 204
+response.badRequest(data)      // 400
+response.unauthorized()        // 401
+response.forbidden()           // 403
+response.notFound()            // 404
+response.error()               // 500
+response.redirect(url, 302)
+response.text('hello')
+response.html('<h1>Hi</h1>')
+```
+
+## Error Responses
+
+```typescript
+createErrorResponse(error, request, options?)
+createMiddlewareErrorResponse(error, request)
+createValidationErrorResponse(errors, request)
+createNotFoundResponse(path, request)
+```
+
+Error response body:
+```typescript
+{ error: string, message: string, status: number, timestamp: string, details?: Record<string, unknown> }
+```
+
+## Request Context
+
+```typescript
+import { getCurrentRequest, setCurrentRequest, runWithRequest, request } from '@stacksjs/router'
+
+// Async context management
+const req = getCurrentRequest()
+runWithRequest(req, async () => {
+  // `request` proxy available here
+})
+```
+
+## Middleware
+
+```typescript
+import { Middleware } from '@stacksjs/router'
+
+const logger = new Middleware({
+  name: 'logger',
+  priority: 5,   // lower = runs first, default 10
+  handle: async (request: EnhancedRequest) => {
+    console.log(`${request.method} ${request.url}`)
+  }
+})
+
+route.use(logger)
+```
+
+### Available Middleware Aliases (from app/Middleware.ts)
+maintenance, auth, guest, api, team, logger, abilities, can, throttle, local, development, staging, production, env.local, env.development, env.staging, env.production, role, permission, verified
+
+## Query Tracking
+
+```typescript
+trackQuery(query, time?, connection?)
+clearTrackedQueries()
+clearMiddlewareCache()
+```
+
+## Default API Routes (routes/api.ts)
+
+### Auth
+- `POST /login`, `POST /register`, `POST /auth/refresh`, `POST /auth/token`
+- `GET /auth/tokens`, `DELETE /auth/tokens/{id}` (auth)
+- `GET /me`, `POST /logout` (auth)
+
+### Email
+- `POST /api/email/subscribe`, `GET /api/email/unsubscribe`
+
+### AI
+- `POST /ai/ask`, `POST /ai/summary`
+
+### CMS
+- `/cms/posts/*`, `/cms/authors/*`, `/cms/categories/*`, `/cms/tags/*`, `/cms/comments/*`
+
+### Commerce
+- `/commerce/products/*`, `/commerce/orders/*`, `/commerce/customers/*`, `/shipping/*`
+
+### Monitoring
+- `/monitoring/errors/*`
+
+### Health
+- `GET /health` — returns status, uptime, memory, PID, Bun version
+
+## Server Integration
+
+```typescript
+import { serve, serverResponse } from '@stacksjs/router'
+
+await serve({ port: 3000 })
+const response = await serverResponse(request)
+```
+
+## URL Generation
+
+```typescript
+import { url } from '@stacksjs/router'
+
+url('admin.dashboard')                    // '/admin/dashboard'
+url('user.show', { id: 42 })             // '/users/42'
+```
+
+## Gotchas
+- Routes use `@stacksjs/bun-router` under the hood
+- Rate limiting via `ts-rate-limiter` is built into the router
+- Route registry in `app/Routes.ts` maps file names to URL prefixes
+- String-based handlers (`'Actions/MyAction'`) are dynamically imported
+- Middleware priority: lower number = runs first
+- The `request` proxy uses AsyncLocalStorage for context — must be inside `runWithRequest()`
+- EnhancedRequest extends the native Bun Request with Laravel-style helpers
+- File uploads return `UploadedFile` objects with metadata
+- Query tracking is for debug/profiling — call `clearTrackedQueries()` to free memory
+- The dev server writes a route manifest to `storage/framework/stx/routes.ts` (stx's `stateDir`, set in `config/ui.ts`); it is a build artifact, not a file to edit
+- The health endpoint returns uptime, memory, PID, and Bun version info