@stacksjs/defaults 0.70.207 → 0.70.208

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

@@ -0,0 +1,149 @@
+---
+name: stacks-plugins
+description: Use when working with the Stacks preload chain and Bun plugins — the env plugin, the framework preloader, how auto-imports get injected into globalThis, why a command does or does not see framework globals, the bun-plugin-stx static-serve plugin, or writing a Bun plugin. Covers bunfig.toml preload and storage/framework/defaults/resources/plugins/preloader.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Plugins and the Preload Chain
+
+Stacks has **no `@stacksjs/plugins` package**. "Plugins" here means Bun's native
+plugin API plus the two modules `bunfig.toml` preloads before any Stacks code
+runs. If you are chasing "why is `User` undefined in this command" or "why did
+`.env` not decrypt", this is the skill.
+
+## Key Paths
+
+- Preload declaration: `bunfig.toml` (`preload`, at the root and under `[test]`)
+- Env plugin: `storage/framework/core/env/plugin.ts`
+- Framework preloader: `storage/framework/defaults/resources/plugins/preloader.ts`
+- Static-serve plugin: `bunfig.toml`, `[serve.static] plugins = ["bun-plugin-stx"]`
+
+## The preload chain
+
+`bunfig.toml` preloads two modules, **in this order**:
+
+```toml
+preload = [
+  "./storage/framework/core/env/plugin.ts",
+  "./storage/framework/defaults/resources/plugins/preloader.ts",
+]
+```
+
+1. **Env plugin** loads `.env` and decrypts dotenvx-style encrypted values, so
+   everything downstream reads plaintext from `process.env`.
+2. **Preloader** loads env files for the resolved environment, then injects the
+   framework's server auto-imports into `globalThis`.
+
+Order is load-bearing: the preloader reads decrypted secrets, so it has to run
+second.
+
+Tests preload a different pair - the env plugin and `tests/setup.ts` - so the
+suite gets production env semantics without the auto-import graph.
+
+## What the preloader does
+
+### 1. Resolves the environment
+
+Before loading any `.env` file it works out `APP_ENV`, because that decides
+*which* file gets decrypted:
+
+- `deploy staging` and `deploy --staging` both resolve to `staging`. Both forms
+  are handled; CI uses the flag form.
+- `cloud:remove`, `cloud:destroy`, `cloud:cleanup`, `undeploy` force `production`.
+- Bare `deploy` defaults to `production`.
+
+### 2. Loads and decrypts env files
+
+Gated on **`isRepl` / `isPostinstall` only** - never on the fast-command list
+below. Fast commands (`migrate`, `build`, `seed`, ...) genuinely need decrypted
+config; gating them here caused stacksjs/stacks#2048, where an encrypted
+`.env.<env>` silently never decrypted even with the key present.
+
+Postinstall skips because `@stacksjs/env` may not be linked yet mid-install.
+
+### 3. Injects auto-imports into `globalThis`
+
+Loads ~24 framework packages plus everything in `app/Jobs/` and
+`resources/functions/`, assigning every named export onto `globalThis`. That is
+why `await User.find(1)` and `response.json(...)` work in an action with no
+import statement. See `stacks-auto-imports` for the full manifest.
+
+A `protectedGlobals` set guards the runtime: `process`, `fetch`, `Promise`,
+`Bun`, `console` and friends are never overwritten, whatever a package exports.
+
+## The fast-command skip (the usual gotcha)
+
+Auto-import injection is **skipped** when the first CLI argument matches:
+
+```
+dev  build  test  lint  migrate  fresh  seed  generate  make
+key:generate  scaffold:crud  version  help  --version  -v  --help  -h
+```
+
+Prefix matches count, so `generate:migrations` skips along with `generate`.
+
+Two reasons: cold-start speed, and correctness. Codegen commands must not pull
+the router and ORM graph in before `bun-query-builder` can diff schemas - a
+broken `@stacksjs/bun-router` install used to make `generate:migrations` exit 1
+with no output at all, because the preloader died loading `@stacksjs/router`.
+
+**Consequence:** inside those commands, framework globals do not exist. Import
+what you need explicitly.
+
+The REPL skips too (`!process.argv[1]`), as does anything running under
+`npm_lifecycle_event === 'postinstall'`.
+
+### Opting back in
+
+The preloader exports `loadAutoImports()` so a server entrypoint can pull the
+graph in deliberately:
+
+```ts
+const { loadAutoImports } = await import('../../../defaults/resources/plugins/preloader.ts')
+await loadAutoImports()
+```
+
+`dev/api.ts` does exactly this. Bun consumes `--watch`, so a directly-run server
+script sees an empty `argv.slice(2)` and would otherwise be indistinguishable
+from a bare invocation.
+
+## Writing a Bun plugin
+
+Use Bun's native API directly - there is no framework wrapper to import:
+
+```ts
+import { plugin } from 'bun'
+
+plugin({
+  name: 'my-loader',
+  setup(build) {
+    build.onLoad({ filter: /\.custom$/ }, async (args) => {
+      const contents = await Bun.file(args.path).text()
+      return { contents: transform(contents), loader: 'ts' }
+    })
+  },
+})
+```
+
+Register it by adding the module to `preload` in `bunfig.toml`. A plugin only
+affects the process that preloaded it.
+
+## Gotchas
+
+- **No `@stacksjs/plugins` package.** Import `plugin` from `bun`.
+- **Preload order matters.** Env decryption has to precede the preloader.
+- **Fast commands have no globals.** If a `make:*` or `generate:*` command needs
+  a framework symbol, import it - do not rely on auto-imports.
+- **`bun-plugin-stx` is a static-serve plugin**, wired through
+  `[serve.static] plugins` in `bunfig.toml`. The preloader's own
+  `import 'bun-plugin-stx'` line is commented out; stx compilation in the dev
+  server runs through the stx package, not that import.
+- **Preloader failures are silent per package.** Each import sits in its own
+  `try {} catch {}`, so a package that fails to build leaves its globals
+  undefined instead of crashing the process. A mysteriously undefined global is
+  usually an unbuilt package - check `storage/framework/core/<pkg>/dist`.
+- **Adding a global?** Export it from a package already in the preloader's list,
+  or from `resources/functions/`, then run `buddy generate --types` so the
+  declarations match the runtime.

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

@@ -0,0 +1,376 @@
+---
+name: stacks-push
+description: Use when implementing push notifications in Stacks — sending via Expo Push Service or Firebase Cloud Messaging (FCM legacy and v1 APIs), configuring push drivers, batch sending, multicast, topic subscriptions, push notification payloads, token validation, or receipt checking. Covers @stacksjs/push.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Push Notifications
+
+Push notification support with Expo Push Service and FCM (Firebase Cloud Messaging) drivers. FCM supports both the legacy server key API and the v1 service account API.
+
+## Key Paths
+- Core package: `storage/framework/core/push/src/`
+- Types: `storage/framework/core/types/src/push.ts`
+
+## Source Files
+```
+push/src/
+├── index.ts              # send(), configureFCM(), PushNotification type
+└── drivers/
+    ├── index.ts          # re-exports expo and fcm
+    ├── expo.ts           # Expo Push Service driver
+    └── fcm.ts            # FCM legacy + v1 API driver
+```
+
+## Main send() Function
+
+```typescript
+async function send(
+  to: string | string[],
+  notification: PushNotification,
+  options?: SendOptions,
+): Promise<PushResult>
+```
+
+Routes to the appropriate driver based on `options.driver` (default: `'expo'`).
+
+- For **Expo**: Passes the notification directly to `expo.send()` with all fields mapped.
+- For **FCM** with single token: Calls `fcm.send()` with notification mapped to `{ to, notification: { title, body }, data, priority }`.
+- For **FCM** with multiple tokens: Calls `fcm.sendMulticast()` and returns an aggregated result with success count.
+- FCM priority mapping: `'default'` is converted to `'normal'`; `'high'` and `'normal'` pass through.
+
+## PushNotification Interface (index.ts)
+
+```typescript
+interface PushNotification {
+  title?: string
+  body: string                           // required
+  data?: Record<string, any>
+  badge?: number
+  sound?: 'default' | null
+  priority?: 'high' | 'normal' | 'default'
+}
+```
+
+## PushResult Interface (from @stacksjs/types)
+
+```typescript
+interface PushResult {
+  success: boolean
+  provider: string          // 'expo' | 'fcm'
+  message: string
+  messageId?: string
+  data?: Record<string, any>
+}
+```
+
+## Types
+
+```typescript
+type PushDriver = 'expo' | 'fcm'
+
+interface SendOptions {
+  driver?: PushDriver       // default: 'expo'
+}
+```
+
+## Expo Push Driver (expo.ts)
+
+### ExpoPushMessage
+```typescript
+interface ExpoPushMessage {
+  to: string | string[]
+  title?: string
+  body: string
+  data?: Record<string, any>
+  sound?: 'default' | null
+  badge?: number
+  channelId?: string         // Android notification channel
+  priority?: 'default' | 'normal' | 'high'
+  ttl?: number               // time-to-live in seconds
+}
+```
+
+### ExpoPushTicket
+```typescript
+interface ExpoPushTicket {
+  id?: string
+  status: 'ok' | 'error'
+  message?: string
+  details?: {
+    error?: 'DeviceNotRegistered' | 'MessageTooBig' | 'MessageRateExceeded' | 'InvalidCredentials'
+  }
+}
+```
+
+### ExpoPushReceipt
+```typescript
+interface ExpoPushReceipt {
+  status: 'ok' | 'error'
+  message?: string
+  details?: { error?: string }
+}
+```
+
+### Functions
+
+#### send()
+```typescript
+async function send(message: ExpoPushMessage): Promise<PushResult>
+```
+
+- Endpoint: `https://exp.host/--/api/v2/push/send`
+- Validates tokens with `isExpoPushToken()` before sending
+- Filters out invalid tokens and warns via `log.warn()`
+- Returns early with failure if no valid tokens remain
+- Creates one payload entry per token (fans out `to` array into individual messages)
+- Default `sound: 'default'`, default `priority: 'high'`
+- Returns `PushResult` with `data: { tickets }` containing the full ticket array
+- `success` is `true` only if zero tickets have `status: 'error'`
+- `messageId` is the first ticket's `id` (if any)
+
+#### isExpoPushToken()
+```typescript
+function isExpoPushToken(token: string): boolean
+```
+Validates token format: matches `Expo(nent)?PushToken[...]` pattern OR alphanumeric with hyphens/underscores.
+
+#### getReceipts()
+```typescript
+async function getReceipts(ticketIds: string[]): Promise<Record<string, ExpoPushReceipt>>
+```
+Endpoint: `https://exp.host/--/api/v2/push/getReceipts`. Checks delivery status for previously sent notifications.
+
+#### sendBatch()
+```typescript
+async function sendBatch(messages: ExpoPushMessage[], chunkSize?: number): Promise<PushResult[]>
+```
+Sends multiple messages in chunks (default chunk size: 100, per Expo's recommendation). Processes chunks sequentially, messages within each chunk in parallel via `Promise.all`.
+
+### Exports
+- `send`, `sendBatch`, `getReceipts`, `isExpoPushToken` functions
+- `Send` alias for `send`
+
+## FCM Driver (fcm.ts)
+
+Supports two APIs:
+1. **Legacy API** (`https://fcm.googleapis.com/fcm/send`) -- uses server key
+2. **v1 API** (`https://fcm.googleapis.com/v1/projects/{projectId}/messages:send`) -- uses service account with OAuth2 JWT
+
+### FCMConfig
+```typescript
+interface FCMConfig {
+  serverKey?: string                    // for legacy API
+  projectId?: string                    // for v1 API
+  serviceAccount?: {
+    clientEmail: string
+    privateKey: string                  // PEM format
+  }
+}
+```
+
+### FCMMessage
+```typescript
+interface FCMMessage {
+  to?: string                           // single device token
+  registrationIds?: string[]            // multiple device tokens (legacy only)
+  topic?: string                        // topic name (auto-prefixed with /topics/)
+  condition?: string                    // topic condition expression
+  notification?: {
+    title: string
+    body: string
+    icon?: string
+    image?: string
+    sound?: string
+    badge?: string
+    clickAction?: string
+    tag?: string
+  }
+  data?: Record<string, string>         // NOTE: values must be strings for FCM
+  priority?: 'high' | 'normal'
+  ttl?: number
+  collapseKey?: string
+}
+```
+
+### FCMResponse (legacy API)
+```typescript
+interface FCMResponse {
+  multicastId?: number
+  success: number
+  failure: number
+  results?: Array<{
+    messageId?: string
+    error?: string
+  }>
+}
+```
+
+### Functions
+
+#### configure()
+```typescript
+function configure(options: FCMConfig): void
+```
+Sets module-level config. Called by `configureFCM()` from the main index.
+
+#### send()
+```typescript
+async function send(message: FCMMessage): Promise<PushResult>
+```
+If `serviceAccount` and `projectId` are configured, uses the v1 API. Otherwise falls back to `sendLegacy()`.
+
+**v1 API flow:**
+1. Generates JWT with RS256 signing using the service account private key
+2. Exchanges JWT for OAuth2 access token at `https://oauth2.googleapis.com/token`
+3. Sends to `https://fcm.googleapis.com/v1/projects/{projectId}/messages:send`
+4. Includes Android priority settings and APNS headers (`apns-priority: 10` for high, `5` for normal)
+5. Supports `to` (token), `topic`, or `condition` targeting
+
+**JWT generation details:**
+- Scope: `https://www.googleapis.com/auth/firebase.messaging`
+- Algorithm: RS256 (RSASSA-PKCS1-v1_5 with SHA-256)
+- Expiry: 1 hour
+- Key imported via `crypto.subtle.importKey('pkcs8', ...)`
+
+#### sendLegacy()
+```typescript
+async function sendLegacy(message: FCMMessage): Promise<PushResult>
+```
+Uses the legacy API with `Authorization: key=<serverKey>`. Supports:
+- Single device via `to`
+- Multiple devices via `registration_ids`
+- Topics via `/topics/<topic>`
+- Conditions via `condition`
+
+#### sendMulticast()
+```typescript
+async function sendMulticast(
+  tokens: string[],
+  message: Omit<FCMMessage, 'to' | 'registrationIds'>,
+): Promise<PushResult[]>
+```
+- v1 API: sends individually to each token via `Promise.all` (v1 doesn't support multicast natively)
+- Legacy API: uses `registrationIds` field for native multicast in a single request
+
+#### sendToTopic()
+```typescript
+async function sendToTopic(
+  topic: string,
+  message: Omit<FCMMessage, 'to' | 'registrationIds' | 'topic'>,
+): Promise<PushResult>
+```
+Convenience wrapper that sets the `topic` field and calls `send()`.
+
+#### subscribeToTopic()
+```typescript
+async function subscribeToTopic(tokens: string[], topic: string): Promise<boolean>
+```
+Uses `https://iid.googleapis.com/iid/v1:batchAdd` with legacy server key auth. Subscribes device tokens to a topic.
+
+#### unsubscribeFromTopic()
+```typescript
+async function unsubscribeFromTopic(tokens: string[], topic: string): Promise<boolean>
+```
+Uses `https://iid.googleapis.com/iid/v1:batchRemove` with legacy server key auth.
+
+### Exports
+- `send`, `sendLegacy`, `sendMulticast`, `sendToTopic`, `subscribeToTopic`, `unsubscribeFromTopic`, `configure` functions
+- `Send` alias for `send`
+
+## Configuration
+
+```typescript
+import { configureFCM } from '@stacksjs/push'
+
+// FCM v1 API (recommended)
+configureFCM({
+  projectId: 'my-firebase-project',
+  serviceAccount: {
+    clientEmail: 'firebase@project.iam.gserviceaccount.com',
+    privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----'
+  }
+})
+
+// FCM Legacy API (simpler setup)
+configureFCM({
+  serverKey: 'your-fcm-server-key'
+})
+
+// Expo requires no configuration
+```
+
+## Usage Examples
+
+```typescript
+import { send } from '@stacksjs/push'
+
+// Expo (default driver)
+await send('ExponentPushToken[xxxxxx]', {
+  title: 'New Order',
+  body: 'You have a new order #1234',
+  data: { orderId: 1234 },
+  badge: 1,
+  sound: 'default',
+  priority: 'high',
+})
+
+// Multiple Expo tokens
+await send(
+  ['ExponentPushToken[aaa]', 'ExponentPushToken[bbb]'],
+  { title: 'Announcement', body: 'Maintenance at 3pm' },
+)
+
+// FCM single device
+await send('fcm-device-token', notification, { driver: 'fcm' })
+
+// FCM multiple devices
+await send(
+  ['token1', 'token2', 'token3'],
+  { title: 'Alert', body: 'New message' },
+  { driver: 'fcm' },
+)
+```
+
+### Direct driver access
+```typescript
+import { expo, fcm } from '@stacksjs/push'
+
+// Expo batch
+await expo.sendBatch(messages, 100)
+
+// Expo receipt check
+const receipts = await expo.getReceipts(['ticket-id-1', 'ticket-id-2'])
+
+// FCM topic
+await fcm.sendToTopic('news', { notification: { title: 'Breaking', body: '...' } })
+
+// FCM topic subscription
+await fcm.subscribeToTopic(['token1', 'token2'], 'news')
+await fcm.unsubscribeFromTopic(['token1'], 'news')
+```
+
+## Dependencies
+- `@stacksjs/types` -- `PushResult`, `PushMessage`, `PushTicket`
+- `@stacksjs/cli` -- `log` for info/warn/error logging
+- Web Crypto API -- used by FCM for JWT signing (`crypto.subtle`)
+
+## Gotchas
+- Default driver is `'expo'`, not FCM
+- Expo token validation accepts both `ExponentPushToken[...]` format and plain alphanumeric strings
+- Expo `send()` fans out array tokens into individual payload entries (one per token)
+- Expo default `sound` is `'default'` and default `priority` is `'high'` (set in the driver, not the main send)
+- FCM `data` values must be `Record<string, string>` (strings only, not arbitrary JSON)
+- FCM `send()` auto-falls back to legacy API if no `serviceAccount`/`projectId` configured
+- FCM v1 API does not support native multicast -- `sendMulticast()` sends individually via `Promise.all`
+- FCM legacy API supports multicast via `registrationIds` in a single request
+- FCM topic names are auto-prefixed with `/topics/` in the legacy API
+- `subscribeToTopic()` and `unsubscribeFromTopic()` require the legacy `serverKey` (not service account)
+- The main `send()` converts `priority: 'default'` to `'normal'` for FCM
+- Expo `sendBatch()` processes chunks sequentially but messages within each chunk in parallel
+- FCM v1 JWT tokens expire after 1 hour -- a new token is generated for each `send()` call (no caching)
+- FCM v1 includes both Android and APNS-specific priority headers automatically
+- `badge` only works on iOS -- Android uses notification channels (set via `channelId` on Expo)
+- `sound: null` sends a silent notification

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

@@ -0,0 +1,128 @@
+---
+name: stacks-query-builder
+description: Use when building database queries in a Stacks application — constructing SQL queries, using the fluent query API, or configuring the query builder. Covers @stacksjs/query-builder which wraps bun-query-builder, and config/query-builder.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Query Builder
+
+## Key Paths
+- Core package: `storage/framework/core/query-builder/src/`
+- Configuration: `config/query-builder.ts`
+- QB state: `.qb/`
+- External library: `bun-query-builder`
+- Package: `@stacksjs/query-builder`
+
+## API
+
+The package re-exports everything from `bun-query-builder` plus a compatibility alias:
+
+```typescript
+export * from 'bun-query-builder'
+export { createQueryBuilder as QueryBuilder } from 'bun-query-builder'
+```
+
+## Usage
+
+```typescript
+import { db } from '@stacksjs/database'
+
+// Select
+const users = await db.selectFrom('users')
+  .where('active', '=', true)
+  .orderBy('name', 'asc')
+  .limit(10)
+  .get()
+
+// Insert
+await db.insertInto('users')
+  .values({ name: 'Alice', email: 'alice@example.com' })
+  .execute()
+
+// Update
+await db.update('users')
+  .set({ active: false })
+  .where('id', '=', 1)
+  .execute()
+
+// Delete
+await db.deleteFrom('users')
+  .where('id', '=', 1)
+  .execute()
+
+// Joins
+const posts = await db.selectFrom('posts')
+  .join('users', 'posts.user_id', '=', 'users.id')
+  .select(['posts.*', 'users.name as author_name'])
+  .get()
+
+// Aggregates
+const count = await db.selectFrom('users').count()
+const total = await db.selectFrom('orders').sum('amount')
+```
+
+## Configuration (config/query-builder.ts)
+
+```typescript
+{
+  verbose: true,
+  dialect: env.DB_CONNECTION || 'sqlite',
+  database: { database, username?, password?, host?, port? },
+
+  timestamps: {
+    createdAt: 'created_at',
+    updatedAt: 'updated_at',
+    defaultOrderColumn: 'created_at',
+  },
+
+  pagination: {
+    defaultPerPage: 25,
+    cursorColumn: 'id',
+  },
+
+  aliasing: {
+    relationColumnAliasFormat: 'table_column',
+  },
+
+  relations: {
+    foreignKeyFormat: 'singularParent_id',
+    maxDepth: 10,
+    maxEagerLoad: 50,
+    detectCycles: true,
+  },
+
+  transactionDefaults: {
+    retries: 2,
+    isolation: 'read committed',
+    sqlStates: ['40001', '40P01'],
+    backoff: { baseMs: 50, factor: 2, maxMs: 2000, jitter: true },
+  },
+
+  sql: {
+    randomFunction: 'RANDOM()',
+    sharedLockSyntax: 'FOR SHARE',
+    jsonContainsMode: 'operator',
+  },
+
+  features: { distinctOn: true },
+  debug: { captureText: true },
+
+  softDeletes: {
+    enabled: false,
+    column: 'deleted_at',
+    defaultFilter: true,
+  },
+}
+```
+
+## Gotchas
+- **Thin wrapper** — re-exports `bun-query-builder` with no additions
+- **One config file** — `config/query-builder.ts`. Its `dialect` and connection details are derived from `DB_CONNECTION` and the other `DB_*` env vars, so switching databases is an env change, not a config edit
+- **`.qb/` directory** — stores query builder state for migration diffing
+- **Prefer ORM models** — query builder is the low-level interface; use models for most operations
+- **`db` proxy** — the `db` export from `@stacksjs/database` is a lazy proxy that auto-initializes the query builder on first access
+- **Soft deletes disabled by default** — must be explicitly enabled in config
+- **Transaction retries** — defaults to 2 retries with exponential backoff + jitter
+- **Dialect detection** — reads `DB_CONNECTION` env var, falls back to `sqlite`