@stacksjs/defaults 0.70.229 → 0.70.231

package/app/Actions/Dashboard/Jobs/job-records.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  matchesJobSearch,
+  normalizeActiveJob,
+  normalizeFailedJob,
+  parseJobReference,
+} from './job-records'
+
+function record(values: Record<string, unknown>) {
+  return {
+    get(key: string) {
+      return values[key]
+    },
+  }
+}
+
+describe('dashboard job records', () => {
+  it('normalizes an active job with recorded queue state', () => {
+    expect(normalizeActiveJob(record({
+      id: 7,
+      queue: 'emails',
+      payload: JSON.stringify({ jobName: 'SendWelcomeEmail', payload: { userId: 4 }, options: { tries: 2 } }),
+      attempts: 1,
+      available_at: 1785000000,
+      reserved_at: null,
+      created_at: '2026-07-29 12:00:00',
+      updated_at: null,
+    }))).toMatchObject({
+      id: 'job-7',
+      recordId: '7',
+      source: 'job',
+      name: 'SendWelcomeEmail',
+      queue: 'emails',
+      connection: null,
+      status: 'queued',
+      attempts: 1,
+      maxAttempts: 2,
+      duration: null,
+      runtime: null,
+    })
+  })
+
+  it('derives processing state from the native reservation timestamp', () => {
+    const job = normalizeActiveJob(record({
+      id: 8,
+      queue: 'default',
+      payload: 'legacy payload',
+      attempts: 1,
+      available_at: 1785000000,
+      reserved_at: 1785000010,
+      created_at: '2026-07-29 12:00:00',
+      updated_at: null,
+    }))
+
+    expect(job.status).toBe('processing')
+    expect(job.reserved_at).toBe('2026-07-25T17:20:10.000Z')
+    expect(job.maxAttempts).toBeNull()
+  })
+
+  it('normalizes persisted failure metrics without inventing diagnostics', () => {
+    expect(normalizeFailedJob(record({
+      id: 3,
+      connection: 'database',
+      queue: 'default',
+      payload: '{"displayName":"SyncSearchIndex"}',
+      exception: 'Search service unavailable',
+      attempts: 2,
+      max_attempts: 2,
+      duration_ms: 184,
+      failed_at: '2026-07-29 12:05:00',
+      created_at: '2026-07-29 12:00:00',
+      updated_at: null,
+    }))).toMatchObject({
+      id: 'failed-3',
+      recordId: '3',
+      source: 'failed',
+      name: 'SyncSearchIndex',
+      connection: 'database',
+      status: 'failed',
+      attempts: 2,
+      maxAttempts: 2,
+      duration: '184ms',
+      runtime: 184,
+      error: 'Search service unavailable',
+      finished_at: '2026-07-29T12:05:00.000Z',
+    })
+  })
+
+  it('keeps unavailable metrics null for legacy failed rows', () => {
+    const job = normalizeFailedJob(record({
+      id: 4,
+      connection: 'database',
+      queue: 'default',
+      payload: '{"displayName":"LegacyJob"}',
+      exception: 'Legacy failure',
+      attempts: null,
+      max_attempts: null,
+      duration_ms: null,
+      failed_at: null,
+      created_at: '2026-07-29 12:00:00',
+      updated_at: null,
+    }))
+
+    expect(job.attempts).toBeNull()
+    expect(job.maxAttempts).toBeNull()
+    expect(job.duration).toBeNull()
+    expect(job.finished_at).toBeUndefined()
+  })
+
+  it('parses typed and legacy job references', () => {
+    expect(parseJobReference('failed-42')).toEqual({ source: 'failed', id: '42' })
+    expect(parseJobReference('job-9')).toEqual({ source: 'job', id: '9' })
+    expect(parseJobReference('12')).toEqual({ source: null, id: '12' })
+  })
+
+  it('searches job identifiers, metadata, errors, and payload values', () => {
+    const job = normalizeFailedJob(record({
+      id: 15,
+      connection: 'database',
+      queue: 'emails',
+      payload: '{"displayName":"SendWelcomeEmail","recipient":"operator@example.com"}',
+      exception: 'SMTP connection refused',
+      attempts: null,
+      max_attempts: null,
+      duration_ms: null,
+      failed_at: '2026-07-29 12:05:00',
+      created_at: '2026-07-29 12:00:00',
+      updated_at: null,
+    }))
+
+    expect(matchesJobSearch(job, 'failed-15')).toBe(true)
+    expect(matchesJobSearch(job, '15')).toBe(true)
+    expect(matchesJobSearch(job, 'EMAILS')).toBe(true)
+    expect(matchesJobSearch(job, 'connection refused')).toBe(true)
+    expect(matchesJobSearch(job, 'operator@example.com')).toBe(true)
+    expect(matchesJobSearch(job, 'missing')).toBe(false)
+  })
+
+  it('rejects corrupted persisted queue fields', () => {
+    const values: Record<string, unknown> = {
+      id: 4,
+      queue: 'emails',
+      payload: '{"jobName":"SendWelcomeEmail","options":{"tries":3}}',
+      attempts: 1,
+      available_at: 1785000000,
+      reserved_at: null,
+      created_at: '2026-07-29 12:00:00',
+      updated_at: null,
+    }
+    const job = record(values)
+
+    expect(normalizeActiveJob(job).maxAttempts).toBe(3)
+    values.attempts = 'unknown'
+    expect(() => normalizeActiveJob(job)).toThrow('Job.attempts must be an integer')
+    values.attempts = 1
+    values.payload = '{"jobName":"SendWelcomeEmail","options":{"tries":0}}'
+    expect(() => normalizeActiveJob(job)).toThrow('options.tries must be a positive integer')
+  })
+})

package/app/Actions/Dashboard/Jobs/job-records.ts

@@ -0,0 +1,221 @@
+export type JobRecordSource = 'job' | 'failed'
+export type DashboardJobStatus = 'queued' | 'processing' | 'failed'
+
+export interface ModelRecord {
+  get: (key: string) => unknown
+}
+
+export interface NormalizedJob {
+  id: string
+  recordId: string
+  source: JobRecordSource
+  name: string
+  queue: string
+  connection: string | null
+  status: DashboardJobStatus
+  attempts: number | null
+  maxAttempts: number | null
+  duration: string | null
+  runtime: number | null
+  error?: string
+  payload: unknown
+  created_at: string
+  updated_at?: string
+  available_at?: string
+  reserved_at?: string
+  started_at?: string
+  finished_at?: string
+}
+
+export function parsePayload(payload: unknown): unknown {
+  if (typeof payload !== 'string')
+    throw new TypeError('Job.payload must be a string.')
+  try {
+    return JSON.parse(payload)
+  }
+  catch {
+    return payload
+  }
+}
+
+function recordId(record: ModelRecord): string {
+  const value = record.get('id')
+  const id = typeof value === 'number'
+    ? value
+    : typeof value === 'string' && value.trim() ? Number(value) : Number.NaN
+  if (!Number.isInteger(id) || id < 1)
+    throw new TypeError('Job.id must be a positive integer.')
+  return String(id)
+}
+
+export function jobReference(source: JobRecordSource, id: string): string {
+  return `${source}-${id}`
+}
+
+export function parseJobReference(reference: string): { source: JobRecordSource | null, id: string } {
+  const match = reference.match(/^(job|failed)-(.+)$/)
+  if (!match)
+    return { source: null, id: reference }
+  return {
+    source: match[1] as JobRecordSource,
+    id: match[2]!,
+  }
+}
+
+function requiredString(record: ModelRecord, key: string, model = 'Job'): string {
+  const value = record.get(key)
+  if (typeof value !== 'string' || !value.trim())
+    throw new TypeError(`${model}.${key} must be a non-empty string.`)
+  return value
+}
+
+function integerValue(
+  record: ModelRecord,
+  key: string,
+  model = 'Job',
+  minimum = 0,
+  optional = false,
+): number | null {
+  const value = record.get(key)
+  if (optional && (value === null || value === undefined))
+    return null
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string' && value.trim() ? Number(value) : Number.NaN
+  if (!Number.isInteger(parsed) || parsed < minimum)
+    throw new TypeError(`${model}.${key} must be an integer of at least ${minimum}.`)
+  return parsed
+}
+
+function timestampValue(
+  record: ModelRecord,
+  key: string,
+  model = 'Job',
+  optional = false,
+): string | undefined {
+  const value = record.get(key)
+  if (optional && (value === null || value === undefined || value === ''))
+    return undefined
+
+  let time = Number.NaN
+  if (typeof value === 'number' && Number.isInteger(value) && value >= 0)
+    time = value * 1000
+  else if (typeof value === 'string' && value.trim())
+    time = new Date(/^\d{4}-\d{2}-\d{2} \d/.test(value) ? `${value.replace(' ', 'T')}Z` : value).getTime()
+
+  if (!Number.isFinite(time))
+    throw new TypeError(`${model}.${key} must be a valid timestamp.`)
+  return new Date(time).toISOString()
+}
+
+function jobName(payload: unknown, fallback: string): string {
+  if (payload && typeof payload === 'object') {
+    const object = payload as { displayName?: unknown, job?: unknown, jobName?: unknown }
+    for (const value of [object.jobName, object.displayName, object.job]) {
+      if (typeof value === 'string' && value.trim())
+        return value.replace(/^.*\\/, '')
+    }
+  }
+  return fallback
+}
+
+function payloadMaxAttempts(payload: unknown): number | null {
+  if (!payload || typeof payload !== 'object')
+    return null
+
+  const object = payload as { displayName?: unknown, job?: unknown, jobName?: unknown, options?: unknown }
+  const hasNativeName = typeof object.jobName === 'string' && Boolean(object.jobName.trim())
+  if (!hasNativeName)
+    return null
+
+  const options = object.options
+  if (options === null || options === undefined)
+    return 1
+  if (typeof options !== 'object')
+    throw new TypeError('Job.payload.options must be an object.')
+
+  const tries = (options as { tries?: unknown }).tries
+  if (tries === null || tries === undefined)
+    return 1
+  const parsed = typeof tries === 'number'
+    ? tries
+    : typeof tries === 'string' && tries.trim() ? Number(tries) : Number.NaN
+  if (!Number.isInteger(parsed) || parsed < 1)
+    throw new TypeError('Job.payload.options.tries must be a positive integer.')
+  return parsed
+}
+
+export function normalizeActiveJob(record: ModelRecord): NormalizedJob {
+  const id = recordId(record)
+  const payload = parsePayload(record.get('payload'))
+  const queue = requiredString(record, 'queue')
+  const reservedAt = timestampValue(record, 'reserved_at', 'Job', true)
+
+  return {
+    id: jobReference('job', id),
+    recordId: id,
+    source: 'job',
+    name: jobName(payload, queue),
+    queue,
+    connection: null,
+    status: reservedAt ? 'processing' : 'queued',
+    attempts: integerValue(record, 'attempts'),
+    maxAttempts: payloadMaxAttempts(payload),
+    duration: null,
+    runtime: null,
+    payload,
+    created_at: timestampValue(record, 'created_at')!,
+    updated_at: timestampValue(record, 'updated_at', 'Job', true),
+    available_at: timestampValue(record, 'available_at', 'Job', true),
+    reserved_at: reservedAt,
+    started_at: reservedAt,
+  }
+}
+
+export function normalizeFailedJob(record: ModelRecord): NormalizedJob {
+  const id = recordId(record)
+  const payload = parsePayload(record.get('payload'))
+  const failedAt = timestampValue(record, 'failed_at', 'FailedJob', true)
+  const runtime = integerValue(record, 'duration_ms', 'FailedJob', 0, true)
+  const queue = requiredString(record, 'queue', 'FailedJob')
+
+  return {
+    id: jobReference('failed', id),
+    recordId: id,
+    source: 'failed',
+    name: jobName(payload, queue),
+    queue,
+    connection: requiredString(record, 'connection', 'FailedJob'),
+    status: 'failed',
+    attempts: integerValue(record, 'attempts', 'FailedJob', 0, true),
+    maxAttempts: integerValue(record, 'max_attempts', 'FailedJob', 1, true),
+    duration: runtime === null ? null : `${runtime}ms`,
+    runtime,
+    error: requiredString(record, 'exception', 'FailedJob'),
+    payload,
+    created_at: timestampValue(record, 'created_at', 'FailedJob')!,
+    updated_at: timestampValue(record, 'updated_at', 'FailedJob', true),
+    finished_at: failedAt,
+  }
+}
+
+export function matchesJobSearch(job: NormalizedJob, search: string): boolean {
+  const query = search.trim().toLowerCase()
+  if (!query)
+    return true
+
+  const payload = typeof job.payload === 'string'
+    ? job.payload
+    : JSON.stringify(job.payload ?? '')
+
+  return [
+    job.id,
+    job.recordId,
+    job.name,
+    job.queue,
+    job.connection || '',
+    job.status,
+    job.error || '',
+    payload,
+  ].some(value => value.toLowerCase().includes(query))
+}

package/app/Actions/Dashboard/Kanban/BoardDestroyAction.ts

@@ -1,5 +1,6 @@
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
+import { kanbanError } from './kanban-response'
 
 /**
  * `DELETE /api/dashboard/kanban/boards/:id` (stacksjs/stacks#1846 Phase 2).
@@ -26,18 +27,12 @@ export default new Action({
     const rawId = (request as any)?.params?.id ?? (request as any)?.param?.('id') ?? null
     const id = Number(rawId)
     if (!Number.isFinite(id) || id <= 0) {
-      return { error: 'Invalid board id', status: 400 }
+      return kanbanError('Invalid board id', 400)
     }
 
     try {
-      // Wrap in a transaction so partial failures roll back. If the
-      // active dialect doesn't support transactions through
-      // `db.transaction` (some shapes pass through to the underlying
-      // bun-query-builder which has driver-specific implementations),
-      // fall through to a best-effort sequential delete — the deletes
-      // are idempotent, so re-running the same DELETE on the same id
-      // is safe.
-      const txOps = async (qb: any) => {
+      await db.transaction(async (rawTrx) => {
+        const qb = rawTrx as unknown as typeof db
         // Pivots + card-scoped children first — they reference cards.
         await qb.unsafe(
           'DELETE FROM card_labels WHERE card_id IN (SELECT id FROM cards WHERE board_id = ?)',
@@ -60,25 +55,13 @@ export default new Action({
         await qb.deleteFrom('labels').where('board_id', '=', id).execute()
         // Finally the board itself.
         await qb.deleteFrom('boards').where('id', '=', id).execute()
-      }
-
-      try {
-        await (db as any).transaction(txOps)
-      }
-      catch (txErr) {
-        // Transaction unavailable or driver-specific shape failed —
-        // run sequentially. If this fails mid-way the next call to
-        // the same action will pick up where the previous one left
-        // off (all deletes are idempotent).
-        console.warn('[dashboard/kanban] BoardDestroyAction transaction unavailable, falling back to sequential:', txErr)
-        await txOps(db)
-      }
+      })
 
       return { deleted: true, id }
     }
     catch (err) {
       console.error('[dashboard/kanban] BoardDestroyAction failed:', err)
-      return { error: err instanceof Error ? err.message : 'unknown error', status: 500 }
+      return kanbanError(err instanceof Error ? err.message : 'unknown error', 500)
     }
   },
 })

package/app/Actions/Dashboard/Kanban/BoardShowAction.ts

@@ -1,5 +1,6 @@
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
+import { kanbanError } from './kanban-response'
 
 interface BoardRow {
   id: number
@@ -83,7 +84,7 @@ export default new Action({
       ?? null
     const id = Number(rawId)
     if (!Number.isFinite(id) || id <= 0) {
-      return { error: 'Invalid board id', status: 400 }
+      return kanbanError('Invalid board id', 400)
     }
 
     try {
@@ -93,7 +94,7 @@ export default new Action({
       ).execute() as BoardRow[]
       const board = boards[0]
       if (!board) {
-        return { error: 'Board not found', status: 404 }
+        return kanbanError('Board not found', 404)
       }
 
       const [columns, cards, labels] = await Promise.all([
@@ -206,10 +207,7 @@ export default new Action({
     }
     catch (err) {
       console.error('[dashboard/kanban] BoardShowAction failed:', err)
-      return {
-        error: err instanceof Error ? err.message : 'unknown error',
-        status: 500,
-      }
+      return kanbanError(err instanceof Error ? err.message : 'unknown error', 500)
     }
   },
 })

package/app/Actions/Dashboard/Kanban/BoardStoreAction.ts

@@ -1,5 +1,7 @@
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
+import { Board } from '@stacksjs/orm'
+import { kanbanError } from './kanban-response'
 
 interface BoardInput {
   name?: unknown
@@ -13,9 +15,8 @@ interface BoardInput {
  *
  * Creates a new board with sensible defaults and appends it to the
  * end of the boards list (`position = max(position) + 1` so the new
- * row shows up last in the index). Returns the inserted row including
- * its id so the optimistic-insert in the dashboard store can swap its
- * temp placeholder for the real record.
+ * row shows up last in the index). Returns the created model including
+ * its id so the dashboard store can reconcile its optimistic state.
  *
  * Validation: title required + length-bounded; everything else is
  * optional with model-level defaults. The validation rules on the
@@ -32,7 +33,7 @@ export default new Action({
 
     const name = typeof body.name === 'string' ? body.name.trim() : ''
     if (!name || name.length > 120) {
-      return { error: 'Name is required and must be 1-120 characters.', status: 400 }
+      return kanbanError('Name is required and must be 1-120 characters.', 400)
     }
     const description = typeof body.description === 'string' ? body.description.trim() : null
     const icon = typeof body.icon === 'string' && body.icon ? body.icon : 'rectangle.stack.fill'
@@ -49,50 +50,34 @@ export default new Action({
       ).execute() as Array<{ m: number }>
       const nextPosition = (Number(maxRow?.[0]?.m ?? -1) + 1) || 0
 
-      await db.insertInto('boards').values({
+      const board = await Board.create({
         name,
         description,
         icon,
         color,
         position: nextPosition,
-        archived: 0,
-      }).execute()
-
-      // SELECT the inserted row back. MySQL doesn't support RETURNING,
-      // so we use the (name, position) pair as a best-effort identifier
-      // — append-only with a unique position keeps this reliable.
-      const inserted = await db.unsafe(
-        `SELECT id, uuid, name, description, icon, color, position, archived, created_at, updated_at
-        FROM boards
-        WHERE name = ? AND position = ?
-        ORDER BY id DESC
-        LIMIT 1`,
-        [name, nextPosition],
-      ).execute() as Array<{ id: number, uuid: string | null, name: string, description: string | null, icon: string, color: string, position: number, archived: number, created_at: string | null, updated_at: string | null }>
-      const row = inserted?.[0]
-      if (!row) {
-        return { error: 'Board insert succeeded but follow-up read returned nothing.', status: 500 }
-      }
+        archived: false,
+      })
 
       return {
         board: {
-          id: row.id,
-          uuid: row.uuid,
-          name: row.name,
-          description: row.description,
-          icon: row.icon,
-          color: row.color,
-          position: row.position,
-          archived: row.archived === 1,
+          id: Number(board.get('id')),
+          uuid: board.get('uuid') == null ? null : String(board.get('uuid')),
+          name,
+          description,
+          icon,
+          color,
+          position: nextPosition,
+          archived: false,
           cardCount: 0,
-          createdAt: row.created_at,
-          updatedAt: row.updated_at,
+          createdAt: board.get('createdAt') ?? board.get('created_at') ?? null,
+          updatedAt: board.get('updatedAt') ?? board.get('updated_at') ?? null,
         },
       }
     }
     catch (err) {
       console.error('[dashboard/kanban] BoardStoreAction failed:', err)
-      return { error: err instanceof Error ? err.message : 'unknown error', status: 500 }
+      return kanbanError(err instanceof Error ? err.message : 'unknown error', 500)
     }
   },
 })

package/app/Actions/Dashboard/Kanban/BoardUpdateAction.ts

@@ -1,5 +1,7 @@
 import { Action } from '@stacksjs/actions'
-import { db } from '@stacksjs/database'
+import { Board } from '@stacksjs/orm'
+import { modelBoolean, modelNullableString, modelNumber, modelString, refreshModel } from './kanban-model'
+import { kanbanError } from './kanban-response'
 
 interface BoardInput {
   name?: unknown
@@ -32,7 +34,7 @@ export default new Action({
     const rawId = (request as any)?.params?.id ?? (request as any)?.param?.('id') ?? null
     const id = Number(rawId)
     if (!Number.isFinite(id) || id <= 0) {
-      return { error: 'Invalid board id', status: 400 }
+      return kanbanError('Invalid board id', 400)
     }
 
     const body = (request as any).jsonBody as BoardInput | undefined ?? {}
@@ -41,7 +43,7 @@ export default new Action({
     if (typeof body.name === 'string') {
       const name = body.name.trim()
       if (!name || name.length > 120) {
-        return { error: 'Name must be 1-120 characters.', status: 400 }
+        return kanbanError('Name must be 1-120 characters.', 400)
       }
       set.name = name
     }
@@ -53,44 +55,36 @@ export default new Action({
     if (typeof body.color === 'string' && body.color)
       set.color = body.color
     if (typeof body.archived === 'boolean')
-      set.archived = body.archived ? 1 : 0
+      set.archived = body.archived
 
     if (Object.keys(set).length === 0) {
-      return { error: 'No updatable fields provided.', status: 400 }
+      return kanbanError('No updatable fields provided.', 400)
     }
 
     try {
-      // The `db.updateTable` chain works across dialects; we accumulate
-      // the partial set above and apply it in one statement.
-      await db.updateTable('boards').set(set as any).where('id', '=', id).execute()
+      const board = await Board.find(id)
+      if (!board)
+        return kanbanError('Board not found', 404)
+      const updated = await refreshModel(await board.update(set))
 
-      const rows = await db.unsafe(
-        `SELECT id, uuid, name, description, icon, color, position, archived, created_at, updated_at
-        FROM boards WHERE id = ? LIMIT 1`,
-        [id],
-      ).execute() as Array<Record<string, unknown>>
-      const r = rows?.[0]
-      if (!r) {
-        return { error: 'Board not found', status: 404 }
-      }
       return {
         board: {
-          id: Number(r.id),
-          uuid: r.uuid == null ? null : String(r.uuid),
-          name: String(r.name),
-          description: r.description == null ? null : String(r.description),
-          icon: String(r.icon),
-          color: String(r.color),
-          position: Number(r.position),
-          archived: Number(r.archived) === 1,
-          createdAt: r.created_at == null ? null : String(r.created_at),
-          updatedAt: r.updated_at == null ? null : String(r.updated_at),
+          id: modelNumber(updated, 'id'),
+          uuid: modelNullableString(updated, 'uuid'),
+          name: modelString(updated, 'name'),
+          description: modelNullableString(updated, 'description'),
+          icon: modelString(updated, 'icon'),
+          color: modelString(updated, 'color'),
+          position: modelNumber(updated, 'position'),
+          archived: modelBoolean(updated, 'archived'),
+          createdAt: modelNullableString(updated, 'createdAt', 'created_at'),
+          updatedAt: modelNullableString(updated, 'updatedAt', 'updated_at'),
         },
       }
     }
     catch (err) {
       console.error('[dashboard/kanban] BoardUpdateAction failed:', err)
-      return { error: err instanceof Error ? err.message : 'unknown error', status: 500 }
+      return kanbanError(err instanceof Error ? err.message : 'unknown error', 500)
     }
   },
 })

package/app/Actions/Dashboard/Kanban/BoardsIndexAction.ts

@@ -1,5 +1,6 @@
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
+import { kanbanError } from './kanban-response'
 
 interface BoardRow {
   id: number
@@ -69,13 +70,7 @@ export default new Action({
     }
     catch (err) {
       console.error('[dashboard/kanban] BoardsIndexAction failed:', err)
-      // Soft-error shape — page renders an empty-state with the
-      // message instead of bubbling a 500. Missing `boards` table
-      // (migrations not run) ends up here on a fresh project.
-      return {
-        boards: [],
-        error: err instanceof Error ? err.message : 'unknown error',
-      }
+      return kanbanError(err instanceof Error ? err.message : 'unknown error', 500)
     }
   },
 })