@stacksjs/defaults 0.70.357 → 0.70.358

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

@@ -100,13 +100,17 @@ Extracts headings, links (`text -> href`), buttons, forms (action + field count)
 ```bash
 bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts scenario <url> \
   --step '{"action":"click","selector":"button[data-open]"}' \
+  --step '{"action":"focus","selector":"input[name=name]"}' \
   --step '{"action":"fill","selector":"input[name=name]","value":"Example"}' \
   --step '{"action":"click","selector":"button[type=submit]"}' \
   --step '{"action":"assert","selector":"main","text":"Saved"}' \
+  --step '{"action":"assert","selector":"[role=dialog]","absent":true}' \
   --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.
+Steps run in order within one isolated browser page, preserving reactive STX state and SPA navigation. Supported actions are `click`, `fill`, `focus`, `press`, `wait`, and `assert`. Each step is a JSON object passed through a repeatable `--step` flag. Click and focus steps may include `text` to select the matching control from their CSS selector. The command reports every completed step, the final URL and page text, console messages, console exceptions, failed requests, and an optional screenshot. It exits nonzero when the scenario assertion, browser console, or network fails.
+Use `{"action":"assert","selector":"...","absent":true}` to verify that an element is missing or hidden after an interaction.
+Use `{"action":"assert","selector":"button","text":"Save","focused":true}` to verify keyboard focus and focus restoration.
 
 ### Crawl (whole-site browser audit)
 ```bash

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

@@ -497,12 +497,14 @@ function parseViewport(value: string | undefined): { w: number, h: number } {
   return { w, h }
 }
 
-type ScenarioAction = 'assert' | 'click' | 'fill' | 'press' | 'wait'
+type ScenarioAction = 'assert' | 'click' | 'fill' | 'focus' | 'press' | 'wait'
 
 interface ScenarioStep {
   action: ScenarioAction
   selector?: string
   text?: string
+  absent?: boolean
+  focused?: boolean
   value?: string
   key?: string
   ms?: number
@@ -522,14 +524,18 @@ function parseScenarioStep(value: string): ScenarioStep {
     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)))
+  if (!['assert', 'click', 'fill', 'focus', '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')
+  if (['assert', 'click', 'fill', 'focus'].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 (step.absent !== undefined && (action !== 'assert' || typeof step.absent !== 'boolean'))
+    throw new TypeError('Scenario "absent" is a boolean supported only by assert actions.')
+  if (step.focused !== undefined && (action !== 'assert' || typeof step.focused !== 'boolean'))
+    throw new TypeError('Scenario "focused" is a boolean supported only by assert actions.')
   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))
@@ -557,23 +563,36 @@ async function runScenarioStep(cdp: Cdp, step: ScenarioStep): Promise<Record<str
       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
+      const element = (step.action === 'click' || step.action === 'focus' || step.action === 'assert') && step.text !== undefined
         ? candidates.find(candidate => normalizedText(candidate) === step.text)
           || candidates.find(candidate => normalizedText(candidate).includes(step.text))
         : candidates[0]
+      if (!element && step.action === 'assert' && step.absent)
+        return { ok: true, action: step.action, selector: step.selector, absent: true }
       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 (step.action === 'assert' && step.absent) {
+        if (visible)
+          return { ok: false, error: 'Expected element to be absent', selector: step.selector }
+        return { ok: true, action: step.action, selector: step.selector, absent: true }
+      }
       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 === 'focus') {
+        if (typeof element.focus !== 'function')
+          return { ok: false, error: 'Element cannot receive focus', selector: step.selector }
+        element.focus()
+        if (document.activeElement !== element)
+          return { ok: false, error: 'Element did not receive focus', selector: step.selector }
       }
       else if (step.action === 'fill') {
         if (!('value' in element))
@@ -593,12 +612,19 @@ async function runScenarioStep(cdp: Cdp, step: ScenarioStep): Promise<Record<str
           return { ok: false, error: 'Expected text was not found', selector: step.selector, expected: step.text, actual: content.slice(0, 240) }
       }
 
+      if (step.action === 'assert' && step.focused !== undefined) {
+        const focused = document.activeElement === element
+        if (focused !== step.focused)
+          return { ok: false, error: step.focused ? 'Expected element to be focused' : 'Expected element not to be focused', selector: step.selector }
+      }
+
       return {
         ok: true,
         action: step.action,
         selector: step.selector,
         tag: element.tagName.toLowerCase(),
         text: normalizedText(element).slice(0, 160),
+        clickPoint: step.action === 'click' ? { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 } : undefined,
       }
     })()`,
     returnByValue: true,
@@ -606,6 +632,12 @@ async function runScenarioStep(cdp: Cdp, step: ScenarioStep): Promise<Record<str
   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 || ''})`)
+  if (step.action === 'click') {
+    const point = value.clickPoint as { x: number, y: number }
+    await cdp.send('Input.dispatchMouseEvent', { type: 'mousePressed', x: point.x, y: point.y, button: 'left', clickCount: 1 })
+    await cdp.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: point.x, y: point.y, button: 'left', clickCount: 1 })
+    delete value.clickPoint
+  }
   return value
 }
 
@@ -741,6 +773,20 @@ async function main() {
       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>[] = []
+      await cdp.send('Page.bringToFront')
+      await cdp.send('Runtime.evaluate', {
+        expression: `(() => {
+          window.__browseFocusHistory = []
+          const describe = (element) => element ? {
+            tag: element.tagName?.toLowerCase() || null,
+            role: element.getAttribute?.('role') || null,
+            ariaLabel: element.getAttribute?.('aria-label') || null,
+            text: (element.innerText || element.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 80),
+          } : null
+          document.addEventListener('focusin', event => window.__browseFocusHistory.push({ event: 'focusin', target: describe(event.target) }), true)
+          document.addEventListener('focusout', event => window.__browseFocusHistory.push({ event: 'focusout', target: describe(event.target), related: describe(event.relatedTarget) }), true)
+        })()`,
+      })
 
       for (const step of steps) {
         results.push(await runScenarioStep(cdp, step))
@@ -752,7 +798,15 @@ async function main() {
         expression: `({
           url: location.href,
           title: document.title,
-          activeElement: document.activeElement?.tagName?.toLowerCase() || null,
+          focusHistory: window.__browseFocusHistory || [],
+          activeElement: document.activeElement ? {
+            tag: document.activeElement.tagName?.toLowerCase() || null,
+            id: document.activeElement.id || null,
+            role: document.activeElement.getAttribute?.('role') || null,
+            ariaLabel: document.activeElement.getAttribute?.('aria-label') || null,
+            ref: document.activeElement.getAttribute?.('data-stx-ref') || null,
+            text: (document.activeElement.innerText || document.activeElement.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 120),
+          } : null,
           bodyText: (document.body.innerText || '').replace(/\\s+/g, ' ').trim().slice(0, 500),
         })`,
         returnByValue: true,
@@ -770,6 +824,7 @@ async function main() {
         steps: results,
         final: finalState.result?.value,
         screenshot,
+        consoleMessages: state.console,
         consoleErrors: state.consoleErrors,
         failedRequests,
       }, null, 2))

package/app/Actions/Dashboard/Actions/GetActions.ts

@@ -1,22 +1,28 @@
 import { Action } from '@stacksjs/actions'
 import process from 'node:process'
 import { discoverActionSources } from '../Source/source-inventory'
+import { dashboardOperationalError } from '../dashboard-response'
 
 export default new Action({
   name: 'GetActions',
   description: 'Lists application and framework Actions from their native source files.',
   method: 'GET',
   async handle() {
-    const items = await discoverActionSources(process.cwd())
+    try {
+      const items = await discoverActionSources(process.cwd())
 
-    return {
-      items,
-      stats: {
-        total: items.length,
-        application: items.filter(item => item.origin === 'Application').length,
-        framework: items.filter(item => item.origin === 'Framework').length,
-        writes: items.filter(item => !['ANY', 'GET', 'HEAD', 'OPTIONS'].includes(item.method || 'ANY')).length,
-      },
+      return {
+        items,
+        stats: {
+          total: items.length,
+          application: items.filter(item => item.origin === 'Application').length,
+          framework: items.filter(item => item.origin === 'Framework').length,
+          writes: items.filter(item => !['ANY', 'GET', 'HEAD', 'OPTIONS'].includes(item.method || 'ANY')).length,
+        },
+      }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Action sources could not be loaded.', 'GetActions')
     }
   },
 })

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

@@ -1,7 +1,8 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
-import { AnalyticsEvent } from '@stacksjs/orm'
+import { AnalyticsEvent, ModelValidationError } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 
 function token(value: unknown, fallback: string): string {
   const normalized = String(value || '')
@@ -46,14 +47,25 @@ export default new Action({
     if (properties.length > 10_000)
       return response.json({ message: 'Properties must be 10,000 characters or fewer.' }, 422)
 
-    await AnalyticsEvent.create({
-      name,
-      category,
-      path,
-      value,
-      currency,
-      properties,
-    })
+    try {
+      await AnalyticsEvent.create({
+        name,
+        category,
+        path,
+        value,
+        currency,
+        properties,
+      })
+    }
+    catch (error) {
+      if (error instanceof ModelValidationError) {
+        return response.json({
+          message: 'Validation failed.',
+          errors: error.errors,
+        }, 422)
+      }
+      return dashboardOperationalError(error, 'Analytics event could not be recorded.', 'EventStoreAction', 500)
+    }
 
     return response.json({ success: true }, 201)
   },

package/app/Actions/Dashboard/Commerce/ProductUnitDefaultAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { products } from '@stacksjs/commerce'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 
 export default new Action({
   name: 'ProductUnitDefaultAction',
@@ -11,11 +12,19 @@ export default new Action({
 
   async handle(request: RequestInstance) {
     const id = Number(request.getParam('id'))
+    if (!Number.isSafeInteger(id) || id <= 0)
+      return response.json({ error: 'A valid product unit id is required.' }, 400)
+    if (typeof request.get('isDefault') !== 'boolean')
+      return response.json({ error: 'isDefault must be a boolean.' }, 422)
     const isDefault = request.boolean('isDefault')
-    if (!Number.isFinite(id) || id <= 0)
-      return response.notFound({ error: 'Product unit not found' })
 
-    const updated = await products.units.updateDefaultStatus(id, isDefault)
+    let updated
+    try {
+      updated = await products.units.updateDefaultStatus(id, isDefault)
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Product unit default could not be updated.', 'ProductUnitDefaultAction', 500)
+    }
     if (!updated)
       return response.notFound({ error: 'Product unit not found' })
 

package/app/Actions/Dashboard/Commerce/TaxRateDefaultAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { tax } from '@stacksjs/commerce'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 
 export default new Action({
   name: 'TaxRateDefaultAction',
@@ -11,11 +12,19 @@ export default new Action({
 
   async handle(request: RequestInstance) {
     const id = Number(request.getParam('id'))
+    if (!Number.isSafeInteger(id) || id <= 0)
+      return response.json({ error: 'A valid tax rate id is required.' }, 400)
+    if (typeof request.get('isDefault') !== 'boolean')
+      return response.json({ error: 'isDefault must be a boolean.' }, 422)
     const isDefault = request.boolean('isDefault')
-    if (!Number.isFinite(id) || id <= 0)
-      return response.notFound({ error: 'Tax rate not found' })
 
-    const updated = await tax.updateDefaultStatus(id, isDefault)
+    let updated
+    try {
+      updated = await tax.updateDefaultStatus(id, isDefault)
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Tax rate default could not be updated.', 'TaxRateDefaultAction', 500)
+    }
     if (!updated)
       return response.notFound({ error: 'Tax rate not found' })
 

package/app/Actions/Dashboard/DashboardHealthAction.ts

@@ -1,6 +1,7 @@
 import process from 'node:process'
 import { Action } from '@stacksjs/actions'
 import { checkApplicationHealth } from '@stacksjs/router'
+import { dashboardOperationalError, dashboardOperationalIssue } from './dashboard-response'
 
 export default new Action({
   name: 'DashboardHealthAction',
@@ -10,21 +11,40 @@ export default new Action({
 
   async handle() {
     const startedAt = performance.now()
-    const health = await checkApplicationHealth()
-    const memory = process.memoryUsage()
+    try {
+      const health = await checkApplicationHealth()
+      const memory = process.memoryUsage()
+      const checks = Object.fromEntries(Object.entries(health.checks).map(([name, check]) => {
+        if (!check.ok) {
+          dashboardOperationalIssue(
+            check.message,
+            'Dependency probe failed.',
+            `DashboardHealthAction.${name}`,
+          )
+        }
+        return [name, {
+          ...check,
+          message: check.ok ? undefined : 'Dependency probe failed.',
+        }]
+      }))
 
-    return {
-      ...health,
-      durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
-      runtime: {
-        bunVersion: process.versions.bun || '',
-        nodeVersion: process.versions.node || '',
-        platform: process.platform,
-        architecture: process.arch,
-        uptimeSeconds: Math.max(0, Math.floor(process.uptime())),
-        residentMemoryBytes: memory.rss,
-        heapUsedBytes: memory.heapUsed,
-      },
+      return {
+        ...health,
+        checks,
+        durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
+        runtime: {
+          bunVersion: process.versions.bun || '',
+          nodeVersion: process.versions.node || '',
+          platform: process.platform,
+          architecture: process.arch,
+          uptimeSeconds: Math.max(0, Math.floor(process.uptime())),
+          residentMemoryBytes: memory.rss,
+          heapUsedBytes: memory.heapUsed,
+        },
+      }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'System health could not be loaded.', 'DashboardHealthAction')
     }
   },
 })

package/app/Actions/Dashboard/DashboardHomeAction.test.ts

@@ -28,7 +28,7 @@ describe('dashboard HTTP metrics', () => {
       name: 'Cache',
       status: 'critical',
       latency: '1500ms',
-      detail: 'timeout',
+      detail: 'Dependency probe failed.',
     })
   })
 

package/app/Actions/Dashboard/DashboardHomeAction.ts

@@ -2,6 +2,7 @@ import { Action } from '@stacksjs/actions'
 import { Order, Post, Product, Request, User } from '@stacksjs/orm'
 import { checkApplicationHealth, type ApplicationHealthCheck } from '@stacksjs/router'
 import { formatRelative, safeGet } from '../../../resources/functions/dashboard/data'
+import { dashboardOperationalIssue } from './dashboard-response'
 
 interface HttpRequestSample {
   duration: number
@@ -28,7 +29,7 @@ export function serializeHealthCheck(name: string, check: ApplicationHealthCheck
     name: name.charAt(0).toUpperCase() + name.slice(1),
     status: check.ok ? 'healthy' : 'critical',
     latency: `${check.ms}ms`,
-    detail: check.message || '',
+    detail: check.ok ? '' : 'Dependency probe failed.',
   }
 }
 
@@ -43,7 +44,11 @@ function issue(source: string, result: PromiseSettledResult<unknown>) {
   return result.status === 'rejected'
     ? {
         source,
-        message: result.reason instanceof Error ? result.reason.message : 'Query failed.',
+        message: dashboardOperationalIssue(
+          result.reason,
+          `${source} data could not be loaded.`,
+          `DashboardHomeAction.${source.toLowerCase().replaceAll(' ', '-')}`,
+        ),
       }
     : null
 }
@@ -65,7 +70,7 @@ export default new Action({
       Request.count(),
       Request.orderBy('created_at', 'desc').limit(1000).get(),
     ])
-    const health = await checkApplicationHealth()
+    const healthResult = await Promise.allSettled([checkApplicationHealth()])
 
     const [
       userCount,
@@ -93,7 +98,19 @@ export default new Action({
       })))
       : summarizeHttpRequests(0, [])
 
-    const services = Object.entries(health.checks).map(([name, check]) => serializeHealthCheck(name, check))
+    const health = healthResult[0]
+    const services = health.status === 'fulfilled'
+      ? Object.entries(health.value.checks).map(([name, check]) => {
+          if (!check.ok) {
+            dashboardOperationalIssue(
+              check.message,
+              'Dependency probe failed.',
+              `DashboardHomeAction.health.${name}`,
+            )
+          }
+          return serializeHealthCheck(name, check)
+        })
+      : []
 
     const activities = [
       ...(recentOrders.status === 'fulfilled' ? recentOrders.value : []).map((order: any) => ({
@@ -127,6 +144,16 @@ export default new Action({
     const issues = modelResults
       .map((result, index) => issue(sources[index], result))
       .filter((entry): entry is { source: string, message: string } => entry !== null)
+    if (health.status === 'rejected') {
+      issues.push({
+        source: 'System health',
+        message: dashboardOperationalIssue(
+          health.reason,
+          'System health could not be loaded.',
+          'DashboardHomeAction.health',
+        ),
+      })
+    }
 
     return { stats, httpMetrics, services, activities, issues }
   },

package/app/Actions/Dashboard/DashboardStatsAction.ts

@@ -1,5 +1,6 @@
 import { Action } from '@stacksjs/actions'
 import { Customer, Order, Post, User } from '@stacksjs/orm'
+import { dashboardOperationalIssue } from './dashboard-response'
 
 interface DashboardStatDefinition {
   title: string
@@ -61,7 +62,11 @@ export default new Action({
     const issues = results.flatMap((result, index) => result.status === 'rejected'
       ? [{
           source: definitions[index].title,
-          message: result.reason instanceof Error ? result.reason.message : 'Model query failed.',
+          message: dashboardOperationalIssue(
+            result.reason,
+            `${definitions[index].title} data could not be loaded.`,
+            `DashboardStatsAction.${definitions[index].title.toLowerCase().replaceAll(' ', '-')}`,
+          ),
         }]
       : [])
 

package/app/Actions/Dashboard/Email/InboxSendAction.ts

@@ -3,6 +3,7 @@ import { Action } from '@stacksjs/actions'
 import { notify } from '@stacksjs/notifications'
 import { response } from '@stacksjs/router'
 import { schema } from '@stacksjs/validation'
+import { dashboardOperationalError } from '../dashboard-response'
 
 export default new Action({
   name: 'InboxSendAction',
@@ -29,15 +30,21 @@ export default new Action({
     const subject = String(request.get('subject') || '').trim()
     const body = String(request.get('body') || '').trim()
 
-    const [result] = await notify(
-      { email: to },
-      { subject, body, data: { source: 'dashboard-inbox' } },
-      ['email'],
-      { ignorePreferences: true },
-    )
+    let result
+    try {
+      [result] = await notify(
+        { email: to },
+        { subject, body, data: { source: 'dashboard-inbox' } },
+        ['email'],
+        { ignorePreferences: true },
+      )
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'The email could not be sent.', 'InboxSendAction.provider', 502)
+    }
 
     if (!result?.success)
-      return response.json({ message: result?.error?.message || 'The email could not be sent.' }, 502)
+      return dashboardOperationalError(result?.error, 'The email could not be sent.', 'InboxSendAction.result', 502)
 
     return response.json({ success: true })
   },

package/app/Actions/Dashboard/Infrastructure/CommandIndexAction.ts

@@ -3,6 +3,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import process from 'node:process'
 import { parseCommandSource } from '../Source/source-inventory'
+import { dashboardOperationalError } from '../dashboard-response'
 
 interface CommandConfig {
   file: string
@@ -15,35 +16,40 @@ export default new Action({
   description: 'Lists commands registered by the application.',
   method: 'GET',
   async handle() {
-    const projectRoot = process.cwd()
-    const registryPath = join(projectRoot, 'app/Commands.ts')
-    const registryModule = await import(registryPath)
-    const registry = (registryModule.default || {}) as Record<string, string | CommandConfig>
-    const items = Object.entries(registry).flatMap(([signature, value]) => {
-      const config = typeof value === 'string'
-        ? { file: value, enabled: true, aliases: [] }
-        : { enabled: true, aliases: [], ...value }
-      const file = join(projectRoot, 'app/Commands', `${config.file}.ts`)
-      if (!existsSync(file))
-        return []
+    try {
+      const projectRoot = process.cwd()
+      const registryPath = join(projectRoot, 'app/Commands.ts')
+      const registryModule = await import(registryPath)
+      const registry = (registryModule.default || {}) as Record<string, string | CommandConfig>
+      const items = Object.entries(registry).flatMap(([signature, value]) => {
+        const config = typeof value === 'string'
+          ? { file: value, enabled: true, aliases: [] }
+          : { enabled: true, aliases: [], ...value }
+        const file = join(projectRoot, 'app/Commands', `${config.file}.ts`)
+        if (!existsSync(file))
+          return []
 
-      return [parseCommandSource(
-        readFileSync(file, 'utf8'),
-        relative(projectRoot, file),
-        signature,
-        config.aliases,
-        statSync(file).mtime.toISOString(),
-      )]
-    })
+        return [parseCommandSource(
+          readFileSync(file, 'utf8'),
+          relative(projectRoot, file),
+          signature,
+          config.aliases,
+          statSync(file).mtime.toISOString(),
+        )]
+      })
 
-    return {
-      items,
-      stats: {
-        total: items.length,
-        aliases: items.reduce((sum, item) => sum + (item.aliases?.length || 0), 0),
-        options: items.reduce((sum, item) => sum + (item.options?.length || 0), 0),
-        registered: Object.keys(registry).length,
-      },
+      return {
+        items,
+        stats: {
+          total: items.length,
+          aliases: items.reduce((sum, item) => sum + (item.aliases?.length || 0), 0),
+          options: items.reduce((sum, item) => sum + (item.options?.length || 0), 0),
+          registered: Object.keys(registry).length,
+        },
+      }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Command sources could not be loaded.', 'CommandIndexAction')
     }
   },
 })

package/app/Actions/Dashboard/Infrastructure/EnvironmentIndexAction.ts

@@ -1,4 +1,5 @@
 import { Action } from '@stacksjs/actions'
+import { dashboardOperationalError } from '../dashboard-response'
 import { readEnvironmentFile } from './environment-file'
 
 export default new Action({
@@ -8,9 +9,14 @@ export default new Action({
   apiResponse: true,
 
   async handle() {
-    return Response.json(
-      { environment: await readEnvironmentFile() },
-      { headers: { 'Cache-Control': 'no-store', Pragma: 'no-cache' } },
-    )
+    try {
+      return Response.json(
+        { environment: await readEnvironmentFile() },
+        { headers: { 'Cache-Control': 'no-store', Pragma: 'no-cache' } },
+      )
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Environment file could not be loaded.', 'EnvironmentIndexAction')
+    }
   },
 })

package/app/Actions/Dashboard/Infrastructure/EnvironmentUpdateAction.ts

@@ -1,6 +1,7 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import { updateEnvironmentFile } from './environment-file'
 
 export default new Action({
@@ -18,7 +19,13 @@ export default new Action({
     if (typeof revision !== 'string' || !/^[a-f0-9]{64}$/.test(revision))
       return response.json({ message: 'A valid environment revision is required.' }, 422)
 
-    const result = await updateEnvironmentFile(content, revision)
+    let result
+    try {
+      result = await updateEnvironmentFile(content, revision)
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Environment file could not be saved.', 'EnvironmentUpdateAction', 500)
+    }
     if (result.issues?.length) {
       const errors = Object.fromEntries(result.issues.map((issue, index) => [
         issue.line ? String(issue.line) : `file-${index}`,