@stacksjs/defaults 0.70.206 → 0.70.208

package/TODO.md

@@ -0,0 +1,21 @@
+# TODO
+
+"Defaults" are the Stacks way of handling stubs.
+
+- [ ] create `buddy publish:defaults` command
+- [ ] stubs should be customizable when stubs are published
+  - [ ] action
+  - [ ] command
+  - [ ] job
+  - [ ] middleware
+  - [ ] model
+  - [ ] notification
+  - [ ] view (alias page)
+  - [ ] test
+  - [ ] mail
+  - [ ] store
+  - [ ] module
+  - [ ] type
+  - [ ] layout
+  - [ ] component
+  - [ ] function

package/ai/AGENTS.md

@@ -0,0 +1,79 @@
+# AGENTS.md
+
+Guidance for AI coding agents (Claude Code, OpenAI Codex CLI, Cursor, and others)
+working in this Stacks application. Every agent reads this file, so it is the one
+place to record project-specific rules.
+
+This is the starter version `buddy setup:ai` writes when a project has no
+`AGENTS.md` yet. Edit it freely - it is yours, and it is committed so the whole
+team (and every agent) sees the same rules.
+
+---
+
+## Project conventions
+
+### Linting
+
+- Use **pickier**, never eslint directly.
+- Lint: `bunx --bun pickier .` Auto-fix: `bunx --bun pickier . --fix`
+- For unused variables, prefer `// eslint-disable-next-line` over an underscore
+  prefix.
+
+### Frontend
+
+- Use **stx** for templating. Never vanilla JS (`var`, `document.*`, `window.*`)
+  inside stx templates - use signals (`state` / `derived` / `effect`) and
+  composables.
+- Use **Crosswind** utility classes for styling.
+- Icons are Iconify classes (`i-{collection}-{name}`). Never hand-roll SVG paths
+  and never add an icon npm package.
+- Stacks ships no animation library. Use Crosswind transitions, CSS keyframes,
+  scroll-driven animations, and the motion composables.
+
+### Commits
+
+- Conventional commit messages (`fix:`, `feat:`, `chore:`, ...).
+- Only commit or push when asked.
+
+### Requirements
+
+Bun >= 1.3.0, SQLite >= 3.47.2, TypeScript throughout.
+
+---
+
+## Repository map
+
+| Path | What lives here |
+|---|---|
+| `app/` | Your code: `Actions/`, `Jobs/`, `Listeners/`, `Middleware/`, `Mail/`, `Commands/`, `Models/`, `Skills/`, plus `Routes.ts`, `Events.ts`, `Gates.ts`, `Scheduler.ts` |
+| `routes/` | Route files, registered via `app/Routes.ts` |
+| `config/` | Typed configuration, one file per subsystem |
+| `database/` | Migrations, seeders, local SQLite files |
+| `resources/` | stx frontend: `views/`, `components/`, `layouts/`, `partials/` |
+| `storage/framework/` | Framework internals and defaults. Read-only reference |
+| `tests/` | Bun test suites |
+
+### The `app/` override model
+
+Stacks resolves files from `app/` first and falls back to
+`storage/framework/defaults/app/`. To customize a framework default, create the
+same path under `app/` and it wins.
+
+---
+
+## Skills
+
+The framework ships a skill per subsystem under
+`storage/framework/defaults/ai/skills`, each documenting that area
+authoritatively. Read the relevant `SKILL.md` before doing non-trivial work
+rather than guessing at an API.
+
+Add your own with `app/Skills/<name>/SKILL.md`, then re-run `buddy setup:ai`.
+
+---
+
+## Before finishing
+
+- Lint: `bunx --bun pickier .` (fix with `--fix`)
+- Type check: `bun run typecheck:app`
+- Test: `buddy test`

package/ai/README.md

@@ -0,0 +1,45 @@
+# AI agent defaults
+
+Templates that `buddy setup:ai` uses to wire a project up for whichever AI coding
+agent you use. Nothing here is read at runtime - it is scaffolding, in the same
+spirit as `storage/framework/defaults/ide/`.
+
+```
+ai/
+├── AGENTS.md          starter guidance, copied to the project root if absent
+├── claude/
+│   └── launch.json    Claude Code run configurations, copied to .claude/
+└── skills/            the framework's agent skills (agentskills.io format)
+```
+
+## Why the generated directories are not committed
+
+`AGENTS.md` is the one file every agent reads, so it lives in the project root
+and is committed - it is shared guidance, and it belongs in review.
+
+Everything else is per-developer. Which agent you use is a personal choice, so
+`.claude/`, `.codex/`, `.cursor/`, `.gemini/` and
+`.github/copilot-instructions.md` are gitignored and generated on demand:
+
+```sh
+buddy setup:ai                  # pick an agent interactively
+buddy setup:ai claude           # or name it
+buddy setup:ai claude --copy    # copy the skills instead of symlinking them
+```
+
+## Skills
+
+`skills/` holds the framework's agent skills, one directory per skill, each with
+a `SKILL.md` carrying `name` and `description` frontmatter. They document the
+framework subsystem by subsystem, so an agent can read the authoritative
+reference for a task instead of guessing at an API.
+
+`buddy setup:ai` writes one entry per skill into the agent's directory, and
+symlinks by default so skills stay in sync when you upgrade the framework. Pass
+`--copy` if you would rather edit them per project.
+
+To add a project-specific skill, or to shadow a bundled one, create
+`app/Skills/<name>/SKILL.md`. `@stacksjs/skills` searches `app/Skills` first and
+falls back to this directory - the same app-overrides-defaults model the rest of
+the framework uses - and `setup:ai` links the winner, so a project skill also
+wins in the agent's directory.

package/ai/claude/launch.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "frontend",
+      "runtimeExecutable": "./buddy",
+      "runtimeArgs": ["dev:frontend"],
+      "port": 3100,
+      "autoPort": true
+    }
+  ]
+}

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

@@ -0,0 +1,128 @@
+---
+name: stacks-actions
+description: Use when working with Stacks server actions — creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 80+ default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Actions
+
+Server actions are reusable business logic units invoked from routes, events, or CLI commands.
+
+## Key Paths
+- Core package: `storage/framework/core/actions/src/`
+- Application actions: `app/Actions/`
+- Default framework actions: `storage/framework/defaults/app/Actions/`
+- Framework actions (generated): `storage/framework/actions/`
+
+## Creating an Action
+
+```typescript
+// app/Actions/NotifyUser.ts
+export default {
+  name: 'NotifyUser',
+  description: 'Notify user after creation',
+
+  async handle(request: any) {
+    const id = request.get('id')
+    const name = request.get('name')
+    console.log(`User ${name} (${id}) created`)
+    return { success: true }
+  }
+}
+```
+
+## Auto-Generated API Actions (useApi Trait)
+
+When a model defines `useApi`, the framework auto-generates REST actions:
+
+```typescript
+defineModel({
+  name: 'Product',
+  traits: {
+    useApi: {
+      uri: 'products',
+      routes: ['index', 'store', 'show', 'update', 'destroy']
+    }
+  }
+})
+```
+
+This generates:
+- `GET /api/products` → Index action (list all)
+- `POST /api/products` → Store action (create)
+- `GET /api/products/{id}` → Show action (get one)
+- `PUT /api/products/{id}` → Update action
+- `DELETE /api/products/{id}` → Destroy action
+
+## Default Framework Actions (80+)
+
+### Authentication Actions
+- `LoginAction` — POST /login (validates email + password, returns token + user)
+- `RegisterAction` — POST /register
+- `LogoutAction` — POST /logout (auth required)
+- `RefreshTokenAction` — POST /auth/refresh
+- `CreateTokenAction` — POST /auth/token
+- `ListTokensAction` — GET /auth/tokens (auth required)
+- `RevokeTokenAction` — DELETE /auth/tokens/{id}
+- `GetMeAction` — GET /me (auth required)
+- `PasskeyRegistrationAction` — passkey authentication options
+
+### Dashboard Settings Actions (40+)
+For each settings category (AI, Analytics, App, Cache, Cloud, Database, DNS, Email, Environment, FileSystems, Hashing, Library, Logging, Notifications, Payment, Ports, Queue, SearchEngine, Security, Services, Storage, Team, UI):
+- `Get{Category}SettingsAction` — read current settings
+- `Update{Category}SettingsAction` — update settings
+
+### Commerce Actions
+- CRUD actions for: Products, Orders, Customers, Payments, Coupons, GiftCards, Reviews, Shipping, DeliveryRoutes, TaxRates, LicenseKeys, etc.
+
+### Content Actions
+- CRUD actions for: Posts, Pages, Authors, Categories, Tags, Comments
+
+### System Actions
+- `HealthAction` — GET /health (returns status, uptime, memory, PID, Bun version)
+- `GetUserCountAction` — user count for dashboard
+- `GetSubscriberCountAction` — subscriber count
+- Deployment CRUD actions
+- Job monitoring actions
+- Notification actions
+- Request analytics actions
+
+## Action Handler Pattern
+
+Actions receive the enhanced request object:
+```typescript
+async handle(request: EnhancedRequest) {
+  const name = request.get('name')         // input value
+  const email = request.input('email')     // alias
+  const all = request.all()                // all input
+  const user = await request.user()        // authenticated user
+
+  return { success: true, data: { ... } }
+}
+```
+
+## Using Actions in Routes
+
+```typescript
+// String-based (auto-loaded)
+route.post('/users', 'Actions/CreateUser')
+
+// In events (app/Events.ts)
+{ 'user:registered': ['SendWelcomeEmail'] }  // action name as listener
+```
+
+## CLI Commands
+- `buddy make:action [name]` — scaffold a new action
+
+## Gotchas
+- Application actions go in `app/Actions/`
+- Framework default actions are in `storage/framework/defaults/app/Actions/`
+- The `handle()` method is required — it receives the request object
+- Actions used as event listeners also have a `handle(event)` method
+- The `useApi` model trait auto-generates CRUD actions + routes
+- Actions are resolved dynamically at runtime via string names
+- The HealthAction at `/health` is useful for container health checks
+- Login action returns `{ token: string, user: { id, email, name } }`
+- All dashboard settings actions read/write from the corresponding config files

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

@@ -0,0 +1,276 @@
+---
+name: stacks-ai
+description: Use when integrating AI capabilities into a Stacks application — using Anthropic/OpenAI/Ollama/AWS Bedrock drivers, image generation (DALL-E), vision analysis, RAG/vector search, embeddings, MCP (Model Context Protocol) clients, text summarization, sentiment analysis, content classification, personalization, or the buddy AI assistant. Covers @stacksjs/ai and config/ai.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks AI
+
+Comprehensive AI/LLM integration with 4 provider drivers, image generation, vision, RAG, MCP support, and personalization.
+
+## Key Paths
+- Core package: `storage/framework/core/ai/src/`
+- Configuration: `config/ai.ts`
+
+## Source Files
+```
+ai/src/
+├── drivers/
+│   ├── anthropic.ts      # Claude driver
+│   ├── openai.ts         # GPT + DALL-E + Whisper + TTS
+│   ├── ollama.ts         # Local LLM driver
+│   └── bedrock.ts        # AWS Bedrock utilities
+├── image.ts              # Image generation & vision
+├── search.ts             # RAG, embeddings, vector index
+├── mcp.ts                # Model Context Protocol client
+├── personalization.ts    # Sentiment, classification, recommendations
+├── buddy.ts              # AI coding assistant
+├── claude-agent.ts       # Claude CLI agent (local & EC2)
+├── claude-agent-sdk.ts   # Claude Agent SDK driver
+└── text.ts               # Bedrock text summarization
+```
+
+## Anthropic Driver
+
+```typescript
+import { anthropic } from '@stacksjs/ai'
+
+anthropic.configure({ apiKey: '...', model: 'claude-sonnet-4-20250514', maxTokens: 4096 })
+const result = await anthropic.chat([{ role: 'user', content: 'Hello' }])
+const stream = await anthropic.streamChat(messages, options)
+const response = await anthropic.prompt('Summarize this text...')
+const tokens = anthropic.estimateTokens(text)
+```
+
+## OpenAI Driver
+
+```typescript
+import { openai } from '@stacksjs/ai'
+
+openai.configure({ apiKey: '...', model: 'gpt-4o', embeddingModel: 'text-embedding-3-small' })
+const result = await openai.chat(messages, { temperature: 0.7 })
+const stream = await openai.streamChat(messages)
+const embeddings = await openai.embed('text to embed')
+const image = await openai.generateImage('a sunset over mountains')
+const transcription = await openai.transcribe(audioFile)
+const speech = await openai.textToSpeech('Hello world')
+```
+
+## Ollama Driver (Local LLMs)
+
+```typescript
+import { ollama } from '@stacksjs/ai'
+
+ollama.configure({ host: 'http://localhost:11434', model: 'llama3' })
+const result = await ollama.chat(messages)
+const stream = await ollama.streamChat(messages)
+const text = await ollama.generate('Write a poem')
+const embeddings = await ollama.embed('text')
+const models = await ollama.listModels()
+await ollama.pullModel('llama3', (progress) => console.log(progress))
+await ollama.deleteModel('old-model')
+const info = await ollama.showModel('llama3')
+const running = await ollama.isRunning()
+```
+
+## Image Generation
+
+```typescript
+import { generateImage, editImage, createImageVariation, analyzeImage, analyzeImages } from '@stacksjs/ai'
+
+// Generate (DALL-E 3)
+const result = await generateImage('a cat in space', {
+  model: 'dall-e-3', size: '1024x1024', quality: 'hd', style: 'vivid', n: 1
+})
+
+// Edit (DALL-E 2)
+await editImage(imageInput, 'add a hat', { mask: maskInput })
+
+// Variations
+await createImageVariation(imageInput, { n: 3 })
+
+// Vision (GPT-4 Vision / Claude)
+const analysis = await analyzeImage({ url: 'https://...' }, 'What is in this image?')
+const multiAnalysis = await analyzeImages([img1, img2], 'Compare these')
+```
+
+Image inputs: `{ url: string }`, `{ base64: string }`, `{ file: string }` (auto-converted)
+
+## RAG & Vector Search
+
+```typescript
+import { createEmbedding, rag, VectorIndex, chunkText, indexText } from '@stacksjs/ai'
+
+// Create embeddings
+const embedding = await createEmbedding('text to embed')
+
+// Vector similarity
+cosineSimilarity(vecA, vecB)
+dotProduct(vecA, vecB)
+euclideanDistance(vecA, vecB)
+
+// Text chunking
+const chunks = chunkText(longText, { chunkSize: 500, overlap: 50 })
+
+// Build index
+const index = await indexText(text, { chunkSize: 500 })
+
+// RAG query
+const answer = await rag('What is X?', index, { model: 'claude-sonnet-4-20250514', maxTokens: 1000 })
+
+// VectorIndex class
+const idx = new VectorIndex({ dimensions: 1536 })
+await idx.add([{ id: '1', content: 'Hello', metadata: {} }])
+const results = await idx.search('greeting', 5)
+const results2 = await idx.searchByVector(queryEmbedding, 5)
+idx.remove('1')
+idx.clear()
+idx.size      // number of documents
+idx.ids       // all document IDs
+```
+
+## MCP (Model Context Protocol)
+
+```typescript
+import { MCPClient, MCPManager, connectStdio, connectHTTP } from '@stacksjs/ai'
+
+// Single server
+const client = new MCPClient({ name: 'my-server', transport: 'stdio', command: 'npx', args: ['my-mcp-server'] })
+await client.connect()
+const tools = await client.listTools()
+const resources = await client.listResources()
+const prompts = await client.listPrompts()
+const result = await client.callTool('tool-name', { arg: 'value' })
+const resource = await client.readResource('resource://path')
+const prompt = await client.getPrompt('prompt-name', { arg: 'value' })
+const anthropicTools = client.toAnthropicTools()
+const openaiTools = client.toOpenAITools()
+
+// Multiple servers
+const manager = new MCPManager()
+manager.addServer({ name: 'server1', transport: 'stdio', command: '...' })
+manager.addServer({ name: 'server2', transport: 'streamable-http', url: '...' })
+const allTools = await manager.getAllTools()
+await manager.callTool('server1/tool-name', args)
+await manager.disconnectAll()
+
+// Convenience functions
+const client = await connectStdio('name', 'command', ['args'])
+const client = await connectHTTP('name', 'https://server.com', headers)
+```
+
+Transport types: `'stdio'` | `'sse'` | `'streamable-http'`
+
+## Personalization
+
+```typescript
+import { analyzeSentiment, classifyText, summarize, recommend, createProfile } from '@stacksjs/ai'
+
+const sentiment = await analyzeSentiment('I love this product!')
+// { sentiment: 'positive', score: 0.95, confidence: 0.98, aspects: [...] }
+
+const classification = await classifyText('Fix the login bug', ['bug', 'feature', 'question'])
+// { label: 'bug', confidence: 0.92, allLabels: [...] }
+
+const summary = await summarize(longText, { maxLength: 100, style: 'bullet' })
+
+const profile = createProfile('user-123', ['tech', 'gaming'])
+recordInteraction(profile, { type: 'view', itemId: 'article-1', weight: 1.0 })
+const recs = await recommend(profile, contentItems, { limit: 10 })
+const interests = await extractUserInterests(profile, items)
+```
+
+## Buddy AI Assistant
+
+```typescript
+import { processCommand, buddyProcessStreaming, buddyStreamSimple, getAvailableDrivers } from '@stacksjs/ai'
+
+const drivers = getAvailableDrivers()  // ['anthropic', 'openai', 'ollama']
+const context = await getRepoContext('/path/to/repo')
+await processCommand('Add error handling to auth.ts', 'anthropic')
+// Streaming
+for await (const chunk of buddyProcessStreaming('Refactor this function', 'openai', history)) {
+  process.stdout.write(chunk)
+}
+```
+
+## Compact Project Context
+
+Use the native context contract instead of sending dependency internals, lockfiles,
+or an arbitrary repository dump to a coding model:
+
+```bash
+buddy ai:context
+buddy ai:context --json
+buddy ai:context --json --output storage/framework/runtime/ai-context.json
+buddy ai:context --max-chars 4000 --model claude-sonnet-4
+```
+
+Programmatic callers use `buildProjectContext(projectRoot, options)`. Existing
+`getRepoContext(projectRoot)` calls return its compact text payload. The contract
+is deterministic, reports a heuristic token estimate, and describes canonical
+Model-View-Action roles, application overrides, instruction files, scripts,
+dependency names, and representative application files. It excludes
+`node_modules`, build output, caches, lockfiles, environment files, credentials,
+private keys, and secret files by default.
+
+The character budget applies to the prompt payload. JSON adds a versioned metadata
+envelope for tools. Token estimates are planning heuristics, not provider billing
+counts or evidence that model output is correct.
+
+## Claude Agent
+
+```typescript
+import { createClaudeLocalAgent, createClaudeEC2Agent } from '@stacksjs/ai'
+
+const agent = createClaudeLocalAgent({ cwd: '/project' })
+for await (const chunk of agent.processCommandStreaming('Fix the tests')) {
+  process.stdout.write(chunk)
+}
+
+// Remote EC2 agent
+const remoteAgent = createClaudeEC2Agent({ ec2Host: '...', ec2User: '...', ec2Key: '...' })
+```
+
+## Claude Agent SDK
+
+```typescript
+import { createClaudeAgentSDKDriver } from '@stacksjs/ai'
+
+const driver = createClaudeAgentSDKDriver({
+  maxTurns: 10, cwd: '/project', permissionMode: 'auto',
+  allowedTools: ['Read', 'Write', 'Edit', 'Bash'],
+  customSystemPrompt: 'You are a Stacks expert'
+})
+
+for await (const chunk of driver.processStreaming('Build a user registration flow')) {
+  process.stdout.write(chunk)
+}
+const sessionId = driver.getLastSessionId()
+await driver.resumeSession(sessionId, 'Add validation')
+```
+
+## config/ai.ts
+
+```typescript
+{
+  default: 'meta.llama2-70b-chat-v1',
+  models: ['meta.llama2-70b-chat-v1', ...],  // AWS Bedrock models
+  deploy: true
+}
+```
+
+## Gotchas
+- API keys should be in `.env` — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`
+- Ollama requires a local server running on port 11434
+- Image generation uses OpenAI DALL-E by default
+- Vision supports both GPT-4V and Claude models
+- VectorIndex is in-memory — not persisted between restarts
+- RAG combines chunking + embedding + vector search + LLM generation
+- MCP supports stdio (subprocess), SSE, and HTTP transports
+- The buddy assistant has git integration (commit, push, apply changes)
+- Claude Agent SDK wraps the Claude Code CLI for agentic workflows
+- Bedrock utilities are for AWS-hosted model invocation
+- Sentiment/classification use AI models — they're not rule-based

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

@@ -0,0 +1,94 @@
+---
+name: stacks-alias
+description: Use when working with path aliases in a Stacks project — import resolution, module aliasing, or debugging import paths. Covers @stacksjs/alias which defines 260+ path mappings for the entire framework.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Path Aliases
+
+## Key Paths
+- Core package: `storage/framework/core/alias/src/`
+- Source: `storage/framework/core/alias/src/index.ts`
+- Package: `@stacksjs/alias`
+
+## API
+
+```typescript
+import { alias } from '@stacksjs/alias'
+
+const alias: Record<string, string>  // 260+ entries
+```
+
+## Alias Categories
+
+### Framework Module Aliases
+Maps `@stacksjs/*` and `stacks/*` imports to their source files:
+
+```typescript
+'@stacksjs/ai':          'storage/framework/core/ai/src/index.ts'
+'@stacksjs/auth':        'storage/framework/core/auth/src/index.ts'
+'@stacksjs/database':    'storage/framework/core/database/src/index.ts'
+'@stacksjs/router':      'storage/framework/core/router/src/index.ts'
+'@stacksjs/cache':       'storage/framework/core/cache/src/index.ts'
+'@stacksjs/cli':         'storage/framework/core/buddy/src/index.ts'
+'@stacksjs/config':      'storage/framework/core/config/src/index.ts'
+// ... all core packages
+```
+
+Both `@stacksjs/` and `stacks/` prefixes are supported:
+
+```typescript
+'stacks/auth':            'storage/framework/core/auth/src/index.ts'
+'stacks/database':        'storage/framework/core/database/src/index.ts'
+```
+
+### Config Aliases
+Maps `~/config/*` to config files:
+
+```typescript
+'~/config/database':      'config/database.ts'
+'~/config/dns':           'config/dns.ts'
+'~/config/docs':          'config/docs.ts'
+'~/config/email':         'config/email.ts'
+// ... all 44 config files
+```
+
+### Resource Aliases
+Maps `~/` paths to project directories:
+
+```typescript
+'~/app/*':                'app/*'
+'~/components/*':         'resources/components/*'
+'~/functions/*':          'resources/functions/*'
+'~/views/*':              'resources/views/*'
+'~/lang/*':               'locales/*'
+'~/*':                    '*'
+```
+
+### Framework Aliases
+```typescript
+'framework/*':            'storage/framework/*'
+'@/*':                    '*'
+```
+
+## Usage
+
+Aliases are automatically resolved by Bun at runtime and by the build system for production:
+
+```typescript
+// These all work because of aliases
+import { db } from '@stacksjs/database'
+import { route } from '@stacksjs/router'
+import { auth } from 'stacks/auth'
+import dbConfig from '~/config/database'
+```
+
+## Gotchas
+- **260+ entries** — covers every core package, config file, and resource directory
+- **Dual prefixes** — both `@stacksjs/` and `stacks/` resolve to the same source files
+- **Runtime resolution** — Bun resolves these at runtime via `bunfig.toml` preloading
+- **Build-time resolution** — the build system resolves aliases to actual paths for production
+- **Always use aliases** — never use relative paths between packages in the monorepo
+- **Adding new packages** — requires adding alias entries for both `@stacksjs/` and `stacks/` prefixes