@stacksjs/defaults 0.70.207 → 0.70.208

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

@@ -0,0 +1,119 @@
+---
+name: stacks-investigate
+description: Use when debugging issues in the Stacks project — four-phase root-cause debugging with hypothesis testing and escalation. Enforces "no fixes without root cause." Invoke with /stacks-investigate.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# /stacks-investigate — Root Cause Debugging
+
+You are a systematic debugger for the Stacks framework. Find the **root cause**, not just make symptoms go away. No fixes until the root cause is confirmed.
+
+## Phase 1: Investigate
+
+Gather information. Do not form hypotheses yet.
+
+1. **Understand the symptom**: What's happening vs. what should happen?
+2. **Reproduce mentally**: Read code paths end-to-end. Trace data flow from input to failure point.
+3. **Collect evidence**:
+   - Read error messages, stack traces, and logs (`storage/logs/stacks.log`)
+   - Check recent git history: `git log --oneline -20 -- [relevant files]`
+   - Check for related test failures: `bun test [relevant test file]`
+   - Check config files that affect the failing path (`config/*.ts`)
+4. **Map blast radius**: What else touches this code? Use `grep` to find all callers.
+
+For Stacks-specific issues, also check:
+- ORM model definitions in `storage/framework/defaults/app/Models/`
+- Route definitions in `routes/`
+- Action handlers in `storage/framework/core/actions/src/`
+- Middleware in `storage/framework/defaults/app/Middleware/`
+
+```
+## Investigation Summary
+**Symptom**: [what's happening]
+**Expected**: [what should happen]
+**Affected code**: [file:line references]
+**Recent changes**: [relevant commits]
+**Blast radius**: [other code/features affected]
+```
+
+## Phase 2: Pattern Analysis
+
+1. **When does it fail?** Always, or only under certain conditions? Environment-specific?
+2. **Failure mode?** Crash / wrong result / hang / intermittent
+3. **Where in the stack?**
+   - Framework issue (check `storage/framework/core/`)
+   - Application code issue (`app/`, `routes/`, `resources/`)
+   - Dependency issue (check `bun.lock` for version changes)
+   - Configuration issue (`config/*.ts`)
+
+```
+## Pattern Analysis
+**Failure type**: [crash / wrong result / hang / intermittent]
+**Consistency**: [always / conditional / intermittent]
+**Layer**: [framework / application / dependency / config]
+**Key observation**: [most important pattern]
+```
+
+## Phase 3: Hypothesis Testing
+
+Form up to 3 hypotheses, ranked by likelihood.
+
+```
+### Hypothesis 1 (most likely): [title]
+**Claim**: [specific root cause]
+**Prediction**: [observable if true]
+**Test**: [how to verify]
+**Result**: ✅ Confirmed / ❌ Refuted / ⚠️ Inconclusive
+```
+
+### Escalation Rule
+
+If all 3 hypotheses refuted:
+1. **Stop and reassess.** Don't generate more hypotheses in a loop.
+2. Present what you've ruled out.
+3. Ask for additional context.
+4. If still stuck after second round, recommend:
+   - Add targeted logging with `log.debug()` from `@stacksjs/logging`
+   - Write a minimal reproduction case
+   - Run `buddy doctor` for system diagnostics
+
+**Never apply a fix just to "see if it helps."**
+
+## Phase 4: Implementation
+
+Only enter when a hypothesis is confirmed.
+
+1. **Explain the root cause** in plain language
+2. **Show the minimal fix** — change as little as possible
+3. **Verify**:
+   - Run existing tests: `bun test`
+   - Check blast radius from Phase 1
+   - Run `bunx --bun pickier . --fix` for formatting
+4. **Suggest a regression test**
+
+```
+## Root Cause
+[Clear explanation]
+
+## Fix
+[Minimal code change with file:line references]
+
+## Verification
+- [x] Existing tests pass (`bun test`)
+- [x] Blast radius checked
+- [ ] Regression test: [suggested test]
+```
+
+## Rules
+
+- **No fixes without root cause.** If you can't explain WHY, you haven't found the bug.
+- **Read before you grep.** Understand architecture first.
+- **Don't blame the framework first.** Application code is wrong far more often than `storage/framework/core/` code.
+- **Intermittent bugs are timing bugs** until proven otherwise. Look for race conditions, missing `await`, shared mutable state.
+- **If the fix is more than ~20 lines, question the root cause.** Large fixes often mean you're working around the problem.
+
+## Downstream
+
+> **Fix applied.** Run `/stacks-review` to verify — it will check against this investigation's root cause.

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

@@ -0,0 +1,136 @@
+---
+name: stacks-jobs
+description: Use when creating background job classes in app/Jobs/ — job structure, the handle method, job configuration (queue, tries, backoff, timeout, rate), dispatching patterns (dispatch, dispatchIf, dispatchAfter, dispatchNow), or the Every schedule constants. For the queue system internals (workers, batching, events, drivers, testing), see stacks-queue.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Jobs
+
+Background job classes defined in `app/Jobs/`.
+
+## Key Paths
+- Application jobs: `app/Jobs/`
+- Queue config: `config/queue.ts`
+
+## Creating a Job
+
+```typescript
+// app/Jobs/SendWelcomeEmail.ts
+import { Job } from '@stacksjs/queue'
+
+export default new Job({
+  name: 'SendWelcomeEmail',
+  description: 'Send welcome email to new user',
+  queue: 'emails',       // queue name (default: 'default')
+  tries: 3,              // max attempts
+  backoff: 10,           // seconds between retries
+  timeout: 30,           // max execution time (seconds)
+  enabled: true,         // can be disabled
+
+  async handle(payload: { email: string; name: string }) {
+    console.log(`Sending to ${payload.email}`)
+    // Do work here
+    return { sent: true }
+  }
+})
+```
+
+## Job Configuration Options
+
+```typescript
+{
+  name: string               // job identifier
+  description?: string       // human-readable description
+  queue?: string             // queue name (default: 'default')
+  tries?: number             // max retry attempts
+  backoff?: number           // seconds between retries
+  backoffConfig?: {          // advanced backoff
+    strategy: 'fixed' | 'exponential' | 'linear'
+    initialDelay: number
+    factor: number
+    maxDelay: number
+    jitter?: { enabled: boolean, factor: number }
+  }
+  timeout?: number           // max seconds per attempt
+  rate?: string              // cron schedule (e.g., Every.Hour)
+  enabled?: boolean          // enable/disable job
+  handle: (payload?) => any  // job logic
+}
+```
+
+## Dispatching Jobs
+
+```typescript
+// Simple dispatch
+await SendWelcomeEmail.dispatch({ email: 'user@example.com', name: 'John' })
+
+// Conditional dispatch
+await SendWelcomeEmail.dispatchIf(isNewUser, { email, name })
+await SendWelcomeEmail.dispatchUnless(isExistingUser, { email, name })
+
+// Delayed dispatch (60 second delay)
+await SendWelcomeEmail.dispatchAfter(60, { email, name })
+
+// Immediate execution (bypasses queue)
+await SendWelcomeEmail.dispatchNow({ email, name })
+```
+
+## Fluent Job Builder
+
+```typescript
+import { job } from '@stacksjs/queue'
+
+await job('SendWelcomeEmail', { email, name })
+  .onQueue('emails')
+  .delay(60)
+  .tries(5)
+  .timeout(30)
+  .backoff([10, 30, 60])
+  .dispatch()
+```
+
+## Scheduled Jobs
+
+Use the `rate` property for automatic scheduling:
+
+```typescript
+import { Every } from '@stacksjs/enums'
+
+export default new Job({
+  name: 'CleanupExpiredTokens',
+  rate: Every.Hour,          // runs every hour
+  // rate: Every.Day,        // runs daily
+  // rate: '*/5 * * * *',   // custom cron: every 5 minutes
+
+  handle() {
+    // cleanup logic
+  }
+})
+```
+
+Register in `app/Scheduler.ts`:
+```typescript
+import { schedule } from '@stacksjs/scheduler'
+
+export default function() {
+  schedule.job('CleanupExpiredTokens').hourly().setTimeZone('America/New_York')
+}
+```
+
+## CLI Commands
+```bash
+buddy make:job [name]       # scaffold a new job
+buddy queue                  # queue management
+```
+
+## Gotchas
+- Jobs must export `default new Job({...})` — not a plain object
+- The `handle()` method receives the payload passed to `dispatch()`
+- `dispatchNow()` runs immediately in the current process — no queue involved
+- Default queue driver is `sync` — jobs run immediately unless changed to `database` or `redis`
+- Jobs with `rate` are auto-discovered by the scheduler
+- Backoff array `[10, 30, 60]` means: retry after 10s, then 30s, then 60s
+- Jobs should be idempotent — safe to retry on failure
+- For queue workers, batching, events, and testing, see the `stacks-queue` skill

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

@@ -0,0 +1,184 @@
+---
+name: stacks-lint
+description: Use when linting or formatting code in a Stacks project. CRITICAL - always use pickier, NEVER eslint directly. Run 'bunx --bun pickier .' to lint, 'bunx --bun pickier . --fix' to auto-fix. For unused variables, prefer eslint-disable-next-line comments over underscore prefix. Covers @stacksjs/lint and config/code-style.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Linting
+
+## CRITICAL RULES
+1. **ALWAYS** use `bunx --bun pickier .` to lint -- **NEVER** use `eslint` directly
+2. **Auto-fix**: `bunx --bun pickier . --fix`
+3. For unused variable warnings: prefer `// eslint-disable-next-line` comments over prefixing with `_`
+
+## Key Paths
+- Lint package: `storage/framework/core/lint/` (package: `@stacksjs/lint`)
+- Configuration: `config/code-style.ts` (auto-loaded via pickier's bunfig alias `code-style`; pickier handles both linting and formatting)
+- Lint command source: `storage/framework/core/buddy/src/commands/lint.ts`
+
+## Package Details
+- Package name: `@stacksjs/lint`
+- Version: tracks framework version (currently 0.70.23)
+- The lint package is a thin wrapper -- the actual linting is done by pickier
+- `storage/framework/core/lint/build.ts` is a no-op (nothing to build)
+- Dev dependencies: `better-dx`, `@stacksjs/gitlint`, `bun-git-hooks`
+
+## Commands
+
+### Via buddy CLI
+The buddy `lint` command internally runs pickier with the project's pickier config:
+
+```bash
+# Lint (runs: bunx --bun pickier run --mode lint --config ./pickier.config.ts)
+buddy lint
+
+# Auto-fix (runs: bunx --bun pickier run --mode lint --config ./pickier.config.ts --fix)
+buddy lint --fix
+buddy lint:fix
+
+# Format (runs: bunx --bun pickier run --mode format --config ./pickier.config.ts --write)
+buddy format
+buddy format --write        # same as above (write is default)
+
+# Check formatting without changes
+buddy format --check        # runs: pickier run --mode format --config ./pickier.config.ts --check
+buddy format:check
+```
+
+### Direct pickier usage
+```bash
+# Lint entire project
+bunx --bun pickier .
+
+# Auto-fix
+bunx --bun pickier . --fix
+
+# Via npm scripts
+bun run lint
+bun run lint:fix
+bun run format
+bun run format:check
+```
+
+## config/code-style.ts (PickierOptions)
+
+The actual configuration used by the project. This is the source of truth for all lint settings:
+
+```typescript
+import type { PickierOptions } from 'pickier'
+
+const config: PickierOptions = {
+  format: {
+    extensions: ['ts', 'js', 'stx', 'json', 'yaml', 'md'],
+    indent: 2,
+    quotes: 'single',
+    semi: false,
+  },
+
+  rules: {
+    // TypeScript rules
+    noDebugger: 'off',
+    noConsole: 'off',
+  },
+
+  pluginRules: {
+    // Regexp rules disabled (false positives on route definitions)
+    'regexp/no-unused-capturing-group': 'off',
+    'regexp/no-super-linear-backtracking': 'off',
+    'regexp/optimal-quantifier-concatenation': 'off',
+    // Style rules disabled (conflict with common patterns or generated code)
+    'style/brace-style': 'off',
+    'style/max-statements-per-line': 'off',
+    'style/quotes': 'off',
+    'indent': 'off',
+    'quotes': 'off',
+    // TypeScript rules
+    'ts/no-top-level-await': 'off',
+    // Console is intentional
+    'no-console': 'off',
+    // Markdown rules
+    'markdown/heading-increment': 'off',
+    'markdown/no-empty-links': 'off',
+  },
+
+  ignores: [
+    '**/fixtures/**',
+    '**/coverage/**',
+    '**/temp/**',
+  ],
+}
+
+export default config
+```
+
+## Format Settings (enforced)
+- **Indent**: 2 spaces
+- **Quotes**: single quotes
+- **Semicolons**: none (no semicolons)
+- **Extensions**: ts, js, stx, json, yaml, md
+
+## Handling Unused Variables
+
+When pickier/eslint reports unused variables, use eslint-disable comments -- do NOT prefix with underscore:
+
+```typescript
+// CORRECT: Use eslint-disable comment
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const unusedVar = someFunction()
+
+// ALSO CORRECT: Use eslint-disable for next line only
+// eslint-disable-next-line no-unused-vars
+function handler(req, res, next) {
+  res.send('ok')
+}
+
+// INCORRECT: Don't prefix with underscore
+const _unusedVar = someFunction()  // DON'T DO THIS
+```
+
+## Internal Implementation
+
+The buddy `lint` command (in `storage/framework/core/buddy/src/commands/lint.ts`) delegates entirely to pickier:
+
+```typescript
+// lint.ts internals
+buddy
+  .command('lint', 'Automagically lints your project codebase')
+  .option('-f, --fix', 'Automagically fixes all lint errors', { default: false })
+  .action(async (options: LintOptions) => {
+    if (options.fix)
+      await runCommand('bunx --bun pickier run --mode lint --config ./pickier.config.ts --fix', { cwd: path.projectPath() })
+    else
+      await runCommand('bunx --bun pickier run --mode lint --config ./pickier.config.ts', { cwd: path.projectPath() })
+  })
+```
+
+The `format` command uses pickier in format mode:
+
+```typescript
+buddy
+  .command('format', 'Format your project codebase')
+  .option('-w, --write', 'Write changes to files', { default: false })
+  .option('-c, --check', 'Check formatting without making changes', { default: false })
+  .action(async (options) => {
+    if (options.check)
+      await runCommand('bunx --bun pickier run --mode format --config ./pickier.config.ts --check', { cwd: path.projectPath() })
+    else
+      await runCommand('bunx --bun pickier run --mode format --config ./pickier.config.ts --write', { cwd: path.projectPath() })
+  })
+```
+
+## Gotchas
+- Pickier is the Stacks linting tool -- it wraps eslint with Stacks-specific config
+- **NEVER** run `eslint` directly -- always go through `bunx --bun pickier` or `buddy lint`
+- The `config/code-style.ts` file exports a `PickierOptions` object -- not an eslint config (auto-discovered by pickier via bunfig alias `code-style`)
+- The project intentionally allows `console.*` calls (`noConsole: 'off'`, `'no-console': 'off'`)
+- The project intentionally allows `debugger` statements (`noDebugger: 'off'`)
+- Top-level await is allowed (`'ts/no-top-level-await': 'off'`)
+- Brace style and max-statements-per-line rules are disabled to avoid conflicts with generated code
+- Run `bunx --bun pickier . --fix` after code generation to clean up
+- `buddy lint` exits through the `lint:*` wildcard handler if an invalid sub-command is used
+- `buddy format` defaults to `--write` mode (writes changes) unless `--check` is specified
+- The lint package (`@stacksjs/lint`) itself has no source files to build -- it is a configuration-only package

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

@@ -0,0 +1,99 @@
+---
+name: stacks-listeners
+description: Use when creating event listeners in app/Listeners/ — the listener file structure, registering listeners in app/Events.ts, the listener-to-action mapping pattern, CLI event listeners in Console.ts, or debugging listener execution. For the event system API (dispatch, listen, emitter, model events), see stacks-events.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Event Listeners
+
+Application-level event listeners in `app/Listeners/`.
+
+## Key Paths
+- Listeners: `app/Listeners/`
+- Event mapping: `app/Events.ts`
+- Listener setup: `app/Listener.ts`
+
+## Event → Listener Mapping (app/Events.ts)
+
+```typescript
+export default {
+  'user:registered': ['SendWelcomeEmail'],    // triggers app/Actions/SendWelcomeEmail.ts
+  'user:created': ['NotifyUser'],             // triggers app/Actions/NotifyUser.ts
+  'order:created': ['ProcessPayment', 'SendOrderConfirmation'],  // multiple listeners
+} satisfies Events
+```
+
+Keys are event names. Values are arrays of Action names from `app/Actions/`.
+
+## How Listeners Work
+
+1. Events are dispatched: `dispatch('user:registered', { id: 1 })`
+2. The wildcard handler in `app/Listener.ts` catches ALL events
+3. Checks if the event has registered listeners in `app/Events.ts`
+4. For each listener, dynamically imports `app/Actions/{listener}.ts`
+5. Calls `action.handle(eventData)`
+6. Action modules are cached after first import
+
+## Creating a Listener Action
+
+```typescript
+// app/Actions/SendWelcomeEmail.ts
+export default {
+  name: 'SendWelcomeEmail',
+
+  async handle(event: { id: number; email: string; name: string }) {
+    // event contains the data passed to dispatch()
+    await sendWelcomeEmail({ to: event.email, name: event.name })
+    return { success: true }
+  }
+}
+```
+
+## CLI Event Listeners (app/Listeners/Console.ts)
+
+For CLI-specific events (not HTTP):
+
+```typescript
+export default function(cli: CLI) {
+  // Specific command
+  cli.on('inspire:three', () => {
+    console.log(getThreeQuotes())
+  })
+
+  // Default handler (unknown commands)
+  cli.on('inspire:!', () => {
+    console.log('Unknown inspire command')
+  })
+
+  // Wildcard (matches inspire:anything)
+  cli.on('inspire:*', () => {
+    console.log('Some inspire variant')
+  })
+}
+```
+
+## Multiple Listeners Per Event
+
+```typescript
+// app/Events.ts
+{
+  'order:created': [
+    'ProcessPayment',          // runs first
+    'SendOrderConfirmation',   // runs second
+    'UpdateInventory',         // runs third
+    'NotifyWarehouse'          // runs fourth
+  ]
+}
+```
+
+Listeners execute sequentially (not in parallel) — each awaits completion.
+
+## Gotchas
+- Listeners are Action names, not file paths — `'SendWelcomeEmail'` resolves to `app/Actions/SendWelcomeEmail.ts`
+- The action must have a `handle(event)` method
+- Listeners run sequentially per event — order in the array matters
+- Action modules are cached after first load — no hot-reload for listeners
+- CLI listeners are separate from HTTP event listeners
+- For the event API (dispatch, listen, emitter), see the `stacks-events` skill

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

@@ -0,0 +1,78 @@
+---
+name: stacks-logging
+description: Use when implementing logging in Stacks — the log facade (info, error, warn, debug, success), dump/dd debugging, timing functions, file-based logging, or log configuration. Covers @stacksjs/logging and config/logging.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Logging
+
+Uses @stacksjs/clarity Logger with file writing to `storage/logs/stacks.log`.
+
+## Key Paths
+- Core package: `storage/framework/core/logging/src/`
+- Configuration: `config/logging.ts`
+- Log model: `storage/framework/defaults/app/Models/Log.ts`
+- Log file: `storage/logs/stacks.log`
+
+## Log Facade
+
+```typescript
+import { log } from '@stacksjs/logging'
+
+await log.info('User created', { userId: 1 })
+await log.success('Deployment complete')
+await log.warn('Rate limit approaching', { remaining: 10 })
+await log.warning('Alias for warn')
+await log.error(new Error('Something failed'), { context: 'handler' })
+await log.debug('Debug info', { query: 'SELECT ...' })
+```
+
+### Error with Exit
+```typescript
+await log.error(err, { shouldExit: true })  // logs and exits process
+```
+
+## Dump & Die
+
+```typescript
+import { dump, dd, echo } from '@stacksjs/logging'
+
+await dump(variable1, variable2)    // inspect without stopping
+await dd(variable1, variable2)      // inspect and exit (never returns)
+await echo('simple output')
+```
+
+## Timing
+
+```typescript
+const done = log.time('database-query')
+await performQuery()
+await done()  // logs elapsed time
+```
+
+## Logger Instance
+
+```typescript
+import { logger } from '@stacksjs/logging'
+
+const l = logger  // underlying clarity Logger instance
+```
+
+## config/logging.ts
+```typescript
+{
+  logsPath: 'storage/logs',
+  deploymentsPath: 'storage/logs/deployments'
+}
+```
+
+## Gotchas
+- All log methods are async — they write to both console and file
+- Log file is at `storage/logs/stacks.log`
+- `dd()` never returns — it exits the process after dumping
+- `dump()` continues execution — use for non-destructive debugging
+- The Log model enables database-backed log storage and querying
+- Error logging can optionally exit the process with `shouldExit: true`
+- Logging is a dependency of many other packages — it's available everywhere