@stacksjs/defaults 0.70.206 → 0.70.208

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

@@ -0,0 +1,163 @@
+---
+name: stacks-build
+description: Use when working with the Stacks build system — building component libraries, CLI binaries, server Docker images, documentation, or the framework core. Covers @stacksjs/build, buddy build commands, build actions, and the server build pipeline.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Build System
+
+## Key Paths
+- Core package: `storage/framework/core/build/`
+- Build actions: `storage/framework/core/actions/src/build/`
+- Main build action: `storage/framework/core/actions/src/build.ts`
+- Buddy commands: `storage/framework/core/buddy/src/commands/build.ts`
+- Server build: `storage/framework/server/build.ts`
+- Server Dockerfile: `storage/framework/server/Dockerfile`
+- Types: `storage/framework/core/types/src/cli.ts`
+
+## Source Files
+```
+build/src/
+├── index.ts              # intro() and outro() — build logging and timing
+├── web-types.ts          # Web types generation for IDE support
+└── build.ts              # Package build config (Bun.build)
+
+actions/src/build/
+├── cli.ts                # Build Buddy CLI binary
+├── server.ts             # Build server Docker image
+├── core.ts               # Build all framework core packages
+├── stacks.ts             # Orchestrate CLI + core builds
+├── component-libs.ts     # Build component libraries (Vue + Web)
+├── docs.ts               # Build documentation
+├── desktop.ts            # Build desktop app
+└── views.ts              # Build frontend views
+```
+
+## Build Types
+
+```typescript
+type BuildOption =
+  | 'components' | 'webComponents' | 'elements'
+  | 'functions' | 'docs' | 'views' | 'stacks' | 'all' | 'buddy' | 'server'
+
+type BuildOptions = { [key in BuildOption]: boolean } & CliOptions
+
+interface CliOptions {
+  verbose?: boolean
+  silent?: boolean
+  quiet?: boolean
+  cwd?: string
+  background?: boolean
+  timeoutMs?: number
+  project?: string
+}
+```
+
+## CLI Commands
+
+```bash
+buddy build                    # Interactive build
+buddy build components         # All component libraries
+buddy build:components         # Alias
+buddy build:web-components     # Web Components library only
+buddy build:functions          # Functions library
+buddy build:cli                # Buddy CLI binary
+buddy build:server             # Server Docker image
+buddy build:core               # All framework core packages
+buddy build:stacks             # CLI + core (full framework)
+buddy build:docs               # Documentation site
+buddy build:desktop            # Desktop application
+buddy build:views              # Frontend views
+
+# Flags
+buddy build -c    # --components
+buddy build -w    # --web-components
+buddy build -f    # --functions
+buddy build -d    # --docs
+buddy build -b    # --buddy
+buddy build -s    # --stacks
+buddy build --server --verbose --project [name]
+```
+
+## Standard Build Pattern
+
+Every core package follows this pattern:
+
+```typescript
+import { dts } from 'bun-plugin-dtsx'
+import { intro, outro } from '../build/src'
+
+const { startTime } = await intro({ dir: import.meta.dir })
+const result = await Bun.build({
+  entrypoints: ['./src/index.ts'],
+  outdir: './dist',
+  format: 'esm',
+  target: 'bun',
+  minify: true,
+  plugins: [dts({ root: '.', outdir: './dist' })],
+})
+await outro({ dir: import.meta.dir, startTime, result })
+```
+
+## Build Utilities (index.ts)
+
+```typescript
+async function intro(options: { dir: string, pkgName?: string, styled?: boolean }): Promise<{ startTime: number }>
+async function outro(options: { dir: string, startTime: number, result: any, pkgName?: string }): Promise<void>
+```
+
+`outro()` handles two result formats:
+- **Bun.build**: checks `result.success` and `result.logs`
+- **esbuild**: checks `result.errors` array
+
+## Server Build Pipeline (7 stages)
+
+```
+1. Stop running stacks-server Docker container
+2. Clean previous build artifacts (app, config, dist, docs, storage)
+3. Build framework server (compile ./src/index.ts)
+4. Build user app files (compile ./app/**/*.{ts,js})
+5. Fix import paths (replace storage/framework/server → dist)
+6. Clean unwanted exports from dist files
+7. Build Docker image (if cloud deployment enabled)
+```
+
+## Build Action Enums
+
+```typescript
+enum Action {
+  BuildViews = 'build/views'
+  BuildStacks = 'build/stacks'
+  BuildComponentLibs = 'build/component-libs'
+  BuildVueComponentLib = 'build-vue-component-lib'
+  BuildWebComponentLib = 'build-web-component-lib'
+  BuildFunctionLib = 'build-function-lib'
+  BuildCli = 'build/cli'
+  BuildCore = 'build/core'
+  BuildDesktop = 'build/desktop'
+  BuildDocs = 'build/docs'
+  BuildServer = 'build/server'
+}
+```
+
+## Build Tool Stack
+
+| Tool | Usage |
+|------|-------|
+| **Bun** | Primary bundler (`target: 'bun'`, `format: 'esm'`) |
+| **Vite** | Component library builds |
+| **bun-plugin-dtsx** | TypeScript declaration generation |
+| **Docker** | Server containerization |
+| **@babel/traverse** | AST traversal for export cleanup |
+
+## Gotchas
+- **Two result formats** — `outro()` must handle both Bun.build and esbuild formats
+- **Server build mutates import paths** — stage 5 rewrites references in compiled output
+- **Core build is sequential** — packages built one at a time, failures collected and reported
+- **Docker build requires cloud config** — only builds if cloud deployment is enabled
+- **Component libraries use Vite** — unlike the rest which uses Bun.build
+- **`build:stacks` builds CLI first** — Buddy binary compiled before core packages
+- **Server build cleans aggressively** — deletes app, config, dist, docs, storage before rebuild
+- **The build package has @babel deps** — uses Babel for AST traversal during export cleanup

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

@@ -0,0 +1,125 @@
+---
+name: stacks-cache
+description: Use when implementing caching in Stacks — memory cache, Redis cache, cache-aside pattern (getOrSet), TTL management, cache stats, or cache configuration. Covers @stacksjs/cache and config/cache.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Cache
+
+## Key Paths
+- Core package: `storage/framework/core/cache/src/`
+- Configuration: `config/cache.ts`
+- Cache storage: `storage/framework/cache/`
+
+## Cache API (StacksCache)
+
+```typescript
+import { cache, memory } from '@stacksjs/cache'
+
+// Get/Set
+await cache.get<string>('key')                    // T | undefined
+await cache.set('key', 'value', 3600)             // TTL in seconds
+await cache.setForever('key', 'value')            // no expiry
+await cache.mget<string>(['key1', 'key2'])        // T[]
+await cache.mset([{ key: 'k1', value: 'v1', ttl: 60 }, ...])
+
+// Cache-aside pattern
+const value = await cache.getOrSet('expensive-key', async () => {
+  return await computeExpensiveValue()
+}, 3600)
+
+// Delete
+await cache.del('key')
+await cache.del(['key1', 'key2'])
+await cache.deleteMany(['key1', 'key2'])
+await cache.remove('key')
+
+// Existence
+await cache.has('key')          // boolean
+await cache.missing('key')     // boolean
+
+// Take (get and delete)
+const value = await cache.take<string>('key')
+
+// TTL management
+await cache.getTtl('key')              // remaining TTL
+await cache.ttl('key', 7200)           // update TTL
+
+// Clear
+await cache.clear()
+await cache.flush()
+
+// Stats
+const stats = await cache.getStats()
+// { hits, misses, keys, size, hitRate }
+
+// Keys
+const keys = await cache.keys('user:*')  // pattern matching
+
+// Cleanup
+await cache.close()
+await cache.disconnect()
+```
+
+## Factory Functions
+
+```typescript
+import { createMemoryCache, createRedisCache, createCache } from '@stacksjs/cache'
+
+const memCache = createMemoryCache({
+  stdTTL: 3600,       // default TTL (seconds)
+  checkPeriod: 120,   // eviction check interval
+  maxKeys: -1,        // -1 = unlimited
+  useClones: true,    // clone on get/set
+  prefix: 'app:'      // key prefix
+})
+
+const redisCache = createRedisCache({
+  url: 'redis://localhost:6379',
+  // or individual:
+  host: 'localhost',
+  port: 6379,
+  username: undefined,
+  password: undefined,
+  database: 0,
+  tls: false,
+  stdTTL: 3600,
+  prefix: 'app:'
+})
+
+// Auto-detect from config
+const cache = createCache('memory')
+const cache = createCache('redis', { host: 'localhost' })
+```
+
+## config/cache.ts
+```typescript
+{
+  driver: 'memory',     // 'memory' | 'redis'
+  prefix: 'stacks',
+  ttl: 3600,            // 1 hour default
+  maxKeys: -1,          // unlimited
+  useClones: true,
+  drivers: {
+    redis: { host: 'localhost', port: 6379 },
+    memory: {}
+  }
+}
+```
+
+## Default Instance
+- `cache` — default memory cache (pre-configured)
+- `memory` — alias for `cache`
+
+## Gotchas
+- Default driver is `memory` — data lost on restart
+- Redis driver requires a running Redis server
+- `getOrSet()` is the cache-aside pattern — fetches only on miss
+- `useClones: true` means mutations to retrieved objects don't affect cache
+- `take()` atomically gets and deletes — useful for one-time tokens
+- Cache stats track hits, misses, and hit rate — useful for tuning
+- `keys()` supports glob patterns for key listing
+- Framework caches (auto-imports, discovered packages) are in `storage/framework/cache/`
+- Use `buddy clean` or `buddy fresh` to clear framework caches

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

@@ -0,0 +1,113 @@
+---
+name: stacks-calendar
+description: Use when working with calendar functionality in Stacks — exporting events to Google Calendar, Outlook, Yahoo, or ICS format, the CalendarLink interface for event definitions, timezone handling, all-day events, or calendar URL generation. Covers @stacksjs/calendar-api.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Calendar
+
+Calendar event export to 4 calendar providers.
+
+## Key Paths
+- Core package: `storage/framework/core/calendar-api/src/`
+- Package: `@stacksjs/calendar-api`
+
+## Export Functions
+
+```typescript
+import { exportCalendarGoogle, exportCalendarIcs, exportCalendarOutlook, exportCalendarYahoo } from '@stacksjs/calendar-api'
+
+const event: CalendarLink = {
+  title: 'Team Meeting',
+  description: 'Weekly standup',
+  from: new Date('2024-06-15T10:00:00'),
+  to: new Date('2024-06-15T11:00:00'),
+  address: '123 Main St, City',
+  timezone: 'America/New_York',
+  allDay: false
+}
+
+// Generate URLs
+const googleUrl = exportCalendarGoogle(event)
+// → https://calendar.google.com/calendar/render?action=TEMPLATE&text=...
+
+const icsContent = exportCalendarIcs(event)
+// → BEGIN:VCALENDAR\nBEGIN:VEVENT\n...
+
+const outlookUrl = exportCalendarOutlook(event)
+// → https://outlook.live.com/calendar/0/deeplink/compose?...
+
+const yahooUrl = exportCalendarYahoo(event)
+// → https://calendar.yahoo.com/?v=60&title=...
+```
+
+## CalendarLink Interface
+
+```typescript
+interface CalendarLink {
+  title: string
+  description?: string
+  from: Date              // start time
+  to: Date                // end time
+  allDay?: boolean        // all-day event (ignores time)
+  address?: string        // location
+  timezone?: string       // IANA timezone (e.g., 'America/New_York')
+}
+```
+
+## Calendar Store Types
+
+```typescript
+interface CalendarStore {
+  day: number
+  month: number
+  year: number
+  currentMonthYear: string
+  datesOfMonth: number[]
+  currentWeekView: WeekDates[]
+}
+
+interface Events {
+  date: string
+  title: string
+  description?: string
+  month: number
+  day: number
+  year: number
+  time?: Time
+}
+
+interface Time { from: string, to: string }
+interface WeekDates { month: number, date: number }
+```
+
+## All-Day Events
+
+```typescript
+const allDayEvent: CalendarLink = {
+  title: 'Company Holiday',
+  from: new Date('2024-12-25'),
+  to: new Date('2024-12-25'),
+  allDay: true  // only date matters, no time component
+}
+```
+
+## Format Differences
+
+| Feature | Google | ICS | Outlook | Yahoo |
+|---------|--------|-----|---------|-------|
+| URL-based | Yes | No (file) | Yes | Yes |
+| Timezone | URL param | VTIMEZONE | URL param | URL param |
+| All-day | Date only | DATE value | isAllDay=true | st= format |
+| Description | details= | DESCRIPTION | body= | desc= |
+
+## Gotchas
+- Note package name is `@stacksjs/calendar-api` (not `@stacksjs/calendar`)
+- ICS export returns file content (not a URL) — serve as `.ics` download
+- All-day events use date-only format, ignoring time components
+- Timezone handling varies by provider — ICS includes VTIMEZONE block
+- Google Calendar uses UTC format in URLs
+- For task scheduling (cron), use `@stacksjs/scheduler` instead
+- ICS generates a unique UID per event for calendar deduplication