@stacksjs/defaults 0.70.353 → 0.70.355

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-dashboard/scripts/audit.ts

@@ -227,7 +227,6 @@ function concreteApiPath(
   dynamicPages: string[],
   modelRoutes: string[],
 ): string {
-  // eslint-disable-next-line pickier/no-unused-vars
   const match = (prefix: string) => dynamicPages
     .find(route => route.startsWith(`${prefix}/`))
     ?.slice(prefix.length + 1)

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
@@ -23,8 +23,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
@@ -106,14 +107,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)
@@ -237,20 +240,35 @@ export async function sendSubscriptionConfirmation({ to, subscriberUuid }: Optio
 }
 ```
 
+## 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
@@ -258,5 +276,7 @@ export async function sendSubscriptionConfirmation({ to, subscriberUuid }: Optio
 - SendGrid/Mailgun retry with exponential backoff on failure
 - 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/Dashboard/Auth/MeAction.ts

@@ -1,3 +1,4 @@
+import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { getUserRoles } from '@stacksjs/auth'
 
@@ -32,7 +33,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,15 +49,15 @@ 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[] = []
     try {
@@ -74,8 +75,8 @@ export default new Action({
     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,
     }

package/app/Actions/Dashboard/Ci/RepoRunJobsAction.ts

@@ -1,6 +1,8 @@
+import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { dashboard as dashboardConfig } from '@stacksjs/config'
 import { fetchRunJobs } from '@stacksjs/github'
+import { response } from '@stacksjs/router'
 
 /**
  * `GET /api/dashboard/ci/repos/:owner/:name/runs/:runId/jobs`
@@ -19,27 +21,26 @@ export default new Action({
   description: 'Job-level breakdown for a single workflow run (drilldown expand).',
   method: 'GET',
   apiResponse: true,
-  async handle(request) {
+  async handle(request: RequestInstance) {
     const ci = dashboardConfig?.ci
 
     if (!ci?.enabled) {
       return { jobs: [], disabled: true }
     }
 
-    const owner = String((request as any)?.params?.owner ?? (request as any)?.param?.('owner') ?? '').trim()
-    const repo = String((request as any)?.params?.name ?? (request as any)?.param?.('name') ?? '').trim()
-    const runIdRaw = (request as any)?.params?.runId ?? (request as any)?.param?.('runId') ?? null
-    const runId = Number(runIdRaw)
+    const owner = request.getParam('owner').trim()
+    const repo = request.getParam('name').trim()
+    const runId = Number(request.getParam('runId'))
     if (!owner || !repo) {
-      return { error: 'Both `owner` and `name` route params are required.', status: 400 }
+      return response.json({ message: 'Both owner and name route parameters are required.' }, 400)
     }
     if (!Number.isFinite(runId) || runId <= 0) {
-      return { error: '`runId` must be a positive integer.', status: 400 }
+      return response.json({ message: 'The run ID must be a positive integer.' }, 400)
     }
 
     const allowedOrgs = ci.orgs ?? []
     if (allowedOrgs.length > 0 && !allowedOrgs.includes(owner)) {
-      return { error: 'Org not in `config.dashboard.ci.orgs`.', status: 403 }
+      return response.json({ message: 'This organization is not configured for CI tracking.' }, 403)
     }
 
     try {
@@ -48,13 +49,7 @@ export default new Action({
     }
     catch (err) {
       console.error('[dashboard/ci] RepoRunJobsAction failed:', err)
-      return {
-        owner,
-        repo,
-        runId,
-        jobs: [],
-        error: err instanceof Error ? err.message : 'unknown error',
-      }
+      return response.json({ message: 'Workflow jobs could not be loaded.' }, 502)
     }
   },
 })

package/app/Actions/Dashboard/Ci/RepoRunsAction.ts

@@ -1,6 +1,9 @@
+import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { dashboard as dashboardConfig } from '@stacksjs/config'
 import { fetchWorkflowRuns } from '@stacksjs/github'
+import { response } from '@stacksjs/router'
+import { dashboardRequestValue } from '../dashboard-request'
 
 /**
  * `GET /api/dashboard/ci/repos/:owner/:name/runs?limit=N`
@@ -23,32 +26,32 @@ export default new Action({
   description: 'Latest N workflow runs for a single repo (drilldown).',
   method: 'GET',
   apiResponse: true,
-  async handle(request) {
+  async handle(request: RequestInstance) {
     const ci = dashboardConfig?.ci
 
     if (!ci?.enabled) {
       return { owner: null, repo: null, runs: [], disabled: true }
     }
 
-    const owner = String((request as any)?.params?.owner ?? (request as any)?.param?.('owner') ?? '').trim()
-    const repo = String((request as any)?.params?.name ?? (request as any)?.param?.('name') ?? '').trim()
+    const owner = request.getParam('owner').trim()
+    const repo = request.getParam('name').trim()
     if (!owner || !repo) {
-      return { error: 'Both `owner` and `name` route params are required.', status: 400 }
+      return response.json({ message: 'Both owner and name route parameters are required.' }, 400)
     }
 
     // Scope check: only fetch runs for orgs the user explicitly
     // configured. Stops the endpoint from being a generic GH proxy.
     const allowedOrgs = ci.orgs ?? []
     if (allowedOrgs.length > 0 && !allowedOrgs.includes(owner)) {
-      return { error: 'Org not in `config.dashboard.ci.orgs`.', status: 403 }
+      return response.json({ message: 'This organization is not configured for CI tracking.' }, 403)
     }
 
-    const url = new URL(request.url ?? `http://localhost/`)
-    const rawLimit = Number(url.searchParams.get('limit') ?? '20')
+    const rawLimit = Number(dashboardRequestValue(request, 'limit', '20'))
     const limit = Number.isFinite(rawLimit) && rawLimit > 0
       ? Math.min(Math.floor(rawLimit), 100)
       : 20
-    const branch = url.searchParams.get('branch') || undefined
+    const branchValue = dashboardRequestValue(request, 'branch')
+    const branch = branchValue || undefined
 
     try {
       const runs = await fetchWorkflowRuns(owner, repo, { limit, branch })
@@ -56,12 +59,7 @@ export default new Action({
     }
     catch (err) {
       console.error('[dashboard/ci] RepoRunsAction failed:', err)
-      return {
-        owner,
-        repo,
-        runs: [],
-        error: err instanceof Error ? err.message : 'unknown error',
-      }
+      return response.json({ message: 'Workflow runs could not be loaded.' }, 502)
     }
   },
 })

package/app/Actions/Dashboard/Ci/RunnerHistoryAction.ts

@@ -1,5 +1,8 @@
+import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { dashboard as dashboardConfig } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+import { dashboardRequestValue } from '../dashboard-request'
 import { fetchRunnerHistory } from './runner-pressure-monitor'
 
 /**
@@ -12,33 +15,31 @@ import { fetchRunnerHistory } from './runner-pressure-monitor'
  * configured retention window — older samples aren't available
  * because they've been pruned.
  *
- * Soft-errors to an empty samples array on any failure so the
- * sparkline gracefully degrades to "no history yet" instead of
- * yelling at the user.
+ * Operational failures use a real 503 response so the client can
+ * distinguish unavailable history from a valid empty sample set.
  */
 export default new Action({
   name: 'Dashboard CI Runner History',
   description: 'Recent runner-sample history for one org (sparkline data).',
   method: 'GET',
   apiResponse: true,
-  async handle(request) {
+  async handle(request: RequestInstance) {
     const ci = dashboardConfig?.ci
     if (!ci?.enabled || !ci.alerts?.enabled) {
       return { org: null, samples: [], disabled: true }
     }
 
-    const url = new URL(request.url ?? 'http://localhost/')
-    const org = String(url.searchParams.get('org') ?? '').trim()
+    const org = dashboardRequestValue(request, 'org')
     if (!org) {
-      return { error: '`org` query param is required.', status: 400 }
+      return response.json({ message: 'The org query parameter is required.' }, 400)
     }
 
     const allowedOrgs = ci.orgs ?? []
     if (allowedOrgs.length > 0 && !allowedOrgs.includes(org)) {
-      return { error: 'Org not in `config.dashboard.ci.orgs`.', status: 403 }
+      return response.json({ message: 'This organization is not configured for CI tracking.' }, 403)
     }
 
-    const rawLimit = Number(url.searchParams.get('limit') ?? '60')
+    const rawLimit = Number(dashboardRequestValue(request, 'limit', '60'))
     const limit = Number.isFinite(rawLimit) && rawLimit > 0
       ? Math.min(Math.floor(rawLimit), 500)
       : 60
@@ -52,7 +53,7 @@ export default new Action({
     }
     catch (err) {
       console.error('[dashboard/ci] RunnerHistoryAction failed:', err)
-      return { org, samples: [], error: err instanceof Error ? err.message : 'unknown error' }
+      return response.json({ message: 'Runner history could not be loaded.' }, 503)
     }
   },
 })