@stacksjs/defaults 0.70.206 → 0.70.208

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

@@ -0,0 +1,138 @@
+---
+name: stacks-auto-imports
+description: Use when working with the Stacks auto-import system — understanding how browser and server auto-imports work, configuring auto-imported functions/models/composables, the auto-import manifests, type generation, or how globals are injected. Covers the auto-import pipeline at storage/framework/auto-imports/.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Auto-Import System
+
+Automatically makes functions, models, composables, and utilities available globally without explicit imports.
+
+## Key Paths
+- Auto-import functions: `storage/framework/auto-imports/functions.ts`
+- Auto-import models: `storage/framework/auto-imports/models.ts`
+- Auto-import index: `storage/framework/auto-imports/index.ts`
+- Auto-import globals: `storage/framework/auto-imports/globals.ts`
+- Global type declarations: `storage/framework/auto-imports/globals.d.ts`
+- Browser manifest: `storage/framework/browser-auto-imports.json`
+- Server manifest: `storage/framework/server-auto-imports.json`
+- Browser type declarations: `storage/framework/types/browser-auto-imports.d.ts` (~80KB)
+- Server type declarations: `storage/framework/types/server-auto-imports.d.ts`
+- General auto-import types: `storage/framework/types/auto-imports.d.ts`
+
+## How Auto-Imports Work
+
+### Browser Context (STX Templates)
+1. `storage/framework/browser-auto-imports.json` defines available imports (200+ entries)
+2. Types are declared in `storage/framework/types/browser-auto-imports.d.ts`
+3. STX plugin (`bun-plugin-stx`) resolves imports at build time
+4. Available in STX `<script>` tags without explicit `import` statements
+
+### Server Context (Routes, Actions, Jobs)
+1. `storage/framework/server-auto-imports.json` defines server-side imports (100+ entries)
+2. Types are declared in `storage/framework/types/server-auto-imports.d.ts`
+3. All 60+ ORM models are auto-imported as globals
+4. Available in any server-side TypeScript file
+
+### Runtime Injection
+`storage/framework/auto-imports/globals.ts` injects functions into `globalThis`:
+```typescript
+// Makes these available globally without imports:
+globalThis.increment = increment
+globalThis.count = count
+globalThis.isDark = isDark
+globalThis.toggleDark = toggleDark
+// ... geo functions, GPX functions, etc.
+```
+
+## What Gets Auto-Imported
+
+### Browser Auto-Imports (200+)
+- **Composables**: useStorage, useLocalStorage, useFetch, useToggle, useCounter, useDark, useNow, etc.
+- **Utilities**: debounce, throttle, retry, sleep, wait, delay, lazy, clamp, rand
+- **Authentication**: useAuth, authGuard, auth
+- **Formatting**: formatCurrency, formatDate, formatNumber, formatDuration
+- **Browser Query Builder**: browserQuery, BrowserQueryBuilder, browserAuth, createBrowserModel
+- **Payment**: confirmCardPayment, confirmPayment, createPaymentMethod, loadCardElement, loadPaymentElement
+- **Stripe**: stripe instance
+- **Custom Functions**: From `resources/functions/` (counter, dark mode, GPX, geo utilities)
+
+### Server Auto-Imports (100+)
+- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (60+ models)
+- **Request Models**: UserRequest, PostRequest, OrderRequest, etc.
+- **Actions**: Action types and helpers
+- **Schema**: validation schema builder
+- **Router**: route, response helpers
+- **String Utilities**: slug, camelCase, pascalCase, snakeCase, kebabCase, titleCase
+- **Core**: path, storage, log, handleError, Auth, register
+
+## Auto-Import Type Declarations
+
+### auto-imports.d.ts (general)
+```typescript
+declare global {
+  const Action: typeof import('@stacksjs/actions').Action
+  const response: typeof import('@stacksjs/router').response
+  const route: typeof import('@stacksjs/router').route
+  const schema: typeof import('@stacksjs/validation').schema
+  const slug: typeof import('@stacksjs/strings').slug
+  // ... all auto-imported identifiers
+}
+```
+
+### Adding Custom Auto-Imports
+
+1. Create function in `resources/functions/`:
+```typescript
+// resources/functions/myUtils.ts
+export function myHelper() { return 'hello' }
+```
+
+2. Export from `storage/framework/auto-imports/functions.ts`:
+```typescript
+export { myHelper } from '../../resources/functions/myUtils'
+```
+
+3. Declare types in `storage/framework/auto-imports/globals.d.ts`:
+```typescript
+declare function myHelper(): string
+```
+
+4. Inject at runtime in `storage/framework/auto-imports/globals.ts`:
+```typescript
+globalThis.myHelper = myHelper
+```
+
+## Generation Commands
+
+```bash
+buddy generate                  # regenerate all auto-imports
+buddy generate --types          # regenerate type declarations
+buddy generate --ide-helpers    # regenerate IDE helpers
+buddy generate:component-meta   # regenerate component metadata
+```
+
+The `build:reset` script also regenerates auto-imports.
+
+## Server Auto-Import Initialization
+
+```typescript
+import { initiateImports, generateAutoImportFiles, injectGlobalAutoImports } from '@stacksjs/server'
+
+initiateImports()              // initialize auto-import plugin
+generateAutoImportFiles()      // generate runtime auto-import files
+injectGlobalAutoImports()      // inject models/functions globally
+```
+
+## Gotchas
+- Browser auto-imports are resolved at BUILD TIME by bun-plugin-stx — not runtime
+- Server auto-imports are injected into globalThis at RUNTIME
+- The browser-auto-imports.d.ts file is ~80KB — it's auto-generated, don't edit manually
+- Custom functions must be exported from both the function file AND the auto-imports barrel
+- Type declarations must match the runtime globals for IDE support
+- All 60+ ORM models are auto-imported on the server — available as `User.find(1)` etc.
+- Request models (e.g., `UserRequest`) are also auto-imported for validated request access
+- Auto-imports are regenerated during `buddy generate` and `build:reset`
+- The discovered-packages.json file at `storage/framework/discovered-packages.json` is part of this system