feat(dashboard): jobs + schedule API actions for the admin views

The dashboard at storage/framework/defaults/views/dashboard/jobs/*
and queue/index.stx already exist but call API endpoints that the
backend doesn't define yet — so the views render empty. This wires
the four canonical endpoints:

  GET  /api/buddy/jobs                — list pending + processing + failed
  POST /api/buddy/jobs/{id}/retry     — re-queue a failed job (resets attempts)
  POST /api/buddy/jobs/{id}/cancel    — set the cancellation flag the worker
                                        polls between iterations
  GET  /api/buddy/schedule            — registered scheduled tasks with
                                        last/next run times

Each action fails soft when its underlying table doesn't exist (most
common cause: the user hasn't run the queue/scheduler migrations yet)
so the dashboard renders a helpful empty state instead of a 500.

Author: chrisbbreuer

routes/buddy.ts

@@ -10,3 +10,12 @@ import { route } from '@stacksjs/router'
 
 route.get('/versions', 'Actions/Buddy/VersionsAction') // your-domain.com/api/buddy/versions
 route.get('/commands', 'Actions/Buddy/CommandsAction') // your-domain.com/api/buddy/commands
+
+// Admin-dashboard backends. The existing dashboard/jobs/*.stx views
+// expect these to exist; without them the dashboard renders empty
+// states. They're under /api/buddy/* so the same auth gate that
+// protects the rest of the buddy admin surface applies.
+route.get('/jobs', 'Actions/Buddy/JobsListAction')
+route.post('/jobs/{id}/retry', 'Actions/Buddy/JobRetryAction')
+route.post('/jobs/{id}/cancel', 'Actions/Buddy/JobCancelAction')
+route.get('/schedule', 'Actions/Buddy/ScheduleListAction')

storage/framework/defaults/app/Actions/Buddy/JobCancelAction.ts

@@ -0,0 +1,32 @@
+import { Action } from '@stacksjs/actions'
+
+/**
+ * POST /api/buddy/jobs/:id/cancel
+ *
+ * Mark an in-flight job as cancelled. Workers that call
+ * `isJobCancelled(id)` between iterations will see the flag and exit
+ * cleanly. The framework can't preempt a running handler, so the
+ * worker is responsible for honoring the cancellation between units
+ * of work.
+ */
+export default new Action({
+  name: 'Buddy Job Cancel',
+  description: 'Signal a running job to stop on its next checkpoint.',
+
+  async handle(request) {
+    const id = String(request.get('id', '') ?? '')
+    if (!id) return new Response(JSON.stringify({ error: 'missing id' }), { status: 400 })
+
+    try {
+      const { cancelJob } = await import('@stacksjs/queue')
+      await cancelJob(id)
+      return { ok: true, id }
+    }
+    catch (err) {
+      return new Response(
+        JSON.stringify({ error: err instanceof Error ? err.message : String(err) }),
+        { status: 500, headers: { 'Content-Type': 'application/json' } },
+      )
+    }
+  },
+})

storage/framework/defaults/app/Actions/Buddy/JobRetryAction.ts

@@ -0,0 +1,49 @@
+import { Action } from '@stacksjs/actions'
+
+/**
+ * POST /api/buddy/jobs/:id/retry
+ *
+ * Move a failed job back into the active queue. The dashboard's
+ * `jobs/history.stx` calls this when the user clicks "Retry" on a
+ * failed-job row.
+ */
+export default new Action({
+  name: 'Buddy Job Retry',
+  description: 'Re-queue a failed job for processing.',
+
+  async handle(request) {
+    const id = String(request.get('id', '') ?? '')
+    if (!id) return new Response(JSON.stringify({ error: 'missing id' }), { status: 400 })
+
+    try {
+      const { db } = await import('@stacksjs/database')
+      const dbAny = db as any
+
+      const failed = await dbAny.selectFrom('failed_jobs').selectAll().where('id', '=', id).executeTakeFirst()
+      if (!failed) {
+        return new Response(JSON.stringify({ error: 'failed job not found' }), { status: 404 })
+      }
+
+      // Move the row back to the live queue, resetting attempts so the
+      // worker doesn't immediately re-fail it.
+      const now = Math.floor(Date.now() / 1000)
+      await dbAny.insertInto('jobs').values({
+        queue: failed.queue,
+        payload: failed.payload,
+        attempts: 0,
+        reserved_at: null,
+        available_at: now,
+        created_at: new Date().toISOString().slice(0, 19).replace('T', ' '),
+      }).execute()
+      await dbAny.deleteFrom('failed_jobs').where('id', '=', id).execute()
+
+      return { ok: true, retriedAt: now }
+    }
+    catch (err) {
+      return new Response(
+        JSON.stringify({ error: err instanceof Error ? err.message : String(err) }),
+        { status: 500, headers: { 'Content-Type': 'application/json' } },
+      )
+    }
+  },
+})

storage/framework/defaults/app/Actions/Buddy/JobsListAction.ts

@@ -0,0 +1,141 @@
+import { Action } from '@stacksjs/actions'
+
+/**
+ * GET /api/buddy/jobs
+ *
+ * Powers the existing `dashboard/jobs/history.stx` view. Reads the
+ * `jobs` and `failed_jobs` tables and merges them into a single
+ * timeline shape the dashboard already understands.
+ *
+ * Query params:
+ *   - status: 'all' | 'queued' | 'processing' | 'completed' | 'failed'
+ *   - queue:  'all' | <queue-name>
+ *   - q:      free-text filter on job name
+ *   - page, perPage: pagination
+ */
+export default new Action({
+  name: 'Buddy Jobs List',
+  description: 'List queued, in-flight, completed, and failed jobs for the admin dashboard.',
+
+  async handle(request) {
+    const status = String(request.get('status', 'all') ?? 'all')
+    const queue = String(request.get('queue', 'all') ?? 'all')
+    const q = String(request.get('q', '') ?? '')
+    const page = Math.max(1, Number(request.get('page', 1) ?? 1))
+    const perPage = Math.min(100, Math.max(1, Number(request.get('perPage', 25) ?? 25)))
+
+    try {
+      const { db } = await import('@stacksjs/database')
+      const dbAny = db as any
+
+      // Pull the live `jobs` table — this contains queued + reserved (processing) rows.
+      let pendingQuery = dbAny.selectFrom('jobs').selectAll()
+      if (queue !== 'all') pendingQuery = pendingQuery.where('queue', '=', queue)
+      if (q) pendingQuery = pendingQuery.where('payload', 'like', `%${q}%`)
+
+      // Pull the failed_jobs table for the failed status.
+      let failedQuery = dbAny.selectFrom('failed_jobs').selectAll()
+      if (queue !== 'all') failedQuery = failedQuery.where('queue', '=', queue)
+      if (q) failedQuery = failedQuery.where('payload', 'like', `%${q}%`)
+
+      const [pending, failed] = await Promise.all([
+        status === 'failed' ? Promise.resolve([]) : pendingQuery.execute(),
+        status === 'queued' || status === 'processing' || status === 'completed' ? Promise.resolve([]) : failedQuery.execute(),
+      ])
+
+      const normalized = [
+        ...(pending as Array<Record<string, unknown>>).map(row => normalizePending(row, status)),
+        ...(failed as Array<Record<string, unknown>>).map(normalizeFailed),
+      ]
+        .filter((j): j is NonNullable<typeof j> => j !== null)
+        .sort((a, b) => (b.created_at?.localeCompare(a.created_at ?? '') ?? 0))
+
+      const total = normalized.length
+      const start = (page - 1) * perPage
+      const items = normalized.slice(start, start + perPage)
+
+      return {
+        items,
+        total,
+        page,
+        perPage,
+        totalPages: Math.max(1, Math.ceil(total / perPage)),
+      }
+    }
+    catch (err) {
+      // Fail soft so the dashboard can render an empty state instead of
+      // an opaque 500. Surface the underlying message so it's visible
+      // in the dev-mode error toast.
+      return {
+        items: [],
+        total: 0,
+        page,
+        perPage,
+        totalPages: 1,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  },
+})
+
+interface NormalizedJob {
+  id: string
+  name: string
+  queue: string
+  status: 'queued' | 'processing' | 'completed' | 'failed'
+  attempts: number
+  runtime?: number
+  started_at?: string
+  finished_at?: string
+  error?: string
+  payload: unknown
+  created_at?: string
+}
+
+function normalizePending(row: Record<string, unknown>, statusFilter: string): NormalizedJob | null {
+  const status: NormalizedJob['status'] = row.reserved_at ? 'processing' : 'queued'
+  if (statusFilter !== 'all' && statusFilter !== status) return null
+  let payload: unknown = row.payload
+  let name = 'unknown'
+  if (typeof payload === 'string') {
+    try {
+      const parsed = JSON.parse(payload) as { jobName?: string }
+      name = parsed.jobName ?? 'unknown'
+      payload = parsed
+    }
+    catch { /* leave as raw string */ }
+  }
+  return {
+    id: String(row.id ?? ''),
+    name,
+    queue: String(row.queue ?? 'default'),
+    status,
+    attempts: Number(row.attempts ?? 0),
+    payload,
+    created_at: row.created_at ? String(row.created_at) : undefined,
+  }
+}
+
+function normalizeFailed(row: Record<string, unknown>): NormalizedJob {
+  let payload: unknown = row.payload
+  let name = 'unknown'
+  if (typeof payload === 'string') {
+    try {
+      const parsed = JSON.parse(payload) as { jobName?: string }
+      name = parsed.jobName ?? 'unknown'
+      payload = parsed
+    }
+    catch { /* leave as raw */ }
+  }
+  return {
+    id: String(row.id ?? ''),
+    name,
+    queue: String(row.queue ?? 'default'),
+    status: 'failed',
+    attempts: Number(row.attempts ?? 0),
+    error: row.exception ? String(row.exception) : undefined,
+    finished_at: row.failed_at ? String(row.failed_at) : undefined,
+    payload,
+    created_at: row.failed_at ? String(row.failed_at) : undefined,
+  }
+}

storage/framework/defaults/app/Actions/Buddy/ScheduleListAction.ts

@@ -0,0 +1,52 @@
+import { Action } from '@stacksjs/actions'
+
+/**
+ * GET /api/buddy/schedule
+ *
+ * Snapshot of every registered scheduled task — pattern, last run,
+ * next run, status — for the admin dashboard's schedule view.
+ *
+ * Reads from the queue/database scheduler's `scheduled_jobs` table
+ * if it exists, falling back to an empty list otherwise so the
+ * dashboard doesn't 500 on apps that don't use scheduled jobs.
+ */
+export default new Action({
+  name: 'Buddy Schedule List',
+  description: 'List registered scheduled tasks with their next/last run times.',
+
+  async handle() {
+    try {
+      const { db } = await import('@stacksjs/database')
+      const dbAny = db as any
+
+      const rows = await dbAny
+        .selectFrom('scheduled_jobs')
+        .selectAll()
+        .orderBy('next_run_at', 'asc')
+        .execute()
+
+      return {
+        items: (rows as Array<Record<string, unknown>>).map(row => ({
+          id: String(row.id ?? ''),
+          name: String(row.name ?? row.action ?? 'unnamed'),
+          pattern: String(row.cron_expression ?? row.pattern ?? '?'),
+          timezone: row.timezone ? String(row.timezone) : null,
+          lastRunAt: row.last_run_at ? String(row.last_run_at) : null,
+          nextRunAt: row.next_run_at ? String(row.next_run_at) : null,
+          enabled: row.enabled !== false,
+          consecutiveFailures: Number(row.consecutive_failures ?? 0),
+        })),
+      }
+    }
+    catch (err) {
+      // Most common cause: the scheduled_jobs table doesn't exist
+      // because the user hasn't run the scheduler migration. Return
+      // an empty list with a hint instead of a 500.
+      return {
+        items: [],
+        error: err instanceof Error ? err.message : String(err),
+        hint: 'If you see "no such table: scheduled_jobs", run `buddy migrate`.',
+      }
+    }
+  },
+})