@stacksjs/defaults 0.70.354 → 0.70.356

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

@@ -96,12 +96,27 @@ bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts snapsho
 ```
 Extracts headings, links (`text -> href`), buttons, forms (action + field count), and ARIA landmarks — useful for auditing structure and catching broken links.
 
+### Scenario (stateful SPA interactions)
+```bash
+bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts scenario <url> \
+  --step '{"action":"click","selector":"button[data-open]"}' \
+  --step '{"action":"fill","selector":"input[name=name]","value":"Example"}' \
+  --step '{"action":"click","selector":"button[type=submit]"}' \
+  --step '{"action":"assert","selector":"main","text":"Saved"}' \
+  --out storage/framework/runtime/shots/scenario.png
+```
+
+Steps run in order within one isolated browser page, preserving reactive STX state and SPA navigation. Supported actions are `click`, `fill`, `press`, `wait`, and `assert`. Each step is a JSON object passed through a repeatable `--step` flag. A click step may include `text` to select the matching control from its CSS selector. The command reports every completed step, the final URL and page text, console exceptions, failed requests, and an optional screenshot. It exits nonzero when the scenario assertion, browser console, or network fails.
+
 ### Crawl (whole-site browser audit)
 ```bash
-bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts crawl <url> [--max 500] [--path /extra-route] [--settle 350] [--progress]
+bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts crawl <url> [--viewport 1280x900] [--max 500] [--path /extra-route] [--settle 350] [--progress]
 ```
-Reuses one Chromium process with a fresh isolated page target per route while
+Uses a fresh isolated page target per route, relaunching Chromium if its DevTools
+session exits during a long audit, while
 following every same-origin link it discovers.
+The viewport is deterministic and defaults to `1280x900`; pass `--viewport 768x1024`
+to repeat the same route audit at a tablet breakpoint.
 Each page is checked for a non-200 document, console exceptions, failed
 requests, and horizontal overflow. Repeat `--path` to seed routes that are not
 linked from the starting page. The command prints every crawled path and exits

package/ai/skills/stacks-browse/scripts/browse.ts

@@ -12,7 +12,8 @@
  *   bun browse.ts responsive <url> [--out-dir DIR]
  *   bun browse.ts monitor    <url> [--ms 5000]
  *   bun browse.ts snapshot   <url>
- *   bun browse.ts crawl      <url> [--max 500] [--path /extra] [--progress]
+ *   bun browse.ts scenario   <url> --step '{"action":"click","selector":"button"}'
+ *   bun browse.ts crawl      <url> [--viewport 1280x900] [--max 500] [--path /extra] [--progress]
  *
  * Browser discovery order: $BROWSE_BROWSER → PATH (chromium, google-chrome, …)
  * → common macOS app bundles → a Playwright-cached chromium as last resort.
@@ -405,6 +406,14 @@ interface CrawlPage {
   consoleErrors: string[]
   failedRequests: Array<{ status: number, url: string }>
   horizontalOverflowPx: number
+  layout: {
+    bodyScrollWidth: number
+    documentScrollWidth: number
+    mainClientWidth: number | null
+    mainOverflowX: string | null
+    mainScrollWidth: number | null
+    viewportWidth: number
+  }
   overflowingElements: Array<{
     element: string
     left: number
@@ -488,6 +497,118 @@ function parseViewport(value: string | undefined): { w: number, h: number } {
   return { w, h }
 }
 
+type ScenarioAction = 'assert' | 'click' | 'fill' | 'press' | 'wait'
+
+interface ScenarioStep {
+  action: ScenarioAction
+  selector?: string
+  text?: string
+  value?: string
+  key?: string
+  ms?: number
+  settle?: number
+}
+
+function parseScenarioStep(value: string): ScenarioStep {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(value)
+  }
+  catch (error) {
+    throw new TypeError(`Invalid scenario step JSON: ${value}`, { cause: error })
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+    throw new TypeError('Each scenario step must be a JSON object.')
+
+  const step = parsed as Record<string, unknown>
+  if (!['assert', 'click', 'fill', 'press', 'wait'].includes(String(step.action)))
+    throw new TypeError(`Unsupported scenario action: ${String(step.action)}`)
+
+  const action = step.action as ScenarioAction
+  if (['assert', 'click', 'fill'].includes(action) && typeof step.selector !== 'string')
+    throw new TypeError(`Scenario action "${action}" requires a selector.`)
+  if (action === 'fill' && typeof step.value !== 'string')
+    throw new TypeError('Scenario action "fill" requires a string value.')
+  if (action === 'press' && typeof step.key !== 'string')
+    throw new TypeError('Scenario action "press" requires a key.')
+  if (action === 'wait' && (!Number.isFinite(step.ms) || Number(step.ms) < 0 || Number(step.ms) > 30_000))
+    throw new TypeError('Scenario action "wait" requires ms between 0 and 30000.')
+
+  return step as unknown as ScenarioStep
+}
+
+async function runScenarioStep(cdp: Cdp, step: ScenarioStep): Promise<Record<string, unknown>> {
+  if (step.action === 'wait') {
+    await Bun.sleep(Number(step.ms))
+    return { action: step.action, ms: Number(step.ms), ok: true }
+  }
+
+  if (step.action === 'press') {
+    const key = step.key || ''
+    const keyCode = key.length === 1 ? key.charCodeAt(0) : ({ Enter: 13, Escape: 27, Tab: 9 }[key] || 0)
+    await cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', key, code: key, windowsVirtualKeyCode: keyCode })
+    await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key, code: key, windowsVirtualKeyCode: keyCode })
+    return { action: step.action, key, ok: true }
+  }
+
+  const result = await cdp.send('Runtime.evaluate', {
+    expression: `(() => {
+      const step = ${JSON.stringify(step)}
+      const candidates = Array.from(document.querySelectorAll(step.selector))
+      const normalizedText = (element) => (element.innerText || element.textContent || '').replace(/\\s+/g, ' ').trim()
+      const element = step.action === 'click' && step.text !== undefined
+        ? candidates.find(candidate => normalizedText(candidate) === step.text)
+          || candidates.find(candidate => normalizedText(candidate).includes(step.text))
+        : candidates[0]
+      if (!element)
+        return { ok: false, error: 'Element not found', selector: step.selector }
+
+      const rect = element.getBoundingClientRect()
+      const style = getComputedStyle(element)
+      const visible = rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden' && style.display !== 'none'
+      if (!visible)
+        return { ok: false, error: 'Element is not visible', selector: step.selector }
+
+      if (step.action === 'click') {
+        if (element.disabled || element.getAttribute('aria-disabled') === 'true')
+          return { ok: false, error: 'Element is disabled', selector: step.selector }
+        element.click()
+      }
+      else if (step.action === 'fill') {
+        if (!('value' in element))
+          return { ok: false, error: 'Element has no value', selector: step.selector }
+        const prototype = Object.getPrototypeOf(element)
+        const setter = Object.getOwnPropertyDescriptor(prototype, 'value')?.set
+        if (setter)
+          setter.call(element, step.value)
+        else
+          element.value = step.value
+        element.dispatchEvent(new InputEvent('input', { bubbles: true, inputType: 'insertText', data: step.value }))
+        element.dispatchEvent(new Event('change', { bubbles: true }))
+      }
+      else if (step.action === 'assert' && step.text !== undefined) {
+        const content = (element.innerText || element.textContent || '').replace(/\\s+/g, ' ').trim()
+        if (!content.includes(step.text))
+          return { ok: false, error: 'Expected text was not found', selector: step.selector, expected: step.text, actual: content.slice(0, 240) }
+      }
+
+      return {
+        ok: true,
+        action: step.action,
+        selector: step.selector,
+        tag: element.tagName.toLowerCase(),
+        text: normalizedText(element).slice(0, 160),
+      }
+    })()`,
+    returnByValue: true,
+  })
+  const value = result.result?.value as Record<string, unknown> | undefined
+  if (!value?.ok)
+    throw new Error(`Scenario ${step.action} failed: ${String(value?.error || 'unknown error')} (${step.selector || step.key || ''})`)
+  return value
+}
+
 const BREAKPOINTS = [
   { device: 'Mobile S', w: 320, h: 568 },
   { device: 'Mobile L', w: 428, h: 926 },
@@ -502,14 +623,14 @@ async function main() {
   const url = positional[0]
 
   if (!command || command === 'help' || !url) {
-    console.log('Usage: bun browse.ts <navigate|screenshot|responsive|monitor|snapshot|crawl> <url> [flags]')
+    console.log('Usage: bun browse.ts <navigate|screenshot|responsive|monitor|snapshot|scenario|crawl> <url> [flags]')
     console.log('  --cookie "name=value"   repeatable; pre-seeds cookies (e.g. coming-soon bypass)')
     console.log('  --settle 1500           ms to wait after load before acting (default 700; stretch for entrance animations)')
     console.log('  --scheme dark           emulate prefers-color-scheme (light|dark) for QA of theme-aware pages')
     process.exit(url ? 0 : 1)
   }
 
-  const session = await launch()
+  let session = await launch()
   const cookies = flagList(flags.cookie)
   const settleMs = flags.settle ? Number(flags.settle) : undefined
   const scheme = typeof flags.scheme === 'string' ? flags.scheme : undefined
@@ -554,7 +675,7 @@ async function main() {
         const cdp = await openPage(session.port)
         const state = await gotoAndInstrument(cdp, url, { viewport: { w: bp.w, h: bp.h }, cookies, settleMs, scheme })
         const overflow = await cdp.send('Runtime.evaluate', {
-          expression: 'document.documentElement.scrollWidth > window.innerWidth ? document.documentElement.scrollWidth - window.innerWidth : 0',
+          expression: 'document.body.scrollWidth > window.innerWidth ? document.body.scrollWidth - window.innerWidth : 0',
           returnByValue: true,
         })
         const out = join(outDir, `${bp.device.toLowerCase().replace(/\s+/g, '-')}.png`)
@@ -611,9 +732,57 @@ async function main() {
       cdp.close()
     }
 
+    else if (command === 'scenario') {
+      const steps = flagList(flags.step).map(parseScenarioStep)
+      if (!steps.length)
+        throw new TypeError('Scenario requires at least one --step JSON object.')
+
+      const cdp = await openPage(session.port)
+      const viewport = parseViewport(typeof flags.viewport === 'string' ? flags.viewport : undefined)
+      const state = await gotoAndInstrument(cdp, url, { viewport, cookies, settleMs, scheme })
+      const results: Record<string, unknown>[] = []
+
+      for (const step of steps) {
+        results.push(await runScenarioStep(cdp, step))
+        if (step.action !== 'wait')
+          await Bun.sleep(step.settle ?? 250)
+      }
+
+      const finalState = await cdp.send('Runtime.evaluate', {
+        expression: `({
+          url: location.href,
+          title: document.title,
+          activeElement: document.activeElement?.tagName?.toLowerCase() || null,
+          bodyText: (document.body.innerText || '').replace(/\\s+/g, ' ').trim().slice(0, 500),
+        })`,
+        returnByValue: true,
+      })
+      let screenshot: string | null = null
+      if (typeof flags.out === 'string') {
+        screenshot = flags.out
+        mkdirSync(screenshot.split('/').slice(0, -1).join('/') || '.', { recursive: true })
+        await Bun.write(screenshot, await captureScreenshot(cdp, { full: !!flags.full }))
+      }
+      const failedRequests = state.responses.filter(response => response.status >= 400)
+      console.log(JSON.stringify({
+        url,
+        viewport: `${viewport.w}x${viewport.h}`,
+        steps: results,
+        final: finalState.result?.value,
+        screenshot,
+        consoleErrors: state.consoleErrors,
+        failedRequests,
+      }, null, 2))
+      if (state.consoleErrors.length || failedRequests.length)
+        process.exitCode = 1
+      state.dispose()
+      cdp.close()
+    }
+
     else if (command === 'crawl') {
       const start = new URL(url)
       const max = flags.max ? Number(flags.max) : 500
+      const crawlViewport = parseViewport(typeof flags.viewport === 'string' ? flags.viewport : undefined)
       if (!Number.isInteger(max) || max < 1)
         throw new TypeError(`Invalid crawl max "${String(flags.max)}". Expected a positive integer.`)
 
@@ -629,9 +798,19 @@ async function main() {
       const crawlSettleMs = settleMs ?? 350
       let browserPage = await createPage(session.port)
       let cdp = browserPage.cdp
+      const createReplacementPage = async (): Promise<BrowserPage> => {
+        try {
+          return await createPage(session.port)
+        }
+        catch {
+          kill(session)
+          session = await launch()
+          return createPage(session.port)
+        }
+      }
       const replacePage = async (): Promise<void> => {
         await closePage(session.port, browserPage)
-        browserPage = await createPage(session.port)
+        browserPage = await createReplacementPage()
         cdp = browserPage.cdp
       }
       const inspectPage = async (current: string): Promise<{
@@ -640,6 +819,7 @@ async function main() {
           links?: string[]
           overflow?: number
           overflowing?: CrawlPage['overflowingElements']
+          layout?: CrawlPage['layout']
           title?: string
         }
       }> => {
@@ -651,12 +831,24 @@ async function main() {
               cookies,
               settleMs: crawlSettleMs,
               scheme,
+              viewport: crawlViewport,
             })
             const inspection = await cdp.send('Runtime.evaluate', {
               expression: `(() => ({
               title: document.title,
               links: Array.from(document.querySelectorAll('a[href]')).map(link => link.href),
-              overflow: Math.max(0, document.documentElement.scrollWidth - window.innerWidth),
+              overflow: Math.max(0, document.body.scrollWidth - window.innerWidth),
+              layout: (() => {
+                const main = document.querySelector('[data-stx-content]')
+                return {
+                  bodyScrollWidth: document.body.scrollWidth,
+                  documentScrollWidth: document.documentElement.scrollWidth,
+                  mainClientWidth: main?.clientWidth ?? null,
+                  mainOverflowX: main ? getComputedStyle(main).overflowX : null,
+                  mainScrollWidth: main?.scrollWidth ?? null,
+                  viewportWidth: window.innerWidth,
+                }
+              })(),
               overflowing: Array.from(document.querySelectorAll('body *'))
                 .map((element) => {
                   const rect = element.getBoundingClientRect()
@@ -736,6 +928,14 @@ async function main() {
             consoleErrors: [...new Set(state.consoleErrors)],
             failedRequests,
             horizontalOverflowPx: Number(value.overflow) || 0,
+            layout: value.layout || {
+              bodyScrollWidth: 0,
+              documentScrollWidth: 0,
+              mainClientWidth: null,
+              mainOverflowX: null,
+              mainScrollWidth: null,
+              viewportWidth: 0,
+            },
             overflowingElements: value.overflowing || [],
           })
           if (flags.progress) {
@@ -767,6 +967,7 @@ async function main() {
       console.log(JSON.stringify({
         start: start.href,
         browser: session.browser,
+        viewport: `${crawlViewport.w}x${crawlViewport.h}`,
         crawled: pages.length,
         remaining: queue.length,
         max,

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-email
-description: Use when working with email in a Stacks application — sending emails via SES/SendGrid/Mailgun/Mailtrap/SMTP, email templates with STX, email drivers, the Mail singleton, the EmailSDK for inbox management, or email configuration. Covers @stacksjs/email, config/email.ts, and app/Mail/.
+description: Use when working with email in a Stacks application - sending emails via SES/SendGrid/Mailgun/Mailtrap/SMTP, email templates with STX, email drivers, the Mail singleton, the EmailSDK for inbox management, inbound MIME parsing, or email configuration. Covers @stacksjs/email, config/email.ts, and app/Mail/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -14,6 +14,7 @@ Multi-driver email system with template rendering, S3-based inbox management, an
 - Core package: `storage/framework/core/email/src/`
 - Configuration: `config/email.ts`
 - Application mail: `app/Mail/`
+- Persistence models: `storage/framework/defaults/app/Models/EmailSuppression.ts`, `EmailIdempotency.ts`, `EmailWebhookEvent.ts`
 - Email layouts: `storage/framework/defaults/resources/emails/layouts/`
 - Email resources: `storage/framework/defaults/resources/emails/`
 
@@ -23,8 +24,9 @@ email/src/
 ├── index.ts          # All exports
 ├── email.ts          # Email class + Mail singleton
 ├── template.ts       # Template rendering engine
+├── inbound-parser.ts # Bounded RFC MIME parsing for inbound mail
 ├── types.ts          # Types and interfaces
-├── sdk/index.ts      # EmailSDK (send + inbox management)
+├── sdk/index.ts      # EmailSDK (send + inbox and attachment management)
 └── drivers/
     ├── base.ts       # BaseEmailDriver abstract class
     ├── ses.ts        # AWS SES driver
@@ -53,11 +55,30 @@ await mail.send({
   text: 'Hello!'
 })
 
+// Use this when later state depends on successful provider delivery.
+await mail.sendOrFail({
+  to: 'user@example.com',
+  subject: 'Your invitation',
+  text: 'Open the invitation link.'
+})
+
 // Switch driver
 const sendgridMail = mail.use('sendgrid')
 await sendgridMail.send(message)
 ```
 
+`mail.send()` always returns an `EmailResult`. Provider rejection is represented
+as `{ success: false, message, provider }`, which is useful for campaign jobs
+that aggregate individual outcomes. It may still throw for invalid framework
+configuration. `mail.sendOrFail()` returns the same successful result and throws
+`EmailDeliveryError` for a structured provider failure. Use `sendOrFail()` when
+an action reports that mail was sent, when a caller relies on `.catch()`, or when
+delivery status is persisted after the call.
+
+Keep template rendering fallback separate from provider delivery. Resolve HTML
+and text first, fall back to plain text only when rendering fails, then call
+`sendOrFail()` once outside the template `try` block.
+
 ## Email Class
 
 ```typescript
@@ -106,14 +127,16 @@ import { emailSDK, sendEmail, getInbox, searchEmails, deleteEmail } from '@stack
 await sendEmail({ from: { address: 'a@b.com' }, to: 'c@d.com', subject: 'Hi', html: '<p>Hello</p>' })
 
 // Send with template
-await emailSDK.sendTemplate({ to: 'user@example.com', templateName: 'welcome', data: { name: 'John' } })
+await emailSDK.sendTemplate({ to: 'user@example.com', template: 'welcome', data: { name: 'John' } })
 
 // Read inbox (from S3)
 const emails = await getInbox('chris', { limit: 20 })
 const email = await emailSDK.getEmail('chris', messageId)
+const attachments = await emailSDK.getAttachments('chris', messageId)
+const download = await emailSDK.getAttachment('chris', messageId, attachments?.[0]?.id || '')
 
 // Search
-const results = await searchEmails('chris', { from: 'boss', after: '2024-01-01', hasAttachments: true })
+const results = await searchEmails('chris', { from: 'boss', after: new Date('2024-01-01'), hasAttachments: true })
 
 // Manage
 await emailSDK.markAsRead('chris', messageId)
@@ -227,7 +250,7 @@ export async function sendSubscriptionConfirmation({ to, subscriberUuid }: Optio
     }
   })
 
-  await mail.send({
+  await mail.sendOrFail({
     from: { name: config.app.name, address: config.email.from.address },
     to,
     subject: 'Confirm your subscription',
@@ -237,26 +260,60 @@ export async function sendSubscriptionConfirmation({ to, subscriberUuid }: Optio
 }
 ```
 
+## Delivery persistence models
+
+Stacks ships three internal models and their generated migrations:
+
+- `EmailSuppression` uses `email_suppressions` and uniquely keys `email + type`.
+- `EmailIdempotency` uses `email_idempotency` and uniquely keys `idempotency_key`.
+- `EmailWebhookEvent` uses `email_webhook_events` and uniquely keys `provider + event_id`.
+
+Each model declares authenticated `useApi` index, show, and destroy routes, but
+sets `dashboard.enabled` to false so operational records do not clutter the
+generic model catalog. Sensitive idempotency keys, recipients, subjects, and
+provider event IDs are hidden from generated responses. Run `buddy migrate`
+after upgrading so suppression, send deduplication, and webhook deduplication
+are enforced rather than using their legacy warn-once compatibility path.
+
+## Inbound MIME and attachment storage
+
+`parseInboundEmail()` parses RFC messages with bounded header, nesting, total-size, and attachment-count limits. It returns normalized sender and recipient data, text and HTML bodies, and binary-safe attachments. Attachment filenames are sanitized before they become S3 keys.
+
+`buddy email:reprocess` reads raw messages with `getObjectBytes()`, parses them through this shared helper, and writes:
+
+- `raw.eml`
+- `metadata.json`
+- `body.txt` and `body.html` when present
+- binary objects under `attachments/`
+- the per-mailbox `inbox.json` index
+
+Reprocessing refreshes existing messages instead of skipping them, preserves their read state, and repairs body and attachment metadata written by older versions. The dashboard receives opaque attachment IDs, resolves them against the stored message before download, and never accepts arbitrary S3 keys from a client.
+
 ## CLI Commands
-- `buddy email` / `buddy mail` — email management
-- `buddy email:verify` — check domain verification
-- `buddy email:test [recipient]` — send test email
-- `buddy email:list` — list mailboxes
-- `buddy email:logs -n 50` — view logs
-- `buddy email:status` — server status
-- `buddy email:inbox [mailbox]` — view inbox from S3
-- `buddy mail:user:add <email>` — add mail user
-- `buddy mail:user:list` — list mail users
-- `buddy mail:user:delete <email>` — delete mail user
+- `buddy email` / `buddy mail` - email management
+- `buddy email:verify` - check domain verification
+- `buddy email:test [recipient]` - send test email
+- `buddy email:list` - list mailboxes
+- `buddy email:logs -n 50` - view logs
+- `buddy email:status` - server status
+- `buddy email:inbox [mailbox]` - view inbox from S3
+- `buddy email:reprocess` - parse raw S3 mail into mailbox bodies and attachments
+- `buddy mail:user:add <email>` - add mail user
+- `buddy mail:user:list` - list mail users
+- `buddy mail:user:delete <email>` - delete mail user
 
 ## Gotchas
-- Default driver is `ses` — requires AWS credentials
+- Default driver is `ses` - requires AWS credentials
 - Template rendering supports both `.stx` and `.html` files
 - Variable interpolation uses `{{ }}` double-brace syntax
 - The `mail` singleton auto-registers all 5 drivers on initialization
 - SMTP driver handles TLS handshake manually (not via node:tls)
 - SendGrid/Mailgun retry with exponential backoff on failure
+- `mail.send()` returns structured failures; use `mail.sendOrFail()` when success is required
+- Suppression, send idempotency, and webhook dedup are backed by built-in `useApi` models
 - Mailtrap requires `inboxId` for sandbox mode
 - EmailSDK reads inbox from S3 (bucket configured via env)
+- EmailSDK attachment downloads use binary-safe S3 reads and opaque IDs
+- `buddy email:reprocess` preserves existing read state and exits nonzero on failure
 - Email categorization auto-sorts incoming mail by domain/substring patterns
 - The `text` fallback is auto-generated from HTML via `htmlToText()`

package/app/Actions/ContactAction.ts

@@ -53,7 +53,7 @@ export default new Action({
     ].join('\n')
 
     try {
-      await mail.send({
+      await mail.sendOrFail({
         to: [toAddress],
         from: { name: appName, address: fromAddress },
         replyTo: email,
@@ -63,7 +63,7 @@ export default new Action({
     }
     catch (err) {
       const errMessage = err instanceof Error ? err.message : String(err)
-      console.error('[ContactAction] mail.send failed:', errMessage)
+      console.error('[ContactAction] mail.sendOrFail failed:', errMessage)
       return { success: false, message: 'We could not send your message. Try again in a moment.' }
     }
 

package/app/Actions/Dashboard/Analytics/EventAnalyticsAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { AnalyticsEvent } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import {
   analyticsCurrency,
   analyticsIdentifier,
@@ -50,9 +51,7 @@ export default new Action({
       )
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Event analytics records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Event analytics records could not be read.', 'EventAnalyticsAction')
     }
   },
 })

package/app/Actions/Dashboard/Analytics/MarketingAnalyticsAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { Campaign } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import {
   analyticsCurrency,
   analyticsIdentifier,
@@ -55,9 +56,7 @@ export default new Action({
       )
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Campaign analytics records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Campaign analytics records could not be read.', 'MarketingAnalyticsAction')
     }
   },
 })

package/app/Actions/Dashboard/Analytics/SalesAnalyticsAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { Category, Order, OrderItem, Payment, Product } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import {
   analyticsCurrency,
   analyticsIdentifier,
@@ -93,9 +94,7 @@ export default new Action({
       )
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Sales analytics records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Sales analytics records could not be read.', 'SalesAnalyticsAction')
     }
   },
 })

package/app/Actions/Dashboard/Analytics/WebAnalyticsAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { Request } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import {
   buildWebAnalytics,
   normalizeAnalyticsRange,
@@ -27,9 +28,14 @@ export default new Action({
         message: error instanceof Error ? error.message : 'The analytics query is invalid.',
       }, 422)
     }
-    const records = await Request.orderByDesc('id').limit(10_000).get()
-    const rows = records.map(requestAnalyticsRow)
+    try {
+      const records = await Request.orderByDesc('id').limit(10_000).get()
+      const rows = records.map(requestAnalyticsRow)
 
-    return buildWebAnalytics(rows, range, new Date(), scope)
+      return buildWebAnalytics(rows, range, new Date(), scope)
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Web analytics records could not be read.', 'WebAnalyticsAction')
+    }
   },
 })

package/app/Actions/Dashboard/Auth/MeAction.ts

@@ -1,5 +1,7 @@
+import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { getUserRoles } from '@stacksjs/auth'
+import { dashboardOperationalError } from '../dashboard-response'
 
 interface MeResponse {
   user: {
@@ -32,7 +34,7 @@ interface MeResponse {
  * a 401 in the network tab. Instead:
  *
  *   - If the request carries a valid bearer token, the framework's auth
- *     middleware already populated `request.user` — we return that user
+ *     middleware already populated `request.user()` - we return that user
  *     plus their roles.
  *   - If not, we return `{ user: null, roles: [], unauthenticated: true }`.
  *     The composable's "no auth → assume dev" default kicks in client-side,
@@ -48,34 +50,30 @@ export default new Action({
   description: 'Returns the authenticated user + their RBAC roles for dashboard role gating.',
   method: 'GET',
   apiResponse: true,
-  async handle(request) {
-    const user = (request as any)?.user ?? (request as any)?._authenticatedUser ?? null
+  async handle(request: RequestInstance) {
+    const user = await request.user()
 
-    if (!user || typeof user !== 'object' || typeof (user as { id?: unknown }).id !== 'number') {
+    if (!user || !Number.isInteger(Number(user.id))) {
       const res: MeResponse = { user: null, roles: [], unauthenticated: true }
       return res
     }
 
-    const userId = (user as { id: number }).id
+    const userId = Number(user.id)
 
-    let roles: string[] = []
+    let roles: string[]
     try {
       const records = await getUserRoles(userId)
       roles = records.map(r => r.name)
     }
-    catch (err) {
-      // RBAC store not configured, migrations not run, or DB unreachable.
-      // Empty roles → useRole will fall back to its dev default. We don't
-      // want to 500 the dashboard just because the role tables haven't
-      // been migrated yet on a fresh project.
-      console.warn('[dashboard/auth/me] getUserRoles failed:', err instanceof Error ? err.message : err)
+    catch (error) {
+      return dashboardOperationalError(error, 'Dashboard identity could not be loaded.', 'MeAction')
     }
 
     const res: MeResponse = {
       user: {
         id: userId,
-        name: (user as { name?: string | null }).name ?? null,
-        email: (user as { email?: string | null }).email ?? null,
+        name: user.name ?? null,
+        email: user.email ?? null,
       },
       roles,
     }