@stacksjs/defaults 0.70.366 → 0.70.368

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

@@ -0,0 +1,72 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { appendOperatorEvent, dashboardOperator } from './control-plane'
+import { jsonObject, stringValue } from './recovery-input'
+import { recoveryEnvironment, recoveryRuntime } from './recovery-runtime'
+
+export default new Action({
+  name: 'RecoveryRestoreAction',
+  description: 'Validates or queues an isolated, in-place, or drill restore.',
+  method: 'POST',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const input = request.all() as Record<string, unknown>
+    const runtime = recoveryRuntime()
+    const { controlPlane } = recoveryEnvironment()
+    const point = runtime.store.getRecoveryPoint(String(request.getParam('id') || ''))
+    if (!point || point.projectId !== controlPlane.project.id)
+      return response.json({ message: 'Recovery point not found.' }, 404)
+
+    const mode = stringValue(input.mode) || 'isolated'
+    const targetName = stringValue(input.targetName)
+    const drill = input.drill === true
+    const execute = input.execute === true
+    if (!['isolated', 'in_place'].includes(mode))
+      return response.json({ message: 'Restore mode must be isolated or in_place.' }, 422)
+    if (!targetName)
+      return response.json({ message: 'A restore target name is required.' }, 422)
+    if (drill && mode === 'in_place')
+      return response.json({ message: 'Recovery drills require an isolated target.' }, 422)
+
+    const safetyBackupId = stringValue(input.safetyBackupId) || undefined
+    if (safetyBackupId) {
+      const safety = runtime.store.getRecoveryPoint(safetyBackupId)
+      if (!safety || safety.projectId !== controlPlane.project.id)
+        return response.json({ message: 'The safety recovery point was not found.' }, 422)
+    }
+    const target = point.kind === 'volume'
+      ? { ...jsonObject(input.target), volumeName: targetName, inPlace: mode === 'in_place' }
+      : point.kind === 'logical_database'
+        ? { ...jsonObject(input.target), targetId: targetName, dataServiceId: targetName, inPlace: mode === 'in_place' }
+        : { ...jsonObject(input.target), targetId: targetName, inPlace: mode === 'in_place' }
+    const restoreInput = {
+      mode: mode as 'isolated' | 'in_place',
+      target,
+      targetName,
+      confirm: stringValue(input.confirm) || undefined,
+      recentAuth: true,
+      downtimeAcknowledged: input.downtimeAcknowledged === true,
+      safetyBackupId,
+    }
+
+    try {
+      const plan = runtime.coordinator.planRestore(point, restoreInput)
+      if (!execute)
+        return { success: true, plan, productionExecutionCreated: false }
+
+      const actor = await dashboardOperator(request)
+      const job = runtime.coordinator.enqueueRestore(point, { ...restoreInput, drill, actorId: actor.id })
+      await appendOperatorEvent(request, drill ? 'backup.drill_queued' : 'backup.restore_queued', {
+        recoveryPointId: point.id,
+        backupJobId: job.id,
+        mode: restoreInput.mode,
+        target: targetName,
+      }, point.resourceId)
+      return response.json({ success: true, plan, job, productionExecutionCreated: true }, 202)
+    }
+    catch (error) {
+      return response.json({ message: error instanceof Error ? error.message : String(error) }, 409)
+    }
+  },
+})

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

@@ -0,0 +1,17 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { appendOperatorEvent } from './control-plane'
+import { recoveryRuntime } from './recovery-runtime'
+
+export default new Action({
+  name: 'RecoveryRetentionAction',
+  description: 'Queues cleanup of expired, unlocked, unheld recovery points.',
+  method: 'POST',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const jobs = recoveryRuntime().coordinator.enqueueRetention()
+    await appendOperatorEvent(request, 'backup.retention_queued', { jobs: jobs.length })
+    return response.json({ success: true, jobs, message: `Queued ${jobs.length} retention cleanup job${jobs.length === 1 ? '' : 's'}.` }, 202)
+  },
+})

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

@@ -0,0 +1,25 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { appendOperatorEvent, dashboardOperator } from './control-plane'
+import { recoveryEnvironment, recoveryRuntime } from './recovery-runtime'
+
+export default new Action({
+  name: 'RecoveryRunAction',
+  description: 'Queues an on-demand run for one configured recovery policy.',
+  method: 'POST',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const runtime = recoveryRuntime()
+    const { controlPlane, environment } = recoveryEnvironment()
+    const policy = runtime.store.getPolicy(String(request.getParam('id') || ''))
+    if (!policy || policy.projectId !== controlPlane.project.id || policy.environmentId !== environment.id)
+      return response.json({ message: 'Recovery policy not found.' }, 404)
+    if (!policy.enabled)
+      return response.json({ message: 'Enable this recovery policy before running it.' }, 409)
+    const actor = await dashboardOperator(request)
+    const job = runtime.coordinator.enqueueBackup(policy, new Date().toISOString(), actor.id)
+    await appendOperatorEvent(request, 'backup.run_queued', { policyId: policy.id, backupJobId: job.id }, policy.resourceId)
+    return response.json({ success: true, job, message: `Backup job ${job.id} was queued.` }, 202)
+  },
+})

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

@@ -0,0 +1,24 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { appendOperatorEvent } from './control-plane'
+import { recoveryEnvironment, recoveryRuntime } from './recovery-runtime'
+
+export default new Action({
+  name: 'RecoveryVerifyAction',
+  description: 'Queues independent verification for one available recovery point.',
+  method: 'POST',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const runtime = recoveryRuntime()
+    const { controlPlane } = recoveryEnvironment()
+    const point = runtime.store.getRecoveryPoint(String(request.getParam('id') || ''))
+    if (!point || point.projectId !== controlPlane.project.id)
+      return response.json({ message: 'Recovery point not found.' }, 404)
+    if (point.status !== 'available')
+      return response.json({ message: 'Only available recovery points can be verified.' }, 409)
+    const job = runtime.coordinator.enqueueVerification(point)
+    await appendOperatorEvent(request, 'backup.verification_queued', { recoveryPointId: point.id, backupJobId: job.id }, point.resourceId)
+    return response.json({ success: true, job, message: `Verification job ${job.id} was queued.` }, 202)
+  },
+})

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

@@ -0,0 +1,34 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { dashboardOperationalError } from '../dashboard-response'
+import { recentOperatorOperations } from './control-plane'
+import { listSchedulerTasks } from './scheduler-operations'
+
+export default new Action({
+  name: 'SchedulerIndexAction',
+  description: 'Lists registered scheduled tasks and their durable operator history.',
+  method: 'GET',
+  apiResponse: true,
+  async handle(_request: RequestInstance) {
+    try {
+      const tasks = await listSchedulerTasks()
+      const operations = recentOperatorOperations('dashboard.scheduler.', 20)
+      return {
+        tasks,
+        operations,
+        summary: {
+          total: tasks.length,
+          active: tasks.filter(task => task.enabled).length,
+          paused: tasks.filter(task => !task.enabled).length,
+          nextRun: tasks
+            .map(task => task.nextRun)
+            .filter((value): value is string => Boolean(value))
+            .sort()[0] || null,
+        },
+      }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Scheduler operations could not be loaded.', 'SchedulerIndexAction')
+    }
+  },
+})

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

@@ -0,0 +1,33 @@
+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 { runScheduledTask, SchedulerOperationError } from './scheduler-operations'
+
+export default new Action({
+  name: 'SchedulerRunAction',
+  description: 'Runs one registered scheduled task immediately and records the operation.',
+  method: 'POST',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const name = String(request.getParam('name') || '').trim()
+    if (!name)
+      return response.json({ message: 'A scheduled task name is required.' }, 422)
+
+    try {
+      const tracked = await trackOperatorOperation(
+        request,
+        'dashboard.scheduler.run',
+        { task: name },
+        () => runScheduledTask(name),
+      )
+      return { success: true, ...tracked.result, operation: tracked.operation }
+    }
+    catch (error) {
+      if (error instanceof SchedulerOperationError)
+        return response.json({ message: error.message }, error.message.includes('not found') ? 404 : 409)
+      return dashboardOperationalError(error, 'The scheduled task could not be run.', 'SchedulerRunAction', 500)
+    }
+  },
+})

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

@@ -0,0 +1,36 @@
+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 { SchedulerOperationError, setScheduledTaskEnabled } from './scheduler-operations'
+
+export default new Action({
+  name: 'SchedulerToggleAction',
+  description: 'Persists the active state of one scheduled task and records the operation.',
+  method: 'PATCH',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const name = String(request.getParam('name') || '').trim()
+    const enabled = request.get<unknown>('enabled')
+    if (!name)
+      return response.json({ message: 'A scheduled task name is required.' }, 422)
+    if (typeof enabled !== 'boolean')
+      return response.json({ message: 'The enabled field must be a boolean.' }, 422)
+
+    try {
+      const tracked = await trackOperatorOperation(
+        request,
+        `dashboard.scheduler.${enabled ? 'enable' : 'disable'}`,
+        { enabled, task: name },
+        () => setScheduledTaskEnabled(name, enabled),
+      )
+      return { success: true, ...tracked.result, operation: tracked.operation }
+    }
+    catch (error) {
+      if (error instanceof SchedulerOperationError)
+        return response.json({ message: error.message }, error.message.includes('not found') ? 404 : 409)
+      return dashboardOperationalError(error, 'The scheduled task could not be updated.', 'SchedulerToggleAction', 500)
+    }
+  },
+})

package/app/Actions/Dashboard/Operations/control-plane.ts

@@ -0,0 +1,150 @@
+import type { RequestInstance } from '@stacksjs/types'
+import type {
+  ControlPlaneActor,
+  ControlPlaneOperation,
+  DashboardControlPlane,
+  JsonValue,
+} from '@stacksjs/ts-cloud'
+import process from 'node:process'
+import { setStateDir } from '@stacksjs/ts-cloud'
+import { initializeDashboardControlPlane } from '@stacksjs/ts-cloud/deploy'
+import { tsCloud } from '~/config/cloud'
+
+let dashboardControlPlane: DashboardControlPlane | undefined
+
+export function operationsControlPlane(): DashboardControlPlane {
+  if (dashboardControlPlane)
+    return dashboardControlPlane
+
+  setStateDir(tsCloud.stateDir)
+  dashboardControlPlane = initializeDashboardControlPlane(process.cwd(), tsCloud)
+  return dashboardControlPlane
+}
+
+export async function dashboardOperator(request: RequestInstance): Promise<ControlPlaneActor> {
+  const controlPlane = operationsControlPlane()
+  const user = await request.user()
+  const id = Number(user?.id)
+  const externalId = Number.isSafeInteger(id) && id > 0 ? `stacks-user:${id}` : 'stacks-dashboard:local'
+  const kind = Number.isSafeInteger(id) && id > 0 ? 'user' : 'system'
+  const displayName = String(user?.name || user?.email || (kind === 'system' ? 'Local dashboard' : `User ${id}`))
+
+  return controlPlane.store.getActorByExternalId(kind, externalId)
+    ?? controlPlane.store.createActor({
+      kind,
+      externalId,
+      displayName,
+      metadata: {
+        source: 'stacks-dashboard',
+        ...(user?.email ? { email: String(user.email) } : {}),
+      },
+    })
+}
+
+export function operationsEnvironment(controlPlane = operationsControlPlane()) {
+  const requested = String(process.env.CLOUD_ENV || process.env.APP_ENV || process.env.NODE_ENV || 'development').toLowerCase()
+  return controlPlane.environments.get(requested)
+    ?? controlPlane.environments.get('development')
+    ?? controlPlane.environments.values().next().value
+}
+
+export async function trackOperatorOperation<T extends JsonValue>(
+  request: RequestInstance,
+  kind: string,
+  input: JsonValue,
+  execute: () => Promise<T>,
+): Promise<{ result: T, operation: ControlPlaneOperation }> {
+  const controlPlane = operationsControlPlane()
+  const actor = await dashboardOperator(request)
+  let operation = controlPlane.store.createOperation({
+    projectId: controlPlane.project.id,
+    environmentId: operationsEnvironment(controlPlane)?.id,
+    actorId: actor.id,
+    kind,
+    input,
+  })
+
+  operation = controlPlane.store.transitionOperation(operation.id, {
+    to: 'running',
+    expectedVersion: operation.version,
+  })
+  controlPlane.store.appendEvent({
+    organizationId: controlPlane.organization.id,
+    projectId: controlPlane.project.id,
+    operationId: operation.id,
+    actorId: actor.id,
+    correlationId: operation.correlationId,
+    type: `${kind}.started`,
+    payload: input,
+  })
+
+  try {
+    const result = await execute()
+    operation = controlPlane.store.transitionOperation(operation.id, {
+      to: 'succeeded',
+      expectedVersion: operation.version,
+      output: result,
+    })
+    controlPlane.store.appendEvent({
+      organizationId: controlPlane.organization.id,
+      projectId: controlPlane.project.id,
+      operationId: operation.id,
+      actorId: actor.id,
+      correlationId: operation.correlationId,
+      type: `${kind}.succeeded`,
+      payload: result,
+    })
+    return { result, operation }
+  }
+  catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    operation = controlPlane.store.transitionOperation(operation.id, {
+      to: 'failed',
+      expectedVersion: operation.version,
+      error: message,
+    })
+    controlPlane.store.appendEvent({
+      organizationId: controlPlane.organization.id,
+      projectId: controlPlane.project.id,
+      operationId: operation.id,
+      actorId: actor.id,
+      correlationId: operation.correlationId,
+      type: `${kind}.failed`,
+      level: 'error',
+      payload: { message },
+    })
+    throw error
+  }
+}
+
+export async function appendOperatorEvent(
+  request: RequestInstance,
+  type: string,
+  payload: JsonValue,
+  resourceId?: string,
+): Promise<void> {
+  const controlPlane = operationsControlPlane()
+  const actor = await dashboardOperator(request)
+  controlPlane.store.appendEvent({
+    organizationId: controlPlane.organization.id,
+    projectId: controlPlane.project.id,
+    resourceId,
+    actorId: actor.id,
+    type,
+    payload,
+  })
+}
+
+export function recentOperatorOperations(prefix: string, limit = 20): Array<ControlPlaneOperation & { actorName: string }> {
+  const controlPlane = operationsControlPlane()
+  return controlPlane.store
+    .listOperations({ projectId: controlPlane.project.id, limit: Math.max(limit * 5, 100) })
+    .filter(operation => operation.kind.startsWith(prefix))
+    .slice(0, limit)
+    .map(operation => ({
+      ...operation,
+      actorName: operation.actorId
+        ? controlPlane.store.getActor(operation.actorId)?.displayName || 'Unknown operator'
+        : 'System',
+    }))
+}

package/app/Actions/Dashboard/Operations/migration-operations.ts

@@ -0,0 +1,80 @@
+import process from 'node:process'
+import { auditMigrationLedger, previewPendingMigrations, reconcileMigrationLedger } from '@stacksjs/database'
+
+export interface MigrationPlanOperation {
+  kind: string
+  table: string
+  column?: string
+  sql?: string
+  destructive: boolean
+}
+
+export class MigrationOperationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'MigrationOperationError'
+  }
+}
+
+const destructiveKinds = new Set(['drop_table', 'drop_column', 'alter_column', 'truncate_table'])
+
+export async function migrationPlan() {
+  const [rawOperations, ledger] = await Promise.all([
+    previewPendingMigrations(),
+    auditMigrationLedger(),
+  ])
+  const operations: MigrationPlanOperation[] = rawOperations.map((operation) => ({
+    kind: String(operation.kind),
+    table: String(operation.table),
+    ...('column' in operation && operation.column ? { column: String(operation.column) } : {}),
+    ...('sql' in operation && operation.sql ? { sql: String(operation.sql) } : {}),
+    destructive: destructiveKinds.has(String(operation.kind)),
+  }))
+  const revision = new Bun.CryptoHasher('sha256')
+    .update(JSON.stringify({ operations, ledger: ledger.entries.map(entry => [entry.file, entry.status]) }))
+    .digest('hex')
+
+  return {
+    environment: String(process.env.APP_ENV || process.env.NODE_ENV || 'development'),
+    dialect: ledger.dialect,
+    operations,
+    revision,
+    applied: ledger.recordedCount,
+    ledger,
+    summary: {
+      pending: operations.length,
+      destructive: operations.filter(operation => operation.destructive).length,
+      drift: ledger.drift,
+      ledgerIssues: ledger.entries.filter(entry => !['applied', 'pending'].includes(entry.status)).length + ledger.orphans.length,
+    },
+  }
+}
+
+export async function applyMigrationPlan(input: { revision: string, confirmation: string }): Promise<{ message: string }> {
+  const plan = await migrationPlan()
+  if (input.revision !== plan.revision)
+    throw new MigrationOperationError('The migration plan changed. Refresh and review the new plan before applying it.')
+  if (input.confirmation !== `migrate ${plan.environment}`)
+    throw new MigrationOperationError(`Type migrate ${plan.environment} to confirm this schema change.`)
+  if (!plan.operations.length)
+    return { message: 'The database schema is already current.' }
+
+  const child = Bun.spawn([`${process.cwd()}/buddy`, 'migrate', '--force'], {
+    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,
+  ])
+  if (exitCode !== 0)
+    throw new MigrationOperationError(stderr.trim() || stdout.trim() || 'The migration command failed.')
+  return { message: `Applied ${plan.operations.length} planned schema operation${plan.operations.length === 1 ? '' : 's'}.` }
+}
+
+export async function reconcileMigrationLedgerPlan(apply = false) {
+  return await reconcileMigrationLedger({ dryRun: !apply })
+}

package/app/Actions/Dashboard/Operations/operations-runtime.ts

@@ -0,0 +1,11 @@
+import process from 'node:process'
+import { AlertStore, ReleaseStore, resolveAuthEncryptionKey } from '@stacksjs/ts-cloud'
+import { operationsControlPlane } from './control-plane'
+
+export function releaseStore(): ReleaseStore {
+  return new ReleaseStore(operationsControlPlane().store)
+}
+
+export function alertStore(): AlertStore {
+  return new AlertStore(operationsControlPlane().store, { encryptionKey: resolveAuthEncryptionKey(process.cwd()) })
+}

package/app/Actions/Dashboard/Operations/recovery-input.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'bun:test'
+import { jsonObject, positiveNumber, stringList, stringValue } from './recovery-input'
+
+describe('recovery input normalization', () => {
+  it('normalizes scalar and list input without accepting nested values', () => {
+    expect(stringValue('  backups  ')).toBe('backups')
+    expect(stringValue({ value: 'backups' })).toBe('')
+    expect(stringList('storage/app, public/uploads, ')).toEqual(['storage/app', 'public/uploads'])
+    expect(stringList([' storage/app ', null, 'public/uploads'])).toEqual(['storage/app', 'public/uploads'])
+  })
+
+  it('bounds positive recovery objectives and retention values', () => {
+    expect(positiveNumber('30', 7, 100)).toBe(30)
+    expect(positiveNumber(500, 7, 100)).toBe(100)
+    expect(positiveNumber(0, 7, 100)).toBe(7)
+  })
+
+  it('accepts only record-shaped restore metadata', () => {
+    expect(jsonObject({ engine: 'postgres' })).toEqual({ engine: 'postgres' })
+    expect(jsonObject(['postgres'])).toEqual({})
+  })
+})

package/app/Actions/Dashboard/Operations/recovery-input.ts

@@ -0,0 +1,33 @@
+import type { BackupResourceKind, JsonValue } from '@stacksjs/ts-cloud'
+
+export const RECOVERY_KINDS: BackupResourceKind[] = [
+  'managed_database',
+  'logical_database',
+  'volume',
+  'files',
+  'control_plane',
+  'infrastructure',
+]
+
+export function stringValue(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+export function stringList(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.map(stringValue).filter(Boolean)
+    : typeof value === 'string'
+      ? value.split(',').map(entry => entry.trim()).filter(Boolean)
+      : []
+}
+
+export function positiveNumber(value: unknown, fallback: number, maximum = Number.MAX_SAFE_INTEGER): number {
+  const number = Number(value)
+  return Number.isFinite(number) && number > 0 ? Math.min(maximum, number) : fallback
+}
+
+export function jsonObject(value: unknown): Record<string, JsonValue> {
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    return {}
+  return value as Record<string, JsonValue>
+}

package/app/Actions/Dashboard/Operations/recovery-runtime.ts

@@ -0,0 +1,99 @@
+import type {
+  BackupDestination,
+  BackupPolicy,
+  BackupSourceAdapter,
+  JsonValue,
+} from '@stacksjs/ts-cloud'
+import { join } from 'node:path'
+import process from 'node:process'
+import {
+  AwsDatabaseBackupSource,
+  AwsInfrastructureBackupSource,
+  BackupCoordinator,
+  BackupStore,
+  ControlPlaneBackupSource,
+  createBackupQueueHandlers,
+  DataServiceStore,
+  DockerVolumeBackupSource,
+  DurableOperationQueue,
+  DurableQueueWorker,
+  EncryptedDataSecretStore,
+  FilesystemBackupSource,
+  LogicalDatabaseBackupSource,
+  resolveAuthEncryptionKey,
+  S3BackupDestinationAdapter,
+} from '@stacksjs/ts-cloud'
+import { operationsControlPlane, operationsEnvironment } from './control-plane'
+
+export interface RecoveryRuntime {
+  store: BackupStore
+  coordinator: BackupCoordinator
+  queue: DurableOperationQueue
+  worker: DurableQueueWorker
+  dataServices: DataServiceStore
+  secrets: EncryptedDataSecretStore
+}
+
+let runtime: RecoveryRuntime | undefined
+
+export function recoveryRuntime(): RecoveryRuntime {
+  if (runtime)
+    return runtime
+
+  const controlPlane = operationsControlPlane()
+  const store = new BackupStore(controlPlane.store)
+  const queue = new DurableOperationQueue(controlPlane.store, { workerId: `stacks-dashboard:${process.pid}` })
+  const coordinator = new BackupCoordinator(store, queue)
+  const dataServices = new DataServiceStore(controlPlane.store)
+  const secrets = new EncryptedDataSecretStore(controlPlane.store, resolveAuthEncryptionKey(process.cwd()))
+  const destination = new S3BackupDestinationAdapter(secrets)
+
+  const resolveSource = (policy: BackupPolicy): BackupSourceAdapter | undefined => {
+    if (policy.resourceKind === 'managed_database')
+      return new AwsDatabaseBackupSource(dataServices)
+    if (policy.resourceKind === 'logical_database')
+      return new LogicalDatabaseBackupSource(dataServices, secrets)
+    if (policy.resourceKind === 'volume')
+      return new DockerVolumeBackupSource()
+    if (policy.resourceKind === 'files')
+      return new FilesystemBackupSource(process.cwd(), undefined, join(process.cwd(), 'storage', 'cloud', 'restores'))
+    if (policy.resourceKind === 'control_plane')
+      return new ControlPlaneBackupSource(controlPlane.store, process.cwd(), join(process.cwd(), 'storage', 'cloud', 'restores'))
+    if (policy.resourceKind === 'infrastructure')
+      return new AwsInfrastructureBackupSource()
+    return undefined
+  }
+
+  const handlers = createBackupQueueHandlers({
+    store,
+    queue,
+    resolveSource,
+    resolveDestination: (value: BackupDestination) => value.provider === 'aws_backup' ? undefined : destination,
+  })
+  const worker = new DurableQueueWorker(queue, handlers, {
+    parallelism: 2,
+    pollIntervalMs: 2_000,
+    onError: error => console.error('[dashboard/recovery] worker failed:', error),
+  }).start()
+
+  runtime = { store, coordinator, queue, worker, dataServices, secrets }
+  return runtime
+}
+
+export function recoveryEnvironment() {
+  const controlPlane = operationsControlPlane()
+  const environment = operationsEnvironment(controlPlane)
+  if (!environment)
+    throw new Error('No cloud environment is configured for recovery operations.')
+  return { controlPlane, environment }
+}
+
+export function safeRecoveryDestination(destination: BackupDestination): Record<string, JsonValue> {
+  return {
+    ...destination,
+    credentialRef: null,
+    encryptionKeyRef: null,
+    credentialsConfigured: Boolean(destination.credentialRef),
+    clientEncryptionConfigured: Boolean(destination.encryptionKeyRef),
+  }
+}

package/app/Actions/Dashboard/Operations/scheduler-operations.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'bun:test'
+import { parseSchedulerRegistry, SchedulerOperationError } from './scheduler-operations'
+
+describe('scheduler operations', () => {
+  it('parses the Buddy scheduler registry marker', () => {
+    const tasks = parseSchedulerRegistry([
+      'loading application',
+      'STACKS_SCHEDULE_JSON={"jobs":[{"name":"Cleanup","pattern":"0 * * * *","timezone":"UTC","nextRun":"2026-08-12T12:00:00.000Z","enabled":false}],"locks":[]}',
+    ].join('\n'))
+
+    expect(tasks).toEqual([{
+      name: 'Cleanup',
+      pattern: '0 * * * *',
+      timezone: 'UTC',
+      nextRun: '2026-08-12T12:00:00.000Z',
+      enabled: false,
+    }])
+  })
+
+  it('rejects unmarked output instead of guessing', () => {
+    expect(() => parseSchedulerRegistry('{"jobs":[]}')).toThrow(SchedulerOperationError)
+  })
+})