refactor(devtools): extract shared functions into src/functions/ to eliminate duplication

Moves duplicated badge, formatter, chart config, and constant definitions
from 12 page scripts into shared TypeScript files, bundled and served as
/bq-utils.js for global access in stx template expressions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: glennmichael123

packages/devtools/src/functions/badges.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared badge/status class utilities for the devtools dashboard.
+ * These are bundled and served as globals for stx template expressions.
+ */
+
+/**
+ * Badge classes for job statuses (active = indigo).
+ * Used by: jobs, index, batch-details, batches, group-details, groups
+ */
+export function badgeClass(status: string): string {
+  const map: Record<string, string> = {
+    completed: 'bg-emerald-500/15 text-emerald-500',
+    finished: 'bg-emerald-500/15 text-emerald-500',
+    failed: 'bg-red-500/15 text-red-500',
+    processing: 'bg-indigo-500/15 text-indigo-400',
+    active: 'bg-indigo-500/15 text-indigo-400',
+    waiting: 'bg-amber-500/15 text-amber-500',
+    pending: 'bg-amber-500/15 text-amber-500',
+    delayed: 'bg-zinc-500/15 text-zinc-500',
+  }
+  return map[status] || 'bg-zinc-500/15 text-zinc-500'
+}
+
+/**
+ * Badge classes for queue health statuses (active = emerald).
+ * Used by: queues, queue-details
+ */
+export function queueBadgeClass(status: string): string {
+  const map: Record<string, string> = {
+    active: 'bg-emerald-500/15 text-emerald-500',
+    paused: 'bg-amber-500/15 text-amber-500',
+    stopped: 'bg-red-500/15 text-red-500',
+    completed: 'bg-emerald-500/15 text-emerald-500',
+    failed: 'bg-red-500/15 text-red-500',
+    waiting: 'bg-amber-500/15 text-amber-500',
+    pending: 'bg-amber-500/15 text-amber-500',
+  }
+  return map[status] || 'bg-zinc-500/15 text-zinc-500'
+}
+
+/**
+ * Progress bar color based on batch/queue status.
+ * Used by: batches
+ */
+export function progressBarColorClass(status: string): string {
+  const map: Record<string, string> = {
+    completed: 'bg-emerald-500',
+    finished: 'bg-emerald-500',
+    failed: 'bg-red-500',
+    processing: 'bg-indigo-500',
+    active: 'bg-indigo-500',
+    pending: 'bg-amber-500',
+    waiting: 'bg-amber-500',
+  }
+  return map[status] || 'bg-indigo-500'
+}
+
+/**
+ * Dot color for monitoring event types.
+ * Used by: monitoring
+ */
+export function dotColor(dot: string): string {
+  const map: Record<string, string> = {
+    completed: 'bg-emerald-500',
+    started: 'bg-indigo-500',
+    failed: 'bg-red-500',
+    queued: 'bg-amber-500',
+  }
+  return map[dot] || 'bg-zinc-500'
+}
+
+/**
+ * Health indicator color based on error rate.
+ * Used by: monitoring
+ */
+export function healthColor(errorRateValue: number): string {
+  if (errorRateValue > 5) return 'bg-red-500'
+  if (errorRateValue > 1) return 'bg-amber-500'
+  return 'bg-emerald-500'
+}
+
+/**
+ * Queue status display label.
+ * Used by: queues
+ */
+export function statusLabel(status: string): string {
+  const map: Record<string, string> = {
+    active: 'Active',
+    paused: 'Paused',
+    stopped: 'Stopped',
+  }
+  return map[status] || status
+}

packages/devtools/src/functions/browser.ts

@@ -0,0 +1,39 @@
+/**
+ * Browser entry point — assigns all shared functions to globalThis
+ * so they're accessible in stx template expressions.
+ */
+import {
+  badgeClass,
+  chartOptions,
+  createLineDataset,
+  DEFAULT_STATUS_COLOR,
+  dotColor,
+  formatDuration,
+  formatEventTime,
+  formatTime,
+  healthColor,
+  MAX_EVENTS,
+  progressBarColorClass,
+  queueBadgeClass,
+  REFRESH_INTERVAL,
+  statusLabel,
+  STATUS_COLORS,
+} from './index'
+
+Object.assign(globalThis, {
+  badgeClass,
+  chartOptions,
+  createLineDataset,
+  DEFAULT_STATUS_COLOR,
+  dotColor,
+  formatDuration,
+  formatEventTime,
+  formatTime,
+  healthColor,
+  MAX_EVENTS,
+  progressBarColorClass,
+  queueBadgeClass,
+  REFRESH_INTERVAL,
+  statusLabel,
+  STATUS_COLORS,
+})

packages/devtools/src/functions/chart.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared Chart.js configuration for the devtools dashboard dark theme.
+ */
+
+/**
+ * Default chart options for the dark-themed dashboard.
+ * Used by: metrics, index, queue-details
+ */
+export function chartOptions(overrides?: Record<string, unknown>): Record<string, unknown> {
+  const defaults: Record<string, unknown> = {
+    responsive: true,
+    maintainAspectRatio: false,
+    plugins: { legend: { display: false } },
+    scales: {
+      x: {
+        grid: { color: 'rgba(39,39,42,0.5)' },
+        ticks: { color: '#71717a', font: { size: 10 }, maxRotation: 0, maxTicksLimit: 10 },
+      },
+      y: {
+        grid: { color: 'rgba(39,39,42,0.5)' },
+        ticks: { color: '#71717a', font: { size: 10 } },
+        beginAtZero: true,
+      },
+    },
+    interaction: { intersect: false, mode: 'index' },
+  }
+
+  if (!overrides) return defaults
+
+  return { ...defaults, ...overrides }
+}
+
+interface LineDataset {
+  label: string
+  data: number[]
+  borderColor: string
+  backgroundColor: string
+  fill: boolean
+  tension: number
+  pointRadius: number
+  pointHitRadius: number
+  borderWidth: number
+}
+
+/**
+ * Create a styled line dataset for Chart.js.
+ * Used by: metrics
+ */
+export function createLineDataset(label: string, data: number[], color: string): LineDataset {
+  return {
+    label,
+    data,
+    borderColor: color,
+    backgroundColor: color.replace(')', ', 0.1)').replace('rgb', 'rgba'),
+    fill: true,
+    tension: 0.4,
+    pointRadius: 0,
+    pointHitRadius: 10,
+    borderWidth: 2,
+  }
+}

packages/devtools/src/functions/constants.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared constants for the devtools dashboard.
+ */
+
+/** Status colors for D3 dependency graph nodes */
+export const STATUS_COLORS: Record<string, string> = {
+  completed: '#10b981',
+  active: '#6366f1',
+  waiting: '#f59e0b',
+  pending: '#f59e0b',
+  failed: '#ef4444',
+}
+
+/** Default color for unknown statuses */
+export const DEFAULT_STATUS_COLOR = '#71717a'
+
+/** Monitoring auto-refresh interval in milliseconds */
+export const REFRESH_INTERVAL = 3000
+
+/** Maximum number of events to keep in the monitoring event log */
+export const MAX_EVENTS = 50

packages/devtools/src/functions/formatters.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared formatting utilities for the devtools dashboard.
+ */
+
+/**
+ * Format an ISO timestamp to a locale string.
+ * Returns em-dash for null/undefined/empty values.
+ * Used by: batches, batch-details, queue-details, job-details, group-details
+ */
+export function formatTime(ts?: string): string {
+  if (!ts) return '\u2014'
+  return new Date(ts).toLocaleString()
+}
+
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ * Used by: index (dashboard overview)
+ */
+export function formatDuration(duration?: number): string {
+  return duration ? (duration / 1000).toFixed(1) + 's' : '\u2014'
+}
+
+/**
+ * Format the current time as HH:MM:SS for event log entries.
+ * Used by: monitoring
+ */
+export function formatEventTime(): string {
+  return new Date().toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' })
+}

packages/devtools/src/functions/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Barrel export for all shared devtools functions.
+ * This file is the entrypoint for Bun.build to create the browser bundle.
+ */
+
+export {
+  badgeClass,
+  dotColor,
+  healthColor,
+  progressBarColorClass,
+  queueBadgeClass,
+  statusLabel,
+} from './badges'
+
+export {
+  formatDuration,
+  formatEventTime,
+  formatTime,
+} from './formatters'
+
+export {
+  chartOptions,
+  createLineDataset,
+} from './chart'
+
+export {
+  DEFAULT_STATUS_COLOR,
+  MAX_EVENTS,
+  REFRESH_INTERVAL,
+  STATUS_COLORS,
+} from './constants'

packages/devtools/src/index.ts

@@ -10,8 +10,29 @@ export { JobStatus } from './types'
 export { createApiRoutes, fetchBatches, fetchDashboardStats, fetchDependencyGraph, fetchJobGroups, fetchJobs, fetchMetrics, fetchQueueMetrics, fetchQueues } from './api'
 
 const PAGES_DIR = path.join(import.meta.dir, 'pages')
+const FUNCTIONS_ENTRY = path.join(import.meta.dir, 'functions', 'browser.ts')
 
 let broadcastServer: BroadcastServer | null = null
+let bundledFunctionsJs: string | null = null
+
+async function buildFunctionsBundle(): Promise<string> {
+  if (bundledFunctionsJs) return bundledFunctionsJs
+
+  const result = await Bun.build({
+    entrypoints: [FUNCTIONS_ENTRY],
+    target: 'browser',
+    minify: false,
+    format: 'iife',
+  })
+
+  if (!result.success) {
+    console.error('Failed to build functions bundle:', result.logs)
+    return ''
+  }
+
+  bundledFunctionsJs = await result.outputs[0].text()
+  return bundledFunctionsJs
+}
 
 async function renderStxPage(templateName: string, wsUrl: string): Promise<string> {
   const templatePath = path.join(PAGES_DIR, `${templateName}.stx`)
@@ -242,6 +263,12 @@ catch { /* try next queue */ }
         return Response.json(allJobs.slice(0, batch.totalJobs > 10 ? 10 : batch.totalJobs))
       }
 
+      // Shared functions bundle
+      if (path === '/bq-utils.js') {
+        const js = await buildFunctionsBundle()
+        return new Response(js, { headers: { 'Content-Type': 'application/javascript', 'Cache-Control': 'no-store' } })
+      }
+
       // Static page routes
       const pageMap: Record<string, string> = {
         '/': 'index',