@stacksjs/defaults 0.75.109 → 0.75.111

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

@@ -8,141 +8,85 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Browser
 
-Frontend/browser utilities for STX applications.
-
-## Key Paths
-- Core package: `storage/framework/core/browser/src/`
-- Auto-imports: `storage/framework/browser-auto-imports.json`
-
-## Authentication Composable (useAuth)
-
-```typescript
-const { user, isAuthenticated, login, register, logout, token, errors, loading } = useAuth()
-
-// Login
-await login({ email: 'user@example.com', password: 'secret' })
-
-// Register
-await register({ email: 'new@example.com', password: 'secret', name: 'John' })
-
-// Logout
-await logout()
-
-// Auth guard (redirect if not authenticated)
-authGuard()              // redirect to /login
-authGuard({ guest: true })  // redirect if authenticated (for login page)
-```
-
-## API Client (Fetch)
-
-```typescript
-import { Fetch, initApi } from '@stacksjs/browser'
-
-initApi({ baseUrl: '/api', onUnauthorized: () => router.push('/login') })
-
-const users = await Fetch.get('/users')
-await Fetch.post('/users', { name: 'John' })
-await Fetch.patch('/users/1', { name: 'Jane' })
-await Fetch.put('/users/1', data)
-await Fetch.destroy('/users/1')
-Fetch.setToken('bearer-token')
-```
-
-## Stripe Billing (Browser-Side)
-
-```typescript
-import { loadCardElement, loadPaymentElement, confirmCardSetup, confirmCardPayment, confirmPayment, createPaymentMethod } from '@stacksjs/browser'
-
-// Load Stripe Elements
-const cardElement = await loadCardElement(clientSecret)
-const paymentElement = await loadPaymentElement(clientSecret)
-
-// Confirm payment
-const { paymentIntent, error } = await confirmCardPayment(clientSecret, elements)
-const { setupIntent, error } = await confirmCardSetup(clientSecret, elements)
-const { paymentIntent, error } = await confirmPayment(elements)
-const { paymentIntent, error } = await createPaymentMethod(elements)
-```
-
-## Browser Model Loading
-
-```typescript
-import { loadBrowserModels, getBrowserModel, getBrowserModelNames } from '@stacksjs/browser'
-
-await loadBrowserModels()               // loads all models from app/Models/
-const User = getBrowserModel('User')
-const names = getBrowserModelNames()     // ['User', 'Post', ...]
-```
-
-## Browser Query Builder
-
-```typescript
-import { browserQuery, BrowserQueryBuilder, browserAuth, createBrowserModel, createBrowserDb } from '@stacksjs/browser'
-
-const users = await browserQuery('users').where('active', true).get()
-const db = createBrowserDb({ baseUrl: '/api' })
-```
-
-## Utility Functions
-
-```typescript
-// API URLs: one canonical `/api` root, legacy-prefixed paths do not double it
-resolveApiBaseUrl() // https://app.example/api in a browser
-resolveApiUrl('/users', 'https://app.example/api') // https://app.example/api/users
-resolveApiUrl('/api/users', 'https://app.example/api') // same URL
-
-// Date
-useDateFormat(date, 'YYYY-MM-DD')
-useNow()
-
-// Formatting
-formatAreaSize(sqMeters)       // '1,234 sq ft' or 'X acres'
-formatDistance(miles)           // '1.5 mi' or '2,640 ft'
-formatElevation(feet)          // '1,234 ft'
-formatDuration(seconds)        // '2h 15m'
-getRelativeTime(dateString)    // '5 minutes ago'
-
-// Async
-fetchData(fetcher, { onError, fallback })
-
-// Random
-random(size?)                  // nanoid
-customAlphabet(alphabet, size) // custom nanoid
-
-
-// Retry
-retry(fn, { retries: 3, initialDelay: 100, backoffFactor: 2 })
-
-// Sleep
-sleep(ms), wait(ms), delay(ms)
-waitUntil(condition, { interval, timeout })
-waitWhile(condition, options)
-
-// Promise
-createSingletonPromise(fn)
-createControlledPromise()
-createPromiseLock()
-```
-
-## Guards
-- `notNullish(v)` — type guard for non-null/undefined
-- `noNull(v)` — excludes null
-- `notUndefined(v)` — excludes undefined
-- `isTruthy(v)` — excludes falsy values
-
-## Auto-Initialization
-```typescript
-autoInit()  // initializes all browser utilities, exposes on window.StacksBrowser
-```
-
-## Re-exports from Composables
-`useDark`, `useFetch`, `useOnline`, `useStorage`, `useToggle`, `useDateFormat`, `useNow`, `usePreferredDark`
-
-## Gotchas
-- All browser utilities are auto-imported in STX templates
-- `initApi()` must be called before using `Fetch`
-- `loadCardElement()` requires Stripe.js to be loaded
-- `publishableKey` must be set for Stripe integration
-- Browser models use a different query builder than server-side models
-- `autoInit()` exposes utilities on `window.StacksBrowser`
-- Do NOT use `document.*`, `window.*` directly in STX templates
+Use `@stacksjs/browser` for client authentication, API transport, browser models,
+request error messages and imported billing/utilities. Imported availability is
+different from an STX runtime global.
+
+## Imports and runtime boundary
+
+Import useAuth/authGuard, initApi/Fetch and needed helpers explicitly. The package
+initializes browser API config as an import side effect, using public injected
+config or same-origin /api; initApi is an optional override. autoInit itself is
+internal, not a public entry export. window.StacksBrowser is a bag of utilities
+and registered models, not proof that each name is attached as a bare global.
+Read stacks-auto-imports for the actual STX runtime names.
+
+The public query builder comes from bun-query-builder/browser, so client bundles
+avoid server SQLite/child_process dependencies. configureBrowser/getBrowserConfig,
+browserQuery/BrowserQueryBuilder/BrowserQueryError, browserAuth and
+createBrowserDb/createBrowserModel are native browser exports. API access remains
+subject to server routes, permissions and row scoping; a client model is not a
+direct SQL connection or authorization layer.
+
+## Authentication and session recovery
+
+~~~ts
+import { useAuth } from '@stacksjs/browser'
+
+const session = useAuth()
+const result = await session.login({ email: 'user@example.com', password: 'secret' })
+~~~
+
+useAuth returns shared client refs and login/register/logout/session methods.
+Login returns a union including validation/refusal and a two-factor challenge;
+inspect the result, rather than assuming a resolved call means signed-in state.
+Browser state uses imported storage helpers, not direct document/window mutation
+inside STX scripts.
+
+refreshSession coalesces concurrent refresh attempts. A server refusal clears the
+session and returns false; a transport failure throws and keeps the existing
+credential. authFetch retries the eligible request after refresh using the native
+credential/CSRF flow. Cookie/session behavior and refresh-token availability
+depend on server browser-session policy. A fixed-lifetime login cannot be made
+renewable by keeping an old client refresh token.
+
+completeSocialLogin applies the native handoff through the same storage refs and
+strips its URL fragment. Use socialHandoffRedirect on the server; a hand-built
+inline script writing token/user keys duplicates the encoding/security contract.
+authGuard controls client navigation; guard server pages/actions independently.
+
+## API transports and errors
+
+initApi configures the browser query builder. The older Fetch facade has its own
+baseURL/token/request path; do not assume initApi changes Fetch's baseURL.
+Fetch.get uses query parameters, post/patch/put JSON bodies, and destroy sends
+DELETE with query parameters. Non-2xx throws an error with status/data after
+body parsing. Its methods return parsed response data, not query-builder Results.
+
+For cookie writes prefer the native auth/composable request flow and
+readCsrfToken/withCsrfHeader. The low-level Fetch facade is not that complete
+session/CSRF abstraction. describeResponseError(status, body?) and
+describeThrownError(error) normalize useful client messages and field errors.
+Read request-error.ts before displaying raw server/provider data to a user.
+
+## Models, billing and utilities
+
+registerModelModules or loadBrowserModels(modules?) registers bundled model
+definitions; loadBrowserModels is synchronous and does not dynamically scan
+server app/Models over HTTP. Only definitions with traits.useApi.uri become
+browser models, with server-only factories/validators stripped. getBrowserModel
+returns a model or null; getBrowserModelNames lists the registered model entries.
+
+Stripe helpers (loadCardElement/loadPaymentElement/confirmCardSetup/
+confirmCardPayment/createPaymentMethod/confirmPayment) are imported exports;
+Stripe.js and the public key are prerequisites. Server payment actions retain
+authority over amounts, ownership and payment completion. Utility/composable
+re-exports have their own signatures in utils/ and composables/; read the native
+composable skill instead of copying another fixed inventory of globals.
+
+## Source and evidence
+
+`storage/framework/core/browser/src/index.ts`, auto-init.ts, model-loader.ts,
+composables/useAuth.ts/useApi.ts/csrf.ts/request-error.ts and utils/fetch.ts.
+Tests: client-bundle-safety.test.ts, use-auth-refresh.test.ts, csrf.test.ts,
+request-error.test.ts and api-url.test.ts under core/browser/tests.

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

@@ -0,0 +1,40 @@
+---
+name: stacks-browser-extension
+description: Use when scaffolding, building, packaging or preparing store submission for a native Stacks MV3 browser extension. Covers @stacksjs/browser-extension and Chrome/Firefox/Safari target boundaries.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Browser extensions
+
+Use the native ExtensionConfig and scaffold/build/package APIs for MV3 targets.
+Read the current target and store adapters before planning distribution; a
+successful local bundle is not proof of store acceptance or device behavior.
+
+## Build workflow
+
+scaffoldExtensionProject creates the established project layout;
+scaffoldSafariApp owns Safari container scaffolding. buildExtension configures
+popup/options pages, background/content scripts,
+static assets and declarativeNetRequest rules. Native page builds use stx,
+resource partials and CSP sanitization rather than embedding arbitrary inline
+script. Keep code in permitted bundled entrypoints and minimize permissions.
+
+Target-specific manifest generation, packaging and validation support Chrome
+and Firefox. Safari additionally uses container-app scaffolding, resource sync
+and xcodebuild on a suitable macOS toolchain. Target limitations are explicit;
+do not substitute one browser's package for another.
+
+## Store preparation and publication
+
+The package includes publish plans and adapters for Chrome Web Store, Firefox
+Add-ons/previews and App Store Connect submission. Prepare a reviewable plan,
+credentials prerequisites and the actual artifacts before an authorized upload.
+Do not upload or submit merely because the build finished. Never put store
+credentials into the extension's public files.
+
+Verify generated manifests, CSP, permissions, scripts, packaged file lists,
+and target-specific tests. Device and store outcomes need their own evidence.
+Source: core/browser-extension/src/{config,manifest,build,package,scaffold,
+publish-plan,safari}.ts and store adapters. Tests cover these same boundaries.

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

@@ -624,6 +624,8 @@ buddy changelog              # generate CHANGELOG.md
   -d/--dry-run               # preview without writing
 buddy release                # release new version via GitHub Actions
   --dry-run                  # preview without releasing
+  --bump <type>              # non-interactive bump, including build, calendar, or x.y.z
+  --preid <identifier>       # prerelease channel, for example beta or rc
 buddy route                  # route management
 buddy share [type]           # share local dev server via public tunnel (localtunnel)
   -p/--port <port>           # local port

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

@@ -20,7 +20,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 ## Source Files
 ```
 build/src/
-├── index.ts              # intro() and outro() — build logging and timing
+├── 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)
 
@@ -86,24 +86,27 @@ buddy build --server --verbose --project [name]
 
 ## Standard Build Pattern
 
-Every core package follows this pattern:
+For a library barrel or a package with public subpaths, preserve the module
+graph with the shared transpiler. Identifier-minifying bundles have produced
+invalid re-export bindings on supported Bun versions. Separate bundles also
+duplicate shared objects across entrypoints, such as validation's schema proxy.
 
 ```typescript
-import { dts } from 'bun-plugin-dtsx'
-import { intro, outro } from '../build/src'
+import { rm } from 'node:fs/promises'
+import { frameworkExternal, intro, outro, transpilePackage } 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 })
+await rm('./dist', { recursive: true, force: true })
+await transpilePackage({ dir: import.meta.dir, external: frameworkExternal() })
+await outro({ dir: import.meta.dir, startTime, result: { errors: [], warnings: [] } })
 ```
 
+The helper emits every source module and its declaration with whitespace-only
+minification. Keep package-specific assets, declaration rewriting, and runtime
+probes around this call. Use Bun.build for intentional executable bundles and
+verify the emitted artifact. ORM inference builds validation before ORM because
+the published ORM imports validation's narrow runtime entry.
+
 ## Releasing libraries out of `resources/`
 
 `resources/functions` and `resources/components` are not limited to one npm
@@ -163,7 +166,7 @@ generated and gitignored.
 ### Release flow
 
 `buddy release` runs `generate/lib-entries`, which stages sources and writes
-each manifest without compiling — so a broken library config fails before a tag
+each manifest without compiling - so a broken library config fails before a tag
 exists rather than after. Versions follow the project version unless a package
 pins its own, which is why the build (not the generate) is what CI runs after
 the bump, and `buddy libs:publish` after that.
@@ -214,24 +217,40 @@ enum Action {
 | Tool | Usage |
 |------|-------|
 | **Bun** | Primary bundler (`target: 'bun'`, `format: 'esm'`) |
-| **Vite** | Component library builds |
+| **stx** | 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
+- **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 compile through stx**, not Vite. `buildComponentLibrary`
   emits its own index and each generated component registers its custom element
   on import, which is why a `web-components` package needs no entry file of its
-  own — it publishes `bundle.js` instead of `index.js`.
+  own - it publishes `bundle.js` instead of `index.js`.
 - **A library barrel is generated with `.ts` specifiers on purpose.**
   `transpilePackage` rewrites relative `.ts` to `.js` on the way into `dist`. An
   extensionless specifier survives as-is and only resolves under Bun, so the
   package installs cleanly and fails on first import from Node or Vite.
-- **`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
+- **`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 build contracts
+
+`@stacksjs/build` exports `transpilePackage` and
+`frameworkExternal(extras?)` alongside intro/outro. Inspect a neighboring
+core build.ts before configuring declaration roots or external dependencies;
+the source example is a pattern, not a universal package manifest. Type-only
+dependencies that escape the package degrade consumers even when local paths
+resolve.
+
+`validateDeclarations(dir)` and `validateRuntimeExports(dir)` are native
+checks used by the build contract. A type declaration export without a matching
+runtime file is a package failure, not a successful build. The current public
+implementation is `storage/framework/core/build/src/index.ts`. Use Bun/TS
+for supporting build scripts and pickier for lint.

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

@@ -8,118 +8,78 @@ 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
+Use `@stacksjs/cache` for cache-aside reads, explicit TTLs and invalidation.
+Read `config/cache.ts` and the selected factory before assuming shared state.
+
+## API and TTL
+
+~~~ts
+import { cache } from '@stacksjs/cache'
+
+await cache.set('product:42', { name: 'Widget' }, 60)
+const product = await cache.get<{ name: string }>('product:42')
+const products = await cache.mget<{ name: string }>(['product:42', 'product:43'])
+// mget returns a record keyed by cache key, not an array.
+~~~
+
+- TTL is in seconds. Zero means forever; omitted TTL uses the factory's
+  stdTTL, which defaults to zero. The exported cache/memory singleton is a
+  memory instance with no default expiry. Config's ttl value does not silently
+  turn that singleton into a configured Redis instance.
+- `setForever` stores without expiry; `getTtl` reads remaining TTL and
+  `ttl(key, seconds)` updates it. Missing values are undefined.
+- `mset([{ key, value, ttl? }])` writes entries. `del(keyOrKeys)` and
+  `deleteMany(keys)` return counts; `remove(key)` returns void.
+- `has/missing/take`, `keys(pattern?)`, `getStats`,
+  `clear/flush` and `close/disconnect` provide the remaining facade API.
+  Consult the driver before relying on take for a distributed atomic claim.
+
+## Cache-aside and concurrent misses
+
+`getOrSet(key, fetcher, ttl?)` computes and stores only on a miss.
+`remember(key, ttl, callback)` is its Laravel-style argument order;
+`rememberForever(key, callback)` uses TTL zero.
+
+Concurrent misses share a promise within one StacksCache instance. Its bounded
+inflight timeout rejects every joined caller and frees that slot for retry.
+The underlying fetcher continues running after timeout; this is not cancellation
+or a lock shared across worker processes. For a distributed lock, inspect the
+re-exported CacheLock contract and selected driver separately.
+
+## Drivers
+
+`createMemoryCache(options?)` accepts stdTTL, checkPeriod, maxKeys, useClones
+and prefix. Clone-on-read/write is enabled by default.
+`createRedisCache(options?)` accepts URL or host/port/credentials/database/TLS
+plus TTL/prefix options. `createSingleStoreCache(options?)` exposes the
+experimental SQL-backed cache. `createCache(driver, options?)` selects one
+of memory, redis or singlestore.
+
+The `cache` export is the same memory instance as `memory`. Use an explicit
+Redis instance for application data that must be shared across processes.
+The capability registry proves memory and a versioned Redis core/TTL contract;
+TLS/authenticated Redis deployments need separate provider evidence. SingleStore
+has no dedicated service conformance matrix. Source:
+`storage/framework/core/config/src/capabilities.ts`.
+
+## Tag invalidation and advanced patterns
+
+`StacksCache.tags(['products', 'tenant-7'])` creates a TaggedCache supporting
+put/set/setForever, remember/rememberForever, get/has and flush. Its tag index
+uses the same backend; process persistence depends on that backend. Tags label
+shared keys rather than granting tenant authorization. Construct an explicit
+tenant key/prefix as well when isolation matters.
+
+The package also re-exports CacheAsidePattern, MultiLevelPattern,
+RefreshAheadPattern, WriteThroughPattern, BatchOperations, CacheInvalidation,
+CacheLock, CircuitBreaker, memoize and RateLimiter from ts-cache. Read the
+installed upstream types before using these advanced classes; their signatures
+are distinct from StacksCache and auth's RateLimiter.
+
+## Source and verification
+
+`storage/framework/core/cache/src/drivers/index.ts` is the facade/factory
+contract. `drivers/singlestore.ts` owns the experimental backend.
+Retained tests: `ttl.test.ts`, `getorset-timeout.test.ts`,
+`tagged-flush-race.test.ts`, `redis-contract.test.ts` and
+`cache-factory.test.ts` under `core/cache/tests/`.