@stacksjs/defaults 0.70.365 → 0.70.367

package/app/Actions/Dashboard/Deployments/deployment-preview.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'bun:test'
+import type { DeploymentPreview } from '@stacksjs/types'
+import { parseDeploymentPreview } from './deployment-preview'
+
+const plan: DeploymentPreview = {
+  version: 1,
+  dryRun: true,
+  project: { name: 'Acme', slug: 'acme' },
+  provider: 'hetzner',
+  mode: 'server',
+  environment: 'production',
+  region: 'us-east-1',
+  target: { site: null, domain: null, attachTo: null },
+  sites: [],
+  operations: [],
+  warnings: [],
+}
+
+describe('dashboard deployment preview process', () => {
+  it('extracts the versioned contract from Buddy output', () => {
+    const output = `[env] loaded\nSTACKS_DEPLOY_PREVIEW_JSON=${JSON.stringify(plan)}\n`
+    expect(parseDeploymentPreview(output)).toEqual(plan)
+  })
+
+  it('rejects missing and malformed preview contracts', () => {
+    expect(() => parseDeploymentPreview('ordinary output')).toThrow('did not return')
+    expect(() => parseDeploymentPreview('STACKS_DEPLOY_PREVIEW_JSON={}')).toThrow('invalid')
+  })
+})

package/app/Actions/Dashboard/Deployments/deployment-preview.ts

@@ -0,0 +1,41 @@
+import type { DeploymentPreview } from '@stacksjs/types'
+import { join } from 'node:path'
+import process from 'node:process'
+
+const previewPrefix = 'STACKS_DEPLOY_PREVIEW_JSON='
+
+export function parseDeploymentPreview(output: string): DeploymentPreview {
+  const line = output.split(/\r?\n/).find(entry => entry.startsWith(previewPrefix))
+  if (!line)
+    throw new Error('Buddy did not return a deployment preview contract.')
+
+  const plan = JSON.parse(line.slice(previewPrefix.length)) as DeploymentPreview
+  if (plan.version !== 1 || plan.dryRun !== true || !Array.isArray(plan.operations) || !Array.isArray(plan.sites))
+    throw new Error('Buddy returned an invalid deployment preview contract.')
+  return plan
+}
+
+export async function runDeploymentPreview(args: string[], timeoutMs = 30_000): Promise<DeploymentPreview> {
+  const child = Bun.spawn([join(process.cwd(), 'buddy'), ...args], {
+    cwd: process.cwd(),
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const stdoutPromise = new Response(child.stdout).text()
+  const stderrPromise = new Response(child.stderr).text()
+  let timeout: ReturnType<typeof setTimeout> | undefined
+  const exitPromise = Promise.race([
+    child.exited,
+    new Promise<never>((_resolve, reject) => {
+      timeout = setTimeout(() => {
+        child.kill()
+        reject(new Error(`Deployment preview timed out after ${timeoutMs}ms.`))
+      }, timeoutMs)
+    }),
+  ])
+  const [exitCode, stdout, stderr] = await Promise.all([exitPromise, stdoutPromise, stderrPromise])
+    .finally(() => clearTimeout(timeout))
+  if (exitCode !== 0)
+    throw new Error(stderr.trim() || `buddy deploy preview exited with code ${exitCode}`)
+  return parseDeploymentPreview(stdout)
+}

package/app/Actions/Dashboard/Deployments/deployment-rollback.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'bun:test'
+import { deploymentRollbackInput } from './deployment-rollback'
+
+describe('deployment rollback input', () => {
+  it('normalizes a scoped rollback target', () => {
+    expect(deploymentRollbackInput({ environment: 'Staging', site: 'Dashboard', release: 'Release-42' })).toEqual({
+      environment: 'staging',
+      site: 'dashboard',
+      release: 'release-42',
+    })
+  })
+
+  it('rejects shell syntax instead of forwarding it', () => {
+    expect(() => deploymentRollbackInput({ environment: 'production; echo unsafe' })).toThrow()
+  })
+})

package/app/Actions/Dashboard/Deployments/deployment-rollback.ts

@@ -0,0 +1,89 @@
+import process from 'node:process'
+
+export interface DeploymentRollbackInput {
+  environment: string
+  site?: string
+  release?: string
+}
+
+export class DeploymentRollbackError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'DeploymentRollbackError'
+  }
+}
+
+function identifier(value: unknown, label: string, required = false): string {
+  const normalized = String(value || '').trim().toLowerCase()
+  if (!normalized && !required) return ''
+  if (!/^[a-z0-9][a-z0-9._-]{0,127}$/.test(normalized))
+    throw new DeploymentRollbackError(`${label} must contain only letters, numbers, dots, underscores, and hyphens.`)
+  return normalized
+}
+
+export function deploymentRollbackInput(input: Record<string, unknown>): DeploymentRollbackInput {
+  return {
+    environment: identifier(input.environment || 'production', 'Environment', true),
+    site: identifier(input.site, 'Site') || undefined,
+    release: identifier(input.release || input.to, 'Release') || undefined,
+  }
+}
+
+function commandArgs(input: DeploymentRollbackInput, preview: boolean): string[] {
+  const args = ['deploy:rollback']
+  if (input.site) args.push(input.site)
+  args.push('--env', input.environment)
+  if (input.release) args.push('--to', input.release)
+  if (preview) args.push('--dry-run')
+  args.push('--no-interaction')
+  return args
+}
+
+function plainOutput(value: string): string {
+  return value.replace(/\u001B\[[0-?]*[ -/]*[@-~]/g, '').trim()
+}
+
+async function run(input: DeploymentRollbackInput, preview: boolean): Promise<string> {
+  const child = Bun.spawn([`${process.cwd()}/buddy`, ...commandArgs(input, preview)], {
+    cwd: process.cwd(),
+    env: { ...process.env, NO_COLOR: '1' },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+  const output = plainOutput([stdout, stderr].filter(Boolean).join('\n'))
+  if (exitCode !== 0)
+    throw new DeploymentRollbackError(output || 'The rollback command failed.')
+  return output
+}
+
+export async function previewDeploymentRollback(input: DeploymentRollbackInput) {
+  const output = await run(input, true)
+  const revision = new Bun.CryptoHasher('sha256').update(JSON.stringify(input)).update(output).digest('hex')
+  return {
+    revision,
+    environment: input.environment,
+    site: input.site || null,
+    release: input.release || null,
+    target: input.release || 'previous preserved release',
+    output,
+    warnings: [
+      'The active release pointer and service runtime will change.',
+      'Database migrations are not reversed automatically.',
+    ],
+  }
+}
+
+export async function executeDeploymentRollback(input: DeploymentRollbackInput, revision: string, confirmation: string) {
+  const preview = await previewDeploymentRollback(input)
+  if (preview.revision !== revision)
+    throw new DeploymentRollbackError('The rollback preview changed. Review the current preview before continuing.')
+  if (confirmation !== `rollback ${input.environment}`)
+    throw new DeploymentRollbackError(`Type rollback ${input.environment} to confirm this recovery action.`)
+  const output = await run(input, false)
+  return { message: `Rollback for ${input.site || input.environment} completed.`, output }
+}

package/app/Actions/Dashboard/Operations/AuditIndexAction.ts

@@ -0,0 +1,25 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { operationsControlPlane } from './control-plane'
+
+export default new Action({
+  name: 'AuditIndexAction',
+  description: 'Returns the append-only operator event stream and its correlated operations.',
+  method: 'GET',
+  apiResponse: true,
+  async handle(_request: RequestInstance) {
+    const controlPlane = operationsControlPlane()
+    const events = controlPlane.store.listEvents({ projectId: controlPlane.project.id, limit: 500 })
+    const operations = controlPlane.store.listOperations({ projectId: controlPlane.project.id, limit: 200 })
+    return {
+      events: events.map(event => ({ ...event, actorName: event.actorId ? controlPlane.store.getActor(event.actorId)?.displayName || 'Unknown operator' : 'System' })),
+      operations,
+      summary: {
+        events: events.length,
+        operators: new Set(events.map(event => event.actorId).filter(Boolean)).size,
+        failures: events.filter(event => event.level === 'error').length,
+        latestSequence: events.reduce((latest, event) => Math.max(latest, event.sequence), 0),
+      },
+    }
+  },
+})

package/app/Actions/Dashboard/Operations/ChangeApprovalAction.ts

@@ -0,0 +1,28 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { dashboardOperator, operationsControlPlane } from './control-plane'
+import { stringValue } from './recovery-input'
+import { releaseStore } from './operations-runtime'
+
+export default new Action({
+  name: 'ChangeApprovalAction',
+  description: 'Approves or rejects a release awaiting operator review.',
+  method: 'POST',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const body = request.all() as Record<string, unknown>
+    const decision = stringValue(body.decision)
+    if (!['approved', 'rejected'].includes(decision))
+      return response.json({ message: 'Decision must be approved or rejected.' }, 422)
+    const store = releaseStore()
+    const release = store.get(String(request.getParam('id') || ''))
+    if (!release || release.projectId !== operationsControlPlane().project.id)
+      return response.json({ message: 'Release approval was not found.' }, 404)
+    if (release.status !== 'awaiting_approval')
+      return response.json({ message: 'This release is no longer awaiting approval.' }, 409)
+    const actor = await dashboardOperator(request)
+    const updated = store.approve(release.id, { actorId: actor.id, decision: decision as 'approved' | 'rejected', comment: stringValue(body.comment) || undefined })
+    return { success: true, release: updated, approvals: store.approvals(release.id) }
+  },
+})

package/app/Actions/Dashboard/Operations/ChangeIndexAction.ts

@@ -0,0 +1,32 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { operationsControlPlane, operationsEnvironment, recentOperatorOperations } from './control-plane'
+import { migrationPlan } from './migration-operations'
+import { releaseStore } from './operations-runtime'
+
+export default new Action({
+  name: 'ChangeIndexAction',
+  description: 'Returns one review surface for pending schema, deployment, and release changes.',
+  method: 'GET',
+  apiResponse: true,
+  async handle(_request: RequestInstance) {
+    const controlPlane = operationsControlPlane()
+    const environment = operationsEnvironment(controlPlane)
+    const releases = releaseStore().list({ projectId: controlPlane.project.id, environmentId: environment?.id })
+    const pendingReleases = releases.filter(release => release.status === 'awaiting_approval')
+    const migrations = await migrationPlan()
+    return {
+      environment,
+      migrations,
+      pendingReleases: pendingReleases.map(release => ({ ...release, approvals: releaseStore().approvals(release.id) })),
+      activeOperations: controlPlane.store.listOperations({ projectId: controlPlane.project.id, limit: 100 }).filter(operation => ['queued', 'running'].includes(operation.state)),
+      recentOperations: recentOperatorOperations('dashboard.', 30),
+      summary: {
+        migrationChanges: migrations.summary.pending,
+        destructiveChanges: migrations.summary.destructive,
+        approvals: pendingReleases.length,
+        activeOperations: controlPlane.store.listOperations({ projectId: controlPlane.project.id, limit: 100 }).filter(operation => ['queued', 'running'].includes(operation.state)).length,
+      },
+    }
+  },
+})

package/app/Actions/Dashboard/Operations/IncidentIndexAction.ts

@@ -0,0 +1,32 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { operationsControlPlane, operationsEnvironment, recentOperatorOperations } from './control-plane'
+import { alertStore } from './operations-runtime'
+
+export default new Action({
+  name: 'IncidentIndexAction',
+  description: 'Returns native application alerts, rules, health checks, and notification delivery state.',
+  method: 'GET',
+  apiResponse: true,
+  async handle(_request: RequestInstance) {
+    const controlPlane = operationsControlPlane()
+    const environment = operationsEnvironment(controlPlane)
+    const store = alertStore()
+    const alerts = store.listAlerts(controlPlane.project.id, { environmentId: environment?.id, limit: 200 })
+    return {
+      environment,
+      alerts: alerts.map(alert => ({ ...alert, ownerName: alert.ownerActorId ? controlPlane.store.getActor(alert.ownerActorId)?.displayName : undefined })),
+      rules: store.listRules(controlPlane.project.id, environment?.id),
+      healthChecks: store.listHealthChecks(controlPlane.project.id, environment?.id),
+      channels: store.listChannels(controlPlane.organization.id),
+      deliveries: store.listDeliveries({ limit: 100 }),
+      operations: recentOperatorOperations('dashboard.incidents.', 20),
+      summary: {
+        firing: alerts.filter(alert => alert.state === 'firing').length,
+        critical: alerts.filter(alert => alert.state === 'firing' && alert.severity === 'critical').length,
+        acknowledged: alerts.filter(alert => Boolean(alert.acknowledgedAt)).length,
+        rules: store.listRules(controlPlane.project.id, environment?.id).filter(rule => rule.enabled).length,
+      },
+    }
+  },
+})

package/app/Actions/Dashboard/Operations/IncidentUpdateAction.ts

@@ -0,0 +1,34 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { dashboardOperator, operationsControlPlane, trackOperatorOperation } from './control-plane'
+import { stringValue } from './recovery-input'
+import { alertStore } from './operations-runtime'
+
+export default new Action({
+  name: 'IncidentUpdateAction',
+  description: 'Acknowledges, assigns, or silences a native application alert.',
+  method: 'PATCH',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const body = request.all() as Record<string, unknown>
+    const action = stringValue(body.action)
+    if (!['acknowledge', 'assign_self', 'unassign', 'silence'].includes(action))
+      return response.json({ message: 'Unsupported incident action.' }, 422)
+    const store = alertStore()
+    const alert = store.getAlert(String(request.getParam('id') || ''))
+    if (!alert || alert.projectId !== operationsControlPlane().project.id)
+      return response.json({ message: 'Alert not found.' }, 404)
+    const actor = await dashboardOperator(request)
+    const tracked = await trackOperatorOperation(request, `dashboard.incidents.${action}`, { alertId: alert.id }, async () => {
+      if (action === 'acknowledge') return store.acknowledge(alert.id, actor.id)
+      if (action === 'assign_self') return store.assign(alert.id, actor.id, actor.id)
+      if (action === 'unassign') return store.assign(alert.id, undefined, actor.id)
+      const until = stringValue(body.until)
+      if (!until || Number.isNaN(new Date(until).getTime()) || new Date(until) <= new Date())
+        throw new Error('A future silence expiry is required.')
+      return store.silenceAlert(alert.id, new Date(until).toISOString(), actor.id)
+    })
+    return { success: true, alert: tracked.result, operation: tracked.operation }
+  },
+})

package/app/Actions/Dashboard/Operations/MigrationApplyAction.ts

@@ -0,0 +1,30 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
+import { trackOperatorOperation } from './control-plane'
+import { applyMigrationPlan, MigrationOperationError } from './migration-operations'
+import { stringValue } from './recovery-input'
+
+export default new Action({
+  name: 'MigrationApplyAction',
+  description: 'Applies an unchanged, explicitly confirmed model-derived migration plan.',
+  method: 'POST',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const input = request.all() as Record<string, unknown>
+    const revision = stringValue(input.revision)
+    const confirmation = stringValue(input.confirmation)
+    if (!revision || !confirmation)
+      return response.json({ message: 'Plan revision and typed confirmation are required.' }, 422)
+    try {
+      const tracked = await trackOperatorOperation(request, 'dashboard.migrations.apply', { revision }, () => applyMigrationPlan({ revision, confirmation }))
+      return { success: true, ...tracked.result, operation: tracked.operation }
+    }
+    catch (error) {
+      if (error instanceof MigrationOperationError)
+        return response.json({ message: error.message }, 409)
+      return dashboardOperationalError(error, 'The migration plan could not be applied.', 'MigrationApplyAction')
+    }
+  },
+})

package/app/Actions/Dashboard/Operations/MigrationIndexAction.ts

@@ -0,0 +1,24 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { dashboardOperationalError } from '../dashboard-response'
+import { recentOperatorOperations } from './control-plane'
+import { migrationPlan, reconcileMigrationLedgerPlan } from './migration-operations'
+
+export default new Action({
+  name: 'MigrationIndexAction',
+  description: 'Returns the model-derived schema plan and migration ledger health.',
+  method: 'GET',
+  apiResponse: true,
+  async handle(_request: RequestInstance) {
+    try {
+      return {
+        ...await migrationPlan(),
+        reconciliation: await reconcileMigrationLedgerPlan(false),
+        operatorOperations: recentOperatorOperations('dashboard.migrations.', 20),
+      }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Migration operations could not be loaded.', 'MigrationIndexAction')
+    }
+  },
+})

package/app/Actions/Dashboard/Operations/MigrationReconcileAction.ts

@@ -0,0 +1,23 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { trackOperatorOperation } from './control-plane'
+import { migrationPlan, reconcileMigrationLedgerPlan } from './migration-operations'
+import { stringValue } from './recovery-input'
+
+export default new Action({
+  name: 'MigrationReconcileAction',
+  description: 'Conservatively reconciles provable migration ledger drift.',
+  method: 'POST',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const input = request.all() as Record<string, unknown>
+    const plan = await migrationPlan()
+    if (stringValue(input.revision) !== plan.revision)
+      return response.json({ message: 'The migration state changed. Refresh before reconciling.' }, 409)
+    if (stringValue(input.confirmation) !== `reconcile ${plan.environment}`)
+      return response.json({ message: `Type reconcile ${plan.environment} to confirm ledger repair.` }, 422)
+    const tracked = await trackOperatorOperation(request, 'dashboard.migrations.reconcile', { revision: plan.revision }, () => reconcileMigrationLedgerPlan(true))
+    return { success: true, result: tracked.result, operation: tracked.operation }
+  },
+})

package/app/Actions/Dashboard/Operations/RecoveryDestinationStoreAction.ts

@@ -0,0 +1,91 @@
+import type { BackupDestinationProvider } from '@stacksjs/ts-cloud'
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
+import { appendOperatorEvent } from './control-plane'
+import { positiveNumber, stringValue } from './recovery-input'
+import { recoveryEnvironment, recoveryRuntime, safeRecoveryDestination } from './recovery-runtime'
+
+export default new Action({
+  name: 'RecoveryDestinationStoreAction',
+  description: 'Creates a native recovery destination with encrypted optional credentials.',
+  method: 'POST',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const input = request.all() as Record<string, unknown>
+    const name = stringValue(input.name)
+    const provider = stringValue(input.provider) as BackupDestinationProvider
+    const bucket = stringValue(input.bucket)
+    const encryption = stringValue(input.encryption) || 'provider'
+    if (!name)
+      return response.json({ message: 'A destination name is required.' }, 422)
+    if (!['aws_s3', 's3_compatible', 'aws_backup'].includes(provider))
+      return response.json({ message: 'Choose a supported destination provider.' }, 422)
+    if (provider !== 'aws_backup' && !bucket)
+      return response.json({ message: 'An object storage bucket is required.' }, 422)
+    if (!['provider', 'client_side', 'both'].includes(encryption))
+      return response.json({ message: 'Choose a supported encryption mode.' }, 422)
+
+    const runtime = recoveryRuntime()
+    const { controlPlane } = recoveryEnvironment()
+    const secretRoot = `secret://data-services/backups/${controlPlane.project.id}/${name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`
+    const credentials = input.credentials && typeof input.credentials === 'object'
+      ? input.credentials as Record<string, unknown>
+      : undefined
+    const accessKeyId = stringValue(credentials?.accessKeyId)
+    const secretAccessKey = stringValue(credentials?.secretAccessKey)
+    const sessionToken = stringValue(credentials?.sessionToken)
+    const encryptionKey = stringValue(input.encryptionKey)
+    const storedSecrets: string[] = []
+    if ((accessKeyId || secretAccessKey) && (!accessKeyId || !secretAccessKey))
+      return response.json({ message: 'Both access key id and secret access key are required.' }, 422)
+    if (encryption !== 'provider' && encryptionKey.length < 32)
+      return response.json({ message: 'Client encryption requires a key of at least 32 characters.' }, 422)
+
+    try {
+      let credentialRef: string | undefined
+      let encryptionKeyRef: string | undefined
+      if (accessKeyId || secretAccessKey) {
+        credentialRef = `${secretRoot}/credentials`
+        await runtime.secrets.put(credentialRef, JSON.stringify({ accessKeyId, secretAccessKey, ...(sessionToken ? { sessionToken } : {}) }))
+        storedSecrets.push(credentialRef)
+      }
+      if (encryption !== 'provider') {
+        encryptionKeyRef = `${secretRoot}/encryption-key`
+        await runtime.secrets.put(encryptionKeyRef, encryptionKey)
+        storedSecrets.push(encryptionKeyRef)
+      }
+
+      const destination = runtime.store.createDestination({
+        organizationId: controlPlane.organization.id,
+        projectId: controlPlane.project.id,
+        name,
+        provider,
+        endpoint: stringValue(input.endpoint) || undefined,
+        endpointPolicy: input.allowPrivate === true ? 'allow_private' : 'public_https',
+        bucket: bucket || undefined,
+        prefix: stringValue(input.prefix),
+        region: stringValue(input.region) || undefined,
+        forcePathStyle: input.forcePathStyle === true,
+        credentialRef,
+        encryption: encryption as 'provider' | 'client_side' | 'both',
+        encryptionKeyRef,
+        immutability: {
+          objectLock: Number(input.lockDays) > 0,
+          defaultRetentionDays: Number(input.lockDays) > 0 ? positiveNumber(input.lockDays, 1, 36_500) : undefined,
+        },
+        status: 'untested',
+      })
+      await appendOperatorEvent(request, 'backup.destination_created', {
+        destinationId: destination.id,
+        provider: destination.provider,
+      })
+      return response.json({ success: true, destination: safeRecoveryDestination(destination) }, 201)
+    }
+    catch (error) {
+      await Promise.all(storedSecrets.map(reference => runtime.secrets.remove(reference).catch(() => {})))
+      return dashboardOperationalError(error, 'The recovery destination could not be created.', 'RecoveryDestinationStoreAction', 422)
+    }
+  },
+})

package/app/Actions/Dashboard/Operations/RecoveryDestinationTestAction.ts

@@ -0,0 +1,34 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { S3BackupDestinationAdapter } from '@stacksjs/ts-cloud'
+import { appendOperatorEvent } from './control-plane'
+import { recoveryRuntime, safeRecoveryDestination } from './recovery-runtime'
+
+export default new Action({
+  name: 'RecoveryDestinationTestAction',
+  description: 'Tests recovery destination write, read, checksum, and cleanup behavior.',
+  method: 'POST',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const runtime = recoveryRuntime()
+    const destination = runtime.store.getDestination(String(request.getParam('id') || ''))
+    if (!destination)
+      return response.json({ message: 'Recovery destination not found.' }, 404)
+    if (destination.provider === 'aws_backup')
+      return response.json({ message: 'AWS Backup destinations are verified by creating a provider recovery point.' }, 409)
+
+    try {
+      await new S3BackupDestinationAdapter(runtime.secrets).test(destination)
+      const tested = runtime.store.recordDestinationTest(destination.id, { ok: true })
+      await appendOperatorEvent(request, 'backup.destination_tested', { destinationId: destination.id, ok: true })
+      return { success: true, destination: safeRecoveryDestination(tested), message: `${destination.name} passed write, read, checksum, and cleanup checks.` }
+    }
+    catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      runtime.store.recordDestinationTest(destination.id, { ok: false, error: message })
+      await appendOperatorEvent(request, 'backup.destination_tested', { destinationId: destination.id, ok: false })
+      return response.json({ message }, 502)
+    }
+  },
+})

package/app/Actions/Dashboard/Operations/RecoveryIndexAction.ts

@@ -0,0 +1,58 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { dashboardOperationalError } from '../dashboard-response'
+import { recoveryEnvironment, recoveryRuntime, safeRecoveryDestination } from './recovery-runtime'
+
+export default new Action({
+  name: 'RecoveryIndexAction',
+  description: 'Returns recovery coverage, destinations, policies, points, jobs, and eligible resources.',
+  method: 'GET',
+  apiResponse: true,
+  async handle(_request: RequestInstance) {
+    try {
+      const { controlPlane, environment } = recoveryEnvironment()
+      const runtime = recoveryRuntime()
+      const policies = runtime.store.listPolicies(controlPlane.project.id, environment.id)
+      const policyIds = new Set(policies.map(policy => policy.id))
+      const recoveryPoints = runtime.store
+        .listRecoveryPoints(controlPlane.project.id)
+        .filter(point => !point.policyId || policyIds.has(point.policyId))
+      const jobs = runtime.store
+        .listJobs(controlPlane.project.id)
+        .filter(job => !job.policyId || policyIds.has(job.policyId))
+      const coverage = runtime.store
+        .coverage(controlPlane.project.id)
+        .filter(item => policyIds.has(item.policy.id))
+      const resources = controlPlane.store.listResources(controlPlane.project.id, environment.id)
+      const dataServices = runtime.dataServices.list(controlPlane.project.id, environment.id).map(service => ({
+        id: service.id,
+        name: service.name,
+        engine: service.engine,
+        provider: service.provider,
+        status: service.status,
+      }))
+
+      return {
+        environment: { id: environment.id, name: environment.name, slug: environment.slug },
+        coverage,
+        destinations: runtime.store.listDestinations(controlPlane.project.id).map(safeRecoveryDestination),
+        policies,
+        recoveryPoints,
+        jobs,
+        resources: resources.map(resource => ({ id: resource.id, kind: resource.kind, name: resource.name, slug: resource.slug })),
+        dataServices,
+        summary: {
+          policies: policies.length,
+          protected: coverage.filter(item => !item.missedRpo && item.destinationHealthy).length,
+          missedRpo: coverage.filter(item => item.missedRpo).length,
+          unverified: recoveryPoints.filter(point => point.verificationState !== 'verified' && point.status === 'available').length,
+          queuedJobs: jobs.filter(job => job.status === 'queued' || job.status === 'running').length,
+          latestPoint: recoveryPoints.map(point => point.pointInTime).sort().at(-1) || null,
+        },
+      }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Recovery operations could not be loaded.', 'RecoveryIndexAction')
+    }
+  },
+})